5. Examples tables and iteration#

For: configurators. Needs: Tutorial 3. You will: read the Inventory feature in .zagalaspec form, see how one word ("Sword") flows through several steps, run a scenario against a table of rows without a Scenario Outline, and build your own examples asset.

The feature as text#

Source/ZagalaSpecExamples/Features/Inventory.zagalaspec in the installed plugin, imported as Plugins > ZagalaSpec Content > DEMO > Data > Inventory > DA_Inventory:

@ZagalaSpec.Import.Features.Inventory
Feature: Inventory
  As a developer using ZagalaSpec
  I want to manage an in-memory inventory through the full execution stack
  So that I have a canonical example of global and local capture groups and
  iterator-based data-driven testing without Scenario Outline.

  Shared Context Extensions:
    Given a fresh empty inventory

  @ZagalaSpec.Import.Features.Inventory.FreshInventoryStartsEmpty
  Scenario: Fresh inventory starts empty
    Then the inventory has 0 of "Sword"

  @ZagalaSpec.Import.Features.Inventory.GlobalCaptureFlowsAcrossSteps
  Scenario: Global capture flows across steps
    Context Extensions:
      Given I focus on item "Sword"
    Expectations:
      When I add 3 of that item
      Then the inventory has 3 of "Sword"
      And the inventory has 3 of that item

  @ZagalaSpec.Import.Features.Inventory.LocalCapturesInSingleStep
  Scenario: Local captures in a single step
    When I add 10 of "Arrow" directly
    Then the inventory has 10 of "Arrow"

  @ZagalaSpec.Import.Features.Inventory.PresetLoadsDefaultStock
  Scenario: Preset loads default stock
    Context Extensions:
      Given the default stock is loaded
    Expectations:
      Then the inventory has 5 of "Arrow"
      And the inventory has 1 of "Sword"

  @ZagalaSpec.Import.Features.Inventory.IteratorReplacesScenarioOutline
  Scenario: Iterator replaces Scenario Outline
    Context Extensions:
      Given iterate over inventory <Examples>
    Expectations:
      When I add the focused item and quantity
      Then the inventory has the focused quantity of that item

Run it: Session Frontend, search Features.ZagalaSpec.Import.Features.Inventory, five green rows.

The .zagalaspec sections#

The native format is Gherkin plus three keywords, and this file uses all of them:

  • Shared Context Extensions: under the feature: setup that runs before every scenario (Gherkin’s Background).

  • Context Extensions: under a scenario: setup for that scenario only. Gherkin has no equivalent; on export to .feature these become ordinary leading steps.

  • Expectations: under a scenario: the Given / When / Then steps. Required whenever Context Extensions: is present; omitted when a scenario has no extensions (see Local captures in a single step).

  • A @tag line immediately before Feature: or Scenario: becomes its identifier. Without one, the identifier is generated from the title.

The split matters at run time: extensions run first, can ask for more passes (next section), and if one fails the expectations are skipped.

One word, many steps: global capture#

Look at Global capture flows across steps. "Sword" is named in the context extension Given I focus on item "Sword"; two later steps say that item and still know it is the sword, and one says "Sword" again.

Two mechanisms are at work:

  • The focus step writes to the cache for everyone. Given I focus on item "Sword" stores an ZagalaSpecDataItemName object under the item-name tag. Every later step written to read the focused item (I add 3 of that item, the inventory has 3 of that item) finds it there. Nothing on those steps needs configuring: the cache carries the value through the scenario.

  • Quoted names resolve globally. Select Then the inventory has 3 of "Sword" and expand the second capture group. Its Scope is Global and there is no Group Value Class on the step. ZagalaSpec looked the text Sword up in Project Settings > ZagalaSpec > Global Capture Group Classes, where the plugin ships two rows:

    Capture Group Value

    Group Value Class

    Converter

    Sword

    ZagalaSpecDataItemName

    default

    Arrow

    ZagalaSpecDataItemName

    default

    Global scope means “this word has one meaning for the whole project”. Any sentence that captures Sword, in any feature, produces the same ZagalaSpecDataItemName object, so a step can be written once and never care which sentence supplied the name. To add an item your designers talk about, add a row; no step changes.

Compare with Local captures in a single step: When I add 10 of "Arrow" directly captures both the quantity and the name itself and uses them immediately. Local is the default and the right choice when a value is only meaningful inside one sentence.

Rows without a Scenario Outline: the iterator#

Iterator replaces Scenario Outline has no <amount> placeholders in its expectations at all. Its extension Given iterate over inventory <Examples> matches the Inventory example’s iterator step entry (^(?:Given |And )?iterate over inventory <(.+)>$), and the capture group’s Group Value Object points at the asset DA_Inventory_ItemQuantity_Examples next to the feature.

Open that asset:

DA_Inventory_ItemQuantity_Examples
  • Examples Collection is the table. Its first line counts the rows (3 examples); each row is a group named after the pass that uses it: Example for first iteration, containing 2 data items, Example for iteration 2, containing 2 data items, and so on.

  • Each row lists the tagged data objects it provides, with their properties inline: an ZagalaSpecDataItemName and an ZagalaSpecDataInteger (the quantity). The dropdown on each object’s line shows its type; properties marked Advanced sit in a collapsed Advanced group.

On each pass the iterator writes the current row’s objects into the cache, then the two expectation steps read the focused item and quantity from there. When the row is used up, the iterator reports a pending iteration, the context clears the cache, advances the row, and runs the pass again. Three rows, one scenario, one green line. Because the shared extension Given a fresh empty inventory resets the inventory in its teardown, every row starts clean.

The core plugin ships a generic iterator sentence as well: Given examples from <YourExamplesAsset> (used by Counter’s Increment table). The Inventory-specific wording exists only to show that a project can name its own.

Build your own examples asset#

  1. Add > Miscellaneous > Data Asset, choose ZagalaSpec Tagged Data Examples, name it Inventory_MoreStock_Examples.

  2. Open it. Under Examples Collection, press + next to the 0 examples count three times. Each press adds one Example for … iteration row.

  3. In each example press + on its header twice. In the first new line’s dropdown pick ZagalaSpecDataItemName and set Item Name (Sword, Arrow, Shield). In the second pick ZagalaSpecDataInteger and set Value (2, 7, 1). The trash button next to a dropdown removes that object; the one on an example header removes the whole example.

    To reuse rows, right-click an example header or a tagged data line and choose Copy, then right-click a target and choose Paste. A copied example pasted on the N examples line is added as a new example; pasted on an example header it replaces that example. A copied tagged data object pasted on an example header is added to that example; pasted on a tagged data line (an empty one included) it replaces that object. Pastes are deep copies and can be undone.

  4. Save.

  5. Open the DA_Inventory feature, add a scenario ZagalaSpec.Import.Features.Inventory.MoreStock. In its Context Extensions add Given iterate over inventory <MoreStock>; in the step’s capture group set Group Value Object to your new asset. In Expectations add When I add the focused item and quantity and Then the inventory has the focused quantity of that item.

  6. Save, refresh, run. One row, three passes.

Shield was never mentioned in a sentence, so it needs no Global Capture Group row: the examples asset supplies the object directly.

What you learned#

  • .zagalaspec separates shared setup, per-scenario setup and expectations, and round-trips without loss.

  • Global scope turns a word into a project-wide meaning via Project Settings; Local scope keeps a value inside its sentence.

  • An examples asset plus an iterator extension replaces Scenario Outline: rows are data, the scenario stays single.

Next: 6. World-based features for features that need a level and physics. Programmers: 9. Inventory in C++ reads the C++ behind this page.