Tepyd¶

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 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 would 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 is 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¶

Tepyd looks at a suite through five complementary lenses. Each is useful alone; together they catch failure modes the others miss.

Lens	Question	Runs your tests?
`shape`	How much test code is there, and in what shape?	no
`gaps`	Does the test tree structurally parallel the source tree?	no
`cover`	Which tier actually executes each unit, and is it the cheap one?	yes
`reach`	Do unit-tier tests stay inside the unit under test?	no
`report`	The static checks at once, plus the why and the how	no

In 30 seconds¶

$ uv run tepyd init          # detect this project's layout, write a config
$ uv run tepyd report        # the checks and the advice, in one read

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).

Start with Getting started, or go straight to the CI gate.

What Tepyd is not¶

Not a test runner, and not a replacement for pytest or coverage: cover orchestrates 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, unless you ask. The lenses all exit 0 even with findings. The numbers are diagnostics: a browser tier showing 1/20 mirrored is often correct by design. tepyd check is the opt-in CI gate.

Requirements¶

Python ≥ 3.10.
No runtime dependencies on Python ≥ 3.11. On 3.10 the single dependency is tomli, the backport of the tomllib that landed in the 3.11 stdlib.
shape, gaps, reach and report need nothing else, because the line counter is built in.
cover additionally needs the analysed project's own pytest and coverage to be importable, so it must run from that project's environment. See cover.
cloc is an optional opt-in for the line counter (counter = "cloc").

License¶

Apache-2.0.