From ad5fe2841651aac3630e79c7d0e3ff8450c680d7 Mon Sep 17 00:00:00 2001 From: Debbie O'Brien Date: Fri, 11 Nov 2022 16:23:00 +0100 Subject: [PATCH] docs: improve locators examples and flow (#18548) --- docs/src/locators.md | 1404 ++++++++++++++++++++--------- docs/src/test-configuration-js.md | 4 + 2 files changed, 998 insertions(+), 410 deletions(-) diff --git a/docs/src/locators.md b/docs/src/locators.md index f27c8676e9..bfb4564138 100644 --- a/docs/src/locators.md +++ b/docs/src/locators.md @@ -10,13 +10,13 @@ a way to find element(s) on the page at any moment. These are the recommended built in locators. -- [`method: Page.getByRole`](#locate-based-on-accessible-attributes) to locate by explicit and implicit accessibility attributes. +- [`method: Page.getByRole`](#locate-by-role) to locate by explicit and implicit accessibility attributes. - [`method: Page.getByText`](#locate-by-text) to locate by text content. -- [`method: Page.getByLabel`](#locate-by-label-text) to locate a form control by associated label's text. -- [`method: Page.getByPlaceholder`](#locate-by-placeholder-text) to locate an input by placeholder. +- [`method: Page.getByLabel`](#locate-by-label) to locate a form control by associated label's text. +- [`method: Page.getByPlaceholder`](#locate-by-placeholder) to locate an input by placeholder. - [`method: Page.getByAltText`](#locate-by-alt-text) to locate an element, usually image, by its text alternative. -- [`method: Page.getByTitle`](#locate-by-title) to locate an element by its title. -- [`method: Page.getByTestId`](#define-explicit-contract-and-use-a-data-testid-attribute) to locate an element based on its `data-testid` attribute (other attribute can be configured). +- [`method: Page.getByTitle`](#locate-by-title) to locate an element by its title attribute. +- [`method: Page.getByTestId`](#locate-by-testid) to locate an element based on its `data-testid` attribute (other attributes can be configured). ```js await page.getByLabel('User Name').fill('John'); @@ -63,195 +63,211 @@ await page.GetByLabel("User Name").FillAsync("John"); await page.GetByLabel("Password").FillAsync("secret-password"); -await page.GetByRole("button", new() { Name = "Sign in" }).ClickAsync(); +await page.GetByRole("button", new() { NameString = "Sign in" }).ClickAsync(); await Expect(page.GetByText("Welcome, John!")).ToBeVisibleAsync(); ``` -Every time locator is used for some action, up-to-date DOM element is located in the page. So in the snippet -below, underlying DOM element is going to be located twice, prior to every action. This means that if the +## Locating elements + +Playwright comes with multiple built-in locators. To make tests resilient, we recommend prioritizing user-facing attributes and explicit contracts such as [`method: Page.getByRole`]. + +For example, consider the following DOM structure. + +```html + +``` +Locate the element by its role of `button` with name "Sign in". + +```js +await page.getByRole('button', { name: 'Sign in' }) + .click(); +``` +```java +page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Sign in")) + .click(); +``` +```python async +await page.get_by_role("button", name="Sign in").click() +``` +```python sync +page.get_by_role("button", name="Sign in").click() +``` +```csharp +await page.GetByRole("button", new() { NameString = "Sign in" }) + .ClickAsync(); +``` + +:::tip +Use the [code generator](./codegen.md) to generate a locator, and then edit it as you'd like. +::: + +Every time a locator is used for an action, an up-to-date DOM element is located in the page. In the snippet +below, the underlying DOM element will be located twice, once prior to every action. This means that if the DOM changes in between the calls due to re-render, the new element corresponding to the locator will be used. ```js -const locator = page.getByText('Submit'); -// ... +const locator = page.getByRole('button', { name: 'Sign in' }) + await locator.hover(); await locator.click(); ``` ```java -Locator locator = page.getByText("Submit"); +Locator locator = page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Sign in")) + locator.hover(); locator.click(); ``` ```python async -locator = page.get_by_text("Submit") +locator = page.get_by_role("button", name="Sign in") + await locator.hover() await locator.click() ``` ```python sync -locator = page.get_by_text("Submit") +locator = page.get_by_role("button", name="Sign in") + locator.hover() locator.click() ``` ```csharp -var locator = page.GetByText("Submit"); +var locator = page.GetByRole("button", new() { NameString = "Sign in" }) + await locator.HoverAsync(); await locator.ClickAsync(); ``` -## Strictness - -Locators are strict. This means that all operations on locators that imply -some target DOM element will throw an exception if more than one element matches -given selector. For example, the following call throws if there are several buttons in the DOM: - -```js -await page.getByRole('button').click(); -``` - -```python async -await page.get_by_role("button").click() -``` - -```python sync -page.get_by_role("button").click() -``` - -```java -page.getByRole("button").click(); -``` - -```csharp -await page.GetByRole("button").ClickAsync(); -``` - -On the other hand, Playwright understands when you perform a multiple-element operation, -so the following call works perfectly fine when locator resolves to multiple elements. - -```js -await page.getByRole('button').count(); -``` - -```python async -await page.get_by_role("button").count() -``` - -```python sync -page.get_by_role("button").count() -``` - -```java -page.getByRole("button").count(); -``` - -```csharp -await page.GetByRole("button").CountAsync(); -``` - -You can explicitly opt-out from strictness check by telling Playwright which element to use when multiple element match, through [`method: Locator.first`], [`method: Locator.last`], and [`method: Locator.nth`]. These methods are **not recommended** because when your page changes, Playwright may click on an element you did not intend. Instead, follow best practices below to create a locator that uniquely identifies the target element. - - -## Locating elements - -Playwright comes with multiple built-in ways to create a locator. To make tests resilient, we recommend prioritizing user-facing attributes and explicit contracts, and provide dedicated methods for them, such as [`method: Page.getByText`]. It is often convenient to use the [code generator](./codegen.md) to generate a locator, and then edit it as you'd like. - -```js -await page.getByText('Log in').click(); -``` -```java -page.getByText("Log in").click(); -``` -```python async -await page.get_by_text("Log in").click() -``` -```python sync -page.get_by_text("Log in").click() -``` -```csharp -await page.GetByText("Log in").ClickAsync(); -``` - -If you absolutely must use CSS or XPath locators, you can use [`method: Page.locator`] to create a locator that takes a [selector](./selectors.md) describing how to find an element in the page. - Note that all methods that create a locator, such as [`method: Page.getByLabel`], are also available on the [Locator] and [FrameLocator] classes, so you can chain them and iteratively narrow down your locator. ```js -const locator = page.frameLocator('#my-frame').getByText('Submit'); +const locator = page.frameLocator('#my-frame') + .getByRole('button', { name: 'Sign in' }); + await locator.click(); ``` ```java -Locator locator = page.frameLocator("#my-frame").getByText("Submit"); +Locator locator = page.frameLocator("#my-frame") + .getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Sign in")); + locator.click(); ``` ```python async -locator = page.frame_locator("#my-frame").get_by_text("Submit") +locator = page.frame_locator("#my-frame") + .get_by_role("button", name="Sign in") + await locator.click() ``` ```python sync -locator = page.frame_locator("my-frame").get_by_text("Submit") +locator = page.frame_locator("my-frame") + .get_by_role("button", name="Sign in") + locator.click() ``` ```csharp -var locator = page.FrameLocator("#my-frame").GetByText("Submit"); +var locator = page.FrameLocator("#my-frame") + .GetByRole("button", new() { NameString = "Sign in" }); + await locator.ClickAsync(); ``` -### Locate based on accessible attributes +### Locate by role -The [`method: Page.getByRole`] locator reflects how users and assistive technology perceive the page, for example whether some element is a button or a checkbox. When locating by role, you should usually pass the accessible name as well, so that locator pinpoints the exact element. +The [`method: Page.getByRole`] locator reflects how users and assistive technology perceive the page, for example whether some element is a button or a checkbox. When locating by role, you should usually pass the accessible name as well, so that the locator pinpoints the exact element. + +For example, consider the following DOM structure. + +```html +

my form

+
+ + + + +``` + +form with newsletter checkbox that is checked and a submit button + +You can locate each element by it's implicit role: ```js -await page.getByRole('button', { name: /submit/i }).click(); +await expect(page.getByRole('heading', { name: 'my form' })) + .toBeVisible() -await page.getByRole('checkbox', { checked: true, name: "Check me" }).check(); +await page.getByRole('checkbox', { checked: true, name: "newsletter" }) + .uncheck(); + +await page.getByRole('button', { name: /submit/i }) + .click(); ``` ```python async -await page.get_by_role("button", name=re.compile("submit", re.IGNORECASE)).click() +await expect(page.get_by_role("heading", name="my form")).to_be_visible() -await page.get_by_role("checkbox", checked=True, name="Check me").check() +await page.get_by_role("checkbox", checked=True, name="newsletter").uncheck() + +await page.get_by_role("button", name=re.compile("submit", re.IGNORECASE)).click() ``` ```python sync -page.get_by_role("button", name=re.compile("submit", re.IGNORECASE)).click() +expect(page.get_by_role("heading", name="my from")).to_be_visible() -page.get_by_role("checkbox", checked=True, name="Check me").check() +page.get_by_role("checkbox", checked=True, name="newsletter").uncheck() + +page.get_by_role("button", name=re.compile("submit", re.IGNORECASE)).click() ``` ```java -page.getByRole("button", new Page.GetByRoleOptions().setName(Pattern.compile("submit", Pattern.CASE_INSENSITIVE))).click(); +assertThat(page.getByRole("heading", new Page.GetByRoleOptions().setName("my form"))) + .isVisible(); -page.getByRole("checkbox", new Page.GetByRoleOptions().setChecked(true).setName("Check me"))).check(); +page.getByRole("checkbox", new Page.GetByRoleOptions().setChecked(true).setName("newsletter")) + .uncheck(); + +page.getByRole("button", new Page.GetByRoleOptions().setName(Pattern.compile("submit", Pattern.CASE_INSENSITIVE))) + .click(); ``` ```csharp -await page.GetByRole("button", new() { Name = new Regex("submit", RegexOptions.IgnoreCase) }).ClickAsync(); +await Expect(page.GetByRole("heading", new() { NameString = "my form" })) + .ToBeVisibleAsync(); -await page.GetByRole("checkbox", new() { Checked = true, Name = "Check me" }).CheckAsync(); +await page.GetByRole("checkbox", new() { Checked = true, NameString = "newsletter" }) + .UncheckAsync(); + +await page.GetByRole("button", new() { NameRegex = new Regex("submit", RegexOptions.IgnoreCase) }) + .ClickAsync(); ``` -Role locators follow W3C specifications for [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles), [ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and [accessible name](https://w3c.github.io/accname/#dfn-accessible-name). +form with newsletter checkbox unchecked and submit button highlighted + +Role locators include [buttons, checkboxes, headings, links, lists, tables, and many more](https://www.w3.org/TR/html-aria/#docconformance) and follow W3C specifications for [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles), [ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and [accessible name](https://w3c.github.io/accname/#dfn-accessible-name). Note that role locators **do not replace** accessibility audits and conformance tests, but rather give early feedback about the ARIA guidelines. -### Locate by label text +:::tip When to use role locators +We recommend prioritizing role locators to locate elements, as it is the closest way to how users and assistive technology perceive the page. +::: + +### Locate by label Most form controls usually have dedicated labels that could be conveniently used to interact with the form. In this case, you can locate the control by its associated label using [`method: Page.getByLabel`]. For example, consider the following DOM structure. ```html - + + ``` +password input with label of password You can fill the input after locating it by the label text: @@ -274,8 +290,12 @@ page.get_by_label("Password").fill("secret") ```csharp await page.GetByLabel("Password").FillAsync("secret"); ``` +password input with label and password filled in with encryption -### Locate by placeholder text +:::tip When to use label locators +Use this locator when locating form fields. +::: +### Locate by placeholder Inputs may have a placeholder attribute to hint to the user what value should be entered. You can locate such an input using [`method: Page.getByPlaceholder`]. @@ -285,14 +305,18 @@ For example, consider the following DOM structure. ``` +input field filled in with name@example.com + You can fill the input after locating it by the placeholder text: ```js -await page.getByPlaceholder("name@example.com").fill("playwright@microsoft.com"); +await page.getByPlaceholder("name@example.com") + .fill("playwright@microsoft.com"); ``` ```java -page.getByPlaceholder("name@example.com").fill("playwright@microsoft.com"); +page.getByPlaceholder("name@example.com") + .fill("playwright@microsoft.com"); ``` ```python async @@ -304,61 +328,111 @@ page.get_by_placeholder("name@example.com").fill("playwright@microsoft.com") ``` ```csharp -await page.GetByPlacheolder("name@example.com").FillAsync("playwright@microsoft.com"); +await page.GetByPlaceholder("name@example.com") + .FillAsync("playwright@microsoft.com"); ``` +input field filled in with playwright@microsoft.com + +:::tip When to use placeholder locators +Use this locator when locating form elements that do not have labels but do have placeholder texts. +::: + ### Locate by text -The easiest way to find an element is to look for the text it contains. You can match by a substring, exact string, or a regular expression when using [`method: Page.getByText`]. +Find an element by the text it contains. You can match by a substring, exact string, or a regular expression when using [`method: Page.getByText`]. + +For example, consider the following DOM structure. + +```html +Welcome, John +``` +Welcome, John + +You can locate the element by the text it contains: ```js -await page.getByText('Log in').click(); -await page.getByText('Log in', { exact: true }).click(); -await page.getByText(/log in$/i).click(); -``` -```java -page.getByText("Log in").click(); -page.getByText("Log in", new Page.GetByTextOptions().setExact(true)).click(); -page.getByText(Pattern.compile("log in$", Pattern.CASE_INSENSITIVE)).click(); -``` -```python async -await page.get_by_text("Log in").click() -await page.get_by_text("Log in", exact=True).click() -await page.get_by_text(re.compile("Log in", re.IGNORECASE)).click() -``` -```python sync -page.get_by_text("Log in").click() -page.get_by_text("Log in", exact=True).click() -page.get_by_text(re.compile("Log in", re.IGNORECASE)).click() -``` -```csharp -await page.GetByText("Log in").ClickAsync(); -await page.GetByText("Log in", new() { Exact: true }).ClickAsync(); -await page.GetByText(new Regex("Log in", RegexOptions.IgnoreCase)).ClickAsync(); +await expect(page.getByText('Welcome, John')) + .toBeVisible(); ``` -You can also [filter by text](#filter-by-text) when locating in some other way, for example find a particular item in the list. +```java +assertThat(page.getByText("Welcome, John")) + .isVisible(); +``` + +```python async +await expect(page.get_by_text("Welcome, John")).to_be_visible() +``` + +```python sync +expect(page.get_by_text("Welcome, John")).to_be_visible() +``` + +```csharp +await Expect(page.GetByText("Welcome, John")) + .ToBeVisibleAsync(); +``` + +Set an exact match: +```js +await expect(page.getByText('Welcome, John', { exact: true })) + .toBeVisible(); +``` + + +```java +assertThat(page.getByText("Welcome, John", new Page.GetByTextOptions().setExact(true))) + .isVisible(); +``` + +```python async +await expect(page.get_by_text("Welcome, John", exact=True)).to_be_visible() +``` + +```python sync +expect(page.get_by_text("Welcome, John", exact=True)).to_be_visible() +``` + +```csharp +await Expect(page.GetByText("Welcome, John", new() { Exact = true })) + .ToBeVisibleAsync(); +``` + +Match with a regular expression: ```js -await page.getByTestId('product-item').filter({ hasText: 'Playwright Book' }).click(); +await expect(page.getByText(/welcome, [A-Za-z]+$/i)) + .toBeVisible(); ``` + ```java -page.getByTestId("product-item").filter(new Locator.FilterOptions().setHasText("Playwright Book")).click(); +assertThat(page.getByText(Pattern.compile("welcome, john$", Pattern.CASE_INSENSITIVE))).isVisible(); ``` + ```python async -await page.get_by_test_id("product-item").filter(has_text="Playwright Book").click() +await expect(page.get_by_text(re.compile("welcome, john", re.IGNORECASE))).to_be_visible() ``` + ```python sync -page.get_by_test_id("product-item").filter(has_text="Playwright Book").click() +expect(page.get_by_text(re.compile("welcome, john", re.IGNORECASE))).to_be_visible() ``` + ```csharp -await page.GetByTestId("product-item").Filter(new() { HasText = "Playwright Book" }).ClickAsync(); +await Expect(page.GetByText(new Regex("welcome, john", RegexOptions.IgnoreCase))) + .ToBeVisibleAsync(); ``` :::note Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple spaces into one, turns line breaks into spaces and ignores leading and trailing whitespace. ::: +:::tip When to use text locators +We recommend using text locators to find non interactive elements like `div`, `span`, `p`, etc. For interactive elements like `button`, `a`, `input`, etc. use [role locators](#locate-by-role). +::: + +You can also [filter by text](#filter-by-text) which can be useful when trying to find a particular item in a list. + ### Locate by alt text All images should have an `alt` attribute that describes the image. You can locate an image based on the text alternative using [`method: Page.getByAltText`]. @@ -370,14 +444,19 @@ For example, consider the following DOM structure. playwright logo ``` +playwright logo + + You can click on the image after locating it by the text alternative: ```js -await page.getByAltText('playwright logo').click(); +await page.getByAltText('playwright logo') + .click(); ``` ```java -page.getByAltText("playwright logo").click(); +page.getByAltText("playwright logo") + .click(); ``` ```python async @@ -389,8 +468,17 @@ page.get_by_alt_text("playwright logo").click() ``` ```csharp -await page.GetByAltText("playwright logo").ClickAsync(); +await page.GetByAltText("playwright logo") + .ClickAsync(); ``` + +playwright logo being clicked + + +:::tip When to use alt locators +Use this locator when your element supports alt text such as `img` and `area` elements. +::: + ### Locate by title Locate an element with a matching title attribute using [`method: Page.getByTitle`]. @@ -400,15 +488,18 @@ For example, consider the following DOM structure. ```html 25 issues ``` +25 issues You can check the issues count after locating it by the title text: ```js -await expect(page.getByTitle('Issues count')).toHaveText('25 issues'); +await expect(page.getByTitle('Issues count')) + .toHaveText('25 issues'); ``` ```java -assertThat(page.getByTitle("Issues count")).hasText("25 issues"); +assertThat(page.getByTitle("Issues count")) + .hasText("25 issues"); ``` ```python async @@ -420,23 +511,35 @@ expect(page.get_by_title("Issues count")).to_have_text("25 issues") ``` ```csharp -await Expect(page.GetByTitle("Issues count")).toHaveText("25 issues"); +await Expect(page.GetByTitle("Issues count")) + .toHaveText("25 issues"); ``` -### Define explicit contract and use a data-testid attribute +:::tip When to use title locators +Use this locator when your element has the `title` attribute. +::: -User-facing attributes like text or accessible name can change over time. In this case it is convenient to define explicit test ids and query them with [`method: Page.getByTestId`]. +### Locate by test id + +Testing by test ids is the most resilient way of testing as even if your text or role of the attribute changes the test will still pass. QA's and developers should define explicit test ids and query them with [`method: Page.getByTestId`]. However testing by test ids is not user facing. If the role or text value is important to you then consider using user facing locators such as [role](#locate-by-role) and [text locators](#locate-by-text). + +For example, consider the following DOM structure. ```html ``` +Screenshot 2022-11-10 at 16 07 47 + +You can locate the element by it's test id: ```js -await page.getByTestId('directions').click(); +await page.getByTestId('directions') + .click(); ``` ```java -page.getByTestId("directions").click(); +page.getByTestId("directions") + .click(); ``` ```python async @@ -448,63 +551,97 @@ page.get_by_test_id("directions").click() ``` ```csharp -await page.GetByTestId("directions").ClickAsync(); +await page.GetByTestId("directions") + .ClickAsync(); ``` -By default, [`method: Page.getByTestId`] will locate elements based on the `data-testid` attribute, but you can configure it in your test config or calling [`method: Selectors.setTestIdAttribute`]. +button with Itinéraire text showing click action -### Locate in a subtree +:::tip When to use testid locators +You can also use test ids when you choose to use the test id methodology or when you can't locate by [role](#locate-by-role) or [text](#locate-by-text). +::: -You can chain methods that create a locator, like [`method: Page.getByText`] or [`method: Locator.getByRole`], to narrow down the search to a particular part of the page. +#### Set a custom test id attribute -For example, consider the following DOM structure: +By default, [`method: Page.getByTestId`] will locate elements based on the `data-testid` attribute, but you can configure it in your test config or by calling [`method: Selectors.setTestIdAttribute`]. -```html -
- Product 1 - -
-
- Product 2 - -
+Set the test id to use a custom data attribute for your tests. + +```js tab=js-js +// playwright.config.js +// @ts-check + +/** @type {import('@playwright/test').PlaywrightTestConfig} */ +const config = { + use: { + testIdAttribute: 'data-pw' + }, +}; +module.exports = config; ``` -For example, we can first find a product card that contains text "Product 2", and then click the button in this specific product card. +```js tab=js-ts +// playwright.config.ts +import type { PlaywrightTestConfig } from '@playwright/test'; -```js -const product = page.getByTestId('product-card').filter({ hasText: 'Product 2' }); - -await product.getByText('Buy').click(); -``` - -```python async -product = page.get_by_test_id("product-card").filter(has_text="Product 2") - -await product.getByText("Buy").click() -``` - -```python sync -product = page.get_by_test_id("product-card").filter(has_text="Product 2") - -product.get_by_text("Buy").click() +const config: PlaywrightTestConfig = { + use: { + testIdAttribute: 'data-pw' + } +}; +export default config; ``` ```java -Locator product = page.getByTestId("product-card").filter(new Locator.FilterOptions().setHasText("Product 2")); +playwright.selectors().setTestIdAttribute("data-pw"); +``` -product.get_by_text("Buy").click(); +```python async +playwright.selectors.set_test_id_attribute("data-pw") +``` + +```python sync +playwright.selectors.set_test_id_attribute("data-pw") ``` ```csharp -var product = page.GetByTestId("product-card").Filter(new() { HasText = "Product 2" }); - -await product.GetByText("Buy").clickAsync(); +playwright.Selectors.SetTestIdAttribute("data-pw"); ``` -### Locate by CSS or XPath selector +In your html you can now use `data-pw` as your test id instead of the default `data-testid`. -Playwright supports CSS and XPath selectors, and auto-detects them if you omit `css=` or `xpath=` prefix. Use [`method: Page.locator`] for this: +```html + +``` + +And then locate the element as you would normally do: + +```js +await page.getByTestId('directions') + .click(); +``` + +```java +page.getByTestId("directions") + .click(); +``` + +```python async +await page.get_by_test_id("directions").click() +``` + +```python sync +page.get_by_test_id("directions").click() +``` + +```csharp +await page.GetByTestId("directions") + .ClickAsync(); +``` + +### Locate by CSS or XPath + +If you absolutely must use CSS or XPath locators, you can use [`method: Page.locator`] to create a locator that takes a [selector](./selectors.md) describing how to find an element in the page. Playwright supports CSS and XPath selectors, and auto-detects them if you omit `css=` or `xpath=` prefix. ```js await page.locator('css=button').click(); @@ -578,113 +715,18 @@ await page.Locator("#tsf > div:nth-child(2) > div.A8SBwf > div.RNNXgb > div > di await page.Locator("//*[@id='tsf']/div[2]/div[1]/div[1]/div/div[2]/input").ClickAsync(); ``` -Instead, try to come up with a locator that is close to how user perceives the page or [define an explicit testing contract](#define-explicit-contract-and-use-pagegetbytestidtestid). +:::tip When to use this +CSS and XPath are not recommended as the DOM can often change leading to non resilient tests. Instead, try to come up with a locator that is close to how the user perceives the page such as [role locators](#locate-by-role) or [define an explicit testing contract](#locate-by-testid) using test ids. +::: -### Locate elements that contain other elements - -#### Filter by text - -Locator can be optionally filtered by text. It will search for a particular string somewhere inside the element, possibly in a descendant element, case-insensitively. You can also pass a regular expression. - -```js -await page.getByTestId('product-card').filter({ hasText: 'Product 3' }).click(); -await page.getByTestId('product-card').filter({ hasText: /product 3/ }).click(); -``` -```java -page.getByTestId("product-card").filter(new Locator.FilterOptions().setHasText("Product 3")).click(); -page.getByTestId("product-card").filter(new Locator.FilterOptions().setHasText(Pattern.compile("Product 3"))).click(); -``` -```python async -await page.get_by_test_id("product-card").filter(has_text="Product 3").click() -await page.get_by_test_id("product-card").filter(has_text=re.compile("Product 3")).click() -``` -```python sync -page.get_by_test_id("product-card").filter(has_text="Product 3").click() -page.get_by_test_id("product-card").filter(has_text=re.compile("Product 3")).click() -``` -```csharp -await page.GetByTestId("product-card").Filter(new() { HasText = "Product 3" }).ClickAsync(); -await page.GetByTestId("product-card").Filter(new() { HasText = new Regex("Product 3") }).ClickAsync(); -``` - -#### Filter by another locator - -Locators support an option to only select elements that have a descendant matching another locator. - -```js -page.getByRole('section').filter({ has: page.getByTestId('subscribe-button') }) -``` -```java -page.getByRole("section").filter(new Locator.FilterOptions().setHas(page.getByTestId("subscribe-button"))) -``` -```python async -page.get_by_role("section").filter(has=page.get_by_test_id("subscribe-button")) -``` -```python sync -page.get_by_role("section").filter(has=page.get_by_test_id("subscribe-button")) -``` -```csharp -page.GetByRole("section"), new() { Has = page.GetByTestId("subscribe-button") }) -``` - -Note that inner locator is matched starting from the outer one, not from the document root. - -#### Augment an existing locator - -You can filter an existing locator by text or another one, using [`method: Locator.filter`] method, possibly chaining it multiple times. - -```js -const rowLocator = page.locator('tr'); -// ... -await rowLocator - .filter({ hasText: 'text in column 1' }) - .filter({ has: page.getByRole('button', { name: 'column 2 button' }) }) - .screenshot(); -``` -```java -Locator rowLocator = page.locator("tr"); -// ... -rowLocator - .filter(new Locator.FilterOptions().setHasText("text in column 1")) - .filter(new Locator.FilterOptions().setHas( - page.getByRole("button", new Page.GetByRoleOptions().setName("column 2 button")) - )) - .screenshot(); -``` -```python async -row_locator = page.locator("tr") -# ... -await row_locator - .filter(has_text="text in column 1") - .filter(has=page.get_by_role("button", name="column 2 button")) - .screenshot() -``` -```python sync -row_locator = page.locator("tr") -# ... -row_locator - .filter(has_text="text in column 1") - .filter(has=page.get_by_role("button", name="column 2 button")) - .screenshot() -``` -```csharp -var rowLocator = page.Locator("tr"); -// ... -await rowLocator - .Filter(new LocatorFilterOptions { HasText = "text in column 1" }) - .Filter(new LocatorFilterOptions { - Has = page.GetByRole("button", new() { Name = "column 2 button" } ) - }) - .ScreenshotAsync(); -``` - -### Locate elements in Shadow DOM +## Locate in Shadow DOM All locators in Playwright **by default** work with elements in Shadow DOM. The exceptions are: - Locating by XPath does not pierce shadow roots. - [Closed-mode shadow roots](https://developer.mozilla.org/en-US/docs/Web/API/Element/attachShadow#parameters) are not supported. Consider the following example with a custom web component: + ```html
Title
@@ -693,172 +735,714 @@ Consider the following example with a custom web component: ``` +Title, shadow-root and details + + You can locate in the same way as if the shadow root was not present at all. -- Click `
Details
` - ```js - await page.getByText('Details').click(); - ``` - ```java - page.getByText("Details").click(); - ``` - ```python async - await page.get_by_text("Details").click() - ``` - ```python sync - page.get_by_text("Details").click() - ``` - ```csharp - await page.GetByText("Details").ClickAsync(); - ``` +To click `
Details
`: -- Click `` - ```js - await page.locator('x-details', { hasText: 'Details' }).click(); - ``` - ```java - page.locator("x-details", new Page.LocatorOptions().setHasText("Details")).click(); - ``` - ```python async - await page.locator("x-details", has_text="Details" ).click() - ``` - ```python sync - page.locator("x-details", has_text="Details" ).click() - ``` - ```csharp - await page.Locator("x-details", new() { HasText = "Details" }).ClickAsync(); - ``` +```js +await page.getByText('Details').click(); +``` +```java +page.getByText("Details").click(); +``` +```python async +await page.get_by_text("Details").click() +``` +```python sync +page.get_by_text("Details").click() +``` +```csharp +await page.GetByText("Details").ClickAsync(); +``` -- Ensure that `` contains text "Details" - ```js - await expect(page.locator('x-details')).toContainText('Details'); - ``` - ```java - assertThat(page.locator("x-details")).containsText("Details"); - ``` - ```python async - await expect(page.locator("x-details")).to_contain_text("Details") - ``` - ```python sync - expect(page.locator("x-details")).to_contain_text("Details") - ``` - ```csharp - await Expect(page.Locator("x-details")).ToContainTextAsync("Details"); - ``` +Title, shadow-root and details with text details highlighted + + +

+ +To click ``: + +```js +await page.locator('x-details', { hasText: 'Details' }).click(); +``` +```java +page.locator("x-details", new Page.LocatorOptions().setHasText("Details")).click(); +``` +```python async +await page.locator("x-details", has_text="Details" ).click() +``` +```python sync +page.locator("x-details", has_text="Details" ).click() +``` +```csharp +await page.Locator("x-details", new() { HasTextString = "Details" }).ClickAsync(); +``` + +Title, shadow-root and details highlighted + +

+ +To ensure that `` contains the text "Details": +```js +await expect(page.locator('x-details')).toContainText('Details'); +``` +```java +assertThat(page.locator("x-details")).containsText("Details"); +``` +```python async +await expect(page.locator("x-details")).to_contain_text("Details") +``` +```python sync +expect(page.locator("x-details")).to_contain_text("Details") +``` +```csharp +await Expect(page.Locator("x-details")).ToContainTextAsync("Details"); +``` +## Filtering Locators + +Consider the following DOM structure where we want to click on the buy button of the second product card. We have a few options in order to filter the locators to get the right one. + +```html +
+

Product 1

+ +
+ +
+

Product 2

+ +
+``` + +2 product cards with text and a button + +### Filter by text + +Locators can be filtered by text with the [`method: Locator.filter`] method. It will search for a particular string somewhere inside the element, possibly in a descendant element, case-insensitively. You can also pass a regular expression. + +```js +await page.getByTestId('product-card') + .filter({ hasText: 'Product 2' }) + .getByRole('button', { name: 'Buy' }) + .click(); +``` + +```java +page.getByTestId("product-card") + .filter(new Locator.FilterOptions().setHasText("Product 2")) + .getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Buy")) + .click(); +``` + +```python async +await page.get_by_test_id("product-card").filter(has_text="Product 2").get_by_role("button", name="Buy").click() +``` + +```python sync +page.get_by_test_id("product-card").filter(has_text="Product 2").get_by_role("button", name="Buy").click() +``` +```csharp +await page.GetByTestId("product-card") + .Filter(new() { HasTextString = "Product 2" }) + .GetByRole(AriaRole.Button, new () { NameString = "Buy" }) + .ClickAsync(); +``` + +Use a regular expression: + +```js +await page.getByTestId('product-card') + .filter({ hasText: /Product 2/ }) + .getByRole('button', { name: 'Buy' }) + .click(); +``` + +```java +page.getByTestId("product-card") + .filter(new Locator.FilterOptions().setHasText(Pattern.compile("Product 2"))) + .getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Buy")) + .click(); +``` + +```python async +await page.get_by_test_id("product-card").filter(has_text=re.compile("Product 2")).get_by_role("button", name="Buy").click() +``` + +```python sync +page.get_by_test_id("product-card") + .filter(has_text=re.compile("Product 2")) + .get_by_role("button", name="Buy") + .click() +``` + +```csharp +await page.GetByTestId("product-card") + .Filter(new() { HasTextRegex = new Regex("Product 2") }) + .GetByRole(AriaRole.Button, new () { NameString = "Buy" }) + .ClickAsync(); +``` + +2 product cards with text and a button and the second one being highlighted + +### Filter by another locator + +Locators support an option to only select elements that have a descendant matching another locator. You can therefore filter by any other locator such as a [`method: Locator.getByRole`], [`method: Locator.getByTestId`], [`method: Locator.getByText`] etc. + +```js +await page.getByTestId('product-card') + .filter({ has: page.getByRole('heading', { name: 'Product 2' })}) + .getByRole('button', { name: 'Buy' }) + .click() +``` +```java +page.getByTestId("product-card") + .filter(new Locator.FilterOptions().setHas(page.GetByRole(AriaRole.HEADING, new Page.GetByRoleOptions().setName("Product 2")))) + .getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Buy"))) + .click() +``` +```python async +await page.get_by_test_id("product-card").filter(has=page.get_by_role("heading", name="Product 2")).get_by_role("button", name="Buy").click() +``` +```python sync +page.get_by_test_id("product-card") + .filter(has=page.get_by_role("heading", name="Product 2")) + .get_by_role("button", name="Buy") + .click() +``` +```csharp +await page.GetByTestId("product-card") + .Filter(new() { Has = page.GetByRole(AriaRole.Heading, new () { NameString = "Product 2" })}) + .GetByRole(AriaRole.Button, new () { NameString = "Buy" }) + .ClickAsync(); +``` + +2 product cards with text and a button and the second one being highlighted + +We can also assert the product card to make sure there is only one + +```js +await expect(page.getByTestId('product-card') + .filter({ has: page.getByText('Product2') })) + .toHaveCount(1); +``` + +```java +assertThat(page.getByTestId("product-card") + .filter(new Locator.FilterOptions().setHas(page.getByText("Product 2"))) + .hasCount(1); +``` + +```python async +await expect(page.get_by_role("product-card").filter(has=page.get_by_role("heading", name="Product 2")).to_have_count(1) +``` + +```python sync +expect(page.get_by_role("product-card").filter(has=page.get_by_role("heading", name="Product 2")).to_have_count(1) +``` + +```csharp +await Expect(page.GetByTestId("product-card") + .Filter(new() { Has = page.GetByRole(AriaRole.Heading, new () { Name = "Product 2" })}) + .toHaveCountAsync(1); +``` + +Note that the inner locator is matched starting from the outer one, not from the document root. + +## Chaining Locators + +You can chain methods that create a locator, like [`method: Page.getByText`] or [`method: Locator.getByRole`], to narrow down the search to a particular part of the page. + +In this example we first create a locator called product by locating the test id. We then filter by text. We can use the product locator again to get by role of button and click it and then use an assertion to make sure there is only one product with the text ' Product 2'. + +```js +const product = page.getByTestId('product-card') + .filter({ hasText: 'Product 2' }); + +await product.getByRole('button', { name: 'Buy' }) + .click(); + +await expect(product).toHaveCount(1); +``` + +```python async +product = page.get_by_test_id("product-card").filter(has_text="Product 2") + +await product.get_by_role("button", name="Buy").click() +``` + +```python sync +product = page.get_by_test_id("product-card").filter(has_text="Product 2") + +product.get_by_role("button", name="Buy").click() +``` + +```java +Locator product = page.getByTestId("product-card") + .filter(new Locator.FilterOptions().setHasText("Product 2")); + +product.getByRole(AriaRole.BUTTON, new Locator.GetByRoleOptions().setName("Buy")) + .click(); +``` + +```csharp +var product = page.GetByTestId("product-card") + .Filter(new() { HasTextString = "Product 2" }); + +await product.GetByRole("button", new() { NameString = "Buy" }) + .ClickAsync(); +``` + +2 product cards with text and a button and the second one being highlighted ## Lists -You can also use locators to work with the element lists. +### Count items in a list + +You can assert locators in order to count the items in a list. + +For example, consider the following DOM structure: + +```html +
    +
  • apple
    • +
  • banana
    • +
  • orange
    • +
