testdesiderata

Lint Python test files against Kent Beck's 12 Test Desiderata. Static analysis only — no test execution required.

$ testdesiderata tests/

tests/test_payment.py
  14:4  DET001  [Deterministic]  random.choice() produces non-deterministic results
  31:8  ISO003  [Isolated]       open() in tests creates file system dependencies
  52:4  FST001  [Fast]           time.sleep() in tests slows down the suite
  67:4  BHV001  [Behavioral]     MagicMock() substitutes real behavior

4 violations in 1 file

Installation

pip install testdesiderata
pip install "testdesiderata[ai]"   # AI review for Writable/Inspiring desiderata

Usage

testdesiderata tests/                     # lint a directory
testdesiderata --select DET,FST tests/    # only deterministic + fast rules
testdesiderata --ignore BHV tests/        # skip behavioral rules
testdesiderata --ai tests/                # include AI review

Exit code 0 = clean, 1 = violations. Suitable for CI.

Configuration

[tool.testdesiderata]
select = ["DET", "FST", "ISO"]
ignore = ["BHV"]

CLI flags override config. Config is found by walking up from the working directory.

Suppress a single violation inline:

def test_something():
    x = random.randint(1, 10)  # noqa: DET001

# noqa (bare) suppresses everything on the line; # noqa: DET suppresses a whole prefix.

Rules

Full rule reference: docs/rules.md

Python API

from testdesiderata.linter import Linter

linter = Linter()
violations = linter.lint_path(Path("tests/"))
for v in violations:
    print(v)  # tests/test_auth.py:14:4: DET001 [Deterministic] ...

Slow test detection

Pass --junit report.xml (or let the CLI auto-detect) to flag tests exceeding --slow seconds (default 1.0).

MCP server

pip install "testdesiderata[mcp]"
claude mcp add testdesiderata -- python -m testdesiderata.mcp_server