Playwright Assertions

Learn how to use Playwright's powerful assertion library to validate your tests.

What are Assertions?

Assertions are used to verify that the application under test behaves as expected. Playwright provides a rich set of assertion methods to help you validate various conditions in your tests.

Playwright provides built-in assertions using the expect() function.

Common Assertion Methods

1. Visibility Assertions:

toBeVisible()

Checks if an element is visible on the page.

await expect(page.getByRole('button', { name: 'Submit' })).toBeVisible();

or

await expect(page.locator('#loginButton')).toBeVisible();

2. Text Assertions:

toHaveText()

Verifies that an element contains specific text.

await expect(page.getByRole('heading')).toHaveText('Welcome');

or

await expect(page.locator('.message')).toHaveText('Login Successful');

3. Attribute Assertions:

toHaveAttribute()

Checks if an element has a specific attribute with a given value.

await expect(page.getByRole('link')).toHaveAttribute('href', '/home');

or

Checks if the page URL matches expected value.

await expect(page).toHaveURL('https://example.com/dashboard');

4. Class Assertions:

toHaveClass()

Verifies that an element has a specific CSS class.

await expect(page.getByRole('button')).toHaveClass(/primary/);

5. Value Assertions:

toHaveValue()

Checks if an input element has a specific value.

await expect(page.getByRole('textbox')).toHaveValue('Hello World');

6. URL Assertions:

toHaveURL()

Checks if the page URL matches expected value.

await expect(page).toHaveURL('https://example.com/dashboard');

7. Title Assertions:

toHaveTitle()

Checks the webpage title.

await expect(page).toHaveTitle('Dashboard');

8. Element State Assertions:

These verify element states such as enabled, disabled, checked, toBeUnchecked, etc..

toBeEnabled()

await expect(page.locator('#submit')).toBeEnabled();

toBeDisabled()

await expect(page.locator('#submit')).toBeDisabled();

toBeChecked()

await expect(page.locator('#agreeTerms')).toBeChecked();

toBeUnchecked()

await expect(page.locator('#agreeTerms')).toBeUnchecked();

9. Auto Waiting in Assertions

Playwright's assertions automatically wait for the expected condition to be met before proceeding. This means you don't need to add explicit waits in your tests, making them more reliable and easier to read.

For example, if you assert that an element should be visible, Playwright will wait until the element becomes visible before failing the test.

await expect(page.getByRole('button', { name: 'Submit' })).toBeVisible();

Playwright will wait until the element becomes visible within the timeout period.

Benefits:

• Reduces flaky tests
• No need for manual waits
• Improves test reliability

Soft vs Hard Assertions

1. Hard Assertion

A hard assertion will immediately fail the test if the condition is not met. This is the default behavior of Playwright's assertions.

expect(value).toBe(10);

2. Soft Assertion

A soft assertion allows the test to continue even if the condition is not met. This can be useful for collecting multiple assertion results before deciding to fail the test.

expect.soft(value).toBe(10);

This is useful when validating multiple elements in one test.