0
# Pytest Marks
1
2
Django-specific pytest marks for test configuration and behavior control. These marks provide fine-grained control over database access, URL configuration, and template error handling.
3
4
## Capabilities
5
6
### Django Database Mark
7
8
Control database access and transaction behavior for individual tests.
9
10
```python { .api }
11
@pytest.mark.django_db(
12
transaction: bool = False,
13
reset_sequences: bool = False,
14
databases: Optional[Union[Literal["__all__"], Iterable[str]]] = None,
15
serialized_rollback: bool = False,
16
available_apps: Optional[List[str]] = None
17
):
18
"""
19
Enable database access for test with configurable behavior.
20
21
Controls how the test interacts with the database, including
22
transaction handling, sequence management, and database selection.
23
24
Args:
25
transaction: Use transactional database (allows testing transactions)
26
reset_sequences: Reset database sequences after test
27
databases: Database aliases to use ("__all__" or list of names)
28
serialized_rollback: Use serialized rollback instead of transactions
29
available_apps: Limit Django apps available during test
30
"""
31
```
32
33
Usage examples:
34
35
```python
36
# Basic database access
37
@pytest.mark.django_db
38
def test_model_creation():
39
from myapp.models import MyModel
40
obj = MyModel.objects.create(name="test")
41
assert obj.pk is not None
42
43
# Transactional testing
44
@pytest.mark.django_db(transaction=True)
45
def test_transaction_behavior():
46
from django.db import transaction
47
from myapp.models import MyModel
48
49
with transaction.atomic():
50
MyModel.objects.create(name="test1")
51
# Test transaction rollback, commit behavior, etc.
52
53
# Multiple databases
54
@pytest.mark.django_db(databases=["default", "users"])
55
def test_multiple_databases():
56
# Test has access to both default and users databases
57
pass
58
59
# All databases
60
@pytest.mark.django_db(databases="__all__")
61
def test_all_databases():
62
# Test has access to all configured databases
63
pass
64
65
# Reset sequences for explicit PKs
66
@pytest.mark.django_db(reset_sequences=True)
67
def test_with_explicit_pk():
68
from myapp.models import MyModel
69
MyModel.objects.create(id=100, name="test")
70
# Sequences reset after test
71
72
# Serialized rollback
73
@pytest.mark.django_db(serialized_rollback=True)
74
def test_with_serialized_rollback():
75
# Database state preserved via serialization
76
pass
77
78
# Limited app availability
79
@pytest.mark.django_db(available_apps=["myapp", "django.contrib.auth"])
80
def test_with_limited_apps():
81
# Only specified apps available during test
82
pass
83
```
84
85
### URL Configuration Mark
86
87
Override Django URL configuration for specific tests.
88
89
```python { .api }
90
@pytest.mark.urls(module: str):
91
"""
92
Override ROOT_URLCONF setting for test.
93
94
Temporarily changes Django's URL configuration to use
95
a different URLconf module for the test. Useful for
96
testing with custom URL patterns or isolated routing.
97
98
Args:
99
module: Python module path containing URL configuration
100
"""
101
```
102
103
Usage examples:
104
105
```python
106
# Use custom URL configuration
107
@pytest.mark.urls("myapp.test_urls")
108
def test_custom_urls(client):
109
# Test uses URL patterns from myapp.test_urls
110
response = client.get("/test-url/")
111
assert response.status_code == 200
112
113
# Test with minimal URLs
114
@pytest.mark.urls("tests.minimal_urls")
115
def test_minimal_routing(client):
116
# Test with only essential URL patterns
117
response = client.get("/health/")
118
assert response.status_code == 200
119
120
# Multiple tests with same URL config
121
pytestmark = pytest.mark.urls("myapp.api_urls")
122
123
def test_api_endpoint_1(client):
124
# Uses myapp.api_urls
125
pass
126
127
def test_api_endpoint_2(client):
128
# Also uses myapp.api_urls
129
pass
130
```
131
132
### Template Error Ignoring Mark
133
134
Ignore Django template variable errors during testing.
135
136
```python { .api }
137
@pytest.mark.ignore_template_errors():
138
"""
139
Ignore invalid template variable errors during test.
140
141
Suppresses Django template errors for invalid/undefined
142
variables. Useful when testing with incomplete template
143
contexts or when template errors are not relevant to test.
144
"""
145
```
146
147
Usage examples:
148
149
```python
150
# Ignore template errors for test
151
@pytest.mark.ignore_template_errors
152
def test_with_incomplete_context(client):
153
# Template may reference undefined variables
154
response = client.get("/page-with-missing-vars/")
155
assert response.status_code == 200
156
# No template errors raised
157
158
# Test template rendering with missing context
159
@pytest.mark.ignore_template_errors
160
def test_template_resilience():
161
from django.template import Template, Context
162
163
template = Template("{{ missing_var }} {{ also_missing }}")
164
result = template.render(Context({}))
165
# No errors for missing variables
166
assert result == " "
167
```
168
169
### Mark Combinations
170
171
Combine multiple marks for complex test scenarios.
172
173
```python
174
# Multiple marks on single test
175
@pytest.mark.django_db(transaction=True)
176
@pytest.mark.urls("myapp.transaction_urls")
177
@pytest.mark.ignore_template_errors
178
def test_complex_scenario(client):
179
# Test with transactions, custom URLs, and ignored template errors
180
pass
181
182
# Class-level marks
183
@pytest.mark.django_db
184
@pytest.mark.urls("myapp.api_urls")
185
class TestAPI:
186
def test_endpoint_1(self, client):
187
# Inherits both marks
188
pass
189
190
def test_endpoint_2(self, client):
191
# Also inherits both marks
192
pass
193
194
# Module-level marks
195
pytestmark = [
196
pytest.mark.django_db,
197
pytest.mark.urls("myapp.test_urls")
198
]
199
200
def test_function_1():
201
# Uses module-level marks
202
pass
203
```
204
205
## Mark Configuration Types
206
207
```python { .api }
208
from typing import Optional, Union, List, Literal, Iterable
209
210
# Database configuration types
211
DatabaseSelection = Optional[Union[Literal["__all__"], Iterable[str]]]
212
AvailableApps = Optional[List[str]]
213
TransactionMode = bool
214
SequenceReset = bool
215
SerializedRollback = bool
216
217
# URL configuration types
218
UrlModule = str # Python module path (e.g., "myapp.urls")
219
220
# Mark parameter types
221
class DjangoDbMarkParams:
222
transaction: bool = False
223
reset_sequences: bool = False
224
databases: DatabaseSelection = None
225
serialized_rollback: bool = False
226
available_apps: AvailableApps = None
227
228
class UrlsMarkParams:
229
module: str
230
231
class IgnoreTemplateErrorsMarkParams:
232
pass # No parameters
233
234
# Internal mark validation types
235
from pytest import Mark
236
237
def validate_django_db_mark(mark: Mark) -> tuple[bool, bool, DatabaseSelection, bool, AvailableApps]: ...
238
def validate_urls_mark(mark: Mark) -> List[str]: ...
239
```