Merge 04cc4ce55c into eeebf152af

src/modules/bmgd/agents/game-qa.agent.yaml

@@ -22,6 +22,8 @@ agent:
 
   critical_actions:
     - "Consult {project-root}/_bmad/bmgd/gametest/qa-index.csv to select knowledge fragments under knowledge/ and load only the files needed for the current task"
+    - "For E2E testing requests, always load knowledge/e2e-testing.md first"
+    - "When scaffolding tests, distinguish between unit, integration, and E2E test needs"
     - "Load the referenced fragment(s) from {project-root}/_bmad/bmgd/gametest/knowledge/ before giving recommendations"
     - "Cross-check recommendations with the current official Unity Test Framework, Unreal Automation, or Godot GUT documentation"
     - "Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`"
@@ -43,6 +45,10 @@ agent:
       workflow: "{project-root}/_bmad/bmgd/workflows/gametest/automate/workflow.yaml"
       description: "[TA] Generate automated game tests"
 
+    - trigger: ES or fuzzy match on e2e-scaffold
+      workflow: "{project-root}/_bmad/bmgd/workflows/gametest/e2e-scaffold/workflow.yaml"
+      description: "[ES] Scaffold E2E testing infrastructure"
+
     - trigger: PP or fuzzy match on playtest-plan
       workflow: "{project-root}/_bmad/bmgd/workflows/gametest/playtest-plan/workflow.yaml"
       description: "[PP] Create structured playtesting plan"

src/modules/bmgd/gametest/knowledge/unity-testing.md

@@ -381,3 +381,17 @@ test:
 | NullReferenceException | Missing Setup      | Ensure [SetUp] initializes all fields      |
 | Tests hang             | Infinite coroutine | Add timeout or max iterations              |
 | Flaky physics tests    | Timing dependent   | Use WaitForFixedUpdate, increase tolerance |
+
+## End-to-End Testing
+
+For comprehensive E2E testing patterns, infrastructure scaffolding, and 
+scenario builders, see **knowledge/e2e-testing.md**.
+
+### Quick E2E Checklist for Unity
+
+- [ ] Create `GameE2ETestFixture` base class
+- [ ] Implement `ScenarioBuilder` for your game's domain
+- [ ] Create `InputSimulator` wrapping Input System
+- [ ] Add `AsyncAssert` utilities
+- [ ] Organize E2E tests under `Tests/PlayMode/E2E/`
+- [ ] Configure separate CI job for E2E suite

src/modules/bmgd/gametest/qa-index.csv

@@ -15,3 +15,4 @@ localization-testing,Localization Testing,"Text, audio, and cultural validation
 certification-testing,Platform Certification,"Console TRC/XR requirements and certification testing","certification,console,trc,xr",knowledge/certification-testing.md
 smoke-testing,Smoke Testing,"Critical path validation for build verification","smoke-tests,bvt,ci",knowledge/smoke-testing.md
 test-priorities,Test Priorities Matrix,"P0-P3 criteria, coverage targets, execution ordering for games","prioritization,risk,coverage",knowledge/test-priorities.md
+e2e-testing,End-to-End Testing,"Complete player journey testing with infrastructure patterns and async utilities","e2e,integration,player-journeys,scenarios,infrastructure",knowledge/e2e-testing.md

src/modules/bmgd/workflows/gametest/automate/instructions.md

