kitaru: Skill for Claude Code

Kitaru Tests, CI, and Release Workflow

Use this when adding, moving, or debugging tests beyond the basic commands and safety rules in tests/AGENTS.md, or when changing CI/release behavior.

Unit and Contract Tests

• Build small typed stubs or SimpleNamespace objects instead of booting unrelated runtime state.
• Assert one behavior or contract at a time.
• Include regression coverage for bug fixes.
• Keep tests independent of working-directory state unless the test creates that state explicitly.
• Avoid shared mutable module-level state and wall-clock ordering assumptions.

V2 has no primed_zenml fixture or test_phase* example suite. Do not copy those v1 patterns into new tests.

CLI Tests

• Install the surface with uv sync --extra cli --extra worker.
• Call src/kitaru/cli/app.py::main with an explicit argument list.
• Assert the returned integer exit code, such as main(["--help"]) == 0; successful calls do not raise SystemExit(0).
• Use capsys and assert stable structured or plain-text contracts.
• Prefer lightweight stubs for remote resources instead of starting the full server.
• Exercise offline help, version, schema, and scaffold commands without reading local configuration.
• Run just cli-artifact-smoke after optional-dependency, entrypoint, or packaging changes.

Keep CLI tests focused on argument parsing, command dispatch, output contracts, and the specific resource interaction under test.

Server and SDK Tests

Follow the four server-resource surfaces in tests/AGENTS.md: service tests, ASGI REST tests, shared repository contracts, and PostgreSQL end-to-end tests. Add SDK round-trip coverage under tests/client/ when a public resource changes.

Use the PostgreSQL-backed tests for transaction, locking, migration, or cross-request behavior that an in-memory fake cannot prove. Run docker compose up -d db before those tests and just migration-check after schema changes.

Task and Worker Tests

• Task subprocess contracts live under tests/task/.
• Worker lifecycle and handler contracts live under tests/worker/.
• Keep subprocess tests bounded and assert structured receipts, exit behavior, and redaction.
• Use the existing worker fakes rather than starting unrelated services.
• When changing dynamic task dependencies or adding a first-party Python distribution, compare the worker's package-age allowlist with every PyPI unit in release/release-units.toml, including non-default packages. Exercise an exact pin under an older exclude-newer cutoff with a candidate or published wheel, and cover the fallback when the installed uv lacks --exclude-newer-package.