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

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

@@ -0,0 +1,376 @@
+# Godot GUT Testing Guide
+
+## Overview
+
+GUT (Godot Unit Test) is the standard unit testing framework for Godot. It provides a full-featured testing framework with assertions, mocking, and CI integration.
+
+## Installation
+
+### Via Asset Library
+
+1. Open AssetLib in Godot
+2. Search for "GUT"
+3. Download and install
+4. Enable the plugin in Project Settings
+
+### Via Git Submodule
+
+```bash
+git submodule add https://github.com/bitwes/Gut.git addons/gut
+```
+
+## Project Structure
+
+```
+project/
+├── addons/
+│   └── gut/
+├── src/
+│   ├── player/
+│   │   └── player.gd
+│   └── combat/
+│       └── damage_calculator.gd
+└── tests/
+    ├── unit/
+    │   └── test_damage_calculator.gd
+    └── integration/
+        └── test_player_combat.gd
+```
+
+## Basic Test Structure
+
+### Simple Test Class
+
+```gdscript
+# tests/unit/test_damage_calculator.gd
+extends GutTest
+
+var calculator: DamageCalculator
+
+func before_each():
+    calculator = DamageCalculator.new()
+
+func after_each():
+    calculator.free()
+
+func test_calculate_base_damage():
+    var result = calculator.calculate(100.0, 1.0)
+    assert_eq(result, 100.0, "Base damage should equal input")
+
+func test_calculate_critical_hit():
+    var result = calculator.calculate(100.0, 2.0)
+    assert_eq(result, 200.0, "Critical hit should double damage")
+
+func test_calculate_with_zero_multiplier():
+    var result = calculator.calculate(100.0, 0.0)
+    assert_eq(result, 0.0, "Zero multiplier should result in zero damage")
+```
+
+### Parameterized Tests
+
+```gdscript
+func test_damage_scenarios():
+    var scenarios = [
+        {"base": 100.0, "mult": 1.0, "expected": 100.0},
+        {"base": 100.0, "mult": 2.0, "expected": 200.0},
+        {"base": 50.0, "mult": 1.5, "expected": 75.0},
+        {"base": 0.0, "mult": 2.0, "expected": 0.0},
+    ]
+
+    for scenario in scenarios:
+        var result = calculator.calculate(scenario.base, scenario.mult)
+        assert_eq(
+            result,
+            scenario.expected,
+            "Base %s * %s should equal %s" % [
+                scenario.base, scenario.mult, scenario.expected
+            ]
+        )
+```
+
+## Testing Nodes
+
+### Scene Testing
+
+```gdscript
+# tests/integration/test_player.gd
+extends GutTest
+
+var player: Player
+var player_scene = preload("res://src/player/player.tscn")
+
+func before_each():
+    player = player_scene.instantiate()
+    add_child(player)
+
+func after_each():
+    player.queue_free()
+
+func test_player_initial_health():
+    assert_eq(player.health, 100, "Player should start with 100 health")
+
+func test_player_takes_damage():
+    player.take_damage(30)
+    assert_eq(player.health, 70, "Health should be reduced by damage")
+
+func test_player_dies_at_zero_health():
+    player.take_damage(100)
+    assert_true(player.is_dead, "Player should be dead at 0 health")
+```
+
+### Testing with Signals
+
+```gdscript
+func test_damage_emits_signal():
+    watch_signals(player)
+
+    player.take_damage(10)
+
+    assert_signal_emitted(player, "health_changed")
+    assert_signal_emit_count(player, "health_changed", 1)
+
+func test_death_emits_signal():
+    watch_signals(player)
+
+    player.take_damage(100)
+
+    assert_signal_emitted(player, "died")
+```
+
+### Testing with Await
+
+```gdscript
+func test_attack_cooldown():
+    player.attack()
+    assert_true(player.is_attacking)
+
+    # Wait for cooldown
+    await get_tree().create_timer(player.attack_cooldown).timeout
+
+    assert_false(player.is_attacking)
+    assert_true(player.can_attack)
+```
+
+## Mocking and Doubles
+
+### Creating Doubles
+
+```gdscript
+func test_enemy_uses_pathfinding():
+    var mock_pathfinding = double(Pathfinding).new()
+    stub(mock_pathfinding, "find_path").to_return([Vector2(0, 0), Vector2(10, 10)])
+
+    var enemy = Enemy.new()
+    enemy.pathfinding = mock_pathfinding
+
+    enemy.move_to(Vector2(10, 10))
+
+    assert_called(mock_pathfinding, "find_path")
+```
+
+### Partial Doubles
+
+```gdscript
+func test_player_inventory():
+    var player_double = partial_double(Player).new()
+    stub(player_double, "save_to_disk").to_do_nothing()
+
+    player_double.add_item("sword")
+
+    assert_eq(player_double.inventory.size(), 1)
+    assert_called(player_double, "save_to_disk")
+```
+
+## Physics Testing
+
+### Testing Collision
+
+```gdscript
+func test_projectile_hits_enemy():
+    var projectile = Projectile.new()
+    var enemy = Enemy.new()
+
+    add_child(projectile)
+    add_child(enemy)
+
+    projectile.global_position = Vector2(0, 0)
+    enemy.global_position = Vector2(100, 0)
+
+    projectile.velocity = Vector2(200, 0)
+
+    # Simulate physics frames
+    for i in range(60):
+        await get_tree().physics_frame
+
+    assert_true(enemy.was_hit, "Enemy should be hit by projectile")
+
+    projectile.queue_free()
+    enemy.queue_free()
+```
+
+### Testing Area2D
+
+```gdscript
+func test_pickup_collected():
+    var pickup = Pickup.new()
+    var player = player_scene.instantiate()
+
+    add_child(pickup)
+    add_child(player)
+
+    pickup.global_position = Vector2(50, 50)
+    player.global_position = Vector2(50, 50)
+
+    # Wait for physics to process overlap
+    await get_tree().physics_frame
+    await get_tree().physics_frame
+
+    assert_true(pickup.is_queued_for_deletion(), "Pickup should be collected")
+
+    player.queue_free()
+```
+
+## Input Testing
+
+### Simulating Input
+
+```gdscript
+func test_jump_on_input():
+    var input_event = InputEventKey.new()
+    input_event.keycode = KEY_SPACE
+    input_event.pressed = true
+
+    Input.parse_input_event(input_event)
+    await get_tree().process_frame
+
+    player._unhandled_input(input_event)
+
+    assert_true(player.is_jumping, "Player should jump on space press")
+```
+
+### Testing Input Actions
+
+```gdscript
+func test_attack_action():
+    # Simulate action press
+    Input.action_press("attack")
+    await get_tree().process_frame
+
+    player._process(0.016)
+
+    assert_true(player.is_attacking)
+
+    Input.action_release("attack")
+```
+
+## Resource Testing
+
+### Testing Custom Resources
+
+```gdscript
+func test_weapon_stats_resource():
+    var weapon = WeaponStats.new()
+    weapon.base_damage = 10.0
+    weapon.attack_speed = 2.0
+
+    assert_eq(weapon.dps, 20.0, "DPS should be damage * speed")
+
+func test_save_load_resource():
+    var original = PlayerData.new()
+    original.level = 5
+    original.gold = 1000
+
+    ResourceSaver.save(original, "user://test_save.tres")
+    var loaded = ResourceLoader.load("user://test_save.tres")
+
+    assert_eq(loaded.level, 5)
+    assert_eq(loaded.gold, 1000)
+
+    DirAccess.remove_absolute("user://test_save.tres")
+```
+
+## GUT Configuration
+
+### gut_config.json
+
+```json
+{
+  "dirs": ["res://tests/"],
+  "include_subdirs": true,
+  "prefix": "test_",
+  "suffix": ".gd",
+  "should_exit": true,
+  "should_exit_on_success": true,
+  "log_level": 1,
+  "junit_xml_file": "results.xml",
+  "font_size": 16
+}
+```
+
+## CI Integration
+
+### Command Line Execution
+
+```bash
+# Run all tests
+godot --headless -s addons/gut/gut_cmdln.gd
+
+# Run specific tests
+godot --headless -s addons/gut/gut_cmdln.gd \
+  -gdir=res://tests/unit \
+  -gprefix=test_
+
+# With JUnit output
+godot --headless -s addons/gut/gut_cmdln.gd \
+  -gjunit_xml_file=results.xml
+```
+
+### GitHub Actions
+
+```yaml
+test:
+  runs-on: ubuntu-latest
+  container:
+    image: barichello/godot-ci:4.2
+  steps:
+    - uses: actions/checkout@v4
+
+    - name: Run Tests
+      run: |
+        godot --headless -s addons/gut/gut_cmdln.gd \
+          -gjunit_xml_file=results.xml
+
+    - name: Publish Results
+      uses: mikepenz/action-junit-report@v4
+      with:
+        report_paths: results.xml
+```
+
+## Best Practices
+
+### DO
+
+- Use `before_each`/`after_each` for setup/teardown
+- Free nodes after tests to prevent leaks
+- Use meaningful assertion messages
+- Group related tests in the same file
+- Use `watch_signals` for signal testing
+- Await physics frames when testing physics
+
+### DON'T
+
+- Don't test Godot's built-in functionality
+- Don't rely on execution order between test files
+- Don't leave orphan nodes
+- Don't use `yield` (use `await` in Godot 4)
+- Don't test private methods directly
+
+## Troubleshooting
+
+| Issue                | Cause              | Fix                                  |
+| -------------------- | ------------------ | ------------------------------------ |
+| Tests not found      | Wrong prefix/path  | Check gut_config.json                |
+| Orphan nodes warning | Missing cleanup    | Add `queue_free()` in `after_each`   |
+| Signal not detected  | Signal not watched | Call `watch_signals()` before action |
+| Physics not working  | Missing frames     | Await `physics_frame`                |
+| Flaky tests          | Timing issues      | Use proper await/signals             |

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

