mirror of
https://github.com/microsoft/playwright.git
synced 2025-06-26 21:40:17 +00:00
177 lines
6.3 KiB
Markdown
177 lines
6.3 KiB
Markdown
---
|
|
id: test-assertions
|
|
title: "Assertions"
|
|
---
|
|
|
|
Playwright includes test assertions in the form of `expect` function. To make an assertion, call `expect(value)` and choose a matcher that reflects the expectation. There are many [generic matchers](./api/class-genericassertions.md) like `toEqual`, `toContain`, `toBeTruthy` that can be used to assert any conditions.
|
|
|
|
```js
|
|
expect(success).toBeTruthy();
|
|
```
|
|
|
|
Playwright also includes web-specific [async matchers](./api/class-locatorassertions.md) that will wait until
|
|
the expected condition is met. Consider the following example:
|
|
|
|
```js
|
|
await expect(page.getByTestId('status')).toHaveText('Submitted');
|
|
```
|
|
|
|
Playwright will be re-testing the element with the test id of `status` until the fetched element has the `"Submitted"` text. It will re-fetch the element and check it over and over, until the condition is met or until the timeout is reached. You can either pass this timeout or configure it once via the [`property: TestConfig.expect`] value in the test config.
|
|
|
|
By default, the timeout for assertions is set to 5 seconds. Learn more about [various timeouts](./test-timeouts.md).
|
|
|
|
## List of assertions
|
|
|
|
| Assertion | Description |
|
|
| :- | :- |
|
|
| [`method: LocatorAssertions.toBeChecked`] | Checkbox is checked |
|
|
| [`method: LocatorAssertions.toBeDisabled`] | Element is disabled |
|
|
| [`method: LocatorAssertions.toBeEditable`] | Element is enabled |
|
|
| [`method: LocatorAssertions.toBeEmpty`] | Container is empty |
|
|
| [`method: LocatorAssertions.toBeEnabled`] | Element is enabled |
|
|
| [`method: LocatorAssertions.toBeFocused`] | Element is focused |
|
|
| [`method: LocatorAssertions.toBeHidden`] | Element is not visible |
|
|
| [`method: LocatorAssertions.toBeVisible`] | Element is visible |
|
|
| [`method: LocatorAssertions.toContainText`] | Element contains text |
|
|
| [`method: LocatorAssertions.toHaveAttribute`] | Element has a DOM attribute |
|
|
| [`method: LocatorAssertions.toHaveClass`] | Element has a class property |
|
|
| [`method: LocatorAssertions.toHaveCount`] | List has exact number of children |
|
|
| [`method: LocatorAssertions.toHaveCSS`] | Element has CSS property |
|
|
| [`method: LocatorAssertions.toHaveId`] | Element has an ID |
|
|
| [`method: LocatorAssertions.toHaveJSProperty`] | Element has a JavaScript property |
|
|
| [`method: LocatorAssertions.toHaveScreenshot#1`] | Element has a screenshot |
|
|
| [`method: LocatorAssertions.toHaveText`] | Element matches text |
|
|
| [`method: LocatorAssertions.toHaveValue`] | Input has a value |
|
|
| [`method: LocatorAssertions.toHaveValues`] | Select has options selected |
|
|
| [`method: PageAssertions.toHaveScreenshot#1`] | Page has a screenshot |
|
|
| [`method: PageAssertions.toHaveTitle`] | Page has a title |
|
|
| [`method: PageAssertions.toHaveURL`] | Page has a URL |
|
|
| [`method: APIResponseAssertions.toBeOK`] | Response has an OK status |
|
|
|
|
## Negating Matchers
|
|
|
|
In general, we can expect the opposite to be true by adding a `.not` to the front
|
|
of the matchers:
|
|
|
|
```js
|
|
expect(value).not.toEqual(0);
|
|
await expect(locator).not.toContainText("some text");
|
|
```
|
|
|
|
## Soft Assertions
|
|
|
|
By default, failed assertion will terminate test execution. Playwright also
|
|
supports *soft assertions*: failed soft assertions **do not** terminate test execution,
|
|
but mark the test as failed.
|
|
|
|
```js
|
|
// Make a few checks that will not stop the test when failed...
|
|
await expect.soft(page.getByTestId('status')).toHaveText('Success');
|
|
await expect.soft(page.getByTestId('eta')).toHaveText('1 day');
|
|
|
|
// ... and continue the test to check more things.
|
|
await page.getByRole('link', { name: 'next page' }).click();
|
|
await expect.soft(page.getByRole('heading', { name: 'Make another order' })).toBeVisible();
|
|
```
|
|
|
|
At any point during test execution, you can check whether there were any
|
|
soft assertion failures:
|
|
|
|
```js
|
|
// Make a few checks that will not stop the test when failed...
|
|
await expect.soft(page.getByTestId('status')).toHaveText('Success');
|
|
await expect.soft(page.getByTestId('eta')).toHaveText('1 day');
|
|
|
|
// Avoid running further if there were soft assertion failures.
|
|
expect(test.info().errors).toHaveLength(0);
|
|
```
|
|
|
|
Note that soft assertions only work with Playwright test runner.
|
|
|
|
## Custom Expect Message
|
|
|
|
You can specify a custom error message as a second argument to the `expect` function, for example:
|
|
|
|
```js
|
|
await expect(page.getByText('Name'), 'should be logged in').toBeVisible();
|
|
```
|
|
|
|
The error would look like this:
|
|
|
|
```bash
|
|
Error: should be logged in
|
|
|
|
Call log:
|
|
- expect.toBeVisible with timeout 5000ms
|
|
- waiting for "getByText('Name')"
|
|
|
|
|
|
2 |
|
|
3 | test('example test', async({ page }) => {
|
|
> 4 | await expect(page.getByText('Name'), 'should be logged in').toBeVisible();
|
|
| ^
|
|
5 | });
|
|
6 |
|
|
```
|
|
|
|
The same works with soft assertions:
|
|
|
|
```js
|
|
expect.soft(value, 'my soft assertion').toBe(56);
|
|
```
|
|
|
|
## Polling
|
|
|
|
You can convert any synchronous `expect` to an asynchronous polling one using `expect.poll`.
|
|
|
|
The following method will poll given function until it returns HTTP status 200:
|
|
|
|
```js
|
|
await expect.poll(async () => {
|
|
const response = await page.request.get('https://api.example.com');
|
|
return response.status();
|
|
}, {
|
|
// Custom error message, optional.
|
|
message: 'make sure API eventually succeeds', // custom error message
|
|
// Poll for 10 seconds; defaults to 5 seconds. Pass 0 to disable timeout.
|
|
timeout: 10000,
|
|
}).toBe(200);
|
|
```
|
|
|
|
You can also specify custom polling intervals:
|
|
|
|
```js
|
|
await expect.poll(async () => {
|
|
const response = await page.request.get('https://api.example.com');
|
|
return response.status();
|
|
}, {
|
|
// Probe, wait 1s, probe, wait 2s, probe, wait 10s, probe, wait 10s, probe, .... Defaults to [100, 250, 500, 1000].
|
|
intervals: [1_000, 2_000, 10_000],
|
|
timeout: 60_000
|
|
}).toBe(200);
|
|
```
|
|
|
|
## Retrying
|
|
|
|
You can retry blocks of code until they are passing successfully.
|
|
|
|
```js
|
|
await expect(async () => {
|
|
const response = await page.request.get('https://api.example.com');
|
|
expect(response.status()).toBe(200);
|
|
}).toPass();
|
|
```
|
|
|
|
You can also specify custom timeout for retry intervals:
|
|
|
|
```js
|
|
await expect(async () => {
|
|
const response = await page.request.get('https://api.example.com');
|
|
expect(response.status()).toBe(200);
|
|
}).toPass({
|
|
// Probe, wait 1s, probe, wait 2s, probe, wait 10s, probe, wait 10s, probe, .... Defaults to [100, 250, 500, 1000].
|
|
intervals: [1_000, 2_000, 10_000],
|
|
timeout: 60_000
|
|
});
|
|
```
|