FAQ#
General#
- What is the difference between a feature, a scenario and a step?
A feature is a user story describing a part of the product in simple terms. A scenario is one concrete example distilled from the feature and becomes one automation test. A step is one sentence inside a scenario. See the vocabulary table in Concepts.
- What is ATDD / BDD, and do I need to know them to use ZagalaSpec?
No prior knowledge needed. Concepts explains both in a few paragraphs: you describe behaviour as Given / When / Then examples, and those examples become automated tests. ZagalaSpec is the Unreal implementation of that idea.
- Do I need to write code?
Not to write, review, import, run or export features. Code (Blueprint or C++) is needed only when a sentence has no step behind it yet; see 7. Create a new step in Blueprint.
- Which Unreal Engine versions and platforms are supported?
Unreal Engine 5.6 to 5.8 on Windows (Win64), Linux and macOS, in Blueprint-only and C++ projects.
- Does ZagalaSpec end up in my shipped game?
No. Its modules are
DeveloperToolandEditormodules and are excluded from Shipping builds.
Writing features#
- Do I need to write text and regex patterns for steps?
No. You only write the sentences in the feature files. Step entries with their patterns are created and maintained separately, usually by programmers. You can also use native steps to match against a step directly, without needing a separate step entry (which is the link from a regex pattern to an actual step).
- Can I edit a feature after importing it?
Yes. The imported asset is a normal Feature asset; open it in the ZagalaSpec Feature Editor and change anything. Export it again to share the text.
- What is the difference between Shared Context Extensions, Context Extensions and Expectations? What relationship do they have with steps?
Steps are the actions or operations (defined as sentences) that are executed within a scenario and they are composed of Expectations, Context Extensions and Shared Context Extensions. Expectations define the expected outcomes or assertions for a scenario. Context Extensions are specific to a particular scenario, providing additional context for that scope. They can iterate many times to parametrize the scenario. Shared Context Extensions are reusable pieces of context that are specified on a feature and applied to all its scenarios. They can iterate too. At execution time, the shared context extensions are executed first, then the scenario specific context extensions and finally the expectations.
- Why does a step show an empty Matched Step Entry?
No registered step entry has a pattern that matches that sentence. Either reword it to match an existing pattern, or ask a programmer to add a step entry. Matching re-runs half a second after you stop typing. 4. Write a feature and import it shows what to check.
- How do identifiers and tags work?
Features and scenarios are identified by gameplay tags; a scenario’s tag is normally a child of its feature’s (
MyGame.Features.Doors.OpensWhenUnlocked). Imports create tags underZagalaSpec.Import.Features(configurable). The automation test name isFeatures.followed by the scenario tag.- Can I keep an unfinished scenario without it failing the build?
Untick Include In Tests on the scenario (or Include All Scenarios In Tests on the feature). In
.zagalaspecfiles, a(disabled)tag does the same on import.- Which file formats can I import?
Gherkin / SpecFlow
.feature, Robot Framework.robot, Gauge.specand.cpt, FitNesse.wiki, and ZagalaSpec’s own.zagalaspec. Only.zagalaspecround-trips without loss (except for configuration of capture groups); the others import the parts that map onto features, scenarios and steps and warn about the rest. The support matrix is in Usage.- Why did my Scenario Outline (other frameworks concept) become a single scenario?
ZagalaSpec represents Scenario Outlines as one scenario plus an examples iterator in its context extensions, with the rows in a Tagged Data Examples asset. One line in the test list, one pass per row. See 5. Examples tables and iteration.
Running#
- Where are my features in the Session Frontend?
Tools > Session Frontend > Automation, search
Features.followed by your feature tag. Each scenario is one test.- How do I run features from the command line or CI?
UnrealEditor-Cmd.exe <Project.uproject> -ExecCmds="Automation RunTests Features.<prefix>; Quit" -unattended -nullrhi -nop4 -log -ReportExportPath=<dir>. Full details in Usage. World-based features run headless too. You can useFeatures.+as a prefix to run all ZagalaSpec features.- A scenario is missing from the test list.
Scenarios register when their Feature asset is saved. Open the feature and save it, then press Refresh Tests in the Session Frontend. If features vanished after a plugin update, see Updating below.
- How do I run a scenario only in the editor or only in some build configurations?
Add
ZagalaSpec.ScenarioFilter.Require.Editor(orExclude.Shipping,Require.Development, and so on) to the scenario’s Filter Tags in the Advanced section of its Details panel, then save the feature. See Filter scenarios by environment in Usage.
- A scenario never finishes.
A step started but never broadcast success or failure. Look in the Output Log (
LogZagalaSpec) for the last step that began. Common causes: a Blueprint path that reaches neither Broadcast node, or a wait with no tick limit. World-based examples setGiven the tick limit is set to N ticksfor exactly this reason.- Where are the reports?
With
-ReportExportPath, anindex.jsonplus per-test files are written there. Without it, results are in the log and the Session Frontend only.- Do world-based features need a window or a GPU?
No. They start Play In Editor internally and work with
-nullrhi. Only a feature that tests rendering itself would need a real renderer.
- Can ZagalaSpec test multiplayer?
Yes. In the editor, a scenario can start Play In Editor as a listen server with several clients and check both the server and each client; the bundled Networking feature does this (12. Multiplayer in the editor). Packaged multiplayer tests (launching client processes, or Gauntlet with ZagalaSpec running in the server) are described at the end of that tutorial but not bundled.
Updating#
- How do I know a new version is out?
Updates are announced on Discord.
- How do I update?
Epic Games Launcher > Fab Library > Update for each engine version you use, then restart the editor and re-run the bundled examples. Steps in Installation.
- Where can I see what changed?
The Changelog page of these docs or release notes.
- Will my features and settings survive an update?
Feature assets live in your project and are untouched. The scenario and step registries are stored in the plugin’s
Configfolder by default and are overwritten by an update. Untick Save Config To Plugin Folder in the ZagalaSpec feature settings so they are saved with the project; if it already happened, re-save your Feature assets to re-register them.- Can I stay on an older plugin version?
The Launcher installs one plugin version per engine version. Not updating keeps what you have; there is no downgrade path other than reinstalling from the Launcher.
Troubleshooting#
- The plugin is missing after installing a new engine version.
Plugins are installed per engine version. In the Launcher, use Install to Engine again for the new version.
- The Output Log warns about a duplicate regex pattern.
Two step entries declare the same pattern. The first registered wins; the second is ignored. Change one pattern, or delete the redundant entry.
- Typing a step sentence feels laggy.
Matching is debounced (default 0.5 s) so it does not run on every keystroke. Adjust Debounce Delay Seconds in the ZagalaSpec feature settings.
- A
BlueprintFeaturescenario fails after I slimmed the plugin. BlueprintFeaturedepends on theZagalaSpecToolkitmodule. Restore the module, or remove the example content as described in Installation.- My world-based scenario fails immediately with “no active world available”.
The scenario has no
a test world is readyextension before the step that needs a world, or that extension’s play-settings capture group is not configured. See 6. World-based features.
- A physics scenario passes in a packaged run but fails intermittently in the editor.
Count ticks of the test world, not application frames. In the editor the PIE world can be skipped (Slate throttling, pause) or ticked several times in one frame (fixed time step), so a wait built on
FTSTickerorFTimerManagerdrifts from the simulation. Derive latent C++ drivers fromUZagalaSpecPDWaitForTicks, which countsFWorldDelegates::OnWorldPostActorTickfor the cached play session world only, and keep Use Fixed Time Step on in the play-settings asset. See 10. Hoverboard in C++.- Capture group settings disappeared after re-importing a feature.
Capture group configuration is stored in the asset and is not part of any export format. After re-import, re-check steps whose groups you customised, or edit the existing asset instead of re-importing.
Support#
- Where do I report a problem?
On the Discord Issues page or by email to support@zagalagamesolutions.com. Include the engine version, the plugin version from the changelog, and the Output Log lines tagged
LogZagalaSpec. Support is best effort support only, and is available from Monday to Thursday, 09:00–13:00 ET, 06:00–10:00 PT, 15:00–19:00 CET.