Tepyd: The TEst PYramid Doctor
Diagnose your test pyramid: is the shape what you say you want?
Tepyd looks at a project's test suite and tells you whether its shape matches the test pyramid you say you want: a broad base of cheap unit tests, fewer integration tests, a thin cap of end-to-end tests. It automates the checks you'd otherwise do by hand: which packages are under- or over-tested, where the cheap tests are missing, whether the test tree mirrors the source tree, and (by running your suite under coverage) which tier actually exercises each package.
It's configuration-driven: point it at any project, describe that project's layout once in pyproject.toml, and run one command.
Think
tepyd doctor: diagnose my pyramid.
The lenses
| Lens | Command | Question | Runs tests? |
|---|---|---|---|
| Shape | tepyd shape |
How much test code is there, and in what shape? | no |
| Gaps | tepyd gaps |
Does the test tree structurally parallel the source tree? | no |
| Cover | tepyd cover |
Which tier actually executes each unit? Is it the cheap one? | yes |
| Reach | tepyd reach |
Do unit-tier tests stay inside the unit under test? | no |
| Report | tepyd report |
The static checks at once, plus advice: the why and the how | no |
Install
Tepyd is on PyPI.
uv add --dev tepyd # in the project you analyse: every lens, `cover` included
uv tool install tepyd # or on your PATH: the static lenses only
cover runs your suite, so it needs Tepyd inside your project's environment; the static lenses run from anywhere. The examples below use uv run; drop it for a tool install.
Quick start
uv run tepyd init # detect this project's layout, write a config
uv run tepyd report # the checks + advice, in one read
uv run tepyd shape --min-src 1 # every unit, including the small ones
uv run tepyd -C /path/to/project shape # analyse another project
uv run tepyd check # CI gate: silent + exit 0, or exit 1
Pyramid health: FAIR — 0 problem(s), 5 warning(s) across 11 unit(s).
• Tier mix: unit 60% / integration 26% / e2e 14% (target: unit ≥ 60%)
• Shape: 11 source units, weighted test/src 0.62x, unit share 60%.
• Gaps: unit tier mirrors 8/11 source packages; 0 orphan(s).
shape, gaps, reach and cover take --json; report renders text or Markdown via --format. All commands take -C/--root DIR. The lenses all exit 0 even with findings; tepyd check is the one command whose exit status is a verdict.
Requirements
- Python ≥ 3.10.
- No runtime dependencies on Python ≥ 3.11; on 3.10,
tomlibackports the stdlib'stomllib. shape,gaps,reachandreportneed nothing else, since the line counter is built in.coveradditionally needs the analysed project's ownpytestandcoverageto be importable, so run it from that project's environment.clocis an optional opt-in for the line counter (counter = "cloc").
Documentation
The full documentation is at tepyd.lab.abilian.com, built from docs/src:
- Getting started: install,
init, running the lenses, exit codes - Concepts: source units, tiers, unit share, shape glyphs, layer awareness
- The lenses: one page each, with its
--jsonshape - CI gate:
tepyd check, what fails a build and what doesn't - Configuration: the full
[tool.tepyd]reference
Build them locally with make docs, or make docs-serve for a live preview.
What Tepyd is not
- Not a test runner, nor a replacement for pytest or coverage:
coverorchestrates them. - Not a correctness checker. LOC is a proxy for effort. A test's directory decides its tier, whatever the test exercises.
- Not a pass/fail gate, except where you ask for one. The lenses report data and advice.
gapsandcoverfigures are diagnostics:1/20 mirroredfor a browser tier is often by design.tepyd checkis the opt-in gate, which fires only on problems.
Development
uv sync # dev environment
make test # pytest
make lint # ruff + ty + pyrefly + mypy
make format # ruff format + autofix
make docs # build the Zensical site
Tepyd eats its own dog food: its tests are organised as a pyramid (tests/a_unit, tests/b_integration, tests/c_e2e).
Changelog
See CHANGES.md.
License
Tepyd is licensed under the Apache License 2.0.
Metadata
Release files for tepyd 0.9.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tepyd-0.9.1.tar.gz | 52.6 kB | Without provenance | Details for tepyd-0.9.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tepyd-0.9.1-py3-none-any.whl | Python 3 | none | any | Details for tepyd-0.9.1-py3-none-any.whl |
Total release size: 113.1 kB
Release files / tepyd-0.9.1.tar.gz
| Download URL | tepyd-0.9.1.tar.gz |
|---|---|
| Size | 52.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f6216b93c49e6d26313bba02e9b652c975fee33a7503b27ad62f57728aae8646
|
|
BLAKE2b-256 checksum How to use checksums |
206a7a1cfd54197169caffcfcd0498170e5dd7214c380d3004272bf72c204834
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.12 {"installer":{"name":"uv","version":"0.12.12","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / tepyd-0.9.1-py3-none-any.whl
| Download URL | tepyd-0.9.1-py3-none-any.whl |
|---|---|
| Size | 60.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1f1e6a3bf01b10e4ca726ee20d0c43b772e80a51a0617a1028a081d3d150470f
|
|
BLAKE2b-256 checksum How to use checksums |
c2b09590504533152e38baba2ffe8cf1a28d5b1d3468d74c739885c08a289e41
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.12 {"installer":{"name":"uv","version":"0.12.12","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for tepyd 0.9.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.