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 expectationsWhen 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 |
|---|---|---|---|---|---|
|
|
|
writes |
||
|
|
|
|
|
writes |
|
|
same |
same |
same |
Amount comes from the examples row |
|
|
|
|
|
writes |
|
|
same |
same |
same |
Expected comes from the examples row |
|
|
|
|
|
reads Ref |
|
|
|
reads |
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.