cito

A fast, pytest-compatible test collector and runner, written in Rust.

cito (Latin: "quickly" — the word doctors still write on urgent orders) does for the pytest inner loop what Ruff and uv did for linting and packaging: reimplement the hot path in Rust, treat the existing tool's behavior as a compatibility contract, and win by 10–100×. cito discovers your tests by parsing them with Ruff's parser — in milliseconds — and verifies against real pytest that it finds the same node IDs.

Collecting home-assistant's 81,251 tests: pytest --collect-only -q 16.91 s → cito collect 0.11 s (156×) — producing the identical node IDs.

Pre-1.0 and under active development: collection is differentially tested against 44 real suites (~716k node IDs checked); the runner is a preview. See the FAQ.

Highlights

• ⚡ Up to 156× faster collection. pytest --collect-only takes seconds to minutes on large suites (pytest#5516) before a single test runs; cito pays that tax in milliseconds — see benchmarks.
• 🧾 The same node IDs as pytest, as a contract. ~716k IDs differentially checked across 44 real suites plus randomized fuzzing, enforced on every commit — see compatibility.
• 🔁 Run only what a change can reach. --changed follows the AST import graph, --lf reruns last failures, --watch reruns on save.
• 🔥 Warm workers and a per-project daemon put one-shot runs at ~0.02 s.
• 🧩 Your plugins keep working — pytest executes your tests unchanged; a tested plugin matrix tracks what affects collection.
• 🤖 Built for the agent loop. Coding agents run the suite dozens of times per task, so suite latency is loop latency.
• 🐍 Static and configuration-aware. Discovers pytest.ini, pyproject.toml, tox.ini, and setup.cfg; env-aware collection with --python.
• 📦 A single Rust binary. pip install cito or uv tool install cito, no runtime dependencies.

Installation

cito is published to PyPI as a prebuilt wheel — install it with pip or uv:

$ pip install cito
$ uv tool install cito       # or, in a project: uv add --dev cito

To build the latest from a checkout you need a Rust toolchain; it builds with maturin or plain cargo:

$ uv tool install .          # or: pip install .
$ cargo install --path .     # Rust-toolchain route

The current release is v0.3.0 — see the CHANGELOG for what's new in each release.

Usage

Collecting tests

$ cito collect                    # pytest-convention discovery, in parallel
tests/test_api.py::test_get
tests/test_api.py::TestAuth::test_login[admin]

$ cito collect --count            # just the number
$ cito collect --json             # grouped by file, for tools and agents
$ cito collect -k "http and not slow"        # keyword filter at collection time
$ cito collect --python .venv/bin/python     # env-aware: honors module-level importorskip

Running tests

$ cito run -n 8                   # parallel runner (subprocess workers)
$ cito run -n 8 --warm            # workers stay warm across chunks
$ cito run tests/test_api.py::TestAuth       # node-ID selectors, like pytest
$ cito run -k "http and not slow" # keyword expressions
$ cito run -m "not slow"          # mark expressions, filtered at collection time
$ cito run -x                     # stop at first failure (--maxfail N)
$ cito run --json                 # machine-readable summary for agents/CI
$ cito run -- --cov=mypkg         # pass anything through to pytest; parallel
                                  # coverage fragments are combined for you

Running only what changed

$ cito run --lf                   # only the tests that failed last time
$ cito run --changed              # only tests a change can reach (AST import graph)
$ cito run --watch --warm         # live loop: warm workers survive across saves

--changed runs only the tests a change can actually reach: a test file counts as impacted when it, a conftest above it, the config file, or any project file it transitively imports changed since the last run. Change one core module and exactly the tests that import it (directly or through other project modules) run; touch nothing and cito run --changed runs nothing. Resolution is AST-level and stays inside the project — third-party packages are treated as stable.

The warm daemon

$ cito run --daemon               # hit the per-project warm daemon: one-shot
                                  # runs in ~0.02s (auto-starts; unix)
$ cito daemon status              # start | stop | status

--warm keeps pytest workers alive and runs chunks via pytest.main() in-process, so conftest, fixtures, and plugins keep working; the daemon extends that across CLI invocations. Execution always stays inside real CPython — cito partitions node IDs (whole files together, like xdist --dist loadfile) and hands them to pytest.

Compatibility

pytest's node IDs are the interface, and cito treats them as a contract:

1. A cito ID with a [...] suffix matches a pytest ID exactly.
2. A bare cito ID stands for pytest's parametrized IDs of the same base — cito's declared fallback wherever static analysis cannot be sure. A bare name is always a valid pytest selector for all of its parametrizations.

scripts/diff_collect.py enforces both directions on every commit — against fixture trees, a generated corpus, and randomized differential fuzzing (bench/fuzz_gen.py builds seeded projects mixing nested classes, cross-module inheritance, re-exports, parametrize variants, fixtures, marks, and shadowing; 100 seeds pass locally, three run in CI). Before releases, scripts/validate_repos.py reruns the whole matrix against fresh clones.

Differential results — pytest IDs vs. cito, on a few of the largest and most hostile suites:

Across 44 suites, ~716k node IDs are checked; the vast majority are exact.

Known gaps, tracked honestly:

• doctest collection (--doctest-modules, .txt doctests)
• exact expansion where parametrization is computed at runtime (falls back to bare names by design; ~4% of IDs in heavily-fixtured repos like pandas), including pytest's duplicate-ID suffixes (True0/True1), which always fall back
• pytest_generate_tests-generated extra tests that add new names
• import-time class factories that synthesize tests from data files (jsonschema builds ~7k tests from the JSON-Schema-Test-Suite this way)
• plugin-driven collection hooks and custom collectors (literal collect_ignore / collect_ignore_glob lists in conftest.py ARE supported; computed appends are not), and plugins that redefine collection semantics outright (pytest-relaxed)

Plugins

Plugins run untouched at execution time — cito hands pytest real node IDs and pytest loads your plugins as always. What matters for cito is whether a plugin changes collection; this matrix is the current, tested state:

Benchmarks

Collection, wall time (Apple M4 Max, Python 3.14, warm cache; see BENCHMARKS.md to reproduce, including the execution/runner numbers):

scripts/diff_collect.py computes the collection equivalence on every CI run, so the speed above always comes with the same answers.

Roadmap

cito ships in phases, each gated on differential parity:

1. v0.1 — collection parity + speed — shipped.
2. v0.2 — warm workers — shipped: --warm pools within a run, --watch keeps them across saves, and cito run --daemon keeps them across CLI invocations (workers self-purge modules whose files changed).
3. v0.3 — scheduling & impact analysis — shipped: failed-first ordering, --lf, --json, and AST-level --changed (follows the project import graph, conftest chain, and config).
4. Plugin compatibility matrix — shipped — see Compatibility; each row is backed by a differential-validated repository.
5. Toward 1.0 — freeze the CLI surface and the node-ID contract.

Contributing

Contributions welcome — see CONTRIBUTING.md for setup, the test pyramid, and how to report a collection mismatch (the most valuable bug report for a compatibility tool). The short version:

$ cargo test                                   # unit + fixture-tree integration tests
$ cargo fmt && cargo clippy --release --all-targets
$ uv run --with pytest scripts/diff_collect.py tests/fixtures/basic

CI blocks on Linux, macOS, and Windows plus a pytest node-ID parity job. If you change collection behavior, name the fixture tree or validated repository that covers it — and if none does, add a fixture.

FAQ

How do you pronounce cito? "KEE-toh" — Latin for "quickly," the word doctors still write on prescriptions and orders to mean urgently. Say it however you like.

Is cito a replacement for pytest? No — and that's a non-goal. cito doesn't execute your tests itself, and it adds no new assertion or fixture DSL; pytest does the running. cito makes the inner loop fast — collection, selection, scheduling, warm workers — and hands pytest the exact node IDs to run. Your tests, fixtures, and plugins are the point.

Which Python and pytest versions does it support? Any Python ≥3.9 with your existing pytest; node-ID parity is validated against pytest 8.x and 9.x (a few repos are pinned per their own constraints). Static collection never imports your code; opt-in --python probing uses whatever interpreter you point it at.

Why is it so much faster? Collection never starts a Python interpreter, imports your modules, or loads plugins and conftest — the three costs that dominate pytest --collect-only. cito parses the source with Ruff's parser and resolves pytest's collection semantics statically, in parallel, in Rust.

Is it ready for production? Collection is the mature part: differentially tested against 44 real suites (~716k node IDs) plus randomized fuzzing, with node-ID parity enforced in CI on every commit. The runner is a preview — it drives real pytest subprocesses, so your fixtures, conftest, and plugins run exactly as before, but its CLI is younger. cito is pre-1.0: 0.x minor versions may change behavior where pytest compatibility requires it (patches are fixes only); 1.0 will freeze the CLI and the node-ID contract.

Does it work on Windows, macOS, and Linux? Yes — CI blocks on all three. The warm daemon is unix-only for now; everything else is cross-platform.

Acknowledgements

• Ruff — cito parses every test file with its ruff_python_parser and ruff_python_ast crates, and Ruff (with uv) is the proof that reimplementing a hot path in Rust while keeping the ecosystem's contract is a recipe worth following.
• pytest — the behavior cito treats as a contract and differentially tests against on every commit. cito is a faster front door to pytest, not a fork of it.

License

Licensed under either of Apache License 2.0 or MIT License at your option.