gds-test-automate

Game Test Automation Workflow

Goal: Generate automated test code for game projects based on test design scenarios or by analyzing existing game code. Creates engine-appropriate tests for Unity, Unreal, or Godot with proper patterns, fixtures, and cleanup.

Your Role: You are a senior game QA engineer and test automation specialist. Work autonomously to analyze the game codebase, detect the engine in use, and generate well-structured unit, integration, and smoke tests. You bring structured testing knowledge and engine-specific patterns, while the user brings domain context about the game's systems.

---

Conventions

• Bare paths (e.g. template.md) resolve from the skill root.
• {skill-root} resolves to this skill's installed directory (where customize.toml lives).
• {project-root} is the nearest folder containing _bmad/, starting at the project working directory and moving up through its parents.
• {skill-name} resolves to the skill directory's basename.

On Activation

Step 1: Resolve the Workflow Block

Run: uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow

If the script fails, resolve the workflow block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:

1. {skill-root}/customize.toml — defaults
2. {project-root}/_bmad/custom/{skill-name}.toml — team overrides
3. {project-root}/_bmad/custom/{skill-name}.user.toml — personal overrides

Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by code or id replace matching entries and append new entries, and all other arrays append.

Step 2: Execute Prepend Steps

Execute each entry in {workflow.activation_steps_prepend} in order before proceeding.

Step 3: Load Persistent Facts

Treat every entry in {workflow.persistent_facts} as foundational context you carry for the rest of the workflow run. Entries prefixed file: are paths or globs under {project-root} — load the referenced contents as facts. All other entries are facts verbatim.

Step 4: Load Config

Load config from {project-root}/_bmad/gds/config.yaml and resolve:

• user_name
• communication_language
• output_folder
• date as the system-generated current datetime

Step 5: Greet the User

Greet {user_name}, speaking in {communication_language}.

Step 6: Execute Append Steps

Execute each entry in {workflow.activation_steps_append} in order.

Activation is complete. If activation_steps_prepend or activation_steps_append were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.

WORKFLOW ARCHITECTURE

This uses an inline workflow pattern for autonomous execution:

• Steps execute sequentially with full autonomy
• Engine detection drives all subsequent decisions
• All test files are written to disk as they are generated
• A final summary report is produced at completion

Preflight Requirements

Before proceeding, verify:

• Test framework already initialized (run framework workflow first)
• Test scenarios defined (from test-design workflow or ad-hoc)
• Game code accessible for analysis

If any preflight requirement is not met, HALT and guide the user.

Paths

• installed_path = {skill_root}
• validation = {installed_path}/checklist.md
• test_dir = {project-root}/tests
• source_dir = {project-root}/src

Variables

• coverage_target = critical-paths (options: critical-paths, comprehensive, selective)
• game_engine = auto (options: auto, unity, unreal, godot)
• default_output_file = {output_folder}/automation-summary.md

Knowledge Fragments

Load the engine-specific knowledge fragment after engine detection in Step 1:

• Unity: {installed_path}/knowledge/unity-testing.md
• Unreal: {installed_path}/knowledge/unreal-testing.md
• Godot: {installed_path}/knowledge/godot-testing.md
• E2E patterns: {installed_path}/knowledge/e2e-testing.md

---

EXECUTION

[TestFixture] public class {ClassName}Tests { private {ClassName} _sut;

[SetUp]
public void Setup()
{
    _sut = new {ClassName}();
}

[Test]
public void {MethodName}_When{Condition}_Should{Expectation}()
{
    // Arrange
    {setup_code}
    // Act
    var result = _sut.{MethodName}({parameters});
    // Assert
    Assert.AreEqual({expected}, result);
}

[TestCase({input1}, {expected1})]
[TestCase({input2}, {expected2})]
public void {MethodName}_Parameterized({inputType} input, {outputType} expected)
{
    var result = _sut.{MethodName}(input);
    Assert.AreEqual(expected, result);
}

}

    </action>
  </check>

  <!-- Unreal (C++) -->
  <check if="engine == 'unreal'">
    <action>Generate Automation Test macros following this pattern:
```cpp
#include "Misc/AutomationTest.h"

IMPLEMENT_SIMPLE_AUTOMATION_TEST(
    F{ClassName}{MethodName}Test,
    "{ProjectName}.{Category}.{TestName}",
    EAutomationTestFlags::ApplicationContextMask |
    EAutomationTestFlags::ProductFilter
)

bool F{ClassName}{MethodName}Test::RunTest(const FString& Parameters)
{
    // Arrange
    {setup_code}
    // Act
    auto Result = {ClassName}::{MethodName}({parameters});
    // Assert
    TestEqual("{assertion_message}", Result, {expected});
    return true;
}

</action>

var _sut: {ClassName}

func before_each(): _sut = {ClassName}.new()

func after_each(): _sut.free()

func test_{method_name}when{condition}should{expectation}(): # Arrange {setup_code} # Act var result = _sut.{method_name}({parameters}) # Assert assert_eq(result, {expected}, "{assertion_message}")

func test_{method_name}_parameterized(): var test_cases = [ {"input": {input1}, "expected": {expected1}}, {"input": {input2}, "expected": {expected2}} ] for tc in test_cases: var result = _sut.{method_name}(tc.input) assert_eq(result, tc.expected)

    </action>
  </check>

  <action>Write each generated unit test file to the appropriate location under `{test_dir}/unit/`</action>
</step>

<step n="3" goal="Generate Integration Tests">
  <action>Generate scene/level integration tests using the appropriate engine template</action>

  <check if="engine == 'unity'">
    <action>Generate Unity Play Mode integration tests:
```csharp
[UnityTest]
public IEnumerator {SceneName}_Loads_WithoutErrors()
{
    SceneManager.LoadScene("{scene_name}");
    yield return new WaitForSeconds(2f);
    var errors = GameObject.FindObjectsOfType<ErrorHandler>()
        .Where(e => e.HasErrors);
    Assert.IsEmpty(errors, "Scene should load without errors");
}

</action>

Write each generated integration test file to {test_dir}/integration/

[UnitySetUp]
public IEnumerator BaseSetUp()
{
    yield return LoadScene("{main_scene}");
    GameState = Object.FindFirstObjectByType<{GameStateClass}>();
    Input = new {InputSimulatorClass}();
    Scenario = new {ScenarioBuilderClass}(GameState);
    yield return WaitForReady();
}

}

  </action>
  <action>Write infrastructure files to `{test_dir}/e2e/infrastructure/` or the engine-appropriate equivalent</action>
  <action>After scaffolding infrastructure, proceed to generate actual E2E tests</action>
</step>

<step n="4" goal="Generate Smoke Tests">
  <action>Create critical path tests that run on every build, covering:
    1. Game launches without crash
    2. Main menu is navigable
    3. New game starts successfully
    4. Core gameplay loop executes
    5. Save/load works
  </action>
  <action>Generate engine-appropriate smoke tests, for example (Unity):
```csharp
[UnityTest, Timeout(60000)]
public IEnumerator Smoke_NewGame_StartsSuccessfully()
{
    SceneManager.LoadScene("MainMenu");
    yield return new WaitForSeconds(2f);
    var newGameButton = GameObject.Find("NewGameButton");
    newGameButton.GetComponent<Button>().onClick.Invoke();
    yield return new WaitForSeconds(5f);
    var player = GameObject.FindWithTag("Player");
    Assert.IsNotNull(player, "Player should exist after new game");
}

Ensure generated tests do NOT: - Test engine functionality (not game logic) - Use hard-coded waits as primary sync (use signals/events) - Depend on execution order - Lack cleanup in teardown

## Automation Summary

**Engine**: {Unity | Unreal | Godot}
**Tests Generated**: {count}
**Date**: {date}

### Test Distribution

| Type        | Count | Coverage      |
| ----------- | ----- | ------------- |
| Unit Tests  | {n}   | {systems}     |
| Integration | {n}   | {features}    |
| Smoke Tests | {n}   | Critical path |

### Files Created

- `tests/unit/{file1}.{ext}`
- `tests/integration/{file2}.{ext}`
- `tests/smoke/{file3}.{ext}`

### Next Steps

1. Review generated tests
2. Fill in test-specific logic where placeholders remain
3. Run tests to verify they pass
4. Add to CI pipeline