0
# Assertions
1
2
Comprehensive assertion framework with built-in waiting and retry logic for reliable test automation. Supports page, element, and API response assertions.
3
4
## Capabilities
5
6
### Expect Function
7
8
Main entry point for assertions with configurable timeouts and retry logic.
9
10
```python { .api }
11
def expect(
12
actual: Union[Page, Locator, APIResponse],
13
message: Optional[str] = None
14
) -> Union[PageAssertions, LocatorAssertions, APIResponseAssertions]:
15
"""
16
Create assertion object for target.
17
18
Args:
19
actual: Object to assert against (Page, Locator, or APIResponse)
20
message: Custom assertion message
21
22
Returns:
23
Union[PageAssertions, LocatorAssertions, APIResponseAssertions]: Assertion object
24
"""
25
26
class Expect:
27
def set_options(self, timeout: Optional[float] = None) -> None:
28
"""
29
Set global assertion options.
30
31
Args:
32
timeout: Default timeout for assertions in milliseconds
33
"""
34
```
35
36
### Page Assertions
37
38
Assertions for page-level properties like title and URL.
39
40
```python { .api }
41
class PageAssertions:
42
def to_have_title(
43
self,
44
title: Union[str, Pattern],
45
timeout: Optional[float] = None
46
) -> None:
47
"""
48
Assert page title matches expected value.
49
50
Args:
51
title: Expected title text or pattern
52
timeout: Assertion timeout in milliseconds
53
"""
54
55
def to_have_url(
56
self,
57
url: Union[str, Pattern],
58
timeout: Optional[float] = None
59
) -> None:
60
"""
61
Assert page URL matches expected value.
62
63
Args:
64
url: Expected URL text or pattern
65
timeout: Assertion timeout in milliseconds
66
"""
67
68
def not_to_have_title(
69
self,
70
title: Union[str, Pattern],
71
timeout: Optional[float] = None
72
) -> None:
73
"""Assert page title does not match value."""
74
75
def not_to_have_url(
76
self,
77
url: Union[str, Pattern],
78
timeout: Optional[float] = None
79
) -> None:
80
"""Assert page URL does not match value."""
81
```
82
83
### Locator Assertions
84
85
Comprehensive element-level assertions with automatic waiting.
86
87
```python { .api }
88
class LocatorAssertions:
89
def to_be_attached(self, timeout: Optional[float] = None) -> None:
90
"""Assert element is attached to DOM."""
91
92
def to_be_checked(self, timeout: Optional[float] = None) -> None:
93
"""Assert checkbox/radio is checked."""
94
95
def to_be_disabled(self, timeout: Optional[float] = None) -> None:
96
"""Assert element is disabled."""
97
98
def to_be_editable(self, timeout: Optional[float] = None) -> None:
99
"""Assert element is editable."""
100
101
def to_be_empty(self, timeout: Optional[float] = None) -> None:
102
"""Assert element is empty."""
103
104
def to_be_enabled(self, timeout: Optional[float] = None) -> None:
105
"""Assert element is enabled."""
106
107
def to_be_focused(self, timeout: Optional[float] = None) -> None:
108
"""Assert element is focused."""
109
110
def to_be_hidden(self, timeout: Optional[float] = None) -> None:
111
"""Assert element is hidden."""
112
113
def to_be_visible(self, timeout: Optional[float] = None) -> None:
114
"""Assert element is visible."""
115
116
def to_contain_text(
117
self,
118
expected: Union[str, Pattern, List[Union[str, Pattern]]],
119
timeout: Optional[float] = None,
120
use_inner_text: Optional[bool] = None
121
) -> None:
122
"""
123
Assert element contains text.
124
125
Args:
126
expected: Text or patterns to find
127
timeout: Assertion timeout
128
use_inner_text: Use innerText instead of textContent
129
"""
130
131
def to_have_attribute(
132
self,
133
name: str,
134
value: Union[str, Pattern],
135
timeout: Optional[float] = None
136
) -> None:
137
"""
138
Assert element has attribute with value.
139
140
Args:
141
name: Attribute name
142
value: Expected attribute value
143
timeout: Assertion timeout
144
"""
145
146
def to_have_class(
147
self,
148
expected: Union[str, Pattern, List[Union[str, Pattern]]],
149
timeout: Optional[float] = None
150
) -> None:
151
"""Assert element has CSS class(es)."""
152
153
def to_have_count(
154
self,
155
count: int,
156
timeout: Optional[float] = None
157
) -> None:
158
"""
159
Assert locator matches exact number of elements.
160
161
Args:
162
count: Expected element count
163
timeout: Assertion timeout
164
"""
165
166
def to_have_css(
167
self,
168
name: str,
169
value: Union[str, Pattern],
170
timeout: Optional[float] = None
171
) -> None:
172
"""
173
Assert element has CSS property value.
174
175
Args:
176
name: CSS property name
177
value: Expected property value
178
timeout: Assertion timeout
179
"""
180
181
def to_have_id(
182
self,
183
id: Union[str, Pattern],
184
timeout: Optional[float] = None
185
) -> None:
186
"""Assert element has ID."""
187
188
def to_have_js_property(
189
self,
190
name: str,
191
value: Any,
192
timeout: Optional[float] = None
193
) -> None:
194
"""Assert element has JavaScript property value."""
195
196
def to_have_screenshot(
197
self,
198
name: Union[str, bytes],
199
timeout: Optional[float] = None,
200
animations: Optional[str] = None,
201
caret: Optional[str] = None,
202
clip: Optional[FloatRect] = None,
203
mask: Optional[List[Locator]] = None,
204
omit_background: Optional[bool] = None,
205
scale: Optional[str] = None,
206
style: Optional[str] = None,
207
threshold: Optional[float] = None,
208
max_diff_pixels: Optional[int] = None
209
) -> None:
210
"""Assert element screenshot matches baseline."""
211
212
def to_have_text(
213
self,
214
expected: Union[str, Pattern, List[Union[str, Pattern]]],
215
timeout: Optional[float] = None,
216
use_inner_text: Optional[bool] = None
217
) -> None:
218
"""Assert element has exact text content."""
219
220
def to_have_value(
221
self,
222
value: Union[str, Pattern],
223
timeout: Optional[float] = None
224
) -> None:
225
"""Assert input element has value."""
226
227
def to_have_values(
228
self,
229
values: List[Union[str, Pattern]],
230
timeout: Optional[float] = None
231
) -> None:
232
"""Assert select element has selected values."""
233
```
234
235
### API Response Assertions
236
237
Assertions for HTTP responses from API testing.
238
239
```python { .api }
240
class APIResponseAssertions:
241
def to_be_ok(self, timeout: Optional[float] = None) -> None:
242
"""Assert response has successful status (200-299)."""
243
244
def not_to_be_ok(self, timeout: Optional[float] = None) -> None:
245
"""Assert response has unsuccessful status."""
246
```
247
248
## Usage Examples
249
250
### Page Assertions
251
252
```python
253
from playwright.sync_api import sync_playwright, expect
254
255
with sync_playwright() as p:
256
browser = p.chromium.launch()
257
page = browser.new_page()
258
259
page.goto("https://example.com")
260
261
# Assert page properties
262
expect(page).to_have_title("Example Domain")
263
expect(page).to_have_url("https://example.com/")
264
265
browser.close()
266
```
267
268
### Element Assertions
269
270
```python
271
with sync_playwright() as p:
272
browser = p.chromium.launch()
273
page = browser.new_page()
274
275
page.goto("https://example.com/form")
276
277
# Element state assertions
278
submit_btn = page.get_by_role("button", name="Submit")
279
expect(submit_btn).to_be_visible()
280
expect(submit_btn).to_be_disabled()
281
282
# Fill form to enable button
283
email_input = page.get_by_label("Email")
284
email_input.fill("test@example.com")
285
286
expect(submit_btn).to_be_enabled()
287
expect(email_input).to_have_value("test@example.com")
288
289
browser.close()
290
```
291
292
### Content Assertions
293
294
```python
295
with sync_playwright() as p:
296
browser = p.chromium.launch()
297
page = browser.new_page()
298
299
page.goto("https://example.com/products")
300
301
# Text content assertions
302
heading = page.get_by_role("heading", name="Products")
303
expect(heading).to_be_visible()
304
expect(heading).to_have_text("Our Products")
305
306
# Count assertions
307
product_cards = page.locator(".product-card")
308
expect(product_cards).to_have_count(12)
309
310
# Multiple element text
311
product_names = page.locator(".product-name")
312
expect(product_names).to_contain_text(["Laptop", "Phone", "Tablet"])
313
314
browser.close()
315
```