Running Tests (Optional)

The Grid Building plugin includes a comprehensive test suite for developers who want to validate functionality or contribute to development.

Test Coverage

Minimal Godot Harness (6.0)

• Purpose: exercise Godot adapters with a tiny scene (PlacementSystem, GridTargetingSystem, IndicatorRoot) while all logic lives in core services.
• Files: gdscript/tests/base/integration_harness.gd, gdscript/tests/helpers/minimal_scene_factory.gd, gdscript/tests/helpers/service_fakes.gd, gdscript/tests/helpers/assertions.gd.
• Rules:
  • Required nodes: PlacementSystem, GridTargetingSystem, IndicatorRoot (asserted by the harness).
  • Inject fakes/stubs for services; adapters must only wrap/forward (no business logic in nodes).
  • Keep tests minimal: cover adapter wiring (valid/invalid placement, indicator updates, targeting snap); rely on core tests for logic.
  • No injector/world/demo scenes or composition containers.
• Usage: build a minimal scene via MinimalSceneFactory, register services with the harness, run simulate_frames, assert via helper fakes/assertions.
• Out-of-scope: physics stress, camera UX, demo asset wiring (add targeted suites separately).

Accessing the Test Suite

Prerequisites

Running Tests via GUI

1. Extract the .tar export containing the plugin and tests
2. Open the project in Godot 4.5
3. Install and enable the GdUnit4 plugin (available from Godot Asset Library)
4. Open the GdUnit4 panel (usually docked at bottom of editor)
5. Navigate to res://test/ to see all test suites
6. Click “Run All” to execute the complete test suite

Running Tests via Command Line

For automated testing or CI:

1
2
3
4
5
6
7
8

# Run all tests
./scripts/testing/run_tests.sh

# Run specific test file
./scripts/testing/run_tests.sh --individual test/systems/manipulation/unit/managers/demolish_manager_unit_test.gd

# Show only failures
./scripts/testing/run_tests.sh --failures-only

Test Organization

Tests are organized by domain, mirroring the runtime addon systems/<domain>/ layout:

• test/systems/<domain>/unit/ - Unit tests for a domain
• test/systems/<domain>/integration/ - Workflow/integration tests for a domain

Optional (use sparingly):

• test/systems/<domain>/regressions/
• test/systems/<domain>/quarantine/

Legacy 5.1 GDScript Tests & Preload Policy

• Scope: GridBuilding 5.1 GDScript plugin tests and early GridPlacement GDScript ports.
• Policy: Test scripts must not use preload("uid://...") directly; instead they preload by res:// paths.
• Centralization:
  • Shared test scenes/resources live in GBTestConstants.
  • Shared test components/managers/helpers live in GBTestPreloads.
• Canonical locations:
  • GridBuilding GDScript tests: plugins/gameplay/GridPlacement/gdscript/grid_building/test/grid_building/helpers/GBTestConstants.gd and GBTestPreloads.gd.
  • GridPlacement GDScript tests: plugins/gameplay/GridPlacement/gdscript/grid_placement/test/grid_building/helpers/GBTestConstants.gd and GBTestPreloads.gd.
• Demo projects: Do not edit the demo addon copies under demos/grid_building_dev/godot/addons/grid_building. Make changes in the canonical plugin folder first, then export/sync to the demo.

For Contributors

If you’re contributing to plugin development, please run the test suite before submitting changes to ensure all existing functionality remains intact.

Legacy vs C# Harnesses

• The GDScript IntegrationHarness + MinimalSceneFactory pattern remains valid for existing GdUnit suites.
• New harness design and per-service DI helpers live in C# GoDotTest:
  • See plugins/gameplay/GridPlacement/Tests/Godot/Main/PlacementHarnesses.cs for the canonical C# harness helpers.
• When adding new integration/smoke tests for GridPlacement:
  • Prefer C# GoDotTest + the shared C# harnesses.
  • Treat new GDScript-based harness patterns as legacy-only and avoid expanding them.