LocatorAssertions
Source URL: https://playwright.dev/docs/api/class-locatorassertions
LocatorAssertions | Playwright
섹션 제목: “LocatorAssertions | Playwright”The LocatorAssertions class provides assertion methods that can be used to make assertions about the Locator state in the tests.
import { test, expect } from '@playwright/test';
test('status becomes submitted', async ({ page }) => { // ... await page.getByRole('button').click(); await expect(page.locator('.status')).toHaveText('Submitted'); });Methods
섹션 제목: “Methods”toBeAttached
섹션 제목: “toBeAttached”Added in: v1.33 locatorAssertions.toBeAttached
Ensures that Locator points to an element that is connected to a Document or a ShadowRoot.
Usage
await expect(page.getByText('Hidden text')).toBeAttached();Arguments
Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toBeChecked
섹션 제목: “toBeChecked”Added in: v1.20 locatorAssertions.toBeChecked
Ensures the Locator points to a checked input.
Usage
const locator = page.getByLabel('Subscribe to newsletter'); await expect(locator).toBeChecked();Arguments
Provides state to assert for. Asserts for input to be checked by default. This option can’t be used when indeterminate is set to true.
* `indeterminate` [boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type "Boolean") _(optional)_ Added in: v1.50[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-be-checked-option-indeterminate)Asserts that the element is in the indeterminate (mixed) state. Only supported for checkboxes and radio buttons. This option can’t be true when checked is provided.
* `timeout` [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number") _(optional)_ Added in: v1.18[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-be-checked-option-timeout)Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toBeDisabled
섹션 제목: “toBeDisabled”Added in: v1.20 locatorAssertions.toBeDisabled
Ensures the Locator points to a disabled element. Element is disabled if it has “disabled” attribute or is disabled via ‘aria-disabled’. Note that only native control elements such as HTML button, input, select, textarea, option, optgroup can be disabled by setting “disabled” attribute. “disabled” attribute on other elements is ignored by the browser.
Usage
const locator = page.locator('button.submit'); await expect(locator).toBeDisabled();Arguments
Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toBeEditable
섹션 제목: “toBeEditable”Added in: v1.20 locatorAssertions.toBeEditable
Ensures the Locator points to an editable element.
Usage
const locator = page.getByRole('textbox'); await expect(locator).toBeEditable();Arguments
optionsObject (optional)
Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toBeEmpty
섹션 제목: “toBeEmpty”Added in: v1.20 locatorAssertions.toBeEmpty
Ensures the Locator points to an empty editable element or to a DOM node that has no text.
Usage
const locator = page.locator('div.warning'); await expect(locator).toBeEmpty();Arguments
Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toBeEnabled
섹션 제목: “toBeEnabled”Added in: v1.20 locatorAssertions.toBeEnabled
Ensures the Locator points to an enabled element.
Usage
const locator = page.locator('button.submit'); await expect(locator).toBeEnabled();Arguments
optionsObject (optional)
Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toBeFocused
섹션 제목: “toBeFocused”Added in: v1.20 locatorAssertions.toBeFocused
Ensures the Locator points to a focused DOM node.
Usage
const locator = page.getByRole('textbox'); await expect(locator).toBeFocused();Arguments
Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toBeHidden
섹션 제목: “toBeHidden”Added in: v1.20 locatorAssertions.toBeHidden
Ensures that Locator either does not resolve to any DOM node, or resolves to a non-visible one.
Usage
const locator = page.locator('.my-element'); await expect(locator).toBeHidden();Arguments
Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toBeInViewport
섹션 제목: “toBeInViewport”Added in: v1.31 locatorAssertions.toBeInViewport
Ensures the Locator points to an element that intersects viewport, according to the intersection observer API.
Usage
const locator = page.getByRole('button'); // Make sure at least some part of element intersects viewport. await expect(locator).toBeInViewport(); // Make sure element is fully outside of viewport. await expect(locator).not.toBeInViewport(); // Make sure that at least half of the element intersects viewport. await expect(locator).toBeInViewport({ ratio: 0.5 });Arguments
The minimal ratio of the element to intersect viewport. If equals to 0, then element should intersect viewport at any positive ratio. Defaults to 0.
* `timeout` [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number") _(optional)_[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-be-in-viewport-option-timeout)Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toBeVisible
섹션 제목: “toBeVisible”Added in: v1.20 locatorAssertions.toBeVisible
Ensures that Locator points to an attached and visible DOM node.
To check that at least one element from the list is visible, use locator.first().
Usage
// A specific element is visible. await expect(page.getByText('Welcome')).toBeVisible();
// At least one item in the list is visible. await expect(page.getByTestId('todo-item').first()).toBeVisible();
// At least one of the two elements is visible, possibly both. await expect( page.getByRole('button', { name: 'Sign in' }) .or(page.getByRole('button', { name: 'Sign up' })) .first() ).toBeVisible();Arguments
Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
* `visible` [boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type "Boolean") _(optional)_ Added in: v1.26[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-be-visible-option-visible)Returns
toContainClass
섹션 제목: “toContainClass”Added in: v1.52 locatorAssertions.toContainClass
Ensures the Locator points to an element with given CSS classes. All classes from the asserted value, separated by spaces, must be present in the Element.classList in any order.
Usage
<div class='middle selected row' id='component'></div> const locator = page.locator('#component'); await expect(locator).toContainClass('middle selected row'); await expect(locator).toContainClass('selected'); await expect(locator).toContainClass('row middle');When an array is passed, the method asserts that the list of elements located matches the corresponding list of expected class lists. Each element’s class attribute is matched against the corresponding class in the array:
<div class='component inactive'></div> <div class='component active'></div> <div class='component inactive'></div> const locator = page.locator('.list > .component'); await expect(locator).toContainClass(['inactive', 'active', 'inactive']);Arguments
A string containing expected class names, separated by spaces, or a list of such strings to assert multiple elements.
Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toContainText
섹션 제목: “toContainText”Added in: v1.20 locatorAssertions.toContainText
Ensures the Locator points to an element that contains the given text. All nested elements will be considered when computing the text content of the element. You can use regular expressions for the value as well.
Usage
const locator = page.locator('.title'); await expect(locator).toContainText('substring'); await expect(locator).toContainText(/\d messages/);If you pass an array as an expected value, the expectations are:
- Locator resolves to a list of elements.
- Elements from a subset of this list contain text from the expected array, respectively.
- The matching subset of elements has the same order as the expected array.
- Each text value from the expected array is matched by some element from the list.
For example, consider the following list:
<ul> <li>Item Text 1</li> <li>Item Text 2</li> <li>Item Text 3</li> </ul>Let’s see how we can use the assertion:
// ✓ Contains the right items in the right order await expect(page.locator('ul > li')).toContainText(['Text 1', 'Text 3']);
// ✖ Wrong order await expect(page.locator('ul > li')).toContainText(['Text 3', 'Text 2']);
// ✖ No item contains this text await expect(page.locator('ul > li')).toContainText(['Some 33']);
// ✖ Locator points to the outer list element, not to the list items await expect(page.locator('ul')).toContainText(['Text 3']);Arguments
Expected substring or RegExp or a list of those.
Whether to perform case-insensitive match. ignoreCase option takes precedence over the corresponding regular expression flag if specified.
* `timeout` [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number") _(optional)_ Added in: v1.18[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-contain-text-option-timeout)Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
* `useInnerText` [boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type "Boolean") _(optional)_ Added in: v1.18[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-contain-text-option-use-inner-text)Whether to use element.innerText instead of element.textContent when retrieving DOM node text.
Returns
Details
When expected parameter is a string, Playwright will normalize whitespaces and line breaks both in the actual text and in the expected string before matching. When regular expression is used, the actual text is matched as is.
toHaveAccessibleDescription
섹션 제목: “toHaveAccessibleDescription”Added in: v1.44 locatorAssertions.toHaveAccessibleDescription
Ensures the Locator points to an element with a given accessible description.
Usage
const locator = page.getByTestId('save-button'); await expect(locator).toHaveAccessibleDescription('Save results to disk');Arguments
Expected accessible description.
Whether to perform case-insensitive match. ignoreCase option takes precedence over the corresponding regular expression flag if specified.
* `timeout` [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number") _(optional)_[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-accessible-description-option-timeout)Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toHaveAccessibleErrorMessage
섹션 제목: “toHaveAccessibleErrorMessage”Added in: v1.50 locatorAssertions.toHaveAccessibleErrorMessage
Ensures the Locator points to an element with a given aria errormessage.
Usage
const locator = page.getByTestId('username-input'); await expect(locator).toHaveAccessibleErrorMessage('Username is required.');Arguments
Expected accessible error message.
Whether to perform case-insensitive match. ignoreCase option takes precedence over the corresponding regular expression flag if specified.
* `timeout` [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number") _(optional)_[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-accessible-error-message-option-timeout)Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toHaveAccessibleName
섹션 제목: “toHaveAccessibleName”Added in: v1.44 locatorAssertions.toHaveAccessibleName
Ensures the Locator points to an element with a given accessible name.
Usage
const locator = page.getByTestId('save-button'); await expect(locator).toHaveAccessibleName('Save to disk');Arguments
Expected accessible name.
Whether to perform case-insensitive match. ignoreCase option takes precedence over the corresponding regular expression flag if specified.
* `timeout` [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number") _(optional)_[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-accessible-name-option-timeout)Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toHaveAttribute(name, value)
섹션 제목: “toHaveAttribute(name, value)”Added in: v1.20 locatorAssertions.toHaveAttribute(name, value)
Ensures the Locator points to an element with given attribute.
Usage
const locator = page.locator('input'); await expect(locator).toHaveAttribute('type', 'text');Arguments
Attribute name.
Expected attribute value.
Whether to perform case-insensitive match. ignoreCase option takes precedence over the corresponding regular expression flag if specified.
* `timeout` [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number") _(optional)_ Added in: v1.18[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-attribute-option-timeout)Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toHaveAttribute(name)
섹션 제목: “toHaveAttribute(name)”Added in: v1.39 locatorAssertions.toHaveAttribute(name)
Ensures the Locator points to an element with given attribute. The method will assert attribute presence.
const locator = page.locator('input'); // Assert attribute existence. await expect(locator).toHaveAttribute('disabled'); await expect(locator).not.toHaveAttribute('open');Usage
await expect(locator).toHaveAttribute(name); await expect(locator).toHaveAttribute(name, options);Arguments
Attribute name.
Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toHaveClass
섹션 제목: “toHaveClass”Added in: v1.20 locatorAssertions.toHaveClass
Ensures the Locator points to an element with given CSS classes. When a string is provided, it must fully match the element’s class attribute. To match individual classes use expect(locator).toContainClass().
Usage
<div class='middle selected row' id='component'></div> const locator = page.locator('#component'); await expect(locator).toHaveClass('middle selected row'); await expect(locator).toHaveClass(/(^|\s)selected(\s|$)/);When an array is passed, the method asserts that the list of elements located matches the corresponding list of expected class values. Each element’s class attribute is matched against the corresponding string or regular expression in the array:
const locator = page.locator('.list > .component'); await expect(locator).toHaveClass(['component', 'component selected', 'component']);Arguments
Expected class or RegExp or a list of those.
Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toHaveCount
섹션 제목: “toHaveCount”Added in: v1.20 locatorAssertions.toHaveCount
Ensures the Locator resolves to an exact number of DOM nodes.
Usage
const list = page.locator('list > .component'); await expect(list).toHaveCount(3);Arguments
Expected count.
Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toHaveCSS
섹션 제목: “toHaveCSS”Added in: v1.20 locatorAssertions.toHaveCSS
Ensures the Locator resolves to an element with the given computed CSS style.
Usage
const locator = page.getByRole('button'); await expect(locator).toHaveCSS('display', 'flex');Arguments
CSS property name.
CSS property value.
Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toHaveId
섹션 제목: “toHaveId”Added in: v1.20 locatorAssertions.toHaveId
Ensures the Locator points to an element with the given DOM Node ID.
Usage
const locator = page.getByRole('textbox'); await expect(locator).toHaveId('lastname');Arguments
Element id.
Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toHaveJSProperty
섹션 제목: “toHaveJSProperty”Added in: v1.20 locatorAssertions.toHaveJSProperty
Ensures the 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.
Usage
const locator = page.locator('.component'); await expect(locator).toHaveJSProperty('loaded', true);Arguments
Property name.
Property value.
Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toHaveRole
섹션 제목: “toHaveRole”Added in: v1.44 locatorAssertions.toHaveRole
Ensures the Locator points to an element with a given ARIA role.
Note that role is matched as a string, disregarding the ARIA role hierarchy. For example, asserting a superclass role "checkbox" on an element with a subclass role "switch" will fail.
Usage
const locator = page.getByTestId('save-button'); await expect(locator).toHaveRole('button');Arguments
role“alert” | “alertdialog” | “application” | “article” | “banner” | “blockquote” | “button” | “caption” | “cell” | “checkbox” | “code” | “columnheader” | “combobox” | “complementary” | “contentinfo” | “definition” | “deletion” | “dialog” | “directory” | “document” | “emphasis” | “feed” | “figure” | “form” | “generic” | “grid” | “gridcell” | “group” | “heading” | “img” | “insertion” | “link” | “list” | “listbox” | “listitem” | “log” | “main” | “marquee” | “math” | “meter” | “menu” | “menubar” | “menuitem” | “menuitemcheckbox” | “menuitemradio” | “navigation” | “none” | “note” | “option” | “paragraph” | “presentation” | “progressbar” | “radio” | “radiogroup” | “region” | “row” | “rowgroup” | “rowheader” | “scrollbar” | “search” | “searchbox” | “separator” | “slider” | “spinbutton” | “status” | “strong” | “subscript” | “superscript” | “switch” | “tab” | “table” | “tablist” | “tabpanel” | “term” | “textbox” | “time” | “timer” | “toolbar” | “tooltip” | “tree” | “treegrid” | “treeitem”#
Required aria role.
Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toHaveScreenshot(name)
섹션 제목: “toHaveScreenshot(name)”Added in: v1.23 locatorAssertions.toHaveScreenshot(name)
This function will wait until two consecutive locator screenshots yield the same result, and then compare the last screenshot with the expectation.
Usage
const locator = page.getByRole('button'); await expect(locator).toHaveScreenshot('image.png');Note that screenshot assertions only work with Playwright test runner.
Arguments
Snapshot name.
When set to "disabled", stops CSS animations, CSS transitions and Web Animations. Animations get different treatment depending on their duration:
* finite animations are fast-forwarded to completion, so they'll fire `transitionend` event. * infinite animations are canceled to initial state, and then played over after the screenshot.Defaults to "disabled" that disables animations.
* `caret` "hide" | "initial" _(optional)_[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-1-option-caret)When set to "hide", screenshot will hide text caret. When set to "initial", text caret behavior will not be changed. Defaults to "hide".
* `mask` [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array")<[Locator](https://playwright.dev/docs/api/class-locator "Locator")> _(optional)_[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-1-option-mask)Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink box #FF00FF (customized by maskColor) that completely covers its bounding box. The mask is also applied to invisible elements, see Matching only visible elements to disable that.
* `maskColor` [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string") _(optional)_ Added in: v1.35[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-1-option-mask-color)Specify the color of the overlay box for masked elements, in CSS color format. Default color is pink #FF00FF.
* `maxDiffPixelRatio` [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number") _(optional)_[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-1-option-max-diff-pixel-ratio)An acceptable ratio of pixels that are different to the total amount of pixels, between 0 and 1. Default is configurable with TestConfig.expect. Unset by default.
* `maxDiffPixels` [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number") _(optional)_[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-1-option-max-diff-pixels)An acceptable amount of pixels that could be different. Default is configurable with TestConfig.expect. Unset by default.
* `omitBackground` [boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type "Boolean") _(optional)_[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-1-option-omit-background)Hides default white background and allows capturing screenshots with transparency. Not applicable to jpeg images. Defaults to false.
* `scale` "css" | "device" _(optional)_[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-1-option-scale)When set to "css", screenshot will have a single pixel per each css pixel on the page. For high-dpi devices, this will keep screenshots small. Using "device" option will produce a single pixel per each device pixel, so screenshots of high-dpi devices will be twice as large or even larger.
Defaults to "css".
* `stylePath` [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string") | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array")<[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string")> _(optional)_ Added in: v1.41[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-1-option-style-path)File name containing the stylesheet to apply while making the screenshot. This is where you can hide dynamic elements, make elements invisible or change their properties to help you creating repeatable screenshots. This stylesheet pierces the Shadow DOM and applies to the inner frames.
* `threshold` [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number") _(optional)_[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-1-option-threshold)An acceptable perceived color difference in the YIQ color space between the same pixel in compared images, between zero (strict) and one (lax), default is configurable with TestConfig.expect. Defaults to 0.2.
* `timeout` [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number") _(optional)_[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-1-option-timeout)Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toHaveScreenshot(options)
섹션 제목: “toHaveScreenshot(options)”Added in: v1.23 locatorAssertions.toHaveScreenshot(options)
This function will wait until two consecutive locator screenshots yield the same result, and then compare the last screenshot with the expectation.
Usage
const locator = page.getByRole('button'); await expect(locator).toHaveScreenshot();Note that screenshot assertions only work with Playwright test runner.
Arguments
When set to "disabled", stops CSS animations, CSS transitions and Web Animations. Animations get different treatment depending on their duration:
* finite animations are fast-forwarded to completion, so they'll fire `transitionend` event. * infinite animations are canceled to initial state, and then played over after the screenshot.Defaults to "disabled" that disables animations.
* `caret` "hide" | "initial" _(optional)_[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-2-option-caret)When set to "hide", screenshot will hide text caret. When set to "initial", text caret behavior will not be changed. Defaults to "hide".
* `mask` [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array")<[Locator](https://playwright.dev/docs/api/class-locator "Locator")> _(optional)_[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-2-option-mask)Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink box #FF00FF (customized by maskColor) that completely covers its bounding box. The mask is also applied to invisible elements, see Matching only visible elements to disable that.
* `maskColor` [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string") _(optional)_ Added in: v1.35[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-2-option-mask-color)Specify the color of the overlay box for masked elements, in CSS color format. Default color is pink #FF00FF.
* `maxDiffPixelRatio` [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number") _(optional)_[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-2-option-max-diff-pixel-ratio)An acceptable ratio of pixels that are different to the total amount of pixels, between 0 and 1. Default is configurable with TestConfig.expect. Unset by default.
* `maxDiffPixels` [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number") _(optional)_[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-2-option-max-diff-pixels)An acceptable amount of pixels that could be different. Default is configurable with TestConfig.expect. Unset by default.
* `omitBackground` [boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type "Boolean") _(optional)_[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-2-option-omit-background)Hides default white background and allows capturing screenshots with transparency. Not applicable to jpeg images. Defaults to false.
* `scale` "css" | "device" _(optional)_[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-2-option-scale)When set to "css", screenshot will have a single pixel per each css pixel on the page. For high-dpi devices, this will keep screenshots small. Using "device" option will produce a single pixel per each device pixel, so screenshots of high-dpi devices will be twice as large or even larger.
Defaults to "css".
* `stylePath` [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string") | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array")<[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string")> _(optional)_ Added in: v1.41[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-2-option-style-path)File name containing the stylesheet to apply while making the screenshot. This is where you can hide dynamic elements, make elements invisible or change their properties to help you creating repeatable screenshots. This stylesheet pierces the Shadow DOM and applies to the inner frames.
* `threshold` [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number") _(optional)_[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-2-option-threshold)An acceptable perceived color difference in the YIQ color space between the same pixel in compared images, between zero (strict) and one (lax), default is configurable with TestConfig.expect. Defaults to 0.2.
* `timeout` [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number") _(optional)_[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-2-option-timeout)Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toHaveText
섹션 제목: “toHaveText”Added in: v1.20 locatorAssertions.toHaveText
Ensures the Locator points to an element with the given text. All nested elements will be considered when computing the text content of the element. You can use regular expressions for the value as well.
Usage
const locator = page.locator('.title'); await expect(locator).toHaveText(/Welcome, Test User/); await expect(locator).toHaveText(/Welcome, .*/);If you pass an array as an expected value, the expectations are:
- Locator resolves to a list of elements.
- The number of elements equals the number of expected values in the array.
- Elements from the list have text matching expected array values, one by one, in order.
For example, consider the following list:
<ul> <li>Text 1</li> <li>Text 2</li> <li>Text 3</li> </ul>Let’s see how we can use the assertion:
// ✓ Has the right items in the right order await expect(page.locator('ul > li')).toHaveText(['Text 1', 'Text 2', 'Text 3']);
// ✖ Wrong order await expect(page.locator('ul > li')).toHaveText(['Text 3', 'Text 2', 'Text 1']);
// ✖ Last item does not match await expect(page.locator('ul > li')).toHaveText(['Text 1', 'Text 2', 'Text']);
// ✖ Locator points to the outer list element, not to the list items await expect(page.locator('ul')).toHaveText(['Text 1', 'Text 2', 'Text 3']);Arguments
Expected string or RegExp or a list of those.
Whether to perform case-insensitive match. ignoreCase option takes precedence over the corresponding regular expression flag if specified.
* `timeout` [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number") _(optional)_ Added in: v1.18[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-text-option-timeout)Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
* `useInnerText` [boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type "Boolean") _(optional)_ Added in: v1.18[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-text-option-use-inner-text)Whether to use element.innerText instead of element.textContent when retrieving DOM node text.
Returns
Details
When expected parameter is a string, Playwright will normalize whitespaces and line breaks both in the actual text and in the expected string before matching. When regular expression is used, the actual text is matched as is.
toHaveValue
섹션 제목: “toHaveValue”Added in: v1.20 locatorAssertions.toHaveValue
Ensures the Locator points to an element with the given input value. You can use regular expressions for the value as well.
Usage
const locator = page.locator('input[type=number]'); await expect(locator).toHaveValue(/[0-9]/);Arguments
Expected value.
Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toHaveValues
섹션 제목: “toHaveValues”Added in: v1.23 locatorAssertions.toHaveValues
Ensures the Locator points to multi-select/combobox (i.e. a select with the multiple attribute) and the specified values are selected.
Usage
For example, given the following element:
<select id="favorite-colors" multiple> <option value="R">Red</option> <option value="G">Green</option> <option value="B">Blue</option> </select> const locator = page.locator('id=favorite-colors'); await locator.selectOption(['R', 'G']); await expect(locator).toHaveValues([/R/, /G/]);Arguments
Expected options currently selected.
Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toMatchAriaSnapshot(expected)
섹션 제목: “toMatchAriaSnapshot(expected)”Added in: v1.49 locatorAssertions.toMatchAriaSnapshot(expected)
Asserts that the target element matches the given accessibility snapshot.
Usage
await page.goto('https://demo.playwright.dev/todomvc/'); await expect(page.locator('body')).toMatchAriaSnapshot(` - heading "todos" - textbox "What needs to be done?" `);Arguments
Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
toMatchAriaSnapshot(options)
섹션 제목: “toMatchAriaSnapshot(options)”Added in: v1.50 locatorAssertions.toMatchAriaSnapshot(options)
Asserts that the target element matches the given accessibility snapshot.
Snapshot is stored in a separate .aria.yml file in a location configured by expect.toMatchAriaSnapshot.pathTemplate and/or snapshotPathTemplate properties in the configuration file.
Usage
await expect(page.locator('body')).toMatchAriaSnapshot(); await expect(page.locator('body')).toMatchAriaSnapshot({ name: 'body.aria.yml' });Arguments
Name of the snapshot to store in the snapshot folder corresponding to this test. Generates sequential names if not specified.
* `timeout` [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number") _(optional)_[#](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-match-aria-snapshot-2-option-timeout)Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns
Properties
섹션 제목: “Properties”Added in: v1.20 locatorAssertions.not
Makes the assertion check for the opposite condition. For example, this code tests that the Locator doesn’t contain text "error":
await expect(locator).not.toContainText('error');Usage
expect(locator).notType