Python Testing
Python testing strategies using pytest, TDD methodology, fixtures, mocking, parametrization, and coverage requirements. Use when writing pytest tests — fixtures, mocks, parametrization, or coverage.
Get the complete skill folder, including its scripts and reference files.
·
When to use this skill
Use Python Testing when an AI agent needs a reusable SKILL.md workflow for this job: Python testing strategies using pytest, TDD methodology, fixtures, mocking, parametrization, and coverage requirements. Use when writing pytest tests — fixtures, mocks, parametrization, or coverage.
When not to use it
Skip Python Testing when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/python-testing # Save SKILL.md to ~/.claude/skills/python-testing/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/python-testing/SKILL.md. For a shared project, commit the folder at .claude/skills/python-testing/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Python Testing skill for this task: Use Python Testing when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 72/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Python Testing Patterns
Comprehensive testing strategies for Python applications using pytest, TDD methodology, and best practices.
## When to Activate
- Writing new Python code (follow TDD: red, green, refactor) - Designing test suites for Python projects - Reviewing Python test coverage - Setting up testing infrastructure
## Core Testing Philosophy
### Test-Driven Development (TDD)
Always follow the TDD cycle:
1. **RED**: Write a failing test for the desired behavior 2. **GREEN**: Write minimal code to make the test pass 3. **REFACTOR**: Improve code while keeping tests green
```python # Step 1: Write failing test (RED) def test_add_numbers(): result = add(2, 3) assert result == 5
# Step 2: Write minimal implementation (GREEN) def add(a, b): return a + b
# Step 3: Refactor if needed (REFACTOR) ```
### Coverage Requirements
- **Target**: 80%+ code coverage - **Critical paths**: 100% coverage required - Use `pytest --cov` to measure coverage
```bash pytest --cov=mypackage --cov-report=term-missing --cov-report=html ```
## pytest Fundamentals
### Basic Test Structure
```python import pytest
def test_addition(): """Test basic addition.""" assert 2 + 2 == 4
def test_string_uppercase(): """Test string uppercasing.""" text = "hello" assert text.upper() == "HELLO"
def test_list_append(): """Test list append.""" items = [1, 2, 3] items.append(4) assert 4 in items assert len(items) == 4 ```
### Assertions
```python # Equality assert result == expected
# Inequality assert result != unexpected
# Truthiness assert result # Truthy assert not result # Falsy assert result is True # Exactly True assert result is False # Exactly False assert result is None # Exactly None
# Membership assert item in collection assert item not in collection
# Comparisons assert result > 0 assert 0 <= result <= 100
# Type checking assert isinstance(result, str)
# Exception testing (preferred approach) with pytest.raises(ValueError): raise ValueError("error message")
# Check exception message with pytest.raises(ValueError, match="invalid input"): raise ValueError("invalid input provided")
# Check exception attributes with pytest.raises(ValueError) as exc_info: raise ValueError("error message") assert str(exc_info.value) == "error message" ```
## Fixtures
### Basic Fixture Usage
```python import pytest
@pytest.fixture def sample_data(): """Fixture providing sample data.""" return {"name": "Alice", "age": 30}
def test_sample_data(sample_data): """Test using the fixture.""" assert sample_data["name"] == "Alice" assert sample_data["age"] == 30 ```
### Fixture with Setup/Teardown
```python @pytest.fixture def database(): """Fixture with setup and teardown.""" # Setup db = Database(":memory:") db.create_tables() db.insert_test_data()
yield db # Provide to test
# Teardown db.close()
def test_database_query(database): """Test database operations.""" result = database.query("SELECT * FROM users") assert len(result) > 0 ```
### Fixture Scopes
```python # Function scope (default) - runs for each test @pytest.fixture def temp_file(): with open("temp.txt", "w") as f: yield f os.remove("temp.txt")
# Module scope - runs once per module @pytest.fixture(scope="module") def module_db(): db = Database(":memory:") db.create_tables() yield db db.close()
# Session scope - runs once per test session @pytest.fixture(scope="session") def shared_resource(): resource = ExpensiveResource() yield resource resource.cleanup() ```
### Fixture with Parameters
```python @pytest.fixture(params=[1, 2, 3]) def number(request): """Parameterized fixture.""" return request.param
def test_numbers(number): """Test runs 3 times, once for each parameter.""" assert number > 0 ```
### Using Multiple Fixtures
```python @pytest.fixture def user(): return User(id=1, name="Alice")
@pytest.fixture def admin(): return User(id=2, name="Admin", role="admin")
def test_user_admin_interaction(user, admin): """Test using multiple fixtures.""" assert admin.can_manage(user) ```
### Autouse Fixtures
```python @pytest.fixture(autouse=True) def reset_config(): """Automatically runs before every test.""" Config.reset() yield Config.cleanup()
def test_without_fixture_call(): # reset_config runs automatically assert Config.get_setting("debug") is False ```
### Conftest.py for Shared Fixtures (Flask)
```python # tests/conftest.py import pytest
@pytest.fixture def client(): """Shared fixture for all tests.""" app = create_app(testing=True) with app.test_client() as client: yield client
@pytest.fixture def auth_headers(client): """Generate auth headers for API testing.""" response = client.post("/api/login", json={ "username": "test", "password": "test" }) token = response.json["token"] return {"Authorization": f"Bearer {token}"} ```
## Parametrization
### Basic Parametrization
```python @pytest.mark.parametrize("input,expected", [ ("hello", "HELLO"), ("world", "WORLD"), ("PyThOn", "PYTHON"), ]) def test_uppercase(input, expected): """Test runs 3 times with different inputs.""" assert input.upper() == expected ```
### Multiple Parameters
```python @pytest.mark.parametrize("a,b,expected", [ (2, 3, 5), (0, 0, 0), (-1, 1, 0), (100, 200, 300), ]) def test_add(a, b, expected): """Test addition with multiple inputs.""" assert add(a, b) == expected ```
### Parametrize with IDs
```python @pytest.mark.parametrize("input,expected", [ ("[email protected]", True), ("invalid", False), ("@no-domain.com", False), ], ids=["valid-email", "missing-at", "missing-domain"]) def test_email_validation(input, expected): """Test email validation with readable test IDs.""" assert is_valid_email(input) is expected ```
### Parametrized Fixtures
```python @pytest.fixture(params=["sqlite", "postgresql", "mysql"]) def db(request): """Test against multiple database backends.""" if request.param == "sqlite": return Database(":memory:") elif request.param == "postgresql": return Database("postgresql://localhost/test") elif request.param == "mysql": return Database("mysql://localhost/test")
def test_database_operations(db): """Test runs 3 times, once for each database.""" result = db.query("SELECT 1") assert result is not None ```
## Markers and Test Selection
### Custom Markers
```python # Mark slow tests @pytest.mark.slow def test_slow_operation(): time.sleep(5)
# Mark integration tests @pytest.mark.integration def test_api_integration(): response = requests.get("https://api.example.com") assert response.status_code == 200
# Mark unit tests @pytest.mark.unit def test_unit_logic(): assert calculate(2, 3) == 5 ```
### Run Specific Tests
```bash # Run only fast tests pytest -m "not slow"
# Run only integration tests pytest -m integration
# Run integration or slow tests pytest -m "integration or slow"
# Run tests marked as unit but not slow pytest -m "unit and not slow" ```
### Configure Markers in pytest.ini
```ini [pytest] markers = slow: marks tests as slow integration: marks tests as integration tests unit: marks tests as unit tests django: marks tests as requiring Django ```
## Mocking and Patching
### Mocking Functions
```python from unittest.mock import patch, Mock
@patch("mypackage.external_api_call") def test_with_mock(api_call_mock): """Test with mocked external API.""" api_call_mock.return_value = {"status": "success"}
result = my_function()
api_call_mock.assert_called_once() assert result["status"] == "success" ```
### Mocking Return Values
```python @patch("mypackage.Database.connect") def test_database_connection(connect_mock): """Test with mocked database connection.""" connect_mock.return_value = MockConnection()
db = Database() db.connect()
connect_mock.assert_called_once_with("localhost") ```
### Mocking Exceptions
```python @patch("mypackage.api_call") def test_api_error_handling(api_call_mock): """Test error handling with mocked exception.""" api_call_mock.side_effect = ConnectionError("Network error")
with pytest.raises(ConnectionError): api_call()
api_call_mock.assert_called_once() ```
### Mocking Context Managers
```python @patch("builtins.open", new_callable=mock_open) def test_file_reading(mock_file): """Test file reading with mocked open.""" mock_file.return_value.read.return_value = "file content"
result = read_file("test.txt")
mock_file.assert_called_once_with("test.txt", "r") assert result == "file content" ```
### Using Autospec
```python @patch("mypackage.DBConnection", autospec=True) def test_autospec(db_mock): """Test with autospec to catch API misuse.""" db = db_mock.return_value db.query("SELECT * FROM users")
# This would fail if DBConnection doesn't have query method db_mock.assert_called_once() ```
### Mock Class Instances
```python class TestUserService: @patch("mypackage.UserRepository") def test_create_user(self, repo_mock): """Test user creation with mocked repository.""" repo_mock.return_value.save.return_value = User(id=1, name="Alice")
service = UserService(repo_mock.return_value) user = service.create_user(name="Alice")
assert user.name == "Alice" repo_mock.return_value.save.assert_called_once() ```
### Mock Property
```python @pytest.fixture def mock_config(): """Create a mock with a property.""" config = Mock() type(config).debug = PropertyMock(return_value=True) type(config).api_key = PropertyMock(return_value="test-key") return config
def test_with_mock_config(mock_config): """Test with mocked config properties.""" assert mock_config.debug is True assert mock_config.api_key == "test-key" ```
## Testing Async Code
### Async Tests with pytest-asyncio
```python import pytest
@pytest.mark.asyncio async def test_async_function(): """Test async function.""" result = await async_add(2, 3) assert result == 5
@pytest.mark.asyncio async def test_async_with_fixture(async_client): """Test async with async fixture.""" response = await async_client.get("/api/users") assert response.status_code == 200 ```
### Async Fixture (FastAPI)
`ASGITransport` does not run lifespan events. Install `asgi-lifespan` and wrap the client in `LifespanManager` when the app uses startup or shutdown handlers. See [FastAPI's async testing guidance](https://github.com/fastapi/fastapi/blob/master/docs/en/docs/advanced/async-tests.md).
```python import pytest import pytest_asyncio from asgi_lifespan import LifespanManager from httpx import ASGITransport, AsyncClient
@pytest_asyncio.fixture async def async_client(): """Async fixture providing async test client with lifespan events.""" app = create_app() # Returns a FastAPI application async with LifespanManager(app) as manager: async with AsyncClient(transport=ASGITransport(app=manager.app), base_url="http://test") as client: yield client
@pytest.mark.asyncio async def test_api_endpoint(async_client): """Test using async fixture.""" response = await async_client.get("/api/data") assert response.status_code == 200 ```
### Mocking Async Functions
```python @pytest.mark.asyncio @patch("mypackage.async_api_call") async def test_async_mock(api_call_mock): """Test async function with mock.""" api_call_mock.return_value = {"status": "ok"}
result = await my_async_function()
api_call_mock.assert_awaited_once() assert result["status"] == "ok" ```
## Testing Exceptions
### Testing Expected Exceptions
```python def test_divide_by_zero(): """Test that dividing by zero raises ZeroDivisionError.""" with pytest.raises(ZeroDivisionError): divide(10, 0)
def test_custom_exception(): """Test custom exception with message.""" with pytest.raises(ValueError, match="invalid input"): validate_input("invalid") ```
### Testing Exception Attributes
```python def test_exception_with_details(): """Test exception with custom attributes.""" with pytest.raises(CustomError) as exc_info: raise CustomError("error", code=400)
assert exc_info.value.code == 400 assert "error" in str(exc_info.value) ```
## Testing Side Effects
### Testing File Operations
```python import tempfile import os
def test_file_processing(): """Test file processing with temp file.""" with tempfile.NamedTemporaryFile(mode='w', delete=False, suffix='.txt') as f: f.write("test content") temp_path = f.name
try: result = process_file(temp_path) assert result == "processed: test content" finally: os.unlink(temp_path) ```
### Testing with pytest's tmp_path Fixture
```python def test_with_tmp_path(tmp_path): """Test using pytest's built-in temp path fixture.""" test_file = tmp_path / "test.txt" test_file.write_text("hello world")
result = process_file(str(test_file)) assert result == "hello world" # tmp_path automatically cleaned up ```
### Testing with tmpdir Fixture
```python def test_with_tmpdir(tmpdir): """Test using pytest's tmpdir fixture.""" test_file = tmpdir.join("test.txt") test_file.write("data")
result = process_file(str(test_file)) assert result == "data" ```
## Test Organization
### Directory Structure
``` tests/ ├── conftest.py # Shared fixtures ├── __init__.py ├── unit/ # Unit tests │ ├── __init__.py │ ├── test_models.py │ ├── test_utils.py │ └── test_services.py ├── integration/ # Integration tests │ ├── __init__.py │ ├── test_api.py │ └── test_database.py └── e2e/ # End-to-end tests ├── __init__.py └── test_user_flow.py ```
### Test Classes
```python class TestUserService: """Group related tests in a class."""
@pytest.fixture(autouse=True) def setup(self): """Setup runs before each test in this class.""" self.service = UserService()
def test_create_user(self): """Test user creation.""" user = self.service.create_user("Alice") assert user.name == "Alice"
def test_delete_user(self): """Test user deletion.""" user = User(id=1, name="Bob") self.service.delete_user(user) assert not self.service.user_exists(1) ```
## Best Practices
### DO
- **Follow TDD**: Write tests before code (red-green-refactor) - **Test one thing**: Each test should verify a single behavior - **Use descriptive names**: `test_user_login_with_invalid_credentials_fails` - **Use fixtures**: Eliminate duplication with fixtures - **Mock external dependencies**: Don't depend on external services - **Test edge cases**: Empty inputs, None values, boundary conditions - **Aim for 80%+ coverage**: Focus on critical paths - **Keep tests fast**: Use marks to separate slow tests
### DON'T
- **Don't test implementation**: Test behavior, not internals - **Don't use complex conditionals in tests**: Keep tests simple - **Don't ignore test failures**: All tests must pass - **Don't test third-party code**: Trust libraries to work - **Don't share state between tests**: Tests should be independent - **Don't catch exceptions in tests**: Use `pytest.raises` - **Don't use print statements**: Use assertions and pytest output - **Don't write tests that are too brittle**: Avoid over-specific mocks
## Common Patterns
### Testing API Endpoints (Flask)
```python @pytest.fixture def client(): app = create_app(testing=True) return app.test_client()
def test_get_user(client): response = client.get("/api/users/1") assert response.status_code == 200 assert response.json["id"] == 1
def test_create_user(client): response = client.post("/api/users", json={ "name": "Alice", "email": "[email protected]" }) assert response.status_code == 201 assert response.json["name"] == "Alice" ```
### Testing Database Operations
```python @pytest.fixture def db_session(): """Create a test database session.""" session = Session(bind=engine) session.begin_nested() yield session session.rollback() session.close()
def test_create_user(db_session): user = User(name="Alice", email="[email protected]") db_session.add(user) db_session.commit()
retrieved = db_session.query(User).filter_by(name="Alice").first() assert retrieved.email == "[email protected]" ```
### Testing Class Methods
```python class TestCalculator: @pytest.fixture def calculator(self): return Calculator()
def test_add(self, calculator): assert calculator.add(2, 3) == 5
def test_divide_by_zero(self, calculator): with pytest.raises(ZeroDivisionError): calculator.divide(10, 0) ```
## pytest Configuration
### pytest.ini
```ini [pytest] testpaths = tests python_files = test_*.py python_classes = Test* python_functions = test_* addopts = --strict-markers --disable-warnings --cov=mypackage --cov-report=term-missing --cov-report=html markers = slow: marks tests as slow integration: marks tests as integration tests unit: marks tests as unit tests ```
### pyproject.toml
```toml [tool.pytest.ini_options] testpaths = ["tests"] python_files = ["test_*.py"] python_classes = ["Test*"] python_functions = ["test_*"] addopts = [ "--strict-markers", "--cov=mypackage", "--cov-report=term-missing", "--cov-report=html", ] markers = [ "slow: marks tests as slow", "integration: marks tests as integration tests", "unit: marks tests as unit tests", ] ```
## Running Tests
```bash # Run all tests pytest
# Run specific file pytest tests/test_utils.py
# Run specific test pytest tests/test_utils.py::test_function
# Run with verbose output pytest -v
# Run with coverage pytest --cov=mypackage --cov-report=html
# Run only fast tests pytest -m "not slow"
# Run until first failure pytest -x
# Run and stop on N failures pytest --maxfail=3
# Run last failed tests pytest --lf
# Run tests with pattern pytest -k "test_user"
# Run with debugger on failure pytest --pdb ```
## Quick Reference
| Pattern | Usage | |---------|-------| | `pytest.raises()` | Test expected exceptions | | `@pytest.fixture()` | Create reusable test fixtures | | `@pytest.mark.parametrize()` | Run tests with multiple inputs | | `@pytest.mark.slow` | Mark slow tests | | `pytest -m "not slow"` | Skip slow tests | | `@patch()` | Mock functions and classes | | `tmp_path` fixture | Automatic temp directory | | `pytest --cov` | Generate coverage report | | `assert` | Simple and readable assertions |
**Remember**: Tests are code too. Keep them clean, readable, and maintainable. Good tests catch bugs; great tests prevent them.
Intended uses
- Use Python Testing when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.