bmad-method 6.0.0-alpha.17 → 6.0.0-alpha.19

package/src/modules/bmgd/gametest/knowledge/test-priorities.md

@@ -0,0 +1,271 @@
+# Test Priorities Matrix
+
+## Overview
+
+Not all tests are equal. This guide provides a framework for prioritizing test creation, execution, and maintenance based on risk, impact, and resources.
+
+## Priority Levels
+
+### P0 - Critical (Ship Blockers)
+
+**Definition**: Failures that prevent the game from being playable or shippable.
+
+| Criteria               | Examples                       |
+| ---------------------- | ------------------------------ |
+| Game cannot start      | Crash on launch, infinite load |
+| Core loop broken       | Cannot perform primary action  |
+| Data loss              | Saves corrupted, progress lost |
+| Platform certification | TRC/XR failures                |
+| Legal/compliance       | Rating violations              |
+
+**Testing Approach**:
+
+- Automated smoke tests on every build
+- Manual verification before any release
+- Zero tolerance for P0 bugs in release builds
+
+### P1 - High (Major Features)
+
+**Definition**: Significant functionality that affects most players' experience.
+
+| Criteria              | Examples                         |
+| --------------------- | -------------------------------- |
+| Major features broken | Multiplayer, progression systems |
+| Frequent player paths | Main story, common actions       |
+| Significant UX issues | Confusing UI, missing feedback   |
+| Performance problems  | Unplayable frame rates           |
+
+**Testing Approach**:
+
+- Comprehensive automated tests
+- Regular regression testing
+- Full coverage in release candidates
+
+### P2 - Medium (Standard Features)
+
+**Definition**: Important functionality that affects significant portions of gameplay.
+
+| Criteria           | Examples                      |
+| ------------------ | ----------------------------- |
+| Secondary features | Side quests, optional content |
+| Edge cases         | Unusual player actions        |
+| Platform-specific  | Single-platform issues        |
+| Minor progression  | Non-critical collectibles     |
+
+**Testing Approach**:
+
+- Selective automation
+- Milestone regression testing
+- Coverage prioritized by usage data
+
+### P3 - Low (Polish Items)
+
+**Definition**: Issues that are noticeable but don't significantly impact gameplay.
+
+| Criteria       | Examples                       |
+| -------------- | ------------------------------ |
+| Visual polish  | Minor clipping, texture issues |
+| Audio polish   | Volume inconsistencies         |
+| Rare scenarios | Edge cases with workarounds    |
+| Nice-to-have   | QoL improvements               |
+
+**Testing Approach**:
+
+- Manual exploratory testing
+- Automated only if easy/cheap
+- Fixed as time permits
+
+## Risk-Based Prioritization
+
+### Risk Factors
+
+| Factor              | High Risk           | Low Risk        |
+| ------------------- | ------------------- | --------------- |
+| Usage frequency     | Core loop           | Rarely accessed |
+| Player visibility   | Always visible      | Hidden/optional |
+| Data impact         | Saves, progression  | Cosmetic only   |
+| Recovery difficulty | No workaround       | Easy to retry   |
+| Change frequency    | Frequently modified | Stable code     |
+
+### Risk Assessment Matrix
+
+```
+                    IMPACT
+                Low      High
+            ┌─────────┬─────────┐
+      High  │   P2    │   P0    │
+LIKELIHOOD  ├─────────┼─────────┤
+      Low   │   P3    │   P1    │
+            └─────────┴─────────┘
+```
+
+## Coverage Targets by Priority
+
+| Priority | Unit Test | Integration | E2E/Smoke | Manual      |
+| -------- | --------- | ----------- | --------- | ----------- |
+| P0       | 100%      | 100%        | Required  | Pre-release |
+| P1       | 80%+      | 80%+        | As needed | Milestone   |
+| P2       | 60%+      | Key paths   | Optional  | Sprint      |
+| P3       | Optional  | Optional    | No        | Ad-hoc      |
+
+## Test Type Distribution
+
+### Recommended Test Pyramid (Games)
+
+```
+                    ▲
+                   /│\
+                  / │ \    E2E/Smoke Tests (5%)
+                 /  │  \   - Full game flow
+                /   │   \  - Platform certification
+               ───────────
+              /     │     \
+             /      │      \   Integration Tests (25%)
+            /       │       \  - System interactions
+           /        │        \ - Network, save, audio
+          ─────────────────────
+         /          │          \
+        /           │           \  Unit Tests (70%)
+       /            │            \ - Pure logic
+      /             │             \- Algorithms, calculations
+     ───────────────────────────────
+```
+
+### Game-Specific Considerations
+
+Unlike web apps, games have unique testing needs:
+
+| Test Type   | Standard App   | Game-Specific              |
+| ----------- | -------------- | -------------------------- |
+| Unit        | Business logic | Damage calc, AI decisions  |
+| Integration | API + DB       | Physics, audio, network    |
+| E2E         | User flows     | Gameplay scenarios         |
+| Additional  | N/A            | Playtesting, balance, feel |
+
+## Execution Order
+
+### CI Pipeline (Every Commit)
+
+1. P0 smoke tests (5-10 minutes)
+2. P0/P1 unit tests (10-15 minutes)
+3. P0 integration tests (5-10 minutes)
+
+### Daily/Nightly
+
+1. Full P0 suite
+2. Full P1 suite
+3. P2 regression suite
+4. Performance benchmarks
+
+### Milestone/Release
+
+1. All automated tests
+2. Full P0-P2 manual testing
+3. Platform certification tests
+4. Exploratory testing
+5. Performance profiling
+
+## Bug Triage Criteria
+
+### Priority Assignment
+
+| Question                   | P0   | P1        | P2   | P3   |
+| -------------------------- | ---- | --------- | ---- | ---- |
+| Can player complete game?  | No   | Affected  | No   | No   |
+| How many players affected? | All  | Most      | Some | Few  |
+| Is there a workaround?     | No   | Difficult | Yes  | Easy |
+| Data at risk?              | Yes  | Possible  | No   | No   |
+| Platform certification?    | Fail | Risk      | Pass | Pass |
+
+### Severity vs Priority
+
+```
+SEVERITY: How bad is the bug?
+  Critical → Crash, data loss
+  Major    → Feature broken
+  Minor    → Incorrect behavior
+  Trivial  → Cosmetic
+
+PRIORITY: How soon to fix?
+  P0 → Immediately (blocks release)
+  P1 → This sprint
+  P2 → This milestone
+  P3 → Backlog
+```
+
+## Resource Allocation
+
+### QA Time Distribution
+
+| Activity         | Percentage |
+| ---------------- | ---------- |
+| P0 verification  | 30%        |
+| P1 testing       | 30%        |
+| P2 testing       | 20%        |
+| Exploratory      | 15%        |
+| Test maintenance | 5%         |
+
+### Automation Investment
+
+| Priority | Automation Value | ROI            |
+| -------- | ---------------- | -------------- |
+| P0       | Essential        | Highest        |
+| P1       | High             | High           |
+| P2       | Medium           | Medium         |
+| P3       | Low              | Often negative |
+
+## Platform Priority Matrix
+
+### Multi-Platform Prioritization
+
+| Platform                | Player Base | Certification | Testing Priority  |
+| ----------------------- | ----------- | ------------- | ----------------- |
+| Primary (e.g., PC)      | 60%         | Light         | P0: All, P1: All  |
+| Secondary (e.g., PS5)   | 25%         | Heavy         | P0: All, P1: Most |
+| Tertiary (e.g., Switch) | 15%         | Medium        | P0: All, P1: Core |
+
+### Cross-Platform Testing Strategy
+
+```
+         Platform Testing Coverage
+
+         PC    PS5   Xbox  Switch  Mobile
+P0       ████  ████  ████  ████    ████
+P1       ████  ███░  ███░  ██░░    ██░░
+P2       ███░  ██░░  ██░░  █░░░    █░░░
+P3       ██░░  █░░░  █░░░  ░░░░    ░░░░
+
+████ = Full coverage
+███░ = High coverage
+██░░ = Medium coverage
+█░░░ = Low coverage
+░░░░ = Minimal/none
+```
+
+## Best Practices
+
+### DO
+
+- Reassess priorities as development progresses
+- Weight user-facing features higher
+- Consider platform certification requirements
+- Focus automation on stable, high-value areas
+- Track bug escape rates by priority
+
+### DON'T
+
+- Treat all tests equally
+- Automate P3 before P0/P1 coverage is solid
+- Skip P0 testing for "small changes"
+- Ignore platform-specific requirements
+- Let P1/P2 bugs accumulate
+
+## Metrics to Track
+
+| Metric              | Target        | Purpose              |
+| ------------------- | ------------- | -------------------- |
+| P0 test pass rate   | 100%          | Build quality        |
+| P0 bug escape rate  | 0%            | Test effectiveness   |
+| P1 coverage         | 80%+          | Feature coverage     |
+| Test execution time | < 30 min (CI) | Development velocity |
+| Flaky test rate     | < 1%          | Test reliability     |

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

