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 [headlesstestrunner.gd](scripts/headlesstestrunner.gd) first (OS.exit_code, GdUnit4 CLI: godot --headless -s addons/gdUnit4/bin/GdUnitCmdTool.gd -a res://test).
• State or visual golden files: read [snapshottester.gd](scripts/snapshottester.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 [mocknetworkprovider.gd](scripts/mocknetworkprovider.gd) before standing up real peers.

Available Scripts

[basicunittest.gd](scripts/basicunittest.gd)

Minimal GdUnit4 (GdUnitTestSuite) structure for pure logic.

[signalemissiontest.gd](scripts/signalemissiontest.gd)

Signal emission monitoring for decoupled architectures.

[mockdependencytest.gd](scripts/mockdependencytest.gd)

Mocks/doubles to isolate external services.

[sceneintegrationtest.gd](scripts/sceneintegrationtest.gd) / [integrationtestbase.gd](scripts/integrationtestbase.gd)

Scene lifecycle + node interaction fixtures.

[headlesstestrunner.gd](scripts/headlesstestrunner.gd)

CI headless orchestration and exit codes.

[snapshottester.gd](scripts/snapshottester.gd)

Dictionary/UI golden snapshot comparison.

[mocknetworkprovider.gd](scripts/mocknetworkprovider.gd)

Loopback / offline multiplayer peer for RPC tests.

[performancebenchmarkrunner.gd](scripts/performancebenchmarkrunner.gd)

Microsecond timers + Performance monitor gates.

[memoryleakdetector.gd](scripts/memoryleakdetector.gd)

Orphan node detection across long suites.

[parameterfuzztester.gd](scripts/parameterfuzztester.gd)

Randomized ranges for edge crashes.

[waitforframetest.gd](scripts/waitforframetest.gd) / [physicscollisiontest.gd](scripts/physicscollisiontest.gd)

Frame/physics-step async verification.

[testdatafactory.gd](scripts/testdatafactory.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 waitforframe 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 [signalemissiontest.gd](scripts/signalemissiontest.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 ([snapshottester.gd](scripts/snapshottester.gd)); regenerate reference PNG on approved visual changes.
• CI: --headless + OS.exitcode non-zero on failure ([headlesstestrunner.gd](scripts/headlesstest_runner.gd)).
• Network: mock peer before real ENet (mocknetworkprovider.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/physicsprocess timing that waitframes / yield helpers must respect.
• Using SceneTree — tree lifecycle, quit(), and process modes used by headless orchestrators.
• Nodes and scene instances — instantiate/addchild/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.
• Physics introduction — layers/masks and step timing for collision integration tests.

Related Skills

Prerequisites

• godot-project-foundations — project layout, scenes, and resources before standing up a res://test/ suite.
• godot-gdscript-mastery — typed GDScript, await, and assert idioms used in every unit/integration test.
• godot-signal-architecture — emit/connect contracts that watch_signals / signal monitors assert against.

Complements

• godot-debugging-profiling — profiler and ObjectDB tools when a red test needs runtime evidence, not another assert.
• godot-scene-management — scene packing/load patterns mirrored in scene integration fixtures.
• godot-input-handling — action maps and event parsing exercised by fuzz and UI press tests.
• godot-2d-physics — layer matrices and body APIs that physics collision tests must keep green.
• godot-resource-data-patterns — Resource schemas that test data factories and snapshot dictionaries serialize.
• godot-save-load-systems — persistence pipelines covered by save/load integration and golden-state tests.

Downstream / consumers

• godot-monte-carlo-balancer — seeded headless gameplay sims that reuse these harnesses for Phase 7 golden cells.
• godot-performance-optimization — budgets that CI performance gates (Performance monitors, draw-call caps) enforce.
• godot-multiplayer-networking — RPC/replication logic validated through mock peers and lag injection.
• godot-export-builds — headless export/CI pipelines that invoke the same --headless test entrypoints.

Master

• godot-master — library router and mirrored module entry for cross-skill discovery.