Testing

Layout

tests/
├── benchmarks/                  # pytest-codspeed micro-benchmarks (ignored by default)
├── test_application.py          # Tests for fastapi/applications.py (~58k lines)
├── test_*.py                    # Other unit/integration tests
├── test_tutorial/               # One sub-directory per docs_src/ topic, mirrors that tree
│   ├── test_path_params/
│   ├── test_dependencies/
│   ├── test_security/
│   └── ...
├── test_request_params/         # Modular fixtures
└── utils.py                     # Shared helpers

There are 581 test files totalling 74,543 lines. Most are short; a handful are very large because they enumerate combinations (see Fun facts).

Frameworks

• pytest 9.x — pinned by the tests dependency-group in pyproject.toml.
• pytest-xdist — -n auto --dist loadgroup is set in scripts/test.sh.
• pytest-cov — coverage collection.
• pytest-codspeed — for tests/benchmarks/.
• pytest-sugar, pytest-timeout — quality of life. Default per-test timeout is 20 seconds (pyproject.toml:tool.pytest.timeout).
• anyio[trio] — exercises the async paths under both asyncio and trio.
• inline-snapshot — used in newer tests to inline expected JSON output.
• dirty-equals — flexible equality matchers.

Running

bash scripts/test.sh                  # full suite
bash scripts/test.sh -k oauth2        # by keyword
bash scripts/test.sh tests/test_sse.py -x   # single file, halt on first failure
bash scripts/test-cov.sh              # full suite + coverage report
bash scripts/test-cov-html.sh         # full suite + HTML report (htmlcov/)

scripts/test.sh exports PYTHONPATH=./docs_src so the tutorial tests can import the documented examples directly.

Tutorial tests

tests/test_tutorial/ is the largest single category. Its layout mirrors docs_src/. For example, a documentation example at docs_src/security/tutorial002_an_py310.py is imported by a test at tests/test_tutorial/test_security/test_tutorial002_an_py310.py. The naming suffixes tell you the variant:

• _an_ — uses Annotated[...] style (Python ≥3.9 / 3.10).
• _py310, _py39 — the minimum Python version exercised.
• (no suffix) — pre-Annotated, kept for back-compat.

If you add an example to docs_src/, add a matching test in tests/test_tutorial/ so it gets run on every PR. CI will fail otherwise.

Coverage

pyproject.toml configures coverage to track fastapi, tests, and docs_src. Coverage is uploaded to a worker maintained by Samuel Colvin (see the README badge) and summarised on PRs by the smokeshow.yml workflow.

Files are excluded from coverage when they are intentionally not exercised:

• tests/benchmarks/*
• A few tutorial examples that are placeholders or migrated to a different version.
• Pydantic v1 migration tutorials (docs_src/pydantic_v1_in_v2/...).

Snapshot tests with inline-snapshot

Some newer tests use inline-snapshot to keep expected JSON inline with the test code. To regenerate after intentional changes:

uv run pytest --inline-snapshot=create tests/test_my_thing.py
uv run pytest --inline-snapshot=fix tests/test_my_thing.py

The pyproject sets defaults under [tool.inline-snapshot] (currently commented out). Avoid committing those defaults — only the snapshot values themselves should change.

Patterns to follow

• For a new path-operation behaviour, add tests using Starlette's TestClient (re-exported as fastapi.testclient.TestClient).
• Set app = FastAPI() per test (or per module if shared). Avoid sharing global app instances across files — pytest-xdist runs files on different workers.
• When testing OpenAPI output, fetch app.openapi() directly rather than hitting /openapi.json. Compare with dict deep-equality and prefer inline-snapshot for large dicts.
• WebSocket tests use client.websocket_connect(...) from Starlette's TestClient.
• For dependency-with-yield behaviours, write tests that assert on side effects observable after the response is returned.