1# python-testing-patterns — detailed patterns and worked examples
2 
3## Fundamental Patterns
4 
5### Pattern 1: Basic pytest Tests
6 
7```python
8# test_calculator.py
9import pytest
10 
11class Calculator:
12    """Simple calculator for testing."""
13 
14    def add(self, a: float, b: float) -> float:
15        return a + b
16 
17    def subtract(self, a: float, b: float) -> float:
18        return a - b
19 
20    def multiply(self, a: float, b: float) -> float:
21        return a * b
22 
23    def divide(self, a: float, b: float) -> float:
24        if b == 0:
25            raise ValueError("Cannot divide by zero")
26        return a / b
27 
28 
29def test_addition():
30    """Test addition."""
31    calc = Calculator()
32    assert calc.add(2, 3) == 5
33    assert calc.add(-1, 1) == 0
34    assert calc.add(0, 0) == 0
35 
36 
37def test_subtraction():
38    """Test subtraction."""
39    calc = Calculator()
40    assert calc.subtract(5, 3) == 2
41    assert calc.subtract(0, 5) == -5
42 
43 
44def test_multiplication():
45    """Test multiplication."""
46    calc = Calculator()
47    assert calc.multiply(3, 4) == 12
48    assert calc.multiply(0, 5) == 0
49 
50 
51def test_division():
52    """Test division."""
53    calc = Calculator()
54    assert calc.divide(6, 3) == 2
55    assert calc.divide(5, 2) == 2.5
56 
57 
58def test_division_by_zero():
59    """Test division by zero raises error."""
60    calc = Calculator()
61    with pytest.raises(ValueError, match="Cannot divide by zero"):
62        calc.divide(5, 0)
63```
64 
65### Pattern 2: Fixtures for Setup and Teardown
66 
67```python
68# test_database.py
69import pytest
70from typing import Generator
71 
72class Database:
73    """Simple database class."""
74 
75    def __init__(self, connection_string: str):
76        self.connection_string = connection_string
77        self.connected = False
78 
79    def connect(self):
80        """Connect to database."""
81        self.connected = True
82 
83    def disconnect(self):
84        """Disconnect from database."""
85        self.connected = False
86 
87    def query(self, sql: str) -> list:
88        """Execute query."""
89        if not self.connected:
90            raise RuntimeError("Not connected")
91        return [{"id": 1, "name": "Test"}]
92 
93 
94@pytest.fixture
95def db() -> Generator[Database, None, None]:
96    """Fixture that provides connected database."""
97    # Setup
98    database = Database("sqlite:///:memory:")
99    database.connect()
100 
101    # Provide to test
102    yield database
103 
104    # Teardown
105    database.disconnect()
106 
107 
108def test_database_query(db):
109    """Test database query with fixture."""
110    results = db.query("SELECT * FROM users")
111    assert len(results) == 1
112    assert results[0]["name"] == "Test"
113 
114 
115@pytest.fixture(scope="session")
116def app_config():
117    """Session-scoped fixture - created once per test session."""
118    return {
119        "database_url": "postgresql://localhost/test",
120        "api_key": "test-key",
121        "debug": True
122    }
123 
124 
125@pytest.fixture(scope="module")
126def api_client(app_config):
127    """Module-scoped fixture - created once per test module."""
128    # Setup expensive resource
129    client = {"config": app_config, "session": "active"}
130    yield client
131    # Cleanup
132    client["session"] = "closed"
133 
134 
135def test_api_client(api_client):
136    """Test using api client fixture."""
137    assert api_client["session"] == "active"
138    assert api_client["config"]["debug"] is True
139```
140 
141### Pattern 3: Parameterized Tests
142 
143```python
144# test_validation.py
145import pytest
146 
147def is_valid_email(email: str) -> bool:
148    """Check if email is valid."""
149    return "@" in email and "." in email.split("@")[1]
150 
151 
152@pytest.mark.parametrize("email,expected", [
153    ("[email protected]", True),
154    ("[email protected]", True),
155    ("invalid.email", False),
156    ("@example.com", False),
157    ("user@domain", False),
158    ("", False),
159])
160def test_email_validation(email, expected):
161    """Test email validation with various inputs."""
162    assert is_valid_email(email) == expected
163 
164 
165@pytest.mark.parametrize("a,b,expected", [
166    (2, 3, 5),
167    (0, 0, 0),
168    (-1, 1, 0),
169    (100, 200, 300),
170    (-5, -5, -10),
171])
172def test_addition_parameterized(a, b, expected):
173    """Test addition with multiple parameter sets."""
174    from test_calculator import Calculator
175    calc = Calculator()
176    assert calc.add(a, b) == expected
177 
178 
179# Using pytest.param for special cases
180@pytest.mark.parametrize("value,expected", [
181    pytest.param(1, True, id="positive"),
182    pytest.param(0, False, id="zero"),
183    pytest.param(-1, False, id="negative"),
184])
185def test_is_positive(value, expected):
186    """Test with custom test IDs."""
187    assert (value > 0) == expected
188```
189 
190### Pattern 4: Mocking with unittest.mock
191 
192```python
193# test_api_client.py
194import pytest
195from unittest.mock import Mock, patch, MagicMock
196import requests
197 
198class APIClient:
199    """Simple API client."""
200 
201    def __init__(self, base_url: str):
202        self.base_url = base_url
203 
204    def get_user(self, user_id: int) -> dict:
205        """Fetch user from API."""
206        response = requests.get(f"{self.base_url}/users/{user_id}")
207        response.raise_for_status()
208        return response.json()
209 
210    def create_user(self, data: dict) -> dict:
211        """Create new user."""
212        response = requests.post(f"{self.base_url}/users", json=data)
213        response.raise_for_status()
214        return response.json()
215 
216 
217def test_get_user_success():
218    """Test successful API call with mock."""
219    client = APIClient("https://api.example.com")
220 
221    mock_response = Mock()
222    mock_response.json.return_value = {"id": 1, "name": "John Doe"}
223    mock_response.raise_for_status.return_value = None
224 
225    with patch("requests.get", return_value=mock_response) as mock_get:
226        user = client.get_user(1)
227 
228        assert user["id"] == 1
229        assert user["name"] == "John Doe"
230        mock_get.assert_called_once_with("https://api.example.com/users/1")
231 
232 
233def test_get_user_not_found():
234    """Test API call with 404 error."""
235    client = APIClient("https://api.example.com")
236 
237    mock_response = Mock()
238    mock_response.raise_for_status.side_effect = requests.HTTPError("404 Not Found")
239 
240    with patch("requests.get", return_value=mock_response):
241        with pytest.raises(requests.HTTPError):
242            client.get_user(999)
243 
244 
245@patch("requests.post")
246def test_create_user(mock_post):
247    """Test user creation with decorator syntax."""
248    client = APIClient("https://api.example.com")
249 
250    mock_post.return_value.json.return_value = {"id": 2, "name": "Jane Doe"}
251    mock_post.return_value.raise_for_status.return_value = None
252 
253    user_data = {"name": "Jane Doe", "email": "[email protected]"}
254    result = client.create_user(user_data)
255 
256    assert result["id"] == 2
257    mock_post.assert_called_once()
258    call_args = mock_post.call_args
259    assert call_args.kwargs["json"] == user_data
260```
261 
262### Pattern 5: Testing Exceptions
263 
264```python
265# test_exceptions.py
266import pytest
267 
268def divide(a: float, b: float) -> float:
269    """Divide a by b."""
270    if b == 0:
271        raise ZeroDivisionError("Division by zero")
272    if not isinstance(a, (int, float)) or not isinstance(b, (int, float)):
273        raise TypeError("Arguments must be numbers")
274    return a / b
275 
276 
277def test_zero_division():
278    """Test exception is raised for division by zero."""
279    with pytest.raises(ZeroDivisionError):
280        divide(10, 0)
281 
282 
283def test_zero_division_with_message():
284    """Test exception message."""
285    with pytest.raises(ZeroDivisionError, match="Division by zero"):
286        divide(5, 0)
287 
288 
289def test_type_error():
290    """Test type error exception."""
291    with pytest.raises(TypeError, match="must be numbers"):
292        divide("10", 5)
293 
294 
295def test_exception_info():
296    """Test accessing exception info."""
297    with pytest.raises(ValueError) as exc_info:
298        int("not a number")
299 
300    assert "invalid literal" in str(exc_info.value)
301```
302 
303For advanced patterns including async testing, monkeypatching, temporary files, conftest setup, property-based testing, database testing, CI/CD integration, and configuration files, see [references/advanced-patterns.md](references/advanced-patterns.md)
304 
305## Test Design Principles
306 
307### One Behavior Per Test
308 
309Each test should verify exactly one behavior. This makes failures easy to diagnose and tests easy to maintain.
310 
311```python
312# BAD - testing multiple behaviors
313def test_user_service():
314    user = service.create_user(data)
315    assert user.id is not None
316    assert user.email == data["email"]
317    updated = service.update_user(user.id, {"name": "New"})
318    assert updated.name == "New"
319 
320# GOOD - focused tests
321def test_create_user_assigns_id():
322    user = service.create_user(data)
323    assert user.id is not None
324 
325def test_create_user_stores_email():
326    user = service.create_user(data)
327    assert user.email == data["email"]
328 
329def test_update_user_changes_name():
330    user = service.create_user(data)
331    updated = service.update_user(user.id, {"name": "New"})
332    assert updated.name == "New"
333```
334 
335### Test Error Paths
336 
337Always test failure cases, not just happy paths.
338 
339```python
340def test_get_user_raises_not_found():
341    with pytest.raises(UserNotFoundError) as exc_info:
342        service.get_user("nonexistent-id")
343 
344    assert "nonexistent-id" in str(exc_info.value)
345 
346def test_create_user_rejects_invalid_email():
347    with pytest.raises(ValueError, match="Invalid email format"):
348        service.create_user({"email": "not-an-email"})
349```
350