pycoati

Audits Python test suites for mock smells and suspicious tests. Walks a project with tree-sitter, optionally runs pytest for collection, durations, and coverage, and emits a structured inventory: per-file and per-test counts, mock-API smells, and a per-test suspicion score.

Install

# From source (Rust)
cargo install --path .

# Or as a Python package (via maturin)
maturin develop

Usage

pycoati --help

pycoati <PATH>

Audit a project directory or a single .py file. Writes the inventory to stdout as JSON unless --output is given.

# Structured inventory to a file
pycoati . --output inventory.json

# Aligned-column terminal view
pycoati . --format pretty

# Static analysis only, no pytest subprocesses
pycoati . --static-only

Key flags: --format <json|pretty>, --output <PATH>, --tests-dir <PATH>, --static-only, --no-coverage, --top-suspicious <N>, --project-package <NAME>, --python <CMD>, --pytest-args <STR>, --member-cwd <root|member>, --accept-file <PATH>, --no-accept, --include-accepted. See pycoati --help for the full list.

Weights behind suspicion_score are documented in WEIGHTS.md.

Accepted findings

An audit that runs on a schedule keeps re-surfacing the same legitimate tests. Record the review decision once, with a reason, in .pycoati-accept.toml at the project root (a single-file scan walks up from the file to find it):

schema_version = "1"

[[accept]]
test = "tests/test_packaging.py::test_wheel_installs"
signals = ["zero_asserts", "high_setup_ratio"]
reason = "assertions run in a child interpreter; the parent propagates failure via subprocess.run(check=True)"
reviewed = "2026-09-12"
fingerprint = "3f0a1c7d9b2e4a56"   # optional: lapses the entry if the test is edited

reason is required — an entry without one is a parse error. Acceptance is scoped to one test and one named signal (mock_only_assertions, mock_overuse, zero_asserts, high_setup_ratio); there is no wildcard, so a new finding on an accepted test still surfaces.

The accepted test keeps running and keeps counting: pytest arguments are untouched, so suite.test_count, runtime and coverage are unchanged, and every count, smell hit and score stays in the inventory as measured. The only effect is that a test whose every active signal is accepted is held back from top_suspicious.test_functions. The decisions and their reasons are reported under accepted.findings, entries that no longer apply under accepted.stale, and --include-accepted puts everything back on the shortlist for a full report.

Run pycoati guide setup for the full reference.

pycoati guide [PAGE]

Prints the workflow instructions that ship inside the binary, aimed at a coding agent working through an audit. Because the pages are embedded at compile time, they always describe the inventory schema this exact build emits.

# Pick the page from the state of the current directory
pycoati guide

# Or ask for one by name
pycoati guide setup
pycoati guide analyze
pycoati guide remediate

With no argument, the page is chosen from the current directory: analyze when an inventory.json is present there, otherwise setup. remediate is never auto-selected — reach it via the analyze page's breadcrumb or by name.

The subcommand shadows a directory of the same name: if you have a ./guide directory to audit, write pycoati ./guide.

Each page ends with a single next: line, so an agent is always one command away from the right instructions. A --format pretty scan that finds candidates ends with the same breadcrumb; JSON output never carries it.

The page sources are plain markdown under docs/guide/, embedded via include_str!. tests/guide_schema_drift.rs asserts that every field name serde emits is documented on the analyze page, so a schema change cannot land without the guide being updated alongside it.

Development

# Pre-commit checks
cargo fmt --check && cargo clippy --all-targets --all-features -- -D warnings && cargo test --all-features

# Full review (fmt, clippy, tests, audit, deny)
make review

License

MIT