Skip to content

Set up gdUnit4 unit testing framework #73

@aebrer

Description

@aebrer

Deep Yellow currently has no automated unit tests. Integrating gdUnit4 will provide a standard Godot testing framework, enable regression catching, and make it safer to refactor core systems like the grid, action layer, and state machine.

Current Behavior

  • No test directory or test runner exists.
  • Core logic (grid coordinate conversion, action validation, state transitions) is only verified through manual gameplay.
  • No CI step validates that the project loads without script errors beyond basic --headless --quit.

Proposed Behavior

  • Add gdUnit4 as an addon (via addons/gdUnit4/) or git submodule.
  • Establish a tests/ directory with a clear structure mirroring scripts/.
  • Create initial test suites for the most testable, high-value systems.
  • Document how to run tests locally (CLI + Godot editor).

Acceptance Criteria

  • gdUnit4 is integrated and loads without errors in the project.
  • tests/ directory exists with a structure matching scripts/ (e.g., tests/actions/, tests/player/, tests/procedural/).
  • At least one passing test suite exists for grid_3d.gd (e.g., grid_to_world / world_to_grid round-trip, is_floor_tile / is_wall_tile logic).
  • At least one passing test suite exists for the action layer (e.g., MovementAction.can_execute returns false for walls, WaitAction costs 1 turn).
  • At least one passing test suite exists for the input state machine (e.g., valid state transitions, unknown state names are handled gracefully).
  • README.md or docs/ is updated with instructions on running tests via the Godot editor and headless CLI.
  • A headless test run command is verified to work (e.g., godot --headless -s addons/gdUnit4/bin/GdUnitCmdTool.gd or equivalent).

Context

  • gdUnit4 repository
  • The project uses Godot 4.6 with a custom Tracy-enabled build — verify gdUnit4 compatibility with 4.6.

Technical Notes

  • gdUnit4 can be installed via the Asset Library, git submodule, or manual download into addons/. Prefer the method that's easiest to reproduce across dev machines and CI.
  • grid_3d.gd has pure functions like grid_to_world, world_to_grid, is_floor_tile, and is_wall_tile that are ideal first test targets.
  • The action layer (scripts/actions/action.gd and subclasses) uses the Command Pattern with can_execute() and execute() — these can be tested with mock player objects.
  • input_state_machine.gd manages state registration and transitions — tests should verify signal connections and invalid-state handling.
  • Avoid testing visual/renderering logic or animation timing in unit tests; focus on deterministic game logic.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions