diff --git a/docs/src/locators.md b/docs/src/locators.md index e755e0a35e..e3018b803c 100644 --- a/docs/src/locators.md +++ b/docs/src/locators.md @@ -137,7 +137,7 @@ given selector. await page.locator('button').click(); // Works because we explicitly tell locator to pick the first element: -await page.locator('button').first().click(); +await page.locator('button').first().click(); // ⚠️ using first disables strictness // Works because count knows what to do with multiple matches: await page.locator('button').count(); @@ -148,7 +148,7 @@ await page.locator('button').count(); await page.locator('button').click() # Works because we explicitly tell locator to pick the first element: -await page.locator('button').first.click() +await page.locator('button').first.click() # ⚠️ using first disables strictness # Works because count knows what to do with multiple matches: await page.locator('button').count() @@ -159,7 +159,7 @@ await page.locator('button').count() page.locator('button').click() # Works because we explicitly tell locator to pick the first element: -page.locator('button').first.click() +page.locator('button').first.click() # ⚠️ using first disables strictness # Works because count knows what to do with multiple matches: page.locator('button').count() @@ -170,7 +170,7 @@ page.locator('button').count() page.locator("button").click(); // Works because we explicitly tell locator to pick the first element: -page.locator("button").first().click(); +page.locator("button").first().click(); // ⚠️ using first disables strictness // Works because count knows what to do with multiple matches: page.locator("button").count(); @@ -181,12 +181,16 @@ page.locator("button").count(); await page.Locator("button").ClickAsync(); // Works because we explicitly tell locator to pick the first element: -await page.Locator("button").First.ClickAsync(); +await page.Locator("button").First.ClickAsync(); // ⚠️ using First disables strictness // Works because Count knows what to do with multiple matches: await page.Locator("button").CountAsync(); ``` +:::caution +Using [`method: Locator.first`], [`method: Locator.last`], and [`method: Locator.nth`] is discouraged since it disables the concept of strictness, and as your page changes, Playwright may click on an element you did not intend. It's better to make your locator more specific. Learn more below in [Filtering Locators](#filtering-locators) and the [selectors guide](./selectors.md). +::: + ## Lists You can also use locators to work with the element lists. diff --git a/docs/src/selectors.md b/docs/src/selectors.md index 8440cb16ab..8379fe73eb 100644 --- a/docs/src/selectors.md +++ b/docs/src/selectors.md @@ -5,6 +5,8 @@ title: "Selectors" Selectors are strings that are used to create [Locator]s. Locators are used to perform actions on the elements by means of methods such as [`method: Locator.click`], [`method: Locator.fill`] and alike. +Writing good selectors is part art, part science so be sure to checkout the [Best Practices](#best-practices) section. + ## Quick guide diff --git a/docs/src/writing-tests-csharp.md b/docs/src/writing-tests-csharp.md index 0acf259b66..cac275ad9a 100644 --- a/docs/src/writing-tests-csharp.md +++ b/docs/src/writing-tests-csharp.md @@ -105,7 +105,7 @@ await Expect(getStarted).ToHaveAttributeAsync("href", "/docs/installation"); await getStarted.ClickAsync(); ``` -[Selectors](./selectors.md) are strings that are used to create Locators. Playwright supports many different selectors like [Text](./selectors.md#text-selector), [CSS](./selectors.md#css-selector), [XPath](./selectors.md#xpath-selectors) and many more. +[Selectors](./selectors.md) are strings that are used to create Locators. Playwright supports many different selectors like [Text](./selectors.md#text-selector), [CSS](./selectors.md#css-selector), [XPath](./selectors.md#xpath-selectors) and many more. Learn more about available selectors and how to pick one in this [in-depth guide](./selectors.md). ```csharp await Expect(Page.Locator("text=Installation")).ToBeVisibleAsync(); diff --git a/docs/src/writing-tests-js.md b/docs/src/writing-tests-js.md index 857a67786a..0e5a22c303 100644 --- a/docs/src/writing-tests-js.md +++ b/docs/src/writing-tests-js.md @@ -78,7 +78,8 @@ await expect(getStarted).toHaveAttribute('href', '/docs/installation'); await getStarted.click(); ``` -[Selectors](./selectors.md) are strings that are used to create Locators. Playwright supports many different selectors like [Text](./selectors.md#text-selector), [CSS](./selectors.md#css-selector), [XPath](./selectors.md#xpath-selectors) and many more. +[Selectors](./selectors.md) are strings that are used to create Locators. Playwright supports many different selectors like [Text](./selectors.md#text-selector), [CSS](./selectors.md#css-selector), [XPath](./selectors.md#xpath-selectors) and many more. Learn more about available selectors and how to pick one in this [in-depth guide](./selectors.md). + ```js await expect(page.locator('text=Installation')).toBeVisible(); diff --git a/docs/src/writing-tests-python.md b/docs/src/writing-tests-python.md index 901925f28f..685d625046 100644 --- a/docs/src/writing-tests-python.md +++ b/docs/src/writing-tests-python.md @@ -59,7 +59,8 @@ expect(get_started).to_have_attribute("href", "/docs/installation") get_started.click() ``` -[Selectors](./selectors.md) are strings that are used to create Locators. Playwright supports many different selectors like [Text](./selectors.md#text-selector), [CSS](./selectors.md#css-selector), [XPath](./selectors.md#xpath-selectors) and many more. +[Selectors](./selectors.md) are strings that are used to create Locators. Playwright supports many different selectors like [Text](./selectors.md#text-selector), [CSS](./selectors.md#css-selector), [XPath](./selectors.md#xpath-selectors) and many more. Learn more about available selectors and how to pick one in this [in-depth guide](./selectors.md). + ```python from playwright.sync_api import expect