3. The Counter feature#

For: everyone; the last section is for programmers. Needs: Tutorial 1. You will: run a six-scenario feature with a real system under test, see shared setup, data-driven scenarios and a negative case, and (optionally) map every sentence to its C++ class.

The feature as text#

The plugin ships the feature in two forms: the asset Plugins > ZagalaSpec Content > DEMO > Data > Counter > DA_Counter, and the file it was imported from, Source/ZagalaSpecExamples/Features/Counter.feature inside the installed plugin:

Feature: Counter
  As a developer using ZagalaSpec
  I want to manage a counter through the full execution stack
  So that I have a canonical example of Feature → Scenario → Context → Expectation → DSL → Driver → SUT

  Background:
    Given a fresh counter

  Scenario: Fresh counter starts at zero
    Then the counter value is 0

  Scenario: Increment by N
    When I increment the counter by 5
    Then the counter value is 5

  Scenario: Sequential increments accumulate
    When I increment the counter by 3
    And I increment the counter by 4
    Then the counter value is 7

  Scenario: Reset returns to zero
    When I increment the counter by 10
    And I reset the counter
    Then the counter value is 0

  Scenario Outline: Increment table
    When I increment the counter by <amount>
    Then the counter value is <expected>

    Examples:
      | amount | expected |
      | 1      | 1        |
      | 10     | 10       |
      | 100    | 100      |

  Scenario: Negative increment fails
    When I increment the counter by -3
    Then the last counter operation failed
    And the counter value is 0

This is standard Gherkin. A stakeholder could have written it in a text editor; 4. Write a feature and import it shows how it gets into Unreal.

Run it#

Session Frontend > Automation, search Features.ZagalaSpec.Import.Features.Counter, tick the group, Start Tests. Six green rows:

Features.ZagalaSpec.Import.Features.Counter.FreshCounterStartsAtZero
Features.ZagalaSpec.Import.Features.Counter.IncrementByN
Features.ZagalaSpec.Import.Features.Counter.SequentialIncrementsAccumulate
Features.ZagalaSpec.Import.Features.Counter.ResetReturnsToZero
Features.ZagalaSpec.Import.Features.Counter.IncrementTable
Features.ZagalaSpec.Import.Features.Counter.NegativeIncrementFails

Scenario identifiers were generated on import from the scenario titles, under the parent tag ZagalaSpec.Import.Features.

What to notice in the asset#

Open the DA_Counter asset in the Feature Editor and compare with the text.

Background became a shared context extension. The feature header shows Given a fresh counter under Shared Context Extensions. It runs before every scenario, so each one starts from zero. Select it: its Matched Step Entry is ZagalaSpecExamplesStepEntryFreshCounter, a C++ step entry (compare with the Blueprint ones in Tutorial 2; they behave identically).

Values are capture groups. Select When I increment the counter by 5. The pattern is ^(?:When |And )I increment the counter by (-?\d+)$ and the single capture group holds 5 with Group Value Class ZagalaSpecDataCounterAmount. Change the 5 to 6 in the Definition and the capture group follows. (Change it back.)

The Scenario Outline became one scenario plus an iterator. Open Increment table. Its Context Extensions contain Given examples from <DA_Counter_AmountAndExpected_Examples>: the stock examples-iterator step, whose capture group’s Group Value Object points at the asset DA_Counter_AmountAndExpected_Examples next to the feature. Open that asset: three examples under Examples Collection, each with an ZagalaSpecDataCounterAmount and an ZagalaSpecDataCounterExpected. The two expectation steps still read <amount> and <expected>; they match the template step entries (…by <(?:.+)>$), which capture nothing and let the step pick the current row’s values up from the cache. One scenario, three passes, one green row.

A failing operation is a scenario, not an error. Negative increment fails expects the counter to refuse -3. The step Then the last counter operation failed reads the result the increment step left in the cache and passes only if the operation was rejected. Negative cases are first-class scenarios; a bug that lets -3 through turns this row red.

