From d76a8aa2d254903cccad43737c22f7549e64d753 Mon Sep 17 00:00:00 2001 From: Yury Semikhatsky Date: Wed, 30 Sep 2026 17:21:07 -0700 Subject: [PATCH] docs(locators): recommend within() for combining locators --- docs/src/api/class-locator.md | 2 +- docs/src/locators.md | 12 ++++++------ packages/playwright-client/types/types.d.ts | 6 +----- packages/playwright-core/types/types.d.ts | 6 +----- 4 files changed, 9 insertions(+), 17 deletions(-) diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.md index 22f5dfbee7a2e..a5a31e6e69119 100644 --- a/docs/src/api/class-locator.md +++ b/docs/src/api/class-locator.md @@ -3061,7 +3061,7 @@ Optional argument to pass to [`param: expression`]. * since: v1.64 - returns: <[Locator]> -Returns a locator that matches this locator's elements inside each element matched by [`param: locator`]. This is the same as calling [`method: Locator.locator`] on [`param: locator`] with this locator as an argument, but reads in the natural order. +Returns a locator that matches this locator's elements inside each element matched by [`param: locator`]. Note that relative locators, such as [`method: Locator.nth`] or [`method: Locator.first`], are resolved separately inside each matched parent. In the example below, `page.getByRole('cell').nth(2)` picks the third cell of every row, not the third cell in the whole table. diff --git a/docs/src/locators.md b/docs/src/locators.md index dd3655859c462..a4307c3b47fc1 100644 --- a/docs/src/locators.md +++ b/docs/src/locators.md @@ -1159,27 +1159,27 @@ await product .ClickAsync(); ``` -You can also chain two locators together, for example to find a "Save" button inside a particular dialog: +You can also combine two locators with [`method: Locator.within`], for example to find a "Save" button inside a particular dialog: ```js const saveButton = page.getByRole('button', { name: 'Save' }); // ... const dialog = page.getByTestId('settings-dialog'); -await dialog.locator(saveButton).click(); +await saveButton.within(dialog).click(); ``` ```python async save_button = page.get_by_role("button", name="Save") # ... dialog = page.get_by_test_id("settings-dialog") -await dialog.locator(save_button).click() +await save_button.within(dialog).click() ``` ```python sync save_button = page.get_by_role("button", name="Save") # ... dialog = page.get_by_test_id("settings-dialog") -dialog.locator(save_button).click() +save_button.within(dialog).click() ``` ```java @@ -1187,14 +1187,14 @@ Locator saveButton = page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Save")); // ... Locator dialog = page.getByTestId("settings-dialog"); -dialog.locator(saveButton).click(); +saveButton.within(dialog).click(); ``` ```csharp var saveButton = page.GetByRole(AriaRole.Button, new() { Name = "Save" }); // ... var dialog = page.GetByTestId("settings-dialog"); -await dialog.Locator(saveButton).ClickAsync(); +await saveButton.Within(dialog).ClickAsync(); ``` ### Matching two locators simultaneously diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts index 34b649bf75716..b7ea37f78e6f6 100644 --- a/packages/playwright-client/types/types.d.ts +++ b/packages/playwright-client/types/types.d.ts @@ -17393,11 +17393,7 @@ export interface Locator { /** * Returns a locator that matches this locator's elements inside each element matched by - * [`locator`](https://playwright.dev/docs/api/class-locator#locator-within-option-locator). This is the same as - * calling - * [locator.locator(selectorOrLocator[, options])](https://playwright.dev/docs/api/class-locator#locator-locator) on - * [`locator`](https://playwright.dev/docs/api/class-locator#locator-within-option-locator) with this locator as an - * argument, but reads in the natural order. + * [`locator`](https://playwright.dev/docs/api/class-locator#locator-within-option-locator). * * Note that relative locators, such as * [locator.nth(index)](https://playwright.dev/docs/api/class-locator#locator-nth) or diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts index 34b649bf75716..b7ea37f78e6f6 100644 --- a/packages/playwright-core/types/types.d.ts +++ b/packages/playwright-core/types/types.d.ts @@ -17393,11 +17393,7 @@ export interface Locator { /** * Returns a locator that matches this locator's elements inside each element matched by - * [`locator`](https://playwright.dev/docs/api/class-locator#locator-within-option-locator). This is the same as - * calling - * [locator.locator(selectorOrLocator[, options])](https://playwright.dev/docs/api/class-locator#locator-locator) on - * [`locator`](https://playwright.dev/docs/api/class-locator#locator-within-option-locator) with this locator as an - * argument, but reads in the natural order. + * [`locator`](https://playwright.dev/docs/api/class-locator#locator-within-option-locator). * * Note that relative locators, such as * [locator.nth(index)](https://playwright.dev/docs/api/class-locator#locator-nth) or