Lesson · 20 min

Assertions

An assertion states a fact

An assertion checks a fact about the page. When the fact is true, the test goes on. When it is false, the test stops and fails, and the report shows what the page had.

await expect(page.getByRole('alert')).toHaveText('Wrong email or password.');

Playwright has two kinds of assertions.

Web-first assertions work on a locator or a page. They wait. If the fact is not true yet, Playwright looks again and again, until the fact is true or the time limit ends. Use them for everything on the page, because a page changes over time. Write await in front of them.

Generic assertions work on a plain value, such as a number or a text. They do not wait. expect(count).toBe(3) checks the value once. Use them for values in your own code.

The assertions that you will use most

Assertion	Checks that
`toBeVisible()` and `toBeHidden()`	The element is shown, or it is not shown.
`toHaveText('...')`	The text of the element is exactly this.
`toContainText('...')`	The text of the element has this text inside it.
`toHaveValue('...')`	A form field has this value.
`toBeChecked()`	A checkbox is ticked.
`toBeEnabled()` and `toBeDisabled()`	A control can be used, or it cannot.
`toBeEmpty()`	A field or element has no content.
`toHaveAttribute('name', 'value')`	An attribute has a value.
`toHaveCount(n)`	The locator matches this many elements.
`toHaveURL('...')`	The address of the page is this.
`toHaveTitle('...')`	The title of the page is this.

Put .not in front of an assertion to turn it around: await expect(box).not.toBeChecked(). Web-first assertions wait for the opposite fact too.

Exact or partial text

toHaveText compares the full text, after Playwright removes extra spaces. toContainText looks for a piece. Both accept a regular expression.

await expect(page.getByRole('alert')).toHaveText('Wrong email or password.');
await expect(page.getByRole('alert')).toContainText('Wrong email');
await expect(page.getByRole('alert')).toHaveText(/wrong email/i);

Use toHaveText when the exact words matter, for example an error message that the product team wrote. Use toContainText when only one part matters, for example a name inside a long sentence.

Many elements

When a locator matches many elements, toHaveText takes a list and compares each element in order.

await expect(page.getByRole('listitem')).toHaveText(['Buy milk', 'Write a test', 'Walk the dog']);

Soft assertions

A normal assertion stops the test when it fails. expect.soft records the failure and goes on, so one run can show several problems. The test still fails at the end.

await expect.soft(page.getByRole('heading')).toHaveText('Sign in');

Your turn

Write four tests for the sign-in page.

Tasks

4 to do

Task 1, not checked yet. Add a test named rejects a wrong password. Open /login. Sign in as ada@example.com with the password not-the-password. Check that the alert has the text Wrong email or password. with toHaveText, and that the page address is still /login with toHaveURL.
Task 2, not checked yet. Add a test named shows the password. Check that the field Password has the attribute type with the value password. Click the button Show password. Check that the attribute is now text. Use toHaveAttribute.
Task 3, not checked yet. Add a test named ticks the remember box. Check that the box Remember me is not checked, with .not.toBeChecked(). Tick it with check(). Check that it is checked, with toBeChecked().
Task 4, not checked yet. Add a test named complains about an empty form. Before you click, check that the field Email is empty (toBeEmpty) and that the button Sign in is enabled (toBeEnabled). Click Sign in with nothing typed. Check that there are two alerts (toHaveCount(2)), and that the page shows Enter a valid email address.

Task 1 of 4

Add a test named rejects a wrong password. Open /login. Sign in as ada@example.com with the password not-the-password. Check that the alert has the text Wrong email or password. with toHaveText, and that the page address is still /login with toHaveURL.

All tasks