Static analyzer for test design quality. Verifies that tests function as executable specifications -- fast, language-agnostic, zero LLM cost.

Public beta (v0.1.2). Dogfooded across 13 projects / 4 languages / ~45,000 tests. Not production-ready -- rule IDs, severity levels, and config format may change.

exspec checks whether your tests are well-designed specifications, not just code that runs. It enforces 4 properties: What not How, Living Documentation, Compositional, Single Source of Truth. See docs/philosophy.md for the full rationale.

Validated against 13 real-world OSS projects (~45,000 tests across Python, TypeScript, PHP, Rust). See Validation below.

cargo install exspec

Or install from source:

cargo install --git https://github.com/morodomi/exspec.git

exspec .                              # Analyze current directory
exspec init --lang python,typescript  # Generate .exspec.toml
exspec --lang python .                # Analyze specific language
exspec --strict .                     # WARN also fails

Example output:

exspec v0.1.2 -- 8 test files, 10 test functions
BLOCK tests/test_example.py:5 T001 assertion-free: test has no assertions
WARN  tests/test_example.py:20 T002 mock-overuse: 6 mocks (6 classes), threshold: 5 mocks / 3 classes
Score: BLOCK 1 | WARN 1 | INFO 0 | PASS 8

Each language has specific detection patterns and known gaps. See docs/languages/ for details.

17 rules across 2 tiers. Tier 1 catches structural issues (assertion-free tests, mock overuse, giant tests). Tier 2 catches design smells (implementation coupling, fixture sprawl, undescriptive names).

See docs/SPEC.md for the full rule reference.

Start with Tier 1 only. Disable Tier 2 until your codebase is clean:

# .exspec.toml
[rules]
disable = ["T101", "T102", "T103", "T105", "T106", "T107", "T108", "T109", "T110"]

Once Tier 1 passes, enable Tier 2 rules one at a time. Use inline suppression for known exceptions:

# exspec-ignore: T002
def test_complex_integration():
    ...

For projects with custom assertion helpers, add them to avoid T001 false positives:

[assertions]
custom_patterns = ["assertJsonStructure", "self.assertValid"]

Two independent mechanisms control what you see:

• [rules.severity] changes how a rule is evaluated. T107 = "off" disables the rule entirely; T101 = "info" downgrades it from WARN to INFO.
• --min-severity controls display filtering. --min-severity warn hides INFO diagnostics from the output but does not change evaluation or exit codes.

# .exspec.toml
[rules.severity]
T107 = "off"      # disable T107 entirely
T101 = "info"     # downgrade T101 to informational

[output]
min_severity = "warn"  # hide INFO in terminal/JSON output

exspec --min-severity warn .   # CLI equivalent of [output] min_severity

- run: cargo install exspec
- run: exspec .

exspec exits 1 on BLOCK violations, 0 otherwise. Use --strict to also fail on WARN. SARIF output is available for GitHub Code Scanning. See docs/ci.md for full examples.

• Rust macro-generated tests: Invisible to tree-sitter. Custom assertion macros need custom_patterns
• TypeScript T107: Intentionally disabled (high false positive rate in dogfooding)
• Helper delegation: Project-local assertion helpers need custom_patterns config

See docs/known-constraints.md for details, workarounds, and dogfooding data.

Dogfooded across 13 real-world projects:

Full results: docs/dogfooding-results.md

1. Fork the repository
2. Create a feature branch
3. Follow TDD: write tests first
4. Submit a pull request

MIT