Testing and CI/CD

Relevant source files

• .github/workflows/pythonpackage.yml
• .pre-commit-config.yaml
• CONTRIBUTING.md
• Makefile
• docs/requirements.txt
• docs/source/conf.py
• docs/source/index.rst
• docs/source/reference.rst
• docs/source/reference/protocol.rst
• examples/downloader.py
• examples/exception.py
• rich/abc.py
• rich/filesize.py
• rich/protocol.py
• tests/test_filesize.py
• tests/test_protocol.py
• tox.ini

This page describes the test suite structure, quality tooling, and continuous integration setup for the Rich project. It covers how to run tests locally, what checks are enforced before commits and in pull requests, and how the GitHub Actions pipeline is structured.

For information on setting up the development environment and submitting pull requests, see Contributing Guide.

---

Test Suite Structure

All tests live in the tests/ directory at the repository root. Each test file maps roughly to one module in the rich/ package. Tests are written using pytest and generally follow the pattern of constructing a Console instance writing to a StringIO buffer and asserting on the captured output.

Example layout:

Test file	Module under test
tests/test_filesize.py	rich/filesize.py
tests/test_protocol.py	rich/protocol.py
tests/test_console.py	rich/console.py
tests/test_text.py	rich/text.py
tests/test_table.py	rich/table.py
tests/test_progress.py	rich/progress.py

A representative test uses a Console with a captured file argument:

Sources: tests/test_protocol.py1-84 tests/test_filesize.py1-20

---

Local Development Commands

The Makefile defines the primary developer-facing commands. All commands assume the Poetry virtual environment is active.

Makefile targets:

Target	Command executed	Purpose
make test	TERM=unknown pytest --cov-report term-missing --cov=rich tests/ -vv	Run full test suite with coverage
make test-no-cov	TERM=unknown pytest tests/ -vv	Run tests without coverage instrumentation
make format-check	black --check .	Verify formatting without modifying files
make format	black .	Apply Black formatting in-place
make typecheck	mypy -p rich --no-incremental	Run mypy on the entire rich package
make typecheck-report	mypy -p rich --html-report mypy_report	Generate an HTML type-checking report
make docs	cd docs; make html	Build Sphinx documentation

Setting TERM=unknown in the test commands forces Rich to use a dumb terminal mode, ensuring deterministic output regardless of the developer's terminal capabilities.

Sources: Makefile1-16

---

GitHub Actions CI Pipeline

The CI workflow is defined in .github/workflows/pythonpackage.yml1-54 It triggers on every pull request.

CI Pipeline Overview

Sources: .github/workflows/pythonpackage.yml1-54

Build Matrix

The pipeline runs across a full cross-product of operating systems and Python versions, with one explicit exclusion:

	Python 3.8	3.9	3.10	3.11	3.12	3.13	3.14
ubuntu-latest	✓	✓	✓	✓	✓	✓	✓
macos-latest	✓	✓	✓	✓	✓	✓	✓
windows-latest	✓	✓	✓	✓	✓	✗	✓

The fail-fast: false setting ensures that a failure in one matrix cell does not cancel the remaining jobs, so the full scope of failures is always visible.

Python 3.14 is a pre-release version; allow-prereleases: true is set on actions/setup-python to enable it.

Sources: .github/workflows/pythonpackage.yml6-13

CI Steps in Detail

Sources: .github/workflows/pythonpackage.yml18-53

---

Code Coverage

Coverage is measured using pytest-cov. The flags used in CI are:

• --cov=./rich — measures coverage of the rich/ package only
• --cov-report=xml:./coverage.xml — writes an XML report consumed by Codecov
• --cov-report term-missing — prints uncovered line numbers to the terminal

The resulting coverage.xml file is uploaded to Codecov via codecov/codecov-action@v4, identified with:

• name: rich
• flags: unittests
• env_vars: OS,PYTHON (allows Codecov to segment results by matrix cell)

Sources: .github/workflows/pythonpackage.yml42-53

---

Type Checking

Rich uses type annotations throughout the codebase. mypy is the type checker.

The make typecheck target runs:

mypy -p rich --no-incremental

The --no-incremental flag disables mypy's cache, ensuring a clean check on every run. An HTML report variant is available via make typecheck-report, which writes results to mypy_report/.

All new code is expected to include type annotations, and the CI pipeline will fail if mypy reports errors.

Sources: Makefile9-12 CONTRIBUTING.md73-87

---

Code Formatting

Rich uses Black as its sole code formatter.

• make format-check — validates formatting without writing changes (black --check .)
• make format — applies formatting in-place (black .)

The CI pipeline runs make format-check and will fail the build if any file is not properly formatted.

Sources: Makefile5-8 CONTRIBUTING.md89-96

---

Pre-commit Hooks

The repository provides a .pre-commit-config.yaml that runs several checks automatically at git commit time. Installing them is strongly recommended.

Hook inventory:

The benchmarks/ directory is excluded globally via the top-level exclude: benchmarks/ key, and also explicitly excluded from the black hook.

Sources: .pre-commit-config.yaml1-44

Installing hooks:

pre-commit install

After installation, every git commit runs the full hook set before the commit is recorded.

---

Tox Configuration

The tox.ini defines isolated test environments for multi-version testing and linting without relying on the developer's active shell environment.

Tox environment map:

Environment	Description	Key commands
py38, py39, py310, py311, py312, py313	Unit tests per Python version	poetry install → pytest --cov-report term-missing --cov=rich tests/
lint	Format and type checks	make format-check → make typecheck
docs	Documentation build	sphinx-build -M html source build

The [testenv] base configuration passes through a limited set of environment variables (CI, GITHUB_*, HOME, PYTEST_*, TERM) to maintain isolation while allowing CI-specific behaviour.

Sources: tox.ini1-52

---

Quality Gate Summary

The following table consolidates every automated check and where it runs:

Check	Tool	Local command	Pre-commit	CI (GitHub Actions)	Tox
Unit tests	pytest	make test	—	✓	✓
Code coverage	pytest-cov	make test	—	✓	✓
Formatting	black	make format-check	✓	✓	✓ (lint env)
Import sorting	isort	—	✓	—	—
Unused imports	pycln	—	✓	—	—
Type checking	mypy	make typecheck	—	✓	✓ (lint env)
AST / file hygiene	pre-commit-hooks	—	✓	—	—
Coverage upload	Codecov	—	—	✓	—

Sources: .github/workflows/pythonpackage.yml1-54 Makefile1-16 .pre-commit-config.yaml1-44 tox.ini1-52 CONTRIBUTING.md44-96