Assertions are used to verify that an application behaves as expected during test execution. They help validate elements, text, URLs, page titles, visibility, and many other conditions.
Playwright provides powerful built-in assertions through the expect() API, making tests more reliable and easier to maintain.
What is an Assertion?
An assertion checks whether a specific condition is true. If the condition fails, the test will fail and report an error.
Example:
await expect(page).toHaveTitle('Dashboard');Importing Assertions
Playwright assertions are available through the @playwright/test package.
const { test, expect } = require('@playwright/test');Why Use Assertions?
- Validate application behavior
- Ensure UI elements appear correctly
- Verify user actions produce expected results
- Detect bugs early
- Increase test reliability
Basic Assertion Syntax
await expect(locator).toBeVisible();Structure:
expect(actualValue).matcher(expectedValue);1. Page Assertions
Verify Page Title
await expect(page).toHaveTitle('Home Page');Verify Partial Title
await expect(page).toHaveTitle(/Home/);Verify URL
await expect(page).toHaveURL(
'https://example.com/dashboard'
);Verify Partial URL
await expect(page).toHaveURL(/dashboard/);2. Visibility Assertions
Element is Visible
await expect(
page.locator('#loginBtn')
).toBeVisible();Element is Hidden
await expect(
page.locator('#loading')
).toBeHidden();3. Text Assertions
Verify Exact Text
await expect(
page.locator('.message')
).toHaveText('Login Successful');
Verify Partial Text
await expect(
page.locator('.message')
).toContainText('Successful');
Verify Multiple Text Values
await expect(
page.locator('.items')
).toContainText([
'Product 1',
'Product 2'
]);
4. Input Field Assertions
Verify Input Value
await expect(
page.locator('#username')
).toHaveValue('admin');
Verify Empty Field
await expect(
page.locator('#username')
).toHaveValue('');
5. Checkbox Assertions
Verify Checkbox is Checked
await expect(
page.locator('#rememberMe')
).toBeChecked();
Verify Checkbox is Not Checked
await expect(
page.locator('#rememberMe')
).not.toBeChecked();
6. Enable and Disable Assertions
Verify Element is Enabled
await expect(
page.locator('#submitBtn')
).toBeEnabled();
Verify Element is Disabled
await expect(
page.locator('#submitBtn')
).toBeDisabled();
7. Editable Assertions
Verify Field is Editable
await expect(
page.locator('#username')
).toBeEditable();
Verify Field is Read Only
await expect(
page.locator('#username')
).not.toBeEditable();
8. Count Assertions
Verify the number of matching elements.
await expect(
page.locator('.product')
).toHaveCount(5);
9. Attribute Assertions
Verify an element attribute.
await expect(
page.locator('#email')
).toHaveAttribute(
'type',
'email'
);
10. CSS Assertions
Verify CSS property values.
await expect(
page.locator('.success')
).toHaveCSS(
'display',
'block'
);
11. Class Assertions
Verify class names.
await expect(
page.locator('.button')
).toHaveClass('button active');
Using Regular Expression:
await expect(
page.locator('.button')
).toHaveClass(/active/);
12. Negative Assertions
Negative assertions verify that something does NOT exist or match.
Element Not Visible
await expect(
page.locator('#error')
).not.toBeVisible();
Text Does Not Match
await expect(
page.locator('.message')
).not.toHaveText('Failed');
13. API Response Assertions
Assertions can also be used with API testing.
const response = await request.get('/users');
expect(response.status()).toBe(200);
Verify Response Body
const data = await response.json();
expect(data.name).toBe('John');
14. Generic Assertions
Playwright uses standard assertion methods for values and variables.
Equal
expect(10).toBe(10);
Contains
expect('Playwright')
.toContain('wright');
Truthy
expect(true).toBeTruthy();
Falsy
expect(false).toBeFalsy();
Auto-Retry Assertions
One of Playwright's most powerful features is automatic retrying.
Assertions automatically wait until the condition becomes true or the timeout is reached.
await expect(
page.locator('.success')
).toBeVisible();
No explicit waits are required in most cases.
Soft Assertions
Soft assertions allow the test to continue even if an assertion fails.
await expect.soft(
page.locator('.title')
).toHaveText('Dashboard');
Useful when validating multiple fields in a single test.
Commonly Used Assertions
| Assertion | Purpose |
|---|---|
| toHaveTitle() | Verify page title |
| toHaveURL() | Verify URL |
| toBeVisible() | Check element visibility |
| toBeHidden() | Check element hidden state |
| toHaveText() | Verify exact text |
| toContainText() | Verify partial text |
| toHaveValue() | Verify input value |
| toBeChecked() | Verify checkbox state |
| toBeEnabled() | Verify enabled state |
| toHaveCount() | Verify element count |
Best Practices
- Use Playwright's built-in assertions whenever possible.
- Prefer locator-based assertions over manual checks.
- Avoid unnecessary wait statements.
- Use soft assertions for multiple validations.
- Keep assertions focused and readable.
- Validate business-critical functionality first.
Conclusion
Assertions are a fundamental part of Playwright testing. They help verify that web applications behave as expected and ensure test reliability. With automatic retries, rich locator assertions, and support for UI and API testing, Playwright provides one of the most powerful assertion systems available in modern test automation frameworks.