Grid Placement

GridPlacement GDScript 5.1 – Test & Infra Roadmap

Scope: Legacy GridBuilding / GridPlacement 5.0–5.1 GDScript line only (addon + demo tests). Horizon: Next legacy‑support cycle until 6.0 C# is stable and primary, at which point 5.1 becomes a frozen legacy slice (critical fixes + curated tests only). Deeper behavioural evolution and 6.0 features live in the C# line; any future GDScript 6.0 work would be a direct translation of the 6.0 C# APIs, not a 5.1 GDScript → 6.0 GDScript upgrade path.

Goal: reduce heavy infra‑style GdUnit suites while making plugins easier to test via small, focused tests and reusable mocks/harnesses.

Complex behavioural coverage should live in C# Core + harness-based Godot tests; 5.1 GDScript keeps only a thin, curated smoke slice.

Canonical workflow: Core-first tests, optional 5.1 mirrors

This is the default workflow for behavior work going forward:

  1. Implement in 6.0 C# Core first

    • The authoritative behavior lives in pure C# services.
    • Define the contract in Core unit tests (fast, deterministic).
    • Done when: Core unit tests are green.

  2. Only if needed, mirror into 5.1 GDScript (legacy)

    • Translate selected logic into pure RefCounted GDScript helpers.
    • Add small, contract-level GdUnit tests that mirror the Core behavior.
    • Prefer mocks/stubs (simple RefCounted fake classes or mock() in GdUnit) instead of introducing interface-heavy patterns.
    • Avoid large scene-tree integration tests in 5.1 unless the wiring itself is the contract.

  3. Keep 5.1 test surface thin

    • Deep behavior coverage belongs in C# Core tests and C# harness-based Godot tests.
    • 5.1 GDScript tests primarily prove:
      • scripts load,
      • wiring is correct,
      • curated legacy contracts still hold.

Execution note (hang avoidance):

  • Strongly prefer running a specific suite file (or the curated smoke_paths list) rather than a folder/full project.
  • Use: scripts/testing/demo_doctor.sh smoke --path <relative_test_file.gd>
  • Folder/full runs are opt-in and should be used only when needed.

Targeting exception: Do not port 6.0 C# targeting logic into the 5.1 TargetingService2D stack. Targeting in 5.1 remains legacy-stable.

🔴 Critical

  1. Lock in curated 5.1 GdUnit slice

    • Keep only the agreed high‑value suites (targeting, manipulation, placement rules, collision/tilemap) from GDSCRIPT_5_1_TEST_SELECTION.md.
    • Delete all other legacy GdUnit suites from addons/grid_building/test/grid_building (Ported/Replaced/Won’tPort/Removed/extra NotStarted).
    • Ensure curated slice runs cleanly in the demo project.

  2. Single 5.1 test + demo run path

    • Document one command to: (1) run the 5.1 demo, and (2) run the curated GdUnit slice.
    • Add this runbook to docs/5.1/gdscript/ROADMAP.md and reference it from GDSCRIPT_5_1_REMAINING_WORK.md.

  3. Kill legacy heavy test harness patterns

    • Remove remaining env/performance/mega integration suites that rely on old TestEnvironment/scene megasetups.
    • Ensure there are no hidden exclusions (no Compile/Remove tricks or skipped paths hiding failures).
    • When deleting heavy suites, backfill any truly missing coverage with C# Core or C# harness-based tests, not new GDScript megasuites.

🟠 High

  1. Standardize lightweight harnesses for plugins

    • Adopt the new C# IntegrationHarness / MinimalSceneFactory pattern as the default for Godot integration tests.
    • Mirror this idea for 5.1 GDScript where needed: tiny scenes + minimal wiring instead of huge envs.
    • Prefer C# harness-based tests (GridPlacement 6.0) for complex multi-scene scenarios; keep 5.1 GDScript tests as thin wiring smokes over the curated slice.

  2. Introduce reusable mock types for plugin logic

    • Identify key plugin‑level services (placement, targeting, inventory, settings) that should be mockable.
    • Provide simple mock/stub types (or factories) that can be used by both C# and GDScript tests.
    • Document where these mocks live and how plugins are expected to use them.

  3. Clarify 5.1 vs 6.0 behaviour contracts

    • List a small set of intentionally different 5.1 behaviours (where 6.0 is not a drop‑in behavioural spec).
    • For each, either:
      • Add/keep a dedicated 5.1 GdUnit test, or
      • Document a manual demo repro if automation is too heavy.

  4. Add service facade over legacy injector for testability

    • Design a small GDScript service facade that wraps the existing injector / global wiring, mirroring the key 6.0 C# service entry points.
    • Route curated 5.1 GdUnit tests and any new harnesses through this facade instead of raw injector types.
    • Document the facade and its responsibilities so future tests and migration work treat it as the primary integration seam.

  5. Resolve remaining demo scenario test parse errors

    • Fix or retire demo scenario tests so they no longer block a clean editor/test run.
    • Current focus: gigantic_egg_tests.gd (present in demo tree).
    • Note: smithy_placeable_test.gd and platformer_enemy_manipulation_test.gd are currently absent from the demo test tree; do not re-add unless explicitly desired.
    • Align outcomes with the curated 5.1 smoke slice (Tier 1 / Tier 2 only).

  6. Stabilize manipulation state core unit tests

    • Bring manipulation_state_unit_test.gd in line with GOLD_STANDARD_TESTING_PATTERNS: small, focused tests that respect current ManipulationData invariants (non-null manipulators, signal timing, status transitions).
    • Decide which scenarios are Tier 1/Tier 2 and trim or simplify the rest.

  7. Modernize shape collision validation tests

    • Fix shape_collision_validation_tests.gd typed-Dictionary parameter issues so capsule/trapezoid cases reflect the current collision API.
    • Extract domain-specific helpers for shape setup and tile expectations; drop or quarantine low-value parameter combinations.

  8. Refine platformer enemy manipulation demo scenario

    • For platformer_enemy_manipulation_test.gd, either migrate to a small number of gold-standard scenarios (enemy scripts disabled during move, correct indicator counts, valid try_move contracts) or retire remaining heavy cases.
    • Ensure any kept tests align with the curated 5.1 smoke slice and do not rely on brittle deep-environment wiring.

