Capsule: testing

Use when writing/debugging tests, changing CI/hooks, or choosing focused verification.

Read first

• docs/design/testing.md §9 — self-play harness (only if touching scripted self-play)
• docs/design/testing.md §10 — dev scenario inspection
• docs/design/testing.md §11 — test selection policy
• docs/design/testing.md §12 — PR CI contract
• docs/design/testing.md §13 — doc drift sweeper

Suites

• node tests/server_integration.mjs — dep-free full server pipeline; needs a running server.
• node tests/regression.mjs — dep-free hardening/DoS/robustness guards; needs a running server.
• node tests/ai_integration.mjs — dep-free AI opponent lobby flow; needs a running server.
• node tests/minimap_input_contracts.mjs — dep-free minimap/router pointer-lock contracts.
• tests/run-all.sh --no-rust — live Node suites plus browser smoke with shared dependencies.
• tests/run-all.sh --with-tri-state-browser --no-rust — opt into latency-sensitive tri-state browser scenarios locally; CI includes them automatically.
• tests/run-all.sh --only-rust — architecture policy plus Rust format, nextest, and lint only.
• tests/run-all.sh --only-live-node — JS contracts plus live Node API suites only.
• tests/run-all.sh --only-browser — browser smoke plus configured tri-state browser suites only.
• cargo nextest run --config-file .config/nextest.toml --manifest-path server/Cargo.toml --profile default — simulation behavior plus fast scripted self-play; no running server needed.
• RTS_FULL_AI_TESTS=1 cargo nextest run --config-file .config/nextest.toml --manifest-path server/Cargo.toml --profile default — long AI self-play/simulation coverage.
• tests/run-all.sh --full-ai — full orchestrator plus long AI self-play/simulation coverage.
• node tests/select-suites.mjs --from=<base-ref> — list expected suites for changed files.
• node scripts/check-docs-health.mjs — docs map, capsule size, and local Markdown link hygiene.
• node scripts/check-wiki.mjs — wiki route hardening, local links, generated stats, and faction catalog parity.
• Render perf: node scripts/client-perf-harness.mjs --render-lag-suite --seconds 10; add --stress-matrix.
• node scripts/check-crate-boundaries.mjs — enforce crate dependency direction.
• cargo run --manifest-path server/Cargo.toml -p rts-archcheck -- check-sim-architecture — enforce rts-sim::game internal architecture ratchets.

Invariants

• The required PR gate is the aggregate ./tests/run-all.sh check from the Main test gate workflow. Split CI jobs cover server binary build, Rust/architecture, live Node, browser, and tri-state coverage; docs-only changes skip expensive lanes but still run docs health.
• tests/run-all.sh uses nextest for Rust tests and prints timing summaries. Missing nextest is a local gate failure with an install hint.
• Live Node suites need a running server. Use tests/run-all.sh to boot a private one, or start cd server && cargo run first for individual Node suites.
• Installed hooks run staged whitespace checks, excluding the human-owned playtest_notes.md, plus node scripts/check-docs-health.mjs before commits and merges. They do not run tests/run-all.sh; GitHub Actions owns the full-suite gate.
• Browser smoke dependencies are shared across worktrees under ${RTS_NODE_DEPS_CACHE_DIR:-/tmp/rts-node-deps} and keyed by tests/package-lock.json.
• Local tests/run-all.sh uses per-worktree Cargo target dirs under /tmp/rts-cargo-target/. Override with CARGO_TARGET_DIR only when a task needs a specific target location.
• A suite can be skipped only when tests/select-suites.mjs maps the changed files away from that behavior.

Self-play failure protocol

If a self-play test fails and the cause is not obvious, start a fresh server on its own port and use macOS open to load the replay artifact:

open "http://localhost:<port>/dev/replay-artifact?replay=<artifact_name>"

Do not use the Browser skill for this flow.

Dev scenarios

Game-backed dev scenarios are live, no-fog watcher rooms for inspecting authored simulation situations through the normal Pixi client. Start a local server, then open:

open "http://localhost:<port>/dev/scenarios"

The scenario index owns the current URL shapes and ids. Scenario setup remains server-side under server/crates/sim/src/game/setup/dev_scenarios.rs; do not expose arbitrary spawning or map editing through client commands.

Cross-capsule triggers

• Touching client rendering, input, HUD, or lobby tests → client-ui.md.
• Touching message shapes or snapshot/event fields → protocol.md.
• Touching sim behavior, AI, pathing, combat, or dev-scenario setup → server-sim.md.
• Touching deployment, hooks, or CI recovery guidance → deployment.md and docs/pr-first-workflow.md.