Playwright Assertions
Playwright Assertions
An assertion checks that the page shows what you expect.
Assertions start with expect(), followed by a matcher: a method like toHaveText() that describes the expected result.
Example
await expect(page.getByTestId('todo-count')).toHaveText('1 item left');
If the check fails, the test fails, and Playwright shows what it expected and what it got.
You import expect together with test:
Example
import { test, expect } from '@playwright/test';
Auto-retrying Assertions
When you pass a locator or a page to expect(), the assertion is web-first.
A web-first assertion retries the check until it passes, or until the time limit (the timeout) ends.
The timeout is 5 seconds by default.
These assertions are async, so always write await in front of them.
The most common ones:
| Assertion | Checks that |
|---|---|
| toBeVisible() | The element is visible |
| toHaveText(text) | The element has this text (the whole text, or a match for a regular expression) |
| toContainText(text) | The element contains this text |
| toHaveValue(value) | An input has this value |
| toBeChecked() | A checkbox or radio button is checked |
| toBeEnabled() | The element is enabled |
| toBeDisabled() | The element is disabled |
| toHaveCount(n) | The locator matches exactly n elements |
| toHaveAttribute(name, value) | The element has this attribute value |
| toHaveClass(className) | The element has this class attribute |
| toHaveURL(url) | The page has this URL |
| toHaveTitle(title) | The page has this title |
This test uses most of them on the practice todo list and actions page:
Example
tests/web-first.spec.js
// @ts-check
import { test, expect } from '@playwright/test';
test('web-first assertions on the todo list', async ({ page }) => {
await page.goto('https://www.w3schools.com/playwright/practice/todo.html');
await expect(page).toHaveTitle('Todo List | Playwright Practice');
await expect(page).toHaveURL(/todo\.html/);
const input = page.getByPlaceholder('What needs to be done?');
await expect(input).toBeEnabled();
await input.fill('Buy milk');
await expect(input).toHaveValue('Buy milk');
await input.press('Enter');
const item = page.getByRole('listitem');
await expect(item).toHaveCount(1);
await expect(item).toContainText('Buy milk');
await page.getByRole('checkbox', { name: 'Complete Buy milk' }).check();
await expect(page.getByRole('checkbox', { name: 'Complete Buy milk' })).toBeChecked();
await expect(item).toHaveClass('done');
await expect(page.getByTestId('todo-count')).toHaveText('0 items left');
await page.getByRole('button', { name: 'Done' }).click();
await expect(page.getByRole('button', { name: 'Done' })).toHaveAttribute('aria-pressed', 'true');
await expect(page.getByRole('button', { name: 'All' })).not.toHaveAttribute('aria-pressed', 'true');
});
test('enabled and disabled', async ({ page }) => {
await page.goto('https://www.w3schools.com/playwright/practice/actions.html');
const save = page.getByRole('button', { name: 'Save note' });
await expect(save).toBeDisabled();
await page.getByLabel('Notes').fill('Buy milk');
await expect(save).toBeEnabled();
await expect(page.getByRole('tooltip')).not.toBeVisible();
});
Output:
Running 2 tests using 2 workers
[1/2] [chromium] › tests/web-first.spec.js:29:1 › enabled and disabled
[2/2] [chromium] › tests/web-first.spec.js:4:1 › web-first assertions on the todo list
2 passed (2.2s)
toHaveText() and toHaveURL() take a string or a regular expression.
toHaveClass('done') matches the whole class attribute.
To check one class when the element has several, use toContainClass('done').
Negation with not
Put .not before the matcher to check the opposite:
Example
await expect(page.getByRole('tooltip')).not.toBeVisible();
await expect(page.getByRole('button', { name: 'All' })).not.toHaveAttribute('aria-pressed', 'true');
A negated assertion also retries: it waits until the condition is no longer true.
For example, not.toBeVisible() waits for a loading message to disappear.
Tip: toBeHidden() is the same as not.toBeVisible().
To check plain values like numbers and arrays, see Generic Assertions.
To keep a test running after a failed check, see Soft Assertions.