@@ -0,0 +1,383 @@
+# Unity Test Framework Guide
+
+## Overview
+
+Unity provides a built-in Test Framework based on NUnit for writing and running automated tests. It supports Edit Mode tests (run without playing) and Play Mode tests (run during gameplay simulation).
+
+## Test Framework Setup
+
+### Package Installation
+
+```json
+// manifest.json - usually pre-installed
+{
+  "dependencies": {
+    "com.unity.test-framework": "1.6.0"
+  }
+}
+```
+
+### Project Structure
+
+```
+Assets/
+├── Scripts/
+│   └── Runtime/
+│       ├── Player/
+│       │   └── PlayerController.cs
+│       └── Combat/
+│           └── DamageCalculator.cs
+└── Tests/
+    ├── EditMode/
+    │   └── DamageCalculatorTests.cs
+    └── PlayMode/
+        └── PlayerMovementTests.cs
+```
+
+### Assembly Definitions
+
+Create `.asmdef` files for test assemblies:
+
+```json
+// Tests/EditMode/EditModeTests.asmdef
+{
+  "name": "EditModeTests",
+  "references": ["GameAssembly"],
+  "includePlatforms": ["Editor"],
+  "defineConstraints": ["UNITY_INCLUDE_TESTS"]
+}
+
+// Tests/PlayMode/PlayModeTests.asmdef
+{
+  "name": "PlayModeTests",
+  "references": ["GameAssembly"],
+  "includePlatforms": [],
+  "defineConstraints": ["UNITY_INCLUDE_TESTS"]
+}
+```
+
+## Edit Mode Tests
+
+Edit Mode tests run in the Editor without entering Play Mode. Best for testing pure logic.
+
+### Basic Test Structure
+
+```csharp
+using NUnit.Framework;
+
+[TestFixture]
+public class DamageCalculatorTests
+{
+    private DamageCalculator _calculator;
+
+    [SetUp]
+    public void Setup()
+    {
+        _calculator = new DamageCalculator();
+    }
+
+    [Test]
+    public void Calculate_BaseDamage_ReturnsCorrectValue()
+    {
+        float result = _calculator.Calculate(100f, 1f);
+        Assert.AreEqual(100f, result);
+    }
+
+    [Test]
+    public void Calculate_CriticalHit_DoublesDamage()
+    {
+        float result = _calculator.Calculate(100f, multiplier: 2f);
+        Assert.AreEqual(200f, result);
+    }
+
+    [TestCase(100f, 0.5f, 50f)]
+    [TestCase(100f, 1.5f, 150f)]
+    [TestCase(50f, 2f, 100f)]
+    public void Calculate_Parameterized_ReturnsExpected(
+        float base_, float mult, float expected)
+    {
+        Assert.AreEqual(expected, _calculator.Calculate(base_, mult));
+    }
+}
+```
+
+### Testing ScriptableObjects
+
+```csharp
+[Test]
+public void WeaponStats_DPS_CalculatesCorrectly()
+{
+    var weapon = ScriptableObject.CreateInstance<WeaponStats>();
+    weapon.baseDamage = 10f;
+    weapon.attacksPerSecond = 2f;
+
+    Assert.AreEqual(20f, weapon.DPS);
+
+    // Cleanup
+    Object.DestroyImmediate(weapon);
+}
+```
+
+## Play Mode Tests
+
+Play Mode tests run during gameplay simulation. Required for testing MonoBehaviours, physics, and runtime behavior.
+
+### Basic Play Mode Test
+
+```csharp
+using System.Collections;
+using NUnit.Framework;
+using UnityEngine;
+using UnityEngine.TestTools;
+
+public class PlayerMovementTests
+{
+    private GameObject _player;
+    private PlayerController _controller;
+
+    [SetUp]
+    public void Setup()
+    {
+        _player = new GameObject("Player");
+        _controller = _player.AddComponent<PlayerController>();
+        _player.AddComponent<Rigidbody>();
+        _player.AddComponent<CapsuleCollider>();
+    }
+
+    [TearDown]
+    public void TearDown()
+    {
+        Object.Destroy(_player);
+    }
+
+    [UnityTest]
+    public IEnumerator Move_WhenInputApplied_ChangesPosition()
+    {
+        Vector3 startPos = _player.transform.position;
+
+        _controller.SetInput(Vector2.right);
+
+        yield return new WaitForSeconds(0.5f);
+
+        Assert.Greater(_player.transform.position.x, startPos.x);
+    }
+
+    [UnityTest]
+    public IEnumerator Jump_WhenGrounded_BecomesAirborne()
+    {
+        // Setup ground
+        var ground = GameObject.CreatePrimitive(PrimitiveType.Plane);
+        _player.transform.position = Vector3.up;
+
+        yield return new WaitForFixedUpdate();
+
+        _controller.Jump();
+
+        yield return new WaitForSeconds(0.1f);
+
+        Assert.IsFalse(_controller.IsGrounded);
+
+        Object.Destroy(ground);
+    }
+}
+```
+
+### Testing Coroutines
+
+```csharp
+[UnityTest]
+public IEnumerator Attack_Cooldown_PreventsSpam()
+{
+    _controller.Attack();
+    Assert.IsTrue(_controller.IsAttacking);
+
+    _controller.Attack(); // Should be blocked
+    Assert.AreEqual(1, _controller.AttackCount);
+
+    yield return new WaitForSeconds(_controller.AttackCooldown + 0.1f);
+
+    _controller.Attack();
+    Assert.AreEqual(2, _controller.AttackCount);
+}
+```
+
+### Scene Testing
+
+```csharp
+using UnityEngine.SceneManagement;
+
+[UnityTest]
+public IEnumerator MainMenu_StartButton_LoadsGameScene()
+{
+    SceneManager.LoadScene("MainMenu");
+    yield return null; // Wait for scene load
+
+    var startButton = GameObject.Find("StartButton")
+        .GetComponent<Button>();
+    startButton.onClick.Invoke();
+
+    yield return new WaitForSeconds(1f);
+
+    Assert.AreEqual("GameScene", SceneManager.GetActiveScene().name);
+}
+```
+
+## Integration Test Patterns
+
+### Prefab Testing
+
+```csharp
+[UnityTest]
+public IEnumerator EnemyPrefab_Spawns_WithCorrectComponents()
+{
+    var prefab = Resources.Load<GameObject>("Prefabs/Enemy");
+    var instance = Object.Instantiate(prefab);
+
+    yield return null;
+
+    Assert.IsNotNull(instance.GetComponent<EnemyAI>());
+    Assert.IsNotNull(instance.GetComponent<Health>());
+    Assert.IsNotNull(instance.GetComponent<NavMeshAgent>());
+
+    Object.Destroy(instance);
+}
+```
+
+### Input System Testing
+
+```csharp
+using UnityEngine.InputSystem;
+
+[UnityTest]
+public IEnumerator InputAction_Fire_TriggersWeapon()
+{
+    var keyboard = InputSystem.AddDevice<Keyboard>();
+
+    yield return null;
+
+    Press(keyboard.spaceKey);
+    yield return null;
+
+    Assert.IsTrue(_controller.IsFiring);
+
+    Release(keyboard.spaceKey);
+    yield return null;
+
+    Assert.IsFalse(_controller.IsFiring);
+}
+```
+
+## Test Utilities
+
+### Custom Assertions
+
+```csharp
+public static class GameAssert
+{
+    public static void AreApproximatelyEqual(
+        Vector3 expected, Vector3 actual, float tolerance = 0.001f)
+    {
+        Assert.AreEqual(expected.x, actual.x, tolerance);
+        Assert.AreEqual(expected.y, actual.y, tolerance);
+        Assert.AreEqual(expected.z, actual.z, tolerance);
+    }
+
+    public static void IsWithinRange(float value, float min, float max)
+    {
+        Assert.GreaterOrEqual(value, min);
+        Assert.LessOrEqual(value, max);
+    }
+}
+```
+
+### Test Fixtures
+
+```csharp
+public class TestScene : IDisposable
+{
+    public GameObject Player { get; private set; }
+    public GameObject Ground { get; private set; }
+
+    public TestScene()
+    {
+        Ground = GameObject.CreatePrimitive(PrimitiveType.Plane);
+        Player = Object.Instantiate(Resources.Load<GameObject>("Player"));
+        Player.transform.position = Vector3.up;
+    }
+
+    public void Dispose()
+    {
+        Object.Destroy(Player);
+        Object.Destroy(Ground);
+    }
+}
+
+[UnityTest]
+public IEnumerator Player_FallsToGround()
+{
+    using var scene = new TestScene();
+
+    yield return new WaitForSeconds(1f);
+
+    Assert.Less(scene.Player.transform.position.y, 0.5f);
+}
+```
+
+## CI Integration
+
+### Command Line Execution
+
+```bash
+# Run Edit Mode tests
+Unity -runTests -batchmode -projectPath . \
+  -testPlatform EditMode \
+  -testResults results.xml
+
+# Run Play Mode tests
+Unity -runTests -batchmode -projectPath . \
+  -testPlatform PlayMode \
+  -testResults results.xml
+```
+
+### GitHub Actions
+
+```yaml
+test:
+  runs-on: ubuntu-latest
+  steps:
+    - uses: game-ci/unity-test-runner@v4
+      with:
+        projectPath: .
+        testMode: all
+        artifactsPath: TestResults
+```
+
+## Best Practices
+
+### DO
+
+- Test pure logic in Edit Mode (faster execution)
+- Use Play Mode only when needed (physics, coroutines, MonoBehaviour)
+- Create test fixtures for common setups
+- Clean up created GameObjects in TearDown
+- Use `[Category]` attributes for test organization
+- Run tests before every commit
+
+### DON'T
+
+- Don't test Unity's built-in functionality
+- Don't rely on specific frame timing (use WaitForSeconds)
+- Don't leave test objects in scenes
+- Don't test private methods directly (test through public API)
+- Don't create tests that depend on execution order
+
+## Troubleshooting
+
+### Common Issues
+
+| Issue                  | Cause              | Fix                                        |
+| ---------------------- | ------------------ | ------------------------------------------ |
+| Tests not appearing    | Missing asmdef     | Create test assembly definition            |
+| 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 |