| name | ironclaw-reborn-testing |
| description | Use when adding or reviewing tests for Reborn behavior — choosing a test tier, covering a bug fix, testing model/tool-choice behavior, touching tests/integration or tests/fixtures/llm_traces, or when a test needs Postgres, Docker, or a live LLM. |
Reborn Testing
Pick the tier first; everything else follows. The repo's tier knowledge lives in tests/integration/CLAUDE.md (read it before writing harness tests); this skill is the decision layer plus the traps.
Tier decision tree
- Pure logic, no gated side effect → unit test in the crate (
mod tests / crate tests/).
- A helper gates a side effect (HTTP, DB write, egress body, approval, dispatch) → you also need a caller-path test driving the real entry point (
*_handler, facade method, adapter, coordinator). Helper-only is insufficient — .claude/rules/testing.md has the bug catalog. Gold standard: tests/integration/group_approvals/scenario_gate_then_approve.rs asserts the approved write exists on disk.
- Whole-turn Reborn behavior (submit → runner → loop → reply), deterministic → the in-process scripted-model harness (
tests/integration/, run as cargo test --test reborn_integration_<name>, zero setup, offline). Mock only at the vendor-SDK seam (TraceLlm): the real ironclaw_llm decorator chain (retry/failover/circuit-breaker) must execute. Mocking at the gateway seam skips it — that's the gateway-seam replay tier's job (RebornBinaryE2EHarness / RebornTraceReplayModelGateway), not yours by default.
- Model tool-choice / request-shape is the behavior under test → recorded QA fixtures (
tests/fixtures/llm_traces/reborn_qa/ + tests/reborn_qa_recorded_behavior.rs: ignored live recorder → hermetic contract assertions → hermetic replay). Fixtures must pass scripts/ci/check-reborn-qa-fixtures.sh (secret/PII scrub). Never commit unscrubbed traces.
- Browser-visible →
tests/e2e/ Playwright (reborn_v2_* fixtures for WebChat v2). Live LLM → #[ignore] canary tier; supplemental only, never the PR gate.
Repo-specific traps
- Regression-per-fix is mechanically checked for conventionally marked fix/high-risk changes (commit-msg hook +
regression-test-check.yml). Escape hatch [skip-regression-check] exists — using it on a real fix will be questioned in review.
- Consolidate, don't proliferate: extend the existing test that already drives the path (a case, a scripted turn, an assertion) before standing up a new file. Say why an existing test couldn't absorb a genuinely new scenario.
- Persistence = both backends. PostgreSQL + libSQL parity where production-facing; the model is
ironclaw_hooks' dual-backend shape (crates/loop/ironclaw_hooks/src/postgres_backend/ + crates/loop/ironclaw_hooks/src/libsql_backend/, proved equivalent by crates/loop/ironclaw_hooks/tests/parity_matrix.rs and crates/loop/ironclaw_hooks/tests/multi_host_adversarial.rs). Feature-gate integration tests.
- The backend-integration tier is NOT a PR gate unless the workflow says so (re-verify:
grep -n integration .github/workflows/platform-and-compat.yml): full Postgres coverage may run post-merge or nightly. A green PR does not prove the tier ran; run it locally when your change is DB/runtime-shaped — crate-level, e.g. cargo test -p ironclaw_hooks --features integration,test-support (the workspace-root integration feature is empty; a bare root cargo test --features integration runs nothing extra).
- Never add a silent self-skip to PR-gated tests.
if docker_missing { return } hides the suite from CI. Existing Docker sandbox canaries still need migration; new tests should skip loudly via feature gates or explicit env opt-outs.
- Capability results and terminal errors have their own test shape — recoverable failures must remain model-visible outcomes, while host failures are terminal; test the caller against the capability-access contract and its real redaction/evidence validation.
- A contract doc change needs its test named. The house pattern:
docs/internal/reborn/contracts/conversation-binding.md names its test file + run command; scripts/reborn-e2e-rust.sh is the machine-readable contract→test map. If you implement contract behavior, wire both.
Verify
cargo test -p <crate> → cargo test --test reborn_<harness> (offline) → cargo test -p ironclaw_architecture_tests if edges changed → the owning crate's feature-gated suite (cargo test -p <crate> --features integration) locally for DB-shaped changes → bash scripts/reborn-e2e-rust.sh when touching contract behavior.
Exemplar tests to open and imitate, per tier: references/exemplar-tests.md — the living copies; update as the suite evolves.