+``` + +list of 3 items, apple, banana and orange + +Use the count assertion to ensure that the list has 3 items. + +```js +await expect(page.getByRole('listitem')).toHaveCount(3); +``` + +```python async +await expect(page.get_by_role("listitem")).to_have_count(3) +``` + +```python sync +expect(page.get_by_role("listitem")).to_have_count(3) +``` + +```java +assertThat(page.getByRole(AriaRole.LISTITEM).hasCount(3); +``` + +```csharp +await Expect(page.GetByRole("listitem")).ToHaveCountAsync(3); +``` + +### Assert all text in a list + +You can assert locators in order to find all the text in a list. + +For example, consider the following DOM structure: + +```html +
    +
  • apple
    • +
  • banana
    • +
  • orange
    • +
+``` +list of 3 items, apple, banana and orange + +Use [`method: LocatorAssertions.toHaveText`] to ensure that the list has the text "apple", "banana" and "orange". + +```js +await expect(page.getByRole('listitem')) + .toHaveText(['apple', 'banana', 'orange']); +``` + +```python async +await expect(page.get_by_role("listitem")).to_have_text(["apple", "banana", "orange"]) +``` + +```python sync +expect(page.get_by_role("listitem")).to_have_text(["apple", "banana", "orange"]) +``` + +```java +assertThat(page.getByRole(AriaRole.LISTITEM)) + .hasText(new String[] { "apple", "banana", "orange" }); +``` + +```csharp +await Expect(page.GetByRole("listitem")) + .ToHaveTextAsync(new string[] {"apple", "banana", "orange"}); +``` + +### Get a specific item + +There are many ways to get a specific item in a list. +#### Get by text + +Use the [`method: Page.getByText`] method to locate an element in a list by it's text content and then click on it. + +For example, consider the following DOM structure: + +```html +
    +
  • apple
    • +
  • banana
    • +
  • orange
    • +
+``` + +Locate an item by it's text content and click it. + +```js +await page.getByText('orange') + .click(); +``` + +```python async +await page.get_by_text("orange").click() +``` + +```python sync +page.get_by_text("orange").click() +``` + +```java +page.getByText("orange") + .click(); +``` + +```csharp +await page.GetByText("orange") + .ClickAsync(); +``` + +list of apple, banana and orange highlighting orange + +#### Filter by text +Use the [`method: Locator.filter`] to locate a specific item in a list. + +For example, consider the following DOM structure: + +```html +
    +
  • apple
    • +
  • banana
    • +
  • orange
    • +
+``` + +Locate an item by the role of "listitem" and then filter by the text of "orange" and then click it. + +```js +await page.getByRole('listitem') + .filter({ hasText: 'orange' }) + .click(); +``` + +```python async +await page.get_by_role("listitem").filter(has_text="orange").click() +``` + +```python sync +page.get_by_role("listitem").filter(has_text="orange").click() +``` + +```java +page.getByRole(AriaRole.LISTITEM) + .filter(new Locator.FilterOptions().setHasText("orange")) + .click(); +``` + +```csharp +await page.GetByRole("listitem") + .Filter(new() { HasTextString = "orange" }) + .ClickAsync(); +``` +list of apple, banana and orange highlighting orange + +#### Get by test id + +Use the [`method: Page.getByTestId`] method to locate an element in a list. You may need to modify the html and add a test id if you don't already have a test id. + +For example, consider the following DOM structure: + +```html +
    +
  • apple
    • +
  • banana
    • +
  • orange
    • +
+``` + +Locate an item by it's test id of "orange" and then click it. + +```js +await page.getByTestId('orange') + .click(); +``` + +```python async +await page.get_by_test_id("orange").click() +``` + +```python sync +page.get_by_test_id("orange").click() +``` + +```java +page.getByTestId("orange") + .click(); +``` + +```csharp +await page.GetByTestId("orange") + .ClickAsync(); +``` + +list of apple, banana and orange highlighting orange + +#### Get by nth item + +If you have a list of identical elements, and the only way to distinguish between them is the order, you can choose a specific element from a list with [`method: Locator.first`], [`method: Locator.last`] or [`method: Locator.nth`]. + +```js +const banana = await page.getByRole('listitem').nth(1); +``` + +```python async +banana = await page.get_by_role("listitem").nth(1) +``` + +```python sync +banana = page.get_by_role("listitem").nth(1) +``` + +```java +Locator banana = page.getByRole(AriaRole.LISTITEM).nth(1); +``` + +```csharp +var banana = await page.GetByRole("listitem") + .NthAsync(1); +``` +However, use this method with caution. Often times, the page might change, and the locator will point to a completely different element from the one you expected. Instead, try to come up with a unique locator that will pass the [strictness criteria](#strictness). + +### Chaining filters + +When you have elements with various similarities, you can use the [`method: Locator.filter`] method to select the right one. You can also chain multiple filters to narrow down the selection. + +For example, consider the following DOM structure: + +```html +
    +
  • +
    John
    +
    +
    • +
  • +
    Mary
    +
    +
    • +
  • +
    John
    +
    +
    • +
  • +
    Mary
    +
    +
    • +
+``` +text John and Mary with buttons say hello and say goodbye beside their names + +To take a screenshot of the row with "Mary" and "Say goodbye": + +```js +const rowLocator = page.getByRole('listitem'); + +await rowLocator + .filter({ hasText: 'Mary' }) + .filter({ has: page.getByRole('button', { name: 'Say goodbye' }) }) + .screenshot({path: 'screenshot.png'}); +``` + +```python async +row_locator = page.get_by_role("listitem") + +await row_locator.filter(has_text="Mary").filter(has=page.get_by_role("button", name="Say goodbye")).screenshot(path="screenshot.png") +``` + +```python sync +row_locator = page.get_by_role("listitem") + +row_locator.filter(has_text="Mary").filter(has=page.get_by_role("button", name="Say goodbye")).screenshot(path="screenshot.png") +``` + +```java +Locator rowLocator = page.getByRole(AriaRole.LISTITEM); + +rowLocator.filter(new Locator.FilterOptions().setHasText("Mary")) + .filter(new Locator.FilterOptions().setHas(page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Say goodbye")))) + .screenshot(new Page.ScreenshotOptions().setPath("screenshot.png")); +``` + +```csharp +var rowLocator = page.GetByRole("listitem"); + +await rowLocator.Filter(new() { HasTextString = "Mary" }) + .Filter(new() { Has = page.GetByRole("button", new() { NameString = "Say goodbye" }) }) + .ScreenshotAsync(new() { Path = "screenshot.png" }); +``` + +You should now have a "screenshot.png" file in your project's root directory. + +text Mary with buttons say goodbye + +### Rare use cases + +#### Get All text contents ```js -// Locate elements, this locator points to a list. const rows = page.getByRole('listitem'); - -// Pattern 1: use locator methods to calculate text on the whole list. const texts = await rows.allTextContents(); +``` -// Pattern 2: do something with each element in the list. -const count = await rows.count() +```python async +rows = page.get_by_role("listitem") +texts = await rows.all_text_contents() +``` + +```python sync +rows = page.get_by_role("listitem") +texts = rows.all_text_contents() +``` + +```java +Locator rows = page.getByRole(AriaRole.LISTITEM); +List texts = rows.allTextContents(); +``` + +```csharp +var rows = page.GetByRole("listitem"); +var texts = await rows.AllTextContentsAsync(); +``` + +#### Do something with each element in the list + +```js +const rows = page.getByRole('listitem'); +const count = await rows.count(); for (let i = 0; i < count; ++i) console.log(await rows.nth(i).textContent()); +``` -// Pattern 3: resolve locator to elements on page and map them to their text content. -// Note: the code inside evaluateAll runs in page, you can call any DOM apis there. +```python async +rows = page.get_by_role("listitem") +count = await rows.count() +for i in range(count): + print(await rows.nth(i).text_content()) +``` + +```python sync +rows = page.get_by_role("listitem") +count = rows.count() +for i in range(count): + print(rows.nth(i).text_content()) +``` + +```java +Locator rows = page.getByRole(AriaRole.LISTITEM); +int count = rows.count(); +for (int i = 0; i < count; ++i) + System.out.println(rows.nth(i).textContent()); +``` + +```csharp +var rows = page.GetByRole("listitem"); +var count = await rows.CountAsync(); +for (int i = 0; i < count; ++i) + Console.WriteLine(await rows.Nth(i).TextContentAsync()); +``` + +#### Evaluate in the page + +The code inside [`method: Locator.evaluateAll`] runs in the page, you can call any DOM apis there. + +```js +const rows = page.getByRole('listitem'); const texts = await rows.evaluateAll(list => list.map(element => element.textContent)); ``` ```python async -# Locate elements, this locator points to a list. rows = page.get_by_role("listitem") - -# Pattern 1: use locator methods to calculate text on the whole list. -texts = await rows.all_text_contents() - -# Pattern 2: do something with each element in the list. -count = await rows.count() -for i in range(count): - print(await rows.nth(i).text_content()) - -# Pattern 3: resolve locator to elements on page and map them to their text content. -# Note: the code inside evaluateAll runs in page, you can call any DOM apis there. texts = await rows.evaluate_all("list => list.map(element => element.textContent)") ``` ```python sync -# Locate elements, this locator points to a list. rows = page.get_by_role("listitem") - -# Pattern 1: use locator methods to calculate text on the whole list. -texts = rows.all_text_contents() - -# Pattern 2: do something with each element in the list. -count = rows.count() -for i in range(count): - print(rows.nth(i).text_content()) - -# Pattern 3: resolve locator to elements on page and map them to their text content. -# Note: the code inside evaluateAll runs in page, you can call any DOM apis there. texts = rows.evaluate_all("list => list.map(element => element.textContent)") ``` ```java -// Locate elements, this locator points to a list. -Locator rows = page.getByRole("listitem"); - -// Pattern 1: use locator methods to calculate text on the whole list. -List texts = rows.allTextContents(); - -// Pattern 2: do something with each element in the list. -int count = rows.count() -for (int i = 0; i < count; ++i) - System.out.println(rows.nth(i).textContent()); - -// Pattern 3: resolve locator to elements on page and map them to their text content. -// Note: the code inside evaluateAll runs in page, you can call any DOM apis there. +Locator rows = page.getByRole(AriaRole.LISTITEM); Object texts = rows.evaluateAll("list => list.map(element => element.textContent)"); ``` - ```csharp -// Locate elements, this locator points to a list. var rows = page.GetByRole("listitem"); - -// Pattern 1: use locator methods to calculate text on the whole list. -var texts = await rows.AllTextContentsAsync(); - -// Pattern 2: do something with each element in the list: -var count = await rows.CountAsync() -for (let i = 0; i < count; ++i) - Console.WriteLine(await rows.Nth(i).TextContentAsync()); - -// Pattern 3: resolve locator to elements on page and map them to their text content -// Note: the code inside evaluateAll runs in page, you can call any DOM apis there var texts = await rows.EvaluateAllAsync("list => list.map(element => element.textContent)"); ``` +## Strictness -### Picking specific element from a list - -If you have a list of identical elements, and the only way to distinguish between them is the order, you can choose a specific element from a list with [`method: Locator.first`], [`method: Locator.last`] or [`method: Locator.nth`]. - -For example, to click the third item in the list of products: +Locators are strict. This means that all operations on locators that imply +some target DOM element will throw an exception if more than one element matches. For example, the following call throws if there are several buttons in the DOM: +#### Throws an error if more than one ```js -await page.getByTestId('product-card').nth(3).click(); -``` - -```java -page.getByTestId("product-card").nth(3).click(); +await page.getByRole('button').click(); ``` ```python async -await page.get_by_test_id("product-card").nth(3).click() +await page.get_by_role("button").click() ``` ```python sync -page.get_by_test_id("product-card").nth(3).click() +page.get_by_role("button").click() +``` + +```java +page.getByRole(AriaRole.BUTTON).click(); ``` ```csharp -await page.GetByTestId("product-card").Nth(3).ClickAsync(); +await page.GetByRole(AriaRole.Button).ClickAsync(); ``` -However, use these methods with caution. Often times, the page might change, and locator will point to a completely different element from the one you expected. Instead, try to come up with a unique locator that will pass the [strictness criteria](#strictness). +On the other hand, Playwright understands when you perform a multiple-element operation, +so the following call works perfectly fine when the locator resolves to multiple elements. + +#### Works fine with multiple elements + +```js +await page.getByRole('button').count(); +``` + +```python async +await page.get_by_role("button").count() +``` + +```python sync +page.get_by_role("button").count() +``` + +```java +page.getByRole("button").count(); +``` + +```csharp +await page.GetByRole("button").CountAsync(); +``` + +You can explicitly opt-out from strictness check by telling Playwright which element to use when multiple elements match, through [`method: Locator.first`], [`method: Locator.last`], and [`method: Locator.nth`]. These methods are **not recommended** because when your page changes, Playwright may click on an element you did not intend. Instead, follow best practices above to create a locator that uniquely identifies the target element. diff --git a/docs/src/test-configuration-js.md b/docs/src/test-configuration-js.md index efef9c4403..0e4c5893c0 100644 --- a/docs/src/test-configuration-js.md +++ b/docs/src/test-configuration-js.md @@ -512,6 +512,7 @@ In addition to configuring [Browser] or [BrowserContext], videos or screenshots, - `globalTeardown`: Path to the global teardown file. This file will be required and run after all the tests. It must export a single function. - `retries`: The maximum number of retry attempts per test. - `testDir`: Directory with the test files. +- `testIdAttribute`: Set a custom data attribute for your [`method: Page.getByTestId`] locators. - `testIgnore`: Glob patterns or regular expressions that should be ignored when looking for the test files. For example, `'**/test-assets'`. - `testMatch`: Glob patterns or regular expressions that match test files. For example, `'**/todo-tests/*.spec.ts'`. By default, Playwright Test runs `.*(test|spec)\.(js|ts|mjs)` files. - `timeout`: Time in milliseconds given to each test. Learn more about [various timeouts](./test-timeouts.md). @@ -529,6 +530,9 @@ const config = { // Look for test files in the "tests" directory, relative to this configuration file testDir: 'tests', + // change the default data-testid to a custom attribute + testIdAttribute: 'data-pw' + // Each test is given 30 seconds timeout: 30000,