@@ -209,6 +209,87 @@ func test_{feature}_integration():
     # Cleanup
     scene.queue_free()
 ```
+### E2E Journey Tests
+
+**Knowledge Base Reference**: `knowledge/e2e-testing.md`
+```csharp
+public class {Feature}E2ETests : GameE2ETestFixture
+{
+    [UnityTest]
+    public IEnumerator {JourneyName}_Succeeds()
+    {
+        // GIVEN
+        yield return Scenario
+            .{SetupMethod1}()
+            .{SetupMethod2}()
+            .Build();
+        
+        // WHEN
+        yield return Input.{Action1}();
+        yield return AsyncAssert.WaitUntil(
+            () => {Condition1}, "{Description1}");
+        yield return Input.{Action2}();
+        
+        // THEN
+        yield return AsyncAssert.WaitUntil(
+            () => {FinalCondition}, "{FinalDescription}");
+        Assert.{Assertion}({expected}, {actual});
+    }
+}
+```
+
+
+## Step 3.5: Generate E2E Infrastructure
+
+Before generating E2E tests, scaffold the required infrastructure.
+
+### Infrastructure Checklist
+
+1. **Test Fixture Base Class**
+   - Scene loading/unloading
+   - Game ready state waiting
+   - Common service access
+   - Cleanup guarantees
+
+2. **Scenario Builder**
+   - Fluent API for game state configuration
+   - Domain-specific methods (e.g., `WithUnit`, `OnTurn`)
+   - Yields for state propagation
+
+3. **Input Simulator**
+   - Click/drag abstractions
+   - Button press simulation
+   - Keyboard input queuing
+
+4. **Async Assertions**
+   - `WaitUntil` with timeout and message
+   - `WaitForEvent` for event-driven flows
+   - `WaitForState` for state machine transitions
+
+### Generation Template
+```csharp
+// GameE2ETestFixture.cs
+public abstract class GameE2ETestFixture
+{
+    protected {GameStateClass} GameState;
+    protected {InputSimulatorClass} Input;
+    protected {ScenarioBuilderClass} Scenario;
+    
+    [UnitySetUp]
+    public IEnumerator BaseSetUp()
+    {
+        yield return LoadScene("{main_scene}");
+        GameState = Object.FindFirstObjectByType<{GameStateClass}>();
+        Input = new {InputSimulatorClass}();
+        Scenario = new {ScenarioBuilderClass}(GameState);
+        yield return WaitForReady();
+    }
+    
+    // ... (fill from e2e-testing.md patterns)
+}
+```
+
+**After scaffolding infrastructure, proceed to generate actual E2E tests.**
 
 ---
 

src/modules/bmgd/workflows/gametest/e2e-scaffold/checklist.md

@@ -0,0 +1,95 @@
+# E2E Infrastructure Scaffold Checklist
+
+## Preflight Validation
+
+- [ ] Test framework already initialized (`Tests/` directory exists with proper structure)
+- [ ] Game state manager class identified
+- [ ] Main gameplay scene identified and loads without errors
+- [ ] No existing E2E infrastructure conflicts
+
+## Architecture Analysis
+
+- [ ] Game engine correctly detected
+- [ ] Engine version identified
+- [ ] Input system type determined (New Input System, Legacy, Custom)
+- [ ] Game state manager class located
+- [ ] Ready/initialized state property identified
+- [ ] Key domain entities catalogued for ScenarioBuilder
+
+## Generated Files
+
+### Directory Structure
+- [ ] `Tests/PlayMode/E2E/` directory created
+- [ ] `Tests/PlayMode/E2E/Infrastructure/` directory created
+- [ ] `Tests/PlayMode/E2E/Scenarios/` directory created
+- [ ] `Tests/PlayMode/E2E/TestData/` directory created
+
+### Infrastructure Files
+- [ ] `E2E.asmdef` created with correct assembly references
+- [ ] `GameE2ETestFixture.cs` created with correct class references
+- [ ] `ScenarioBuilder.cs` created with at least placeholder methods
+- [ ] `InputSimulator.cs` created matching detected input system
+- [ ] `AsyncAssert.cs` created with core assertion methods
+
+### Example and Documentation
+- [ ] `ExampleE2ETest.cs` created with working infrastructure test
+- [ ] `README.md` created with usage documentation
+
+## Code Quality
+
+### GameE2ETestFixture
+- [ ] Correct namespace applied
+- [ ] Correct `GameStateClass` reference
+- [ ] Correct `SceneName` default
+- [ ] `WaitForGameReady` uses correct ready property
+- [ ] `UnitySetUp` and `UnityTearDown` properly structured
+- [ ] Virtual methods for derived class customization
+
+### ScenarioBuilder
+- [ ] Fluent API pattern correctly implemented
+- [ ] `Build()` executes all queued actions
+- [ ] At least one domain-specific method added (or clear TODOs)
+- [ ] `FromSaveFile` method scaffolded
+
+### InputSimulator
+- [ ] Matches detected input system (New vs Legacy)
+- [ ] Mouse click simulation works
+- [ ] Button click by name works
+- [ ] Keyboard input scaffolded
+- [ ] `Reset()` method cleans up state
+
+### AsyncAssert
+- [ ] `WaitUntil` includes timeout and descriptive failure
+- [ ] `WaitForValue` provides current vs expected in failure
+- [ ] `AssertNeverTrue` for negative assertions
+- [ ] Frame/physics wait utilities included
+
+## Assembly Definition
+
+- [ ] References main game assembly
+- [ ] References Unity.InputSystem (if applicable)
+- [ ] `overrideReferences` set to true
+- [ ] `precompiledReferences` includes nunit.framework.dll
+- [ ] `precompiledReferences` includes UnityEngine.TestRunner.dll
+- [ ] `precompiledReferences` includes UnityEditor.TestRunner.dll
+- [ ] `UNITY_INCLUDE_TESTS` define constraint set
+
+## Verification
+
+- [ ] Project compiles without errors after scaffold
+- [ ] `ExampleE2ETests.Infrastructure_GameLoadsAndReachesReadyState` passes
+- [ ] Test appears in Test Runner under PlayMode → E2E category
+
+## Documentation Quality
+
+- [ ] README explains all infrastructure components
+- [ ] Quick start example is copy-pasteable
+- [ ] Extension instructions are clear
+- [ ] Troubleshooting table addresses common issues
+
+## Handoff
+
+- [ ] Summary output provided with all configuration values
+- [ ] Next steps clearly listed
+- [ ] Customization requirements highlighted
+- [ ] Knowledge fragments referenced

src/modules/bmgd/workflows/gametest/e2e-scaffold/workflow.yaml

@@ -0,0 +1,145 @@
+# E2E Test Infrastructure Scaffold Workflow
+
+workflow:
+  id: e2e-scaffold
+  name: E2E Test Infrastructure Scaffold
+  version: 1.0
+  module: bmgd
+  agent: game-qa
+
+  description: |
+    Scaffold complete E2E testing infrastructure for an existing game project.
+    Creates test fixtures, scenario builders, input simulators, and async
+    assertion utilities tailored to the project's architecture.
+
+  triggers:
+    - "ES"
+    - "e2e-scaffold"
+    - "scaffold e2e"
+    - "e2e infrastructure"
+    - "setup e2e"
+
+  preflight:
+    - "Test framework initialized (run `test-framework` workflow first)"
+    - "Game has identifiable state manager"
+    - "Main gameplay scene exists"
+
+  # Paths are relative to this workflow file's location
+  knowledge_fragments:
+    - "../../../gametest/knowledge/e2e-testing.md"
+    - "../../../gametest/knowledge/unity-testing.md"
+    - "../../../gametest/knowledge/unreal-testing.md"
+    - "../../../gametest/knowledge/godot-testing.md"
+
+  inputs:
+    game_state_class:
+      description: "Primary game state manager class name"
+      required: true
+      example: "GameStateManager"
+
+    main_scene:
+      description: "Scene name where core gameplay occurs"
+      required: true
+      example: "GameScene"
+
+    input_system:
+      description: "Input system in use"
+      required: false
+      default: "auto-detect"
+      options:
+        - "unity-input-system"
+        - "unity-legacy"
+        - "unreal-enhanced"
+        - "godot-input"
+        - "custom"
+
+  # Output paths vary by engine. Generate files matching detected engine.
+  outputs:
+    unity:
+      condition: "engine == 'unity'"
+      infrastructure_files:
+        description: "Generated E2E infrastructure classes"
+        files:
+          - "Tests/PlayMode/E2E/Infrastructure/GameE2ETestFixture.cs"
+          - "Tests/PlayMode/E2E/Infrastructure/ScenarioBuilder.cs"
+          - "Tests/PlayMode/E2E/Infrastructure/InputSimulator.cs"
+          - "Tests/PlayMode/E2E/Infrastructure/AsyncAssert.cs"
+      assembly_definition:
+        description: "E2E test assembly configuration"
+        files:
+          - "Tests/PlayMode/E2E/E2E.asmdef"
+      example_test:
+        description: "Working example E2E test"
+        files:
+          - "Tests/PlayMode/E2E/ExampleE2ETest.cs"
+      documentation:
+        description: "E2E testing README"
+        files:
+          - "Tests/PlayMode/E2E/README.md"
+
+    unreal:
+      condition: "engine == 'unreal'"
+      infrastructure_files:
+        description: "Generated E2E infrastructure classes"
+        files:
+          - "Source/{ProjectName}/Tests/E2E/GameE2ETestBase.h"
+          - "Source/{ProjectName}/Tests/E2E/GameE2ETestBase.cpp"
+          - "Source/{ProjectName}/Tests/E2E/ScenarioBuilder.h"
+          - "Source/{ProjectName}/Tests/E2E/ScenarioBuilder.cpp"
+          - "Source/{ProjectName}/Tests/E2E/InputSimulator.h"
+          - "Source/{ProjectName}/Tests/E2E/InputSimulator.cpp"
+          - "Source/{ProjectName}/Tests/E2E/AsyncAssert.h"
+      build_configuration:
+        description: "E2E test build configuration"
+        files:
+          - "Source/{ProjectName}/Tests/E2E/{ProjectName}E2ETests.Build.cs"
+      example_test:
+        description: "Working example E2E test"
+        files:
+          - "Source/{ProjectName}/Tests/E2E/ExampleE2ETest.cpp"
+      documentation:
+        description: "E2E testing README"
+        files:
+          - "Source/{ProjectName}/Tests/E2E/README.md"
+
+    godot:
+      condition: "engine == 'godot'"
+      infrastructure_files:
+        description: "Generated E2E infrastructure classes"
+        files:
+          - "tests/e2e/infrastructure/game_e2e_test_fixture.gd"
+          - "tests/e2e/infrastructure/scenario_builder.gd"
+          - "tests/e2e/infrastructure/input_simulator.gd"
+          - "tests/e2e/infrastructure/async_assert.gd"
+      example_test:
+        description: "Working example E2E test"
+        files:
+          - "tests/e2e/scenarios/example_e2e_test.gd"
+      documentation:
+        description: "E2E testing README"
+        files:
+          - "tests/e2e/README.md"
+
+  steps:
+    - id: analyze
+      name: "Analyze Game Architecture"
+      instruction_file: "instructions.md#step-1-analyze-game-architecture"
+
+    - id: scaffold
+      name: "Generate Infrastructure"
+      instruction_file: "instructions.md#step-2-generate-infrastructure"
+
+    - id: example
+      name: "Generate Example Test"
+      instruction_file: "instructions.md#step-3-generate-example-test"
+
+    - id: document
+      name: "Generate Documentation"
+      instruction_file: "instructions.md#step-4-generate-documentation"
+
+    - id: complete
+      name: "Output Summary"
+      instruction_file: "instructions.md#step-5-output-summary"
+
+  validation:
+    checklist: "checklist.md"

src/modules/bmgd/workflows/gametest/test-design/instructions.md

@@ -91,6 +91,18 @@ Create comprehensive test scenarios for game projects, covering gameplay mechani
 | Performance   | FPS, loading times  | P1       |
 | Accessibility | Assist features     | P1       |
 
+### E2E Journey Testing
+
+**Knowledge Base Reference**: `knowledge/e2e-testing.md`
+
+| Category | Focus | Priority |
+|----------|-------|----------|
+| Core Loop | Complete gameplay cycle | P0 |
+| Turn Lifecycle | Full turn from start to end | P0 |
+| Save/Load Round-trip | Save → quit → load → resume | P0 |
+| Scene Transitions | Menu → Game → Back | P1 |
+| Win/Lose Paths | Victory and defeat conditions | P1 |
+
 ---
 
 ## Step 3: Create Test Scenarios
@@ -153,6 +165,39 @@ SCENARIO: Gameplay Under High Latency
   CATEGORY: multiplayer
 ```
 
