playwright/docs/src/test-assertions-js.md

id	title
test-assertions	Assertions

Playwright Test uses expect library for test assertions. This library provides a lot of matchers like toEqual, toContain, toMatch, toMatchSnapshot and many more:

expect(success).toBeTruthy();

Playwright also extends it with convenience async matchers that will wait until the expected condition is met.

Matching

Consider the following example:

await expect(page.locator('.status')).toHaveText('Submitted');

Playwright Test will be re-testing the node with the selector .status until fetched Node has the "Submitted" text. It will be re-fetching the node and checking 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: Fixtures.actionTimeout] value in test config.

By default, the timeout for assertions is not set, so it'll wait forever, until the whole test times out.

expect(locator).toBeChecked

• options
  • timeout: <[number]> Time to retry assertion for, defaults to [property: Fixtures.actionTimeout].

Ensures [Locator] points to the checked input.

const locator = await page.locator('.subscribe');
await expect(locator).toBeChecked();

expect(locator).toBeDisabled

• options
  • timeout: <[number]> Time to retry assertion for, defaults to [property: Fixtures.actionTimeout].

Ensures [Locator] points to a disabled element.

const locator = await page.locator('button.submit');
await expect(locator).toBeDisabled();

expect(locator).toBeEditable

• options
  • timeout: <[number]> Time to retry assertion for, defaults to [property: Fixtures.actionTimeout].

Ensures [Locator] points to an editable element.

const locator = await page.locator('input');
await expect(locator).toBeEditable();

expect(locator).toBeEmpty

• options
  • timeout: <[number]> Time to retry assertion for, defaults to [property: Fixtures.actionTimeout].

Ensures [Locator] points to an empty editable element or to a DOM node that has no text.

const locator = await page.locator('div.warning');
await expect(locator).toBeEmpty();

expect(locator).toBeEnabled

• options
  • timeout: <[number]> Time to retry assertion for, defaults to [property: Fixtures.actionTimeout].

Ensures [Locator] points to an enabled element.

const locator = await page.locator('button.submit');
await expect(locator).toBeEnabled();

expect(locator).toBeFocused

• options
  • timeout: <[number]> Time to retry assertion for, defaults to [property: Fixtures.actionTimeout].

Ensures [Locator] points to a focused DOM node.

const locator = await page.locator('input');
await expect(locator).toBeFocused();

expect(locator).toBeHidden

• options
  • timeout: <[number]> Time to retry assertion for, defaults to [property: Fixtures.actionTimeout].

Ensures [Locator] points to a hidden DOM node, which is the opposite of visible.

const locator = await page.locator('.my-element');
await expect(locator).toBeHidden();

expect(locator).toBeSelected

• options
  • timeout: <[number]> Time to retry assertion for, defaults to [property: Fixtures.actionTimeout].

Ensures [Locator] points to a selected option.

const locator = await page.locator('option[value=Three]');
await expect(locator).toBeSelected();

expect(locator).toBeVisible

• options
  • timeout: <[number]> Time to retry assertion for, defaults to [property: Fixtures.actionTimeout].

Ensures [Locator] points to a visible DOM node.

const locator = await page.locator('.my-element');
await expect(locator).toBeVisible();

expect(locator).toContainText(text, options?)

• text: <[string]> Text to look for inside the element
• options
  • timeout: <[number]> Time to wait for, defaults to [property: Fixtures.actionTimeout].
  • useInnerText: <[boolean]> Whether to use element.innerText instead of element.textContent when retrieving DOM node text.

Ensures [Locator] points to a selected option.

const locator = await page.locator('.title');
await expect(locator).toContainText('substring');

expect(locator).toHaveAttr(name, value)

• name: <[string]> Attribute name
• value: <[string]|[RegExp]> Attribute value
• options
  • timeout: <[number]> Time to retry assertion for, defaults to [property: Fixtures.actionTimeout].

Ensures [Locator] points to an element with given attribute.

const locator = await page.locator('input');
await expect(locator).toHaveAttr('type', 'text');

expect(locator).toHaveClass(expected)

