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.
Rules
| Prefix | Desideratum | What it catches |
|---|---|---|
DET |
Deterministic | random, datetime.now, uuid4, os.urandom, numpy.random |
ISO |
Isolated | global, env mutation, file I/O, network, DB connections, tempfile, shutil, subprocess |
FST |
Fast | time.sleep, polling loops |
AUT |
Automated | input(), breakpoint(), pdb.set_trace() |
BHV |
Behavioral | Mock/MagicMock, @patch, mocker.spy, autospec=False |
STR |
Structure-insensitive | .assert_called_with() and related mock methods |
SPC |
Specific | bare/broad except, compound assert without message, raises(Exception) |
PRD |
Predictive | pytest.skip, @mark.skip, @mark.xfail without strict=True |
CMP |
Composable | >10 assertions or >50 lines per test |
RDL |
Readable | non-descriptive names, long tests without docstrings |
WRT |
Writable | boilerplate cost, maintenance burden (requires --ai) |
INS |
Inspiring | weak assertions, missing edge cases (requires --ai) |
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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
testdesiderata-0.1.1.tar.gz
(187.6 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file testdesiderata-0.1.1.tar.gz.
File metadata
- Download URL: testdesiderata-0.1.1.tar.gz
- Upload date:
- Size: 187.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
173d72fa15bc4e82ad3a0f1cc504989843599582130cc3b4fbfd7ed2f612e1f9
|
|
| MD5 |
7e4873893fb4bcd4c3899b13e30687ee
|
|
| BLAKE2b-256 |
72dfc969ad22052dcd04701243617f0d4eae782b10a79fc012e5d6e84251a101
|
Provenance
The following attestation bundles were made for testdesiderata-0.1.1.tar.gz:
Publisher:
ci.yml on benomahony/testdesiderata
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
testdesiderata-0.1.1.tar.gz -
Subject digest:
173d72fa15bc4e82ad3a0f1cc504989843599582130cc3b4fbfd7ed2f612e1f9 - Sigstore transparency entry: 2781138581
- Sigstore integration time:
-
Permalink:
benomahony/testdesiderata@2ba3b0f8dff00b797d235aff782cf43addb0940a -
Branch / Tag:
refs/heads/main - Owner: https://github.com/benomahony
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
ci.yml@2ba3b0f8dff00b797d235aff782cf43addb0940a -
Trigger Event:
push
-
Statement type:
File details
Details for the file testdesiderata-0.1.1-py3-none-any.whl.
File metadata
- Download URL: testdesiderata-0.1.1-py3-none-any.whl
- Upload date:
- Size: 23.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
9332fa3ab84da41b57c51abee95394749c17d2c9dcdca9438188b62fc86de42c
|
|
| MD5 |
f5d8ef1a35979531fa56f80b5eb337f2
|
|
| BLAKE2b-256 |
17bb4e269ef2b3277257e532b1c1c1708db9f4dba41fde4ed9e9ffefd6c939c4
|
Provenance
The following attestation bundles were made for testdesiderata-0.1.1-py3-none-any.whl:
Publisher:
ci.yml on benomahony/testdesiderata
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
testdesiderata-0.1.1-py3-none-any.whl -
Subject digest:
9332fa3ab84da41b57c51abee95394749c17d2c9dcdca9438188b62fc86de42c - Sigstore transparency entry: 2781139239
- Sigstore integration time:
-
Permalink:
benomahony/testdesiderata@2ba3b0f8dff00b797d235aff782cf43addb0940a -
Branch / Tag:
refs/heads/main - Owner: https://github.com/benomahony
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
ci.yml@2ba3b0f8dff00b797d235aff782cf43addb0940a -
Trigger Event:
push
-
Statement type:
