ci: report test coverage

.github/workflows/ci.yml

@@ -30,8 +30,8 @@ jobs:
       - name: Check formatting
         run: uv run ruff format --check .
 
-      - name: Run tests
-        run: uv run pytest
+      - name: Run tests with coverage
+        run: uv run pytest --cov=text_toolkit --cov-report=term-missing
 
       - name: Run type checking
         run: uv run mypy

CONTRIBUTING.md

@@ -189,7 +189,7 @@ Before opening a pull request with code changes, run the local quality checks:
 ```bash
 uv run ruff check .
 uv run ruff format --check .
-uv run pytest
+uv run pytest --cov=text_toolkit --cov-report=term-missing
 uv run mypy
 uv build --no-sources
 ```
@@ -205,7 +205,7 @@ Then repeat the checks:
 ```bash
 uv run ruff check .
 uv run ruff format --check .
-uv run pytest
+uv run pytest --cov=text_toolkit --cov-report=term-missing
 uv run mypy
 uv build --no-sources
 ```

README.md

@@ -121,7 +121,7 @@ Run the same quality checks used by CI:
 ```bash
 uv run ruff check .
 uv run ruff format --check .
-uv run pytest
+uv run pytest --cov=text_toolkit --cov-report=term-missing
 uv run mypy
 uv build --no-sources
 ```

docs/06_github_actions.md

@@ -47,7 +47,7 @@ In this project, the local checks are:
 ```bash
 uv run ruff check .
 uv run ruff format --check .
-uv run pytest
+uv run pytest --cov=text_toolkit --cov-report=term-missing
 uv run mypy
 uv build --no-sources
 ```
@@ -169,6 +169,7 @@ This is important in CI because the workflow should check the project using the
 The `--group dev` option installs development dependencies such as:
 
 - `pytest`,
+- `pytest-cov`,
 - `mypy`,
 - `ruff`.
 
@@ -213,16 +214,18 @@ The developer can fix formatting locally with:
 uv run ruff format .
 ```
 
-## Tests
+## Tests and coverage
 
-The workflow runs tests:
+The workflow runs tests and prints a coverage report:
 
 ```yaml
-- name: Run tests
-  run: uv run pytest
+- name: Run tests with coverage
+  run: uv run pytest --cov=text_toolkit --cov-report=term-missing
 ```
 
-This verifies the behavior of the example package.
+This verifies the behavior of the example package while measuring statement and
+branch coverage. The terminal report shows missing source lines, but the project
+does not fail the workflow based on a coverage percentage.
 
 At this stage, the tests check:
 

docs/07_git_commits_branches_prs.md

@@ -334,7 +334,7 @@ For code changes, run:
 ```bash
 uv run ruff check .
 uv run ruff format --check .
-uv run pytest
+uv run pytest --cov=text_toolkit --cov-report=term-missing
 uv run mypy
 ```
 

docs/08_common_mistakes.md

@@ -145,7 +145,7 @@ For code changes, run:
 ```bash
 uv run ruff check .
 uv run ruff format --check .
-uv run pytest
+uv run pytest --cov=text_toolkit --cov-report=term-missing
 uv run mypy
 ```
 

docs/09_checklist.md

@@ -140,6 +140,24 @@ uv run mypy
 
 Type checking complements tests and Ruff; it does not replace them.
 
+## Test coverage
+
+The project should use coverage as a diagnostic tool:
+
+- [ ] pytest-cov is installed as a development dependency
+- [ ] coverage is limited to production source code
+- [ ] statement and branch coverage are measured
+- [ ] missing lines are visible in the terminal report
+- [ ] a percentage is not treated as proof of test quality
+
+In this guide, tests and coverage run together:
+
+```bash
+uv run pytest --cov=text_toolkit --cov-report=term-missing
+```
+
+There is no minimum percentage gate.
+
 ## Continuous integration
 
 The project should run checks automatically in CI:
@@ -150,7 +168,7 @@ The project should run checks automatically in CI:
 - [ ] CI installs dependencies from the lockfile
 - [ ] CI runs linting
 - [ ] CI checks formatting
-- [ ] CI runs tests
+- [ ] CI runs tests with coverage reporting
 - [ ] CI runs type checking
 - [ ] CI builds a wheel and source distribution
 - [ ] CI status is visible in the README
@@ -198,7 +216,7 @@ For code changes, run:
 ```bash
 uv run ruff check .
 uv run ruff format --check .
-uv run pytest
+uv run pytest --cov=text_toolkit --cov-report=term-missing
 uv run mypy
 uv build --no-sources
 ```
@@ -214,7 +232,7 @@ Then repeat:
 ```bash
 uv run ruff check .
 uv run ruff format --check .