• expected: <[string] | [RegExp] | [Array]<[string]>>
• options
  • timeout: <[number]> Time to retry assertion for, defaults to [property: Fixtures.actionTimeout].

Ensures [Locator] points to an element with given CSS class.

const locator = await page.locator('#component');
await expect(locator).toHaveClass(/selected/);

Note that if array is passed as an expected value, entire lists can be asserted:

const locator = await page.locator('list > #component');
await expect(locator).toHaveClass(['component', 'component selected', 'component']);

expect(locator).toHaveCount(count)

• count: <[number]>
• options
  • timeout: <[number]> Time to retry assertion for, defaults to [property: Fixtures.actionTimeout].

Ensures [Locator] resolves to an exact number of DOM nodes.

const list = await page.locator('list > #component');
await expect(list).toHaveCount(3);

expect(locator).toHaveCSS(name, value)

• name: <[string]> CSS property name
• value: <[string]|[RegExp]> CSS property value
• options
  • timeout: <[number]> Time to retry assertion for, defaults to [property: Fixtures.actionTimeout].

Ensures [Locator] resolves to an element with the given computed CSS style

const locator = await page.locator('button');
await expect(locator).toHaveCSS('display', 'flex');

expect(locator).toHaveData(name, value)

• name: <[string]> Data attribute name
• value: <[string]|[RegExp]> Data value
• options
  • timeout: <[number]> Time to retry assertion for, defaults to [property: Fixtures.actionTimeout].

Ensures [Locator] points to an element with given data binding.

const locator = await page.locator('input');
await expect(locator).toHaveData('mydata', 'myvalue');

expect(locator).toHaveId(id)

• id: <[string]> Element id
• options
  • timeout: <[number]> Time to retry assertion for, defaults to [property: Fixtures.actionTimeout].

Ensures [Locator] points to an element with the given DOM Node ID.

const locator = await page.locator('input');
await expect(locator).toHaveId('lastname');

expect(locator).toHaveProp(name, value)

• name: <[string]> Property name
• value: <[any]> Property value
• options
  • timeout: <[number]> Time to retry assertion for, defaults to [property: Fixtures.actionTimeout].

Ensures [Locator] points to an element with given JavaScript property. Note that this property can be of a primitive type as well as a plain serializable JavaScript object.

const locator = await page.locator('.component');
await expect(locator).toHaveProp('loaded', true);

expect(locator).toHaveText(expected, options)

• expected: <[string] | [RegExp] | [Array]<[string]>>
• options
  • timeout: <[number]> Time to retry assertion for, defaults to [property: Fixtures.actionTimeout].
  • useInnerText: <[boolean]> Whether to use element.innerText instead of element.textContent when retrieving DOM node text.

Ensures [Locator] points to an element with the given text. You can use regular expressions for the value as well.

const locator = await page.locator('.title');
await expect(locator).toHaveText(/Welcome, .*/);

Note that if array is passed as an expected value, entire lists can be asserted:

const locator = await page.locator('list > #component');
await expect(locator).toHaveText(['Text 1', 'Text 2', 'Text 3']);

expect(page).toHaveTitle(title)

• title: <[string] | [RegExp]>>
• options
  • timeout: <[number]> Time to retry assertion for, defaults to [property: Fixtures.actionTimeout].

Ensures page has a given title.

await expect(page).toHaveTitle(/.*checkout/);

expect(page).toHaveURL(url)

• url: <[string] | [RegExp]>>
• options
  • timeout: <[number]> Time to retry assertion for, defaults to [property: Fixtures.actionTimeout].

Ensures page is navigated to a given URL.

await expect(page).toHaveURL(/.*checkout/);

expect(locator).toHaveValue(value)

• value: <[string] | [RegExp]>>
• options
  • timeout: <[number]> Time to retry assertion for, defaults to [property: Fixtures.actionTimeout].

Ensures [Locator] points to an element with the given input value. You can use regular expressions for the value as well.

const locator = await page.locator('input[type=number]');
await expect(locator).toHaveValue(/[0-9]/);