Godot Testing Patterns

Decision Tree → Scripts

Do NOT Load assert-catalog tutorials or manual gameplay checklists into context — pick a row, read the script, implement.

MANDATORY Triggers

• CI / `--headless`: always read headless_test_runner.gd first (OS.exit_code, GdUnit4 CLI: godot --headless -s addons/gdUnit4/bin/GdUnitCmdTool.gd -a res://test).
• State or visual golden files: read snapshot_tester.gd before writing JSON/image goldens. Approve workflow: first run saves reference; intentional UI change → delete or overwrite res://tests/snapshots/<name>.png, re-run to regenerate, commit new golden; never hand-edit PNG bytes.
• Any RPC / MultiplayerSynchronizer test: read mock_network_provider.gd before standing up real peers.

Available Scripts

basic_unit_test.gd

Minimal GdUnit4 (GdUnitTestSuite) structure for pure logic.

signal_emission_test.gd

Signal emission monitoring for decoupled architectures.

mock_dependency_test.gd

Mocks/doubles to isolate external services.

scene_integration_test.gd / integration_test_base.gd

Scene lifecycle + node interaction fixtures.

headless_test_runner.gd

CI headless orchestration and exit codes.

snapshot_tester.gd

Dictionary/UI golden snapshot comparison.

mock_network_provider.gd

Loopback / offline multiplayer peer for RPC tests.

performance_benchmark_runner.gd

Microsecond timers + Performance monitor gates.

memory_leak_detector.gd

Orphan node detection across long suites.

parameter_fuzz_tester.gd

Randomized ranges for edge crashes.

wait_for_frame_test.gd / physics_collision_test.gd

Frame/physics-step async verification.

test_data_factory.gd

Schema-compliant fixture builders.

NEVER Do in Testing (GdUnit4)

• NEVER test private implementation details — Assert public behavior only.
• NEVER share mutable state between tests — Fresh setup per test (before_test / equivalent).
• NEVER use wall-clock `sleep` / blind timers — Prefer frame steppers from wait_for_frame patterns.
• NEVER skip cleanup — Free instantiated nodes after each test.
• NEVER test randomness without seeding.
• NEVER assert signals without the GdUnit signal assert/monitor helpers from signal_emission_test.gd.
• NEVER mix GUT and GdUnit4 APIs in one suite.
• NEVER rely on editor-only features for CI — Headless-compatible tests only.
• NEVER default to full-level integration tests — Prefer unit + small scene tests; escalate only when the decision tree says so.
• NEVER hardcode brittle absolute file paths in fixtures.
• NEVER test third-party plugin internals — Test your integration only.

Expert Gates (short)

• Snapshot: serialize → compare golden (snapshot_tester.gd); regenerate reference PNG on approved visual changes.
• CI: --headless + OS.exit_code non-zero on failure (headless_test_runner.gd).
• Network: mock peer before real ENet (mock_network_provider.gd).
• Perf: Performance monitors / draw-call caps in benchmark runner.

Deep recipes (on demand)

LLM-ignorance rule: if a general agent would not know it before reading, it lives here or in scripts/ — never delete, only move.

Reference

Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Command line tutorial — --headless, -s, and exit-code patterns for CI test runners.
• Overview of debugging tools — debugger, profiler, and remote inspect when a failing test needs engine-side diagnosis.
• Custom performance monitors — Performance monitors and custom metrics for benchmark gates and orphan detection.
• Idle and physics processing — frame/_physics_process timing that wait_frames / yield helpers must respect.
• Using SceneTree — tree lifecycle, quit(), and process modes used by headless orchestrators.
• Nodes and scene instances — instantiate/add_child/free hygiene for scene integration tests.
• Instancing with signals — signal wiring patterns that signal-emission tests verify.
• High-level multiplayer — RPC/peer APIs mocked via OfflineMultiplayerPeer or latency simulators.
• Using InputEvent — synthetic InputEvent* injection for fuzz and UI interaction tests.
• Random number generation — seeding for deterministic fuzz and Monte Carlo harnesses.
• Saving games — serialize/deserialize patterns behind golden JSON and save/load integration tests.