5.1 GDScript Architecture Entry Points for Testing

The only GDScript-level entry points that should matter for tests in 5.1 are:

  • Runtime demo controllers

    • Main demo scenes and their primary controllers (e.g. scripts like gb_control.gd).
    • Complex behaviour (placement rules, targeting, manipulation) is covered by C# Core + harness tests; 5.1 GDScript tests should only prove that these controllers load, wire correctly, and call into the right services.

  • Service wiring and state holders

    • Internal scripts such as gb_internals.gd, gb_placement_persistence.gd, and grid_targeting_state.gd that compose services and state machines.
    • Their detailed behaviour is validated via C# unit tests and C# harness-based integration tests; the curated 5.1 GdUnit slice should exercise them indirectly through normal flows, not with bespoke mega-harnesses.

  • Public 5.1 API surface

    • The small set of scripts/nodes treated as public API in GDSCRIPT_5_1_REMAINING_WORK.md (API surface + migration notes).
    • New tests (C# or GDScript) should target these entry points, not deep internals, keeping the architecture testable and aligned with the 6.0 service model.

This keeps 5.1 GDScript tests focused on wiring and smoke coverage, while C# harness-based tests own deep behavioural and multi-scene integration coverage.

🟡 Medium

  1. Extend curated slice with a small compatibility belt (optional)

    • Add a handful of extra 5.1 tests around high‑risk workflows (e.g., specific placement modes, known regressions).
    • Keep each new test small and focused; avoid new mega‑harnesses.
    • Next 5.1 test cases (next 5)
      1. TC‑5.1‑001 — Placement rule: bounds/OOB guard
        • Scenario: attempt to place a 1x1 at (inside bounds) and (outside bounds) on a minimal TileMap.
        • Done when: in-bounds succeeds; out-of-bounds fails with a deterministic “blocked”/invalid result; no scene-tree megasetup.
        • Implemented: demos/grid_building_dev/godot/addons/grid_building/test/systems/placement/unit/validators/tilemap_bounds_guard_unit_test.gd
      2. TC‑5.1‑002 — Placement rule: blocked tile collision guard
        • Scenario: mark a tile as blocked/occupied, then attempt placement on blocked vs unblocked tiles.
        • Done when: placement is rejected on blocked tiles and accepted on unblocked tiles; test is a small harness (no demo scene dependency).
        • Implemented: demos/grid_building_dev/godot/addons/grid_building/test/systems/placement/unit/validators/blocked_tile_collision_guard_unit_test.gd
      3. TC‑5.1‑003 — Manipulation: move workflow preserves validity
        • Scenario: place a building, enter move/manipulation, move to a valid tile, then confirm.
        • Done when: state transitions are correct (enter/active/confirm), and final placement location matches expected tile coordinates.
      4. TC‑5.1‑004 — Indicators: validation indicators reflect rule outcome
        • Scenario: in a valid placement location indicators are “valid”; in an invalid location indicators switch to “invalid”.
        • Done when: indicator state changes are asserted via a thin adapter seam (prefer data/state over pixel assertions).
      5. TC‑5.1‑005 — Targeting: snap-to-tile-center contract
        • Scenario: pointer/world positions near tile boundaries snap to the expected tile center.
        • Done when: snapping is deterministic across boundary conditions (including negative coords), matching the curated targeting/positioning expectations.
        • Implemented: demos/grid_building_dev/godot/addons/grid_building/test/shared/utils/positioning/snap_to_tile_center_contract_unit_test.gd

  2. Improve “How to test a plugin” docs

    • Add a short guide under docs/5.1/gdscript/5.1 (or reuse existing guides) explaining:
      • When to write Core C# tests vs Godot integration vs GDScript tests.
      • How to use mocks/harnesses instead of env mega‑tests.
    • Done when: docs/5.1/gdscript/GDSCRIPT_5_1_TESTING_GUIDE.md exists and is kept consistent with the curated-slice policy.

  3. Consolidate remaining legacy helpers

    • Any GDScript helpers that only support deleted suites should be removed or folded into smaller, clearer utilities.

🟢 Low

  1. Sample plugin test templates

    • Provide example test files/templates for new plugins (C# core + Godot integration + optional GDScript smoke).

  2. Nice‑to‑have coverage

    • Add small tests for less critical paths (UI polish, logging, diagnostics) only if they stay light.

Milestones

  • Milestone 1 – 5.1 Test Surface Trimmed

    • Curated GdUnit slice defined and green.
    • Heavy legacy infra suites deleted.
    • Single run path for demo + curated tests documented.

  • Milestone 2 – Plugin Testability Foundations

    • Lightweight harness patterns adopted, with C# harness-based tests as the default path for new integration coverage.
    • Core plugin services have reusable mocks.
    • 5.1 vs 6.0 behavioural differences documented and guarded where needed (via either the curated GDScript slice or C# harness tests).

  • Milestone 3 – Developer Experience

    • Plugin authors have clear docs and templates for writing tests.
    • New tests follow the “small, focused, mock‑friendly” pattern by default.