Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
docs(locators): recommend within() for combining locators (#43031)
Yury Semikhatskybf587e954b9a
diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.mdindex 22f5dfbee7..a5a31e6e69 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.mdindex dd3655859c..a4307c3b47 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:```jsconst saveButton = page.getByRole('button', { name: 'Save' });// ...const dialog = page.getByTestId('settings-dialog');-await dialog.locator(saveButton).click();+await saveButton.within(dialog).click();``````python asyncsave_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 syncsave_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();``````csharpvar 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 simultaneouslydiff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.tsindex 34b649bf75..b7ea37f78e 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) ordiff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.tsindex 34b649bf75..b7ea37f78e 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