Pytest Testing Skill

Write and run Python tests using pytest with Test-Driven Development (TDD).

Before Implementation

Gather context to ensure successful test implementation:

Clarifications

Required (ask if not clear)

1. Test type? Unit tests / Integration tests / End-to-end tests
2. Framework being tested? FastAPI / Django / CLI / Pure Python
3. Async code? Yes (need pytest-asyncio) / No

Optional (ask if relevant)

4. Coverage target? 80% / 90% / 100% / No requirement
5. Mocking needed? External APIs / Database / File system

Official Documentation

Version Note: This skill follows pytest 7.x+ patterns. For older versions, check migration guides.

TDD Workflow (Red-Green-Refactor)

ALWAYS follow TDD when writing code:

The Cycle

🔴 RED    → Write a failing test first
🟢 GREEN  → Write minimal code to pass the test
🔄 REFACTOR → Clean up code, keep tests green

TDD Rules

1. Never write code without a failing test first
2. Write only enough code to make the test pass
3. Refactor only when tests are green

Quick Example

# Step 1: 🔴 RED - Write failing test
def test_add():
    assert add(2, 3) == 5  # NameError: 'add' is not defined

# Step 2: 🟢 GREEN - Minimal implementation
def add(a, b):
    return a + b  # Test passes!

# Step 3: 🔄 REFACTOR - Improve if needed (tests stay green)

TDD for FastAPI Endpoints

# Step 1: 🔴 RED - Test first (endpoint doesn't exist)
def test_get_user(client):
    response = client.get("/users/1")
    assert response.status_code == 200
    assert response.json()["id"] == 1

# Step 2: 🟢 GREEN - Create endpoint
@app.get("/users/{user_id}")
def get_user(user_id: int):
    return {"id": user_id, "name": "Test User"}

# Step 3: 🔄 REFACTOR - Add proper DB lookup, error handling

See references/tdd.md for complete TDD workflow and patterns.

Quick Start

Write a Basic Test

def test_function_name():
    result = function_under_test(input)
    assert result == expected

Run Tests

uv run pytest                      # Run all tests
uv run pytest tests/test_file.py   # Run specific file
uv run pytest -k "test_name"       # Run matching tests
uv run pytest -x                   # Stop on first failure
uv run pytest --lf                 # Run last failed only
uv run pytest -v                   # Verbose output

Test File Structure

Place tests in tests/ directory mirroring source structure:

project/
├── src/
│   ├── api.py
│   └── utils.py
└── tests/
    ├── conftest.py      # Shared fixtures
    ├── test_api.py
    └── test_utils.py

Test files must start with test_ or end with _test.py.

Writing Tests

Test Functions

def test_addition():
    assert add(2, 3) == 5

def test_raises_error():
    with pytest.raises(ValueError):
        validate("")

Test Classes

class TestCalculator:
    def test_add(self):
        calc = Calculator()
        assert calc.add(2, 3) == 5

    def test_divide_by_zero(self):
        calc = Calculator()
        with pytest.raises(ZeroDivisionError):
            calc.divide(1, 0)

Fixtures

@pytest.fixture
def client():
    return TestClient(app)

def test_endpoint(client):
    response = client.get("/api/users")
    assert response.status_code == 200

Parametrized Tests

@pytest.mark.parametrize("input,expected", [
    ("hello", 5),
    ("", 0),
    ("world", 5),
])
def test_length(input, expected):
    assert len(input) == expected

Mocking

from unittest.mock import patch, Mock

@patch("module.external_api")
def test_with_mock(mock_api):
    mock_api.return_value = {"status": "ok"}
    result = fetch_data()
    assert result["status"] == "ok"
    mock_api.assert_called_once()

FastAPI Async Testing (httpx)

import pytest
from httpx import ASGITransport, AsyncClient
from app.main import app

@pytest.mark.anyio
async def test_async_endpoint():
    async with AsyncClient(
        transport=ASGITransport(app=app),
        base_url="http://test"
    ) as ac:
        response = await ac.get("/")
    assert response.status_code == 200

See references/fastapi_testing.md for dependency overrides, auth testing, WebSockets.

Common Markers

@pytest.mark.skip(reason="Not implemented")
@pytest.mark.skipif(sys.version < "3.10", reason="Requires 3.10+")
@pytest.mark.xfail(reason="Known bug")
@pytest.mark.asyncio  # For async tests (requires pytest-asyncio)
@pytest.mark.slow     # Custom marker for slow tests

Coverage

uv run pytest --cov=src --cov-report=term-missing
uv run pytest --cov=src --cov-report=html

Resources

Scripts

• scripts/run_tests.py – Run pytest with useful defaults
• scripts/generate_tests.py – Generate test file stubs from source
• scripts/check_coverage.py – Check coverage thresholds and report files below target

References

• references/tdd.md – TDD workflow, Red-Green-Refactor cycle, TDD patterns for APIs
• references/patterns.md – Fixture patterns, mocking, async testing, database testing
• references/conftest_templates.md – Ready-to-use conftest.py templates for web apps, FastAPI, Django, CLI testing
• references/fastapi_testing.md – FastAPI-specific testing: dependency overrides, async testing with httpx, auth, WebSockets, background tasks
• references/plugins.md – Popular pytest plugins with usage examples
• references/troubleshooting.md – Common errors and how to fix them
• references/ci_cd.md – GitHub Actions and GitLab CI integration

Popular Plugins

See references/plugins.md for detailed usage.

CI/CD Quick Start

GitHub Actions

- name: Install uv
  uses: astral-sh/setup-uv@v4
- name: Run tests
  run: uv run pytest --cov=src --cov-report=xml

GitLab CI

test:
  script:
    - pip install uv
    - uv run pytest --cov=src

See references/ci_cd.md for complete examples.

Troubleshooting

See references/troubleshooting.md for detailed solutions.

Common Mistakes

Before Delivery Checklist

Test Quality

• Tests follow TDD (written before implementation)
• Each test tests one thing (single assertion focus)
• Tests are independent (can run in any order)
• Edge cases covered (empty, null, boundaries)

Coverage

• Coverage meets project requirements
• Critical paths have 100% coverage
• Run: uv run pytest --cov --cov-report=term-missing

Organization

• Tests mirror source structure
• Shared fixtures in conftest.py
• Descriptive test names (test_<action>_<scenario>_<expected>)

CI Ready

• All tests pass: uv run pytest
• No hardcoded paths or credentials
• Async tests properly marked