pytest-local-badge 1.2.1

Pytest plugin that writes self-hosted SVG badges (tests, coverage, skipped, xfailed, warnings, duration) to your repo — no third-party shield service required.

pytest-local-badge

Our badges:

Session badges (regenerated every pytest run):

Package-metadata badges (rendered from the installed dist's classifiers / METADATA):

Self-hosted pytest & package badges — tests, coverage, skipped, xfailed, warnings, duration, last-run, plus version/python/license/maturity/os and more pulled straight from your installed dist's metadata. No shields.io, no Codecov, no third-party uptime to depend on — just SVG files committed alongside your code.

Why?

Shiny badges in your README are great. But the usual recipe — a hosted shield service reading numbers from a hosted CI provider — falls apart the moment you:

• Work on a private repo the badge service can't see.
• Run on internal CI behind a VPN.
• Don't want a third-party SVG endpoint loading every time someone opens your README.
• Want badges that work offline (think air-gapped environments, local docs builds, PDFs).

pytest-local-badge skips the round-trip. Every test run regenerates plain SVG files next to your source. Commit them. Reference them with a normal relative path. Done.

Install

Just the test-count badge:

pip install pytest-local-badge

With the coverage badge (pytest-cov pulled in automatically):

pip install "pytest-local-badge[cov]"

Quick start

Tell pytest where to drop the SVGs:

pytest --cov=my_package --local-badge-output-dir badges/

You'll get:

badges/
├── tests.svg       # e.g. "tests | 142"  (or "139/142" if some fail)
├── coverage.svg    # e.g. "coverage | 87%"
├── skipped.svg     # e.g. "skipped | 3"
├── xfailed.svg     # e.g. "xfailed | 1"
├── warnings.svg    # e.g. "warnings | 0"
├── duration.svg    # e.g. "duration | 4.2s"
└── last-run.svg    # e.g. "last run | 2026-03-14 09:26 UTC"

All seven session badges are generated by default; narrow the set with --local-badge-generate (see below).

Package metadata badges

Pass --local-badge-package=YOUR_DIST to also render badges sourced from the installed distribution's metadata (importlib.metadata):

pytest --local-badge-output-dir badges/ --local-badge-package=my_package

That adds (when the corresponding classifier / metadata field is present):

badges/
├── my-package-version.svg           # e.g. "version | 1.2.3"        (md["Version"])
├── my-package-python.svg            # e.g. "python | 3.10 | 3.11"   (Programming Language :: Python :: X.Y classifiers)
├── my-package-requires-python.svg   # e.g. "python | >=3.10"        (md["Requires-Python"])
├── my-package-implementation.svg    # e.g. "implementation | CPython | PyPy"
├── my-package-license.svg           # e.g. "License | MIT"          (License :: ... classifier)
├── my-package-maturity.svg          # e.g. "status | beta"          (Development Status :: N - ...)
├── my-package-framework.svg         # e.g. "framework | Pytest"     (Framework :: X)
├── my-package-os.svg                # e.g. "OS | Linux | MacOS"     (Operating System :: ... classifiers; "OS Independent" wins if set)
├── my-package-typed.svg             # only if `Typing :: Typed` is set
└── my-package-private.svg           # only if `Private :: Do Not Upload` is set

Repeat the flag for more than one distribution — each gets its own set of files, prefixed with the PEP 503-canonical name:

pytest --local-badge-output-dir badges/ \
       --local-badge-package=my_lib \
       --local-badge-package=my_cli

Disable any of them by listing only the ones you want via --local-badge-generate:

# Get version + license, skip the python-versions enumeration in favour of Requires-Python:
pytest --local-badge-output-dir badges/ \
       --local-badge-package=my_package \
       --local-badge-generate status cov version license requires-python

Then in your README.md:

![Tests](badges/tests.svg)
![Coverage](badges/coverage.svg)
![Skipped](badges/skipped.svg)
![XFailed](badges/xfailed.svg)
![Warnings](badges/warnings.svg)
![Duration](badges/duration.svg)
![Last run](badges/last-run.svg)

<!-- if you used --local-badge-package=my_package -->
![Version](badges/my-package-version.svg)
![Python](badges/my-package-python.svg)
![License](badges/my-package-license.svg)
![OS](badges/my-package-os.svg)

Make it permanent

Add it to your pyproject.toml so every pytest run keeps the badges in sync:

[tool.pytest.ini_options]
addopts = "--cov=my_package --local-badge-output-dir badges/"

…and commit the badge directory. The diff is tiny (an SVG only changes when the numbers change) and lives forever in your repo's history.

Command-line options

--no-local-badge                 Disable the plugin for this run.
--local-badge-output-dir DIR     Where to write the SVGs. (Required to activate.)
--local-badge-generate {cov,duration,framework,implementation,last-run,
                        license,maturity,os,private,python,requires-python,
                        skipped,status,typed,version,warnings,xfailed} [...]
                                 Which badges to generate. Defaults to all of them.
                                 Package-metadata badges (version, python, license,
                                 maturity, framework, implementation, typed, private,
                                 requires-python, os) only fire when --local-badge-package
                                 is also set.
--local-badge-package PACKAGE    Installed distribution name to read metadata from.
                                 Repeat the flag for more than one package.
--local-badge-duration-max SECONDS
                                 Duration "budget" for the `duration` badge. When
                                 set, colour thresholds scale proportionally — e.g.
                                 `--local-badge-duration-max=60` gives brightgreen
                                 ≤ 6 s, orange ≤ 60 s, red > 60 s. Without it, the
                                 default absolute scale applies.

Badge colour scale

Most badges colour-grade by ratio (pass rate, coverage, or skipped/xfailed fraction of the suite). warnings and duration use absolute thresholds instead — see the Supported badges table. The ratio scale:

Range	Colour
≥ 99%	brightgreen
≥ 87%	green
≥ 75%	yellowgreen
≥ 50%	yellow
≥ 30%	orange
< 30%	red
no data	lightgrey

"No data" is reserved for genuinely missing input (no tests collected, pytest-cov produced no report) — a real 0% renders red, not grey.

Supported badges

Session badges (always on)

These read from the live pytest session, no extra flags required.

Name	File	Shows
status	tests.svg	Total tests collected, or passed/total when some failed.
cov	coverage.svg	pytest-cov line coverage as a percentage. Requires pytest-cov.
skipped	skipped.svg	Count of @pytest.mark.skip / pytest.skip(...) tests. Colours by the fraction of the suite that actually ran.
xfailed	xfailed.svg	Count of expected-failure (@pytest.mark.xfail) tests.
warnings	warnings.svg	Number of warnings raised during the run. Colour-graded by absolute count (0 → green, anything else escalates fast).
duration	duration.svg	Total test session wall-clock time (4.2s, 1m 23s, 1h 30m). Colours by absolute thresholds by default, or by --local-badge-duration-max=SECONDS when you set a budget.

Package-metadata badges (opt in with --local-badge-package)

Read from the installed distribution's METADATA via importlib.metadata. Each file is prefixed with the package's canonical name, e.g. my-package-version.svg. Badges only render when the underlying classifier / field is actually present — no empty placeholders.

Name	File suffix	Source	Shows
version	-version.svg	md["Version"]	The distribution version, e.g. version | 1.2.3.
python	-python.svg	Programming Language :: Python :: X.Y classifiers	Pipe-joined Python versions, e.g. python | 3.10 | 3.11 | 3.12.
requires-python	-requires-python.svg	md["Requires-Python"]	The declared constraint as-is, e.g. python | >=3.10. Often a cleaner alternative to python when you don't list every version in classifiers.
implementation	-implementation.svg	Programming Language :: Python :: Implementation :: X classifiers	implementation | CPython | PyPy.
license	-license.svg	License :: ... classifier	The final trove segment with a trailing " License" trimmed, e.g. License | MIT.
maturity	-maturity.svg	Development Status :: N - ... classifier	Project status — planning, pre-alpha, alpha, beta, production/stable, mature, inactive. Colour-graded by the trove digit (1–2 red, 3 orange, 4 yellow, 5 brightgreen, 6 green, 7 grey).
framework	-framework.svg	Framework :: X classifiers	Top-level framework names, deduplicated (Framework :: Django :: 4.2 collapses to Django).
typed	-typed.svg	Typing :: Typed classifier	Renders typed | py.typed if the classifier is set; nothing otherwise.
private	-private.svg	Private :: Do Not Upload classifier	Renders package | private if the marker is set; nothing otherwise. Useful for in-house dists you don't want anyone to twine-upload.

Pick which ones to render with --local-badge-generate, e.g.:

# Just the basics, no package badges:
pytest --local-badge-output-dir badges/ --local-badge-generate status cov warnings

# Session badges plus version + license for the installed dist:
pytest --local-badge-output-dir badges/ \
       --local-badge-package=my_package \
       --local-badge-generate status cov version license

By default all badges are listed under --local-badge-generate. Session badges always run when the plugin is active; package badges additionally require --local-badge-package to be set.

How it compares

	shields.io / Codecov / Coveralls	pytest-local-badge
Needs an external HTTP service	yes	no
Works on private repos out of the box	depends on plan	yes
Survives going offline	no	yes
Adds extra commits to history	no	yes (one per badge change)
Cost	free → paid tiers	free, forever

If you're already happy with a hosted service, keep using it. If "another SaaS dependency for a handful of SVGs" feels excessive — this plugin is for you.

Contributing

Issues and PRs welcome: https://github.com/IljaOrlovs/pytest-local-badge

git clone https://github.com/IljaOrlovs/pytest-local-badge
cd pytest-local-badge
pdm install

# Measure coverage of the plugin itself, then regenerate the committed
# badges with that data. We need `coverage run` (not just `pytest --cov`)
# because the plugin is imported by pytest *before* pytest-cov starts
# measuring, which would otherwise leave module-level code uncounted.
# CI enforces 100% via `--fail-under=100`.
pdm run coverage erase
pdm run coverage run -m pytest
pdm run coverage combine
pdm run coverage report -m --fail-under=100
# Pipe the same data into pytest-cov so the coverage badge reflects the
# real 100%, not the partial number you'd get from `pytest --cov` alone.
pdm run pytest --cov=pytest_local_badge --cov-append

pdm run ruff check ./src ./test
pdm run pyright

Acknowledgements

The bundled verdana_11px_normal.json character-width table comes from anafanafo (MIT). It's the same table shields.io uses to size their badges, so locally generated badges line up visually with their hosted siblings. See NOTICE for attribution details.

License

MIT — see LICENSE.