Try it#

  • Add a scenario: select the feature, press + on Scenarios, set Identifier ZagalaSpec.Import.Features.Counter.TwoResets, add expectations When I increment the counter by 2, And I reset the counter, And I reset the counter, Then the counter value is 0. Save, refresh the Session Frontend, run. Every sentence was already understood; no code was needed.

  • Break it: change the last line to Then the counter value is 2, press Check. Read the reason. Restore it.

For programmers: the class map#

Each sentence resolves to a C++ step in the ZagalaSpecExamples module. The chain for the two most interesting sentences:

        flowchart LR
    A["When I increment the counter by 5<br/>UZagalaSpecStepIncrementBy"] --> B["UZagalaSpecDSLIncrementCounter"] --> C["UZagalaSpecPDIncrementCounter"] --> SUT["UZagalaSpecExamplesCounter"]
    D["Then the counter value is 5<br/>UZagalaSpecStepCounterIs"] --> E["chainer: UZagalaSpecDSLReadCounterValue → UZagalaSpecDSLCheckCounterValue"] --> F["UZagalaSpecPDReadCounterValue, UZagalaSpecPDCheckCounterValue"] --> SUT
    

Sentence (pattern)

Step entry

Execution step

DSL

Protocol driver

Tagged data written / read

^Given a fresh counter$

UZagalaSpecExamplesStepEntryFreshCounter

UZagalaSpecCEFreshCounter

writes UZagalaSpecDataCounterRef

^(?:When |And )I increment the counter by (-?\d+)$

…_IncrementBy

UZagalaSpecStepIncrementBy

UZagalaSpecDSLIncrementCounter

UZagalaSpecPDIncrementCounter

writes UZagalaSpecDataCounterAmount; driver reads Ref + Amount, writes UZagalaSpecDataCounterOpResult

^(?:When |And )I increment the counter by <(?:.+)>$

…_IncrementBy_Template

same

same

same

Amount comes from the examples row

^(?:Then |And )the counter value is (-?\d+)$

…_CounterIs

UZagalaSpecStepCounterIs

UZagalaSpecDSLReadCounterValue, UZagalaSpecDSLCheckCounterValue

UZagalaSpecPDReadCounterValue, UZagalaSpecPDCheckCounterValue

writes UZagalaSpecDataCounterExpected; drivers write UZagalaSpecDataCounterValue, compare

^(?:Then |And )the counter value is <(?:.+)>$

…_CounterIs_Template

same

same

same

Expected comes from the examples row

^(?:When |And )I reset the counter$

…_ResetCounter

UZagalaSpecStepResetCounter

UZagalaSpecDSLResetCounter

UZagalaSpecPDResetCounter

reads Ref

^Then the last counter operation failed$

…_LastOpFailed

UZagalaSpecStepLastOpFailed

reads UZagalaSpecDataCounterOpResult

All tags live under ZagalaSpec.DSL.Data.Examples.Counter.* and are declared in the ZagalaSpecNativeTags module. The system under test, UZagalaSpecExamplesCounter, is a plain UObject with Increment(int32) (rejects negatives, returns false), Reset(), GetValue() and GetLastOperationSucceeded(). It knows nothing about ZagalaSpec.

UZagalaSpecStepIncrementBy in full:

void UZagalaSpecStepIncrementBy::InternalExecute_Implementation(const TScriptInterface<IZagalaSpecTaggedDataCacher>& AssignedCacher)
{
    Action = NewObject<UZagalaSpecDSLIncrementCounter>(this);
    Action->AddSubscriber(this);

    AddLocalSetupDataToCache(AssignedCacher); // UZagalaSpecDataCounterAmount
    Action->Execute(AssignedCacher);
}

That is the whole step: the base class UZagalaSpecChainLinkOnStep forwards the action’s success or failure and tears it down. See the API reference for each class, and 8. Create a new step in C++ to write your own.