@@ -0,0 +1,315 @@
+# Input Testing Guide
+
+## Overview
+
+Input testing validates that all supported input devices work correctly across platforms. Poor input handling frustrates players instantly—responsive, accurate input is foundational to game feel.
+
+## Input Categories
+
+### Device Types
+
+| Device            | Platforms      | Key Concerns                        |
+| ----------------- | -------------- | ----------------------------------- |
+| Keyboard + Mouse  | PC             | Key conflicts, DPI sensitivity      |
+| Gamepad (Xbox/PS) | PC, Console    | Deadzone, vibration, button prompts |
+| Touch             | Mobile, Switch | Multi-touch, gesture recognition    |
+| Motion Controls   | Switch, VR     | Calibration, drift, fatigue         |
+| Specialty         | Various        | Flight sticks, wheels, fight sticks |
+
+### Input Characteristics
+
+| Characteristic | Description                  | Test Focus                       |
+| -------------- | ---------------------------- | -------------------------------- |
+| Responsiveness | Input-to-action delay        | Should feel instant (< 100ms)    |
+| Accuracy       | Input maps to correct action | No ghost inputs or missed inputs |
+| Consistency    | Same input = same result     | Deterministic behavior           |
+| Accessibility  | Alternative input support    | Remapping, assist options        |
+
+## Test Scenarios
+
+### Keyboard and Mouse
+
+```
+SCENARIO: All Keybinds Functional
+  GIVEN default keyboard bindings
+  WHEN each bound key is pressed
+  THEN corresponding action triggers
+  AND no key conflicts exist
+
+SCENARIO: Key Remapping
+  GIVEN player remaps "Jump" from Space to F
+  WHEN F is pressed
+  THEN jump action triggers
+  AND Space no longer triggers jump
+  AND remapping persists after restart
+
+SCENARIO: Mouse Sensitivity
+  GIVEN sensitivity set to 5 (mid-range)
+  WHEN mouse moves 10cm
+  THEN camera rotation matches expected degrees
+  AND movement feels consistent at different frame rates
+
+SCENARIO: Mouse Button Support
+  GIVEN mouse with 5+ buttons
+  WHEN side buttons are pressed
+  THEN they can be bound to actions
+  AND they function correctly in gameplay
+```
+
+### Gamepad
+
+```
+SCENARIO: Analog Stick Deadzone
+  GIVEN controller with slight stick drift
+  WHEN stick is in neutral position
+  THEN no movement occurs (deadzone filters drift)
+  AND intentional small movements still register
+
+SCENARIO: Trigger Pressure
+  GIVEN analog triggers
+  WHEN trigger is partially pressed
+  THEN partial values are read (e.g., 0.5 for half-press)
+  AND full press reaches 1.0
+
+SCENARIO: Controller Hot-Swap
+  GIVEN game running with keyboard
+  WHEN gamepad is connected
+  THEN input prompts switch to gamepad icons
+  AND gamepad input works immediately
+  AND keyboard still works if used
+
+SCENARIO: Vibration Feedback
+  GIVEN rumble-enabled controller
+  WHEN damage is taken
+  THEN controller vibrates appropriately
+  AND vibration intensity matches damage severity
+```
+
+### Touch Input
+
+```
+SCENARIO: Multi-Touch Accuracy
+  GIVEN virtual joystick and buttons
+  WHEN left thumb on joystick AND right thumb on button
+  THEN both inputs register simultaneously
+  AND no interference between touch points
+
+SCENARIO: Gesture Recognition
+  GIVEN swipe-to-attack mechanic
+  WHEN player swipes right
+  THEN attack direction matches swipe
+  AND swipe is distinguished from tap
+
+SCENARIO: Touch Target Size
+  GIVEN minimum touch target of 44x44 points
+  WHEN buttons are placed
+  THEN all interactive elements meet minimum size
+  AND elements have adequate spacing
+```
+
+## Platform-Specific Testing
+
+### PC
+
+- Multiple keyboard layouts (QWERTY, AZERTY, QWERTZ)
+- Different mouse DPI settings (400-3200+)
+- Multiple monitors (cursor confinement)
+- Background application conflicts
+- Steam Input API integration
+
+### Console
+
+| Platform    | Specific Tests                             |
+| ----------- | ------------------------------------------ |
+| PlayStation | Touchpad, adaptive triggers, haptics       |
+| Xbox        | Impulse triggers, Elite controller paddles |
+| Switch      | Joy-Con detachment, gyro, HD rumble        |
+
+### Mobile
+
+- Different screen sizes and aspect ratios
+- Notch/cutout avoidance
+- External controller support
+- Apple MFi / Android gamepad compatibility
+
+## Automated Test Examples
+
+### Unity
+
+```csharp
+using UnityEngine.InputSystem;
+
+[UnityTest]
+public IEnumerator Movement_WithGamepad_RespondsToStick()
+{
+    var gamepad = InputSystem.AddDevice<Gamepad>();
+
+    yield return null;
+
+    // Simulate stick input
+    Set(gamepad.leftStick, new Vector2(1, 0));
+    yield return new WaitForSeconds(0.1f);
+
+    Assert.Greater(player.transform.position.x, 0f,
+        "Player should move right");
+
+    InputSystem.RemoveDevice(gamepad);
+}
+
+[UnityTest]
+public IEnumerator InputLatency_UnderLoad_StaysAcceptable()
+{
+    float inputTime = Time.realtimeSinceStartup;
+    bool actionTriggered = false;
+
+    player.OnJump += () => {
+        float latency = (Time.realtimeSinceStartup - inputTime) * 1000;
+        Assert.Less(latency, 100f, "Input latency should be under 100ms");
+        actionTriggered = true;
+    };
+
+    var keyboard = InputSystem.AddDevice<Keyboard>();
+    Press(keyboard.spaceKey);
+
+    yield return new WaitForSeconds(0.2f);
+
+    Assert.IsTrue(actionTriggered, "Jump should have triggered");
+}
+
+[Test]
+public void Deadzone_FiltersSmallInputs()
+{
+    var settings = new InputSettings { stickDeadzone = 0.2f };
+
+    // Input below deadzone
+    var filtered = InputProcessor.ApplyDeadzone(new Vector2(0.1f, 0.1f), settings);
+    Assert.AreEqual(Vector2.zero, filtered);
+
+    // Input above deadzone
+    filtered = InputProcessor.ApplyDeadzone(new Vector2(0.5f, 0.5f), settings);
+    Assert.AreNotEqual(Vector2.zero, filtered);
+}
+```
+
+### Unreal
+
+```cpp
+bool FInputTest::RunTest(const FString& Parameters)
+{
+    // Test gamepad input mapping
+    APlayerController* PC = GetWorld()->GetFirstPlayerController();
+
+    // Simulate gamepad stick input
+    FInputKeyParams Params;
+    Params.Key = EKeys::Gamepad_LeftX;
+    Params.Delta = FVector(1.0f, 0, 0);
+    PC->InputKey(Params);
+
+    // Verify movement
+    APawn* Pawn = PC->GetPawn();
+    FVector Velocity = Pawn->GetVelocity();
+
+    TestTrue("Pawn should be moving", Velocity.SizeSquared() > 0);
+
+    return true;
+}
+```
+
+### Godot
+
+```gdscript
+func test_input_action_mapping():
+    # Verify action exists
+    assert_true(InputMap.has_action("jump"))
+
+    # Simulate input
+    var event = InputEventKey.new()
+    event.keycode = KEY_SPACE
+    event.pressed = true
+
+    Input.parse_input_event(event)
+    await get_tree().process_frame
+
+    assert_true(Input.is_action_just_pressed("jump"))
+
+func test_gamepad_deadzone():
+    var input = Vector2(0.15, 0.1)
+    var deadzone = 0.2
+
+    var processed = input_processor.apply_deadzone(input, deadzone)
+
+    assert_eq(processed, Vector2.ZERO, "Small input should be filtered")
+
+func test_controller_hotswap():
+    # Simulate controller connect
+    Input.joy_connection_changed(0, true)
+    await get_tree().process_frame
+
+    var prompt_icon = ui.get_action_prompt("jump")
+
+    assert_true(prompt_icon.texture.resource_path.contains("gamepad"),
+        "Should show gamepad prompts after controller connect")
+```
+
+## Accessibility Testing
+
+### Requirements Checklist
+
+- [ ] Full keyboard navigation (no mouse required)
+- [ ] Remappable controls for all actions
+- [ ] Button hold alternatives to rapid press
+- [ ] Toggle options for hold actions
+- [ ] One-handed control schemes
+- [ ] Colorblind-friendly UI indicators
+- [ ] Screen reader support for menus
+
+### Accessibility Test Scenarios
+
+```
+SCENARIO: Keyboard-Only Navigation
+  GIVEN mouse is disconnected
+  WHEN navigating through all menus
+  THEN all menu items are reachable via keyboard
+  AND focus indicators are clearly visible
+
+SCENARIO: Button Hold Toggle
+  GIVEN "sprint requires hold" is toggled OFF
+  WHEN sprint button is tapped once
+  THEN sprint activates
+  AND sprint stays active until tapped again
+
+SCENARIO: Reduced Button Mashing
+  GIVEN QTE assist mode enabled
+  WHEN QTE sequence appears
+  THEN single press advances sequence
+  AND no rapid input required
+```
+
+## Performance Metrics
+
+| Metric                  | Target          | Maximum Acceptable |
+| ----------------------- | --------------- | ------------------ |
+| Input-to-render latency | < 50ms          | 100ms              |
+| Polling rate match      | 1:1 with device | No input loss      |
+| Deadzone processing     | < 1ms           | 5ms                |
+| Rebind save/load        | < 100ms         | 500ms              |
+
+## Best Practices
+
+### DO
+
+- Test with actual hardware, not just simulated input
+- Support simultaneous keyboard + gamepad
+- Provide sensible default deadzones
+- Show device-appropriate button prompts
+- Allow complete control remapping
+- Test at different frame rates
+
+### DON'T
+
+- Assume controller layout (Xbox vs PlayStation)
+- Hard-code input mappings
+- Ignore analog input precision
+- Skip accessibility considerations
+- Forget about input during loading/cutscenes
+- Neglect testing with worn/drifting controllers