FastAPI Test Fixtures — Core Concepts

Why fixtures matter for FastAPI

FastAPI applications have dependencies — database connections, authentication, external services, configuration. Testing these applications means controlling those dependencies. Pytest fixtures give you a structured way to provide controlled, reusable test environments that set up before each test and tear down after.

Without fixtures, every test file duplicates setup code: creating database tables, constructing test clients, generating auth tokens. Fixtures centralize this in conftest.py and let tests declare what they need.

The essential fixtures

Test client fixture

The test client sends HTTP requests to your FastAPI app without starting a real server:

The fixture creates a TestClient (from Starlette) wrapping your FastAPI app. Every test that needs to make API requests uses this fixture. The client handles cookies, redirects, and authentication headers just like a real HTTP client would.

For async tests, you can use httpx.AsyncClient instead, which supports async test patterns and ASGI lifespan events.

Database fixture

Most FastAPI apps need a database. The standard fixture pattern:

1. Create a test database engine (SQLite in-memory or a dedicated test PostgreSQL database)
2. Create all tables before the test
3. Provide a session that wraps each test in a transaction
4. Roll back the transaction after the test — no data persists between tests

Transaction rollback is faster than creating and dropping tables for each test. A suite with 500 tests might save minutes of runtime using this approach.

Authenticated user fixture

Many routes require authentication. Instead of generating JWT tokens in every test, create a fixture that overrides the auth dependency to return a known user.

This fixture uses FastAPI’s dependency_overrides to bypass real authentication entirely. The route thinks a real user is logged in, but no token was ever generated or validated.

Fixture composition

Fixtures can depend on other fixtures. This creates a composition chain:

• db_engine → creates the test database engine
• db_session → depends on db_engine, creates a session within a transaction
• client → depends on db_session, creates a test client with the database overridden
• authenticated_client → depends on client, adds auth override

Each fixture declares its dependencies as function parameters. Pytest resolves the chain automatically. A test that asks for authenticated_client gets the full stack without knowing the details.

Fixture scopes

Pytest fixtures have scopes that control their lifetime:

• function (default): Created fresh for every test. Best isolation but slowest.
• class: Shared across all tests in a class.
• module: Shared across all tests in a file.
• session: Created once for the entire test run.

For FastAPI, the common pattern: database engine at session scope (creating it once), database sessions at function scope (fresh transaction per test), test client at function scope (fresh overrides per test).

Using too broad a scope causes test pollution. Using too narrow a scope wastes time. The guideline: immutable resources (engines, configurations) can be session-scoped. Mutable resources (database sessions, override dictionaries) should be function-scoped.

Factory fixtures

Sometimes different tests need different data. Factory fixtures return a function that creates objects on demand:

Instead of a fixture that always creates the same user, you get a create_user function that accepts parameters. Each test calls it with the specific data it needs. This avoids the “god fixture” problem where one massive fixture tries to anticipate every test’s needs.

Async fixtures

When testing async FastAPI endpoints with httpx.AsyncClient, your fixtures need to be async too. Use pytest-asyncio and mark fixtures with @pytest.fixture as normal — pytest-asyncio detects async fixture functions automatically.

Async fixtures are essential when your setup code needs to call async functions (like populating a database through an async ORM).

Common misconception

Developers often create a single massive conftest.py with dozens of fixtures. This becomes unmaintainable. Instead, organize fixtures by concern:

• conftest.py at the project root for truly global fixtures (database engine, test client)
• conftest.py in each test subdirectory for domain-specific fixtures (user factories, order factories)

Pytest discovers conftest files hierarchically. A test in tests/api/test_orders.py can use fixtures from both tests/conftest.py and tests/api/conftest.py.

Pitfalls

• Fixture ordering bugs: If fixture A sets a dependency override and fixture B clears all overrides, the order they tear down matters. Use explicit cleanup (delete specific keys) rather than clear() in fixtures that might compose.
• Shared mutable state: A session-scoped fixture that returns a mutable object (like a list) will accumulate state across tests. Use function scope for anything mutable.
• Import-time side effects: If your FastAPI app does work at import time (connecting to databases, reading config files), importing it in fixtures can cause unexpected behavior. Structure your app to defer side effects to startup events.

The one thing to remember: Well-structured pytest fixtures — composed in layers from engine to session to client to auth — give you isolated, fast, and maintainable tests that let you focus on testing behavior rather than fighting setup code.