Testing

Use the pinned environment and test the boundary your change affects. Taskfile.yml owns the commands; task --list shows the current inventory.

Command layers

Intent	Command
Prepare dependencies	task setup
Repair one behavior	task verify-one -- '<file-or-node>' -vv
Lint, typecheck, and check dependencies	task check
Run hermetic pytest suites	task verify
Test an installed release wheel	task verify-packaged
Complete a change or promotion proof	task ship

Use uv run or the owning task for all Python commands. A focused rerun helps repair a failure; it does not replace the final fresh gate.

Where checks live

tests/ owns deterministic harness and TUI coverage, with fake backends and temporary state. scripts/ owns live, smoke, and probe programs. A hermetic test of a script does not prove its live boundary.

slow marks machine, rendering, PTY, or performance-sensitive checks; live requires an endpoint, network, or external process. Run these through task test-slow and task test-live when relevant.

Promotion proof

task ship runs code checks, hermetic suites, the serving-container and packaged-wheel proofs, and documentation/code audits. After those pass, it runs the dry live-drive stage. Its evidence names the source revision, results, and diagnostic logs. Local proof owns promotion; there is no hosted CI gate.

Calling-environment and resource constraints

Run the gate with loopback-socket permission. Sandbox denials can look like unrelated 60-second aiohttp or WebSocket timeouts. PTY checks likewise need openpty/pty.fork permission; out of pty devices can mean a sandbox denial.

On constrained machines, set KIN_TEST_WORKERS=4 task verify to reduce the main lane’s default ceiling of eight workers.

Isolation contracts

Use shared fixtures in tests/conftest.py for the fake backend, Session, Textual pilot, temporary Kin home, and session directory. tests/__init__.py isolates settings before product imports; avoid module-level environment changes. Never clear KIN_HOME inside a test using temp_kin_home, which would redirect writes to the person’s real home.

SDK imports stay lazy. task test-cov provides visibility without a numeric promotion threshold.

Baselines and source-owned visuals

Regenerate intentional changes through their owners:

task verify-evals -- --update-baseline
task verify-snapshot -- --update
task docs-screenshots-tui

Review each changed artifact before accepting it. Kin owns technical screenshots; this site owns the published manual’s reviewed copies.

Live and publication gates

Run the live gate for a changed live boundary. Record the command, exact source or deployment identity, result, and limits. Keep credentials, raw traces, prompts, and private workspace content out of committed evidence.

KIN_LIVE_GIT_PUBLISH=1 task live-git-tools mutates disposable remote branches and a draft PR. It needs separate operator authority and is outside ship.

Performance-shape telemetry (the bench lane)

The bench measures cache use, token trajectory, compaction, latency, and injected context using synthetic workloads derived from aggregate shapes. It does not replay private conversation content. Continuous quantities and repeat reliability are reported; deterministic protocol failures are graded.

Start with task live-bench-dry; use task live-bench-all -- --passk 3 for a real sampling run. The ignored compare target is local. task live-soak repeats the existing runners under time and attempt limits; the environment owns its availability. These lanes are outside verify and ship.

The maintainer testing guide owns workload contracts, sampling, soak recovery, and evidence retention.

External outcome compatibility (Harbor / Terminal-Bench)

task harbor-compat-dry inspects the pinned external task. The live lane requires a clean pushed Kin revision, a passing Oracle control, and the container boundary before testing Kin. task harbor-compat-panel samples a small frozen task panel; it is comparative evidence, not a representative score or a replacement for Kin’s invariants.

Dataset identity, installation, sampling, interruption recovery, and private artifact handling are documented in the owning guide.

Deterministic failure injection

Inject failures where their outcome can be checked: interrupted tool dispatch, partial model streams, failed compaction, child-process timeouts, truncated output, and unsafe restore targets. The owning guide maps these cases to focused tests. Add a case when it proves a distinct contract.

Verify the world, not the self-report

Read the resulting file, journal, process state, or exit status independently. Check both the intended change and protected state that must survive. A model’s claim that it succeeded is not evidence. Demonstrate that a new guard fails on the defect it is meant to catch.

Adding a test

Choose the narrowest real seam and reuse existing fixtures. Mark live or slow only when the boundary requires it. Run the focused node and task check, review any intentional baseline update, and finish with one fresh task ship.