Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

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.md
index 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.md
index 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:
```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 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) or
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index 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