Skip to main content

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, tomli backports the stdlib's tomllib.
  • shape, gaps, reach and report need nothing else, since the line counter is built in.
  • cover additionally needs the analysed project's own pytest and coverage to be importable, so run it from that project's environment.
  • cloc is 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 --json shape
  • 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: 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, except where you ask for one. The lenses report data and advice. gaps and cover figures are diagnostics: 1/20 mirrored for a browser tier is often by design. tepyd check is 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.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tepyd 0.9.0
File Size Uploaded Provenance Actions
tepyd-0.9.0.tar.gz 52.3 kB Without provenance Details for tepyd-0.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tepyd 0.9.0
File Interpreter ABI Platform Actions
tepyd-0.9.0-py3-none-any.whl Python 3 none any Details for tepyd-0.9.0-py3-none-any.whl

Total release size: 112.6 kB

Release files / tepyd-0.9.0.tar.gz

Download URL tepyd-0.9.0.tar.gz
Size 52.3 kB
Tags Source
SHA-256 checksum
How to use checksums
2dd9abdf2cd6e3799278bf2cffd59b66b456f62843904423da3a43693258b524
BLAKE2b-256 checksum
How to use checksums
8d0855f89f21e459fa1e3d72d33a1511e2654095669679d5bbaa998a2c7cacc1
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.0-py3-none-any.whl

Download URL tepyd-0.9.0-py3-none-any.whl
Size 60.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4fede5b8bb3d18db5d040877b6f6c13a176916df1f55c299d80cca0e62769d6e
BLAKE2b-256 checksum
How to use checksums
358e95754158d873f1b097995dc4f2af39ae8ce9c2fb402519779636db286d70
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.0

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page