Test Infrastructure & Behavioral Specs

Status: Partially implemented — insta snapshot testing and cargo-fuzz (for jackin-term, scheduled nightly) are in use; a shared jackin-test-support crate, mega-test-file splits, behavioral specs for the capsule daemon and operator console, and proptest/fuzz coverage for parser surfaces all remain open

Shipped facts

Behavioral specs already exist for two components: runtime/launch.rs (published at runtime/launch.rs Behavioral Spec, tracked at Behavioral spec: runtime/launch.rs) and the console op_picker (published at op_picker Behavioral Spec), plus a related but differently-scoped spec for alternate agent credential/config folder sync (Auth Source-Folder Sync). insta is already a dev-dependency in jackin-image, jackin-console, jackin, jackin-runtime, and jackin-capsule, though not yet standardized through a shared harness. cargo-fuzz exists for jackin-term (the damage_grid_process target) and runs nightly via .github/workflows/hygiene.yml; no parser crate has an equivalent target, and proptest is not in the dependency graph at all. crates/jackin/tests/manager_flow.rs (1,528 lines) and crates/jackin/tests/dind_e2e.rs (1,669 lines) remain large, and test helpers (mock runners, config builders, workspace builders) are still duplicated across multiple test files rather than consolidated into a shared crate.

Remaining work

1. Extract a crates/jackin-test-support/ dev-dependency crate consolidating the duplicated mock runners, config/workspace builders, and role-seeding helpers scattered across test files; no such crate exists yet.
2. Split tests/manager_flow.rs and tests/dind_e2e.rs into smaller per-scenario files, after the helper extraction (companion to each source-file split in the codebase readability program).
3. Standardize insta snapshot/golden-file usage through the test-support crate (shared determinism harness: fixed size/theme/clock, redaction).
4. Write a behavioral spec for the capsule daemon (crates/jackin-capsule/src/daemon.rs) — PID 1 contract, single-attach-client invariant, session lifecycle, PTY mutex poison recovery, sessions persistence and reattach.
5. Write a behavioral spec for the operator console TUI state machine (workspace to role to agent selection, instance lifecycle, keybinding dispatch, dialog stack).
6. Add proptest invariant tests and cargo-fuzz targets for parser surfaces: crates/jackin-manifest/src/validate.rs, crates/jackin-env/src/env_resolver.rs, and the migration chains (crates/jackin-config/src/migrations.rs, crates/jackin-manifest/src/migrations.rs); extend the existing nightly fuzz schedule to cover the new targets.

Related work

• Research: Test infrastructure: shared test-support crate, behavioral specs, and parser fuzzing — design rationale, phasing, and open questions for this item
• Visual snapshot testing (CLI & TUI) — SVG golden-artifact format that would build on the shared test-support crate
• Rust CI tooling & dependency hygiene — cargo insta for snapshot tests, cargo-llvm-cov for coverage
• Behavioral spec: runtime/launch.rs — existing spec item this extends to other components
• Codebase map — workspace crate structure the behavioral specs will cover