-uv run pytest
+uv run pytest --cov=text_toolkit --cov-report=term-missing
 uv run mypy
 uv build --no-sources
 ```
@@ -250,6 +268,7 @@ How do I install it?
 Where is the code?
 Where are the tests?
 How do I run the tests?
+How do I inspect test coverage?
 How do I check formatting and linting?
 How do I check type annotations?
 How do I build distribution files?

docs/12_test_coverage.md

@@ -97,6 +97,17 @@ The important columns are:
 
 The exact counts will change when the package changes.
 
+## Coverage in CI
+
+The `Quality checks` job runs the same command:
+
+```bash
+uv run pytest --cov=text_toolkit --cov-report=term-missing
+```
+
+The report is visible in the GitHub Actions log. CI fails when tests or coverage
+collection fail, but it does not fail because the percentage decreases.
+
 ## Why there is no percentage gate
 
 This project intentionally does not configure `fail_under`.

docs/ROADMAP.md

@@ -96,6 +96,7 @@ These parts are already included in the repository.
 - [x] Run linting in CI
 - [x] Run formatting checks in CI
 - [x] Run tests in CI
+- [x] Run coverage reporting in CI
 - [x] Run type checking in CI
 - [x] Build distributions in CI
 - [x] Add a CI badge to the README
@@ -138,10 +139,6 @@ These parts are already included in the repository.
 
 These are good candidates for upcoming small pull requests.
 
-### Test coverage
-
-- [ ] Run coverage reporting in CI and align workflow documentation
-
 ### Repository polish
 
 - [ ] Add issue templates only if the repository starts receiving external feedback

docs/cheatsheet.md

@@ -62,6 +62,7 @@ Examples:
 uv add --group dev pytest
 uv add --group dev ruff
 uv add --group dev mypy
+uv add --group dev pytest-cov
 ```
 
 Sync the local environment:
@@ -84,6 +85,12 @@ Run tests:
 uv run pytest
 ```
 
+Run tests with coverage:
+
+```bash
+uv run pytest --cov=text_toolkit --cov-report=term-missing
+```
+
 Run type checking:
 
 ```bash
@@ -113,7 +120,7 @@ Run all local checks:
 ```bash
 uv run ruff check .
 uv run ruff format --check .
-uv run pytest
+uv run pytest --cov=text_toolkit --cov-report=term-missing
 uv run mypy
 uv build --no-sources
 ```
@@ -136,7 +143,7 @@ If formatting fails:
 uv run ruff format .
 uv run ruff check .
 uv run ruff format --check .
-uv run pytest
+uv run pytest --cov=text_toolkit --cov-report=term-missing
 uv run mypy
 uv build --no-sources
 ```
@@ -154,7 +161,7 @@ Then run:
 ```bash
 uv run ruff check .
 uv run ruff format --check .
-uv run pytest
+uv run pytest --cov=text_toolkit --cov-report=term-missing
 uv run mypy
 ```
 
@@ -250,7 +257,7 @@ uv python install
 uv sync --locked --group dev
 uv run ruff check .
 uv run ruff format --check .
-uv run pytest
+uv run pytest --cov=text_toolkit --cov-report=term-missing
 uv run mypy
 uv build --no-sources
 ```
@@ -305,7 +312,7 @@ git status
 uv sync
 uv run ruff check .
 uv run ruff format --check .
-uv run pytest
+uv run pytest --cov=text_toolkit --cov-report=term-missing
 uv run mypy
 ```
 

docs/common_questions.md

@@ -224,7 +224,7 @@ This guide first teaches the commands directly:
 ```bash
 uv run ruff check .
 uv run ruff format --check .
-uv run pytest
+uv run pytest --cov=text_toolkit --cov-report=term-missing
 uv run mypy
 ```
 
@@ -305,7 +305,7 @@ Then run the local checks:
 ```bash
 uv run ruff check .
 uv run ruff format --check .
-uv run pytest
+uv run pytest --cov=text_toolkit --cov-report=term-missing
 uv run mypy
 ```
 

docs/example_pull_request.md

@@ -289,7 +289,7 @@ For code changes, run:
 ```bash
 uv run ruff check .
 uv run ruff format --check .
-uv run pytest
+uv run pytest --cov=text_toolkit --cov-report=term-missing
 uv run mypy
 ```
 

docs/from_script_to_project.md

@@ -249,6 +249,7 @@ build-backend = "uv_build"
 dev = [
     "mypy>=2.3.1",
     "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
     "ruff>=0.15.12",
 ]
 
@@ -260,6 +261,13 @@ python_version = "3.12"
 files = ["src", "tests"]
 strict = true
 
+[tool.coverage.run]
+branch = true
+source = ["text_toolkit"]
+
+[tool.coverage.report]
+show_missing = true
+
 [tool.ruff]
 line-length = 88
 target-version = "py312"
@@ -308,7 +316,7 @@ In this guide, the main local checks are:
 ```bash
 uv run ruff check .
 uv run ruff format --check .
-uv run pytest
+uv run pytest --cov=text_toolkit --cov-report=term-missing
 uv run mypy
 uv build --no-sources
 ```
@@ -317,7 +325,7 @@ These commands check:
 
 - linting,
 - formatting,
-- behavior,
+- behavior and test coverage,
 - type annotations,
 - package distribution builds.
 
@@ -348,7 +356,7 @@ uv python install
 uv sync --locked --group dev
 uv run ruff check .
 uv run ruff format --check .
-uv run pytest
+uv run pytest --cov=text_toolkit --cov-report=term-missing
 uv run mypy
 uv build --no-sources
 ```
@@ -429,7 +437,7 @@ The project now has:
 - documentation in `docs/`,
 - dependencies described in `pyproject.toml`,
 - exact dependency versions in `uv.lock`,
-- local checks with Ruff, pytest, and mypy,
+- local checks with Ruff, pytest-cov, and mypy,
 - CI with GitHub Actions,
 - a branch and pull request workflow.