+### E2E Scenario Format
+
+For player journey tests, use this extended format:
+```
+E2E SCENARIO: [Player Journey Name]
+  GIVEN [Initial game state - use ScenarioBuilder terms]
+  WHEN [Sequence of player actions]
+  THEN [Observable outcomes]
+  TIMEOUT: [Expected max duration in seconds]
+  PRIORITY: P0/P1
+  CATEGORY: e2e
+  INFRASTRUCTURE: [Required fixtures/builders]
+```
+
+### Example E2E Scenario
+```
+E2E SCENARIO: Complete Combat Encounter
+  GIVEN game loaded with player unit adjacent to enemy
+  AND player unit has full health and actions
+  WHEN player selects unit
+  AND player clicks attack on enemy
+  AND player confirms attack
+  AND attack animation completes
+  AND enemy responds (if alive)
+  THEN enemy health is reduced OR enemy is defeated
+  AND turn state advances appropriately
+  AND UI reflects new state
+  TIMEOUT: 15
+  PRIORITY: P0
+  CATEGORY: e2e
+  INFRASTRUCTURE: ScenarioBuilder, InputSimulator, AsyncAssert
+```
+
 ---
 
 ## Step 4: Prioritize Test Coverage
@@ -161,12 +206,12 @@ SCENARIO: Gameplay Under High Latency
 
 **Knowledge Base Reference**: `knowledge/test-priorities.md`
 
-| Priority | Criteria                     | Coverage Target |
+| Priority | Criteria | Unit | Integration | E2E | Manual |
-| -------- | ---------------------------- | --------------- |
+|----------|----------|------|-------------|-----|--------|
-| P0       | Ship blockers, certification | 100% automated  |
+| P0 | Ship blockers | 100% | 80% | Core flows | Smoke |
-| P1       | Major features, common paths | 80% automated   |
+| P1 | Major features | 90% | 70% | Happy paths | Full |
-| P2       | Secondary features           | 60% automated   |
+| P2 | Secondary | 80% | 50% | - | Targeted |
-| P3       | Edge cases, polish           | Manual only     |
+| P3 | Edge cases | 60% | - | - | As needed |
 
 ### Risk-Based Ordering