Skip to content

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

feat(locator): add page.getByRef (#43055)

Pavel Feldman3cf9b39ba197
diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md
index d880a95ed2..951bae8ccf 100644
--- a/docs/src/api/class-page.md
+++ b/docs/src/api/class-page.md
@@ -2346,6 +2346,49 @@ Attribute name to get the value for.
### option: Page.getByPlaceholder.exact = %%-locator-get-by-text-exact-%%
+## method: Page.getByRef
+* since: v1.64
+- returns: <[Locator]>
+
+Locate element by its aria ref. Refs like `[ref=e2]` are reported by [`method: Page.ariaSnapshot`] when called with
+the `"ai"` mode, and resolve against the latest snapshot taken in the element's frame.
+
+**Usage**
+
+Consider the following aria snapshot.
+
+```yaml
+- button "Submit" [ref=e2]
+```
+
+You can locate the button by its ref:
+
+```js
+await page.getByRef('e2').click();
+```
+
+```java
+page.getByRef("e2").click();
+```
+
+```python async
+await page.get_by_ref("e2").click()
+```
+
+```python sync
+page.get_by_ref("e2").click()
+```
+
+```csharp
+await page.GetByRef("e2").ClickAsync();
+```
+
+### param: Page.getByRef.ref
+* since: v1.64
+- `ref` <[string]>
+
+Aria ref of the element, for example `e2` or `f1e3`.
+
## method: Page.getByRole
* since: v1.27
- returns: <[Locator]>
diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts
index b6cb56d11a..eef3801009 100644
--- a/packages/playwright-client/types/types.d.ts
+++ b/packages/playwright-client/types/types.d.ts
@@ -3156,6 +3156,25 @@ export interface Page {
exact?: boolean;
}): Locator;
+ /**
+ * Locate element by its aria ref. Refs like `[ref=e2]` are reported by
+ * [page.ariaSnapshot([options])](https://playwright.dev/docs/api/class-page#page-aria-snapshot) when called with the
+ * `"ai"` mode, and resolve against the latest snapshot taken in the element's frame.
+ *
+ * **Usage**
+ *
+ * Consider the following aria snapshot.
+ *
+ * You can locate the button by its ref:
+ *
+ * ```js
+ * await page.getByRef('e2').click();
+ * ```
+ *
+ * @param ref Aria ref of the element, for example `e2` or `f1e3`.
+ */
+ getByRef(ref: string): Locator;
+
/**
* Allows locating elements by their [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
diff --git a/packages/playwright-core/src/client/page.ts b/packages/playwright-core/src/client/page.ts
index ac106def73..063a6176b0 100644
--- a/packages/playwright-core/src/client/page.ts
+++ b/packages/playwright-core/src/client/page.ts
@@ -773,6 +773,10 @@ export class Page extends ChannelOwner<channels.PageChannel> implements api.Page
return this.mainFrame().getByPlaceholder(text, options);
}
+ getByRef(ref: string): Locator {
+ return this.locator(`aria-ref=${ref}`);
+ }
+
getByText(text: string | RegExp, options?: { exact?: boolean }): Locator {
return this.mainFrame().getByText(text, options);
}
diff --git a/packages/playwright-core/src/tools/backend/tab.ts b/packages/playwright-core/src/tools/backend/tab.ts
index e9b3a4db41..a996d11733 100644
--- a/packages/playwright-core/src/tools/backend/tab.ts
+++ b/packages/playwright-core/src/tools/backend/tab.ts
@@ -568,7 +568,7 @@ export class Tab extends EventEmitter<TabEventsInterface> {
return { locator: this.page.locator(selector), resolved: asLocator('javascript', selector), selector };
} else {
try {
- let locator = this.page.locator(`aria-ref=${param.target}`);
+ let locator = this.page.getByRef(param.target);
if (param.element)
locator = locator.describe(param.element);
const resolved = await locator.normalize();
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index b6cb56d11a..eef3801009 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -3156,6 +3156,25 @@ export interface Page {
exact?: boolean;
}): Locator;
+ /**
+ * Locate element by its aria ref. Refs like `[ref=e2]` are reported by
+ * [page.ariaSnapshot([options])](https://playwright.dev/docs/api/class-page#page-aria-snapshot) when called with the
+ * `"ai"` mode, and resolve against the latest snapshot taken in the element's frame.
+ *
+ * **Usage**
+ *
+ * Consider the following aria snapshot.
+ *
+ * You can locate the button by its ref:
+ *
+ * ```js
+ * await page.getByRef('e2').click();
+ * ```
+ *
+ * @param ref Aria ref of the element, for example `e2` or `f1e3`.
+ */
+ getByRef(ref: string): Locator;
+
/**
* Allows locating elements by their [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
diff --git a/tests/page/page-aria-snapshot-ai.spec.ts b/tests/page/page-aria-snapshot-ai.spec.ts
index 7d070c25c5..867f088ba6 100644
--- a/tests/page/page-aria-snapshot-ai.spec.ts
+++ b/tests/page/page-aria-snapshot-ai.spec.ts
@@ -37,11 +37,11 @@ it('should generate refs', async ({ page }) => {
- button "Two" [ref=e3]
- button "Three" [ref=e4]
`);
- await expect(page.locator('aria-ref=e2')).toHaveText('One');
- await expect(page.locator('aria-ref=e3')).toHaveText('Two');
- await expect(page.locator('aria-ref=e4')).toHaveText('Three');
+ await expect(page.getByRef('e2')).toHaveText('One');
+ await expect(page.getByRef('e3')).toHaveText('Two');
+ await expect(page.getByRef('e4')).toHaveText('Three');
- await page.locator('aria-ref=e3').evaluate((e: HTMLElement) => {
+ await page.getByRef('e3').evaluate((e: HTMLElement) => {
e.textContent = 'Not Two';
});
@@ -114,30 +114,30 @@ it('should stitch all frame snapshots', async ({ page, server }) => {
- generic [ref=f2e1]: Hi, I'm frame
`);
- const href = await page.locator('aria-ref=e1').evaluate(e => e.ownerDocument.defaultView.location.href);
+ const href = await page.getByRef('e1').evaluate(e => e.ownerDocument.defaultView.location.href);
expect(href).toBe(server.PREFIX + '/frames/nested-frames.html');
- const href2 = await page.locator('aria-ref=f1e2').evaluate(e => e.ownerDocument.defaultView.location.href);
+ const href2 = await page.getByRef('f1e2').evaluate(e => e.ownerDocument.defaultView.location.href);
expect(href2).toBe(server.PREFIX + '/frames/two-frames.html');
- const href3 = await page.locator('aria-ref=f4e2').evaluate(e => e.ownerDocument.defaultView.location.href);
+ const href3 = await page.getByRef('f4e2').evaluate(e => e.ownerDocument.defaultView.location.href);
expect(href3).toBe(server.PREFIX + '/frames/frame.html');
{
- const resolved = await page.locator('aria-ref=e1').normalize();
+ const resolved = await page.getByRef('e1').normalize();
expect(resolved.toString()).toBe(`locator('body')`);
}
{
- const resolved = await page.locator('aria-ref=f4e2').normalize();
+ const resolved = await page.getByRef('f4e2').normalize();
expect(resolved.toString()).toBe(`locator('iframe[name="2frames"]').contentFrame().locator('iframe[name="dos"]').contentFrame().getByText('Hi, I\\'m frame')`);
}
{
// Should tolerate .describe().
- const resolved = await page.locator('aria-ref=f3e2').describe('foo bar').normalize();
+ const resolved = await page.getByRef('f3e2').describe('foo bar').normalize();
expect(resolved.toString()).toBe(`locator('iframe[name=\"2frames\"]').contentFrame().locator('iframe[name=\"uno\"]').contentFrame().getByText('Hi, I\\'m frame')`);
}
{
- const error = await page.locator('aria-ref=e1000').normalize().catch(e => e);
+ const error = await page.getByRef('e1000').normalize().catch(e => e);
expect(error.message).toContain(`No element matching aria-ref=e1000`);
}
});
@@ -155,21 +155,21 @@ it('should re-number refs across navigations but not same-document navigations',
// The first committed document keeps the base seq, so the main frame has no prefix.
await page.goto(server.PREFIX + '/one.html');
const oneRef = (await snapshotForAI(page)).match(/button "One" \[ref=(e\d+)\]/)![1];
- await expect(page.locator(`aria-ref=${oneRef}`)).toHaveText('One');
+ await expect(page.getByRef(oneRef)).toHaveText('One');
// Cross-document navigation re-numbers the main frame, so its refs gain a frame prefix.
await page.goto(server.PREFIX + '/two.html');
const twoRef = (await snapshotForAI(page)).match(/button "Two" \[ref=(f\d+e\d+)\]/)![1];
- await expect(page.locator(`aria-ref=${twoRef}`)).toHaveText('Two');
+ await expect(page.getByRef(twoRef)).toHaveText('Two');
// The stale ref from the previous document must not resolve against the new one.
- const error = await page.locator(`aria-ref=${oneRef}`).normalize().catch(e => e);
+ const error = await page.getByRef(oneRef).normalize().catch(e => e);
expect(error.message).toContain(`No element matching aria-ref=${oneRef}`);
// Same-document navigation keeps refs intact.
await page.evaluate(() => history.pushState({}, '', '/pushed.html'));
expect(await snapshotForAI(page)).toContain(`button "Two" [ref=${twoRef}]`);
- await expect(page.locator(`aria-ref=${twoRef}`)).toHaveText('Two');
+ await expect(page.getByRef(twoRef)).toHaveText('Two');
});
it('should persist iframe references', async ({ page }) => {
@@ -197,7 +197,7 @@ it('should persist iframe references', async ({ page }) => {
- iframe [ref=e6]:
- button "button2" [ref=f2e2]
`);
- await expect(page.locator('aria-ref=f2e2')).toHaveText('button2');
+ await expect(page.getByRef('f2e2')).toHaveText('button2');
await page.evaluate(() => {
const frame = document.createElement('iframe');
@@ -213,8 +213,8 @@ it('should persist iframe references', async ({ page }) => {
- iframe [ref=e6]:
- button "button2" [ref=f2e2]
`);
- await expect(page.locator('aria-ref=f3e2')).toHaveText('button1');
- await expect(page.locator('aria-ref=f2e2')).toHaveText('button2');
+ await expect(page.getByRef('f3e2')).toHaveText('button1');
+ await expect(page.getByRef('f2e2')).toHaveText('button2');
});
it('should not generate refs for elements with pointer-events:none', async ({ page }) => {
@@ -524,7 +524,7 @@ it('should resolve refs of distilled-away nodes', async ({ page }) => {
const snapshot = await snapshotForAI(page);
// The inner leaf generic is distilled away, but its ref still resolves to the element.
expect(snapshot).not.toContain('[ref=e3]');
- await expect(page.locator('aria-ref=e3')).toHaveText('[Feature] a dedicated clipboard API');
+ await expect(page.getByRef('e3')).toHaveText('[Feature] a dedicated clipboard API');
});
it('should not distill snapshots outside of ai mode', async ({ page }) => {
@@ -737,7 +737,7 @@ it('should snapshot frameset pages', { annotation: { type: 'issue', description:
- iframe [ref=e5]:
- button "Button three" [ref=f3e2]
`);
- await expect(page.locator('aria-ref=f2e2')).toHaveText('Button two');
+ await expect(page.getByRef('f2e2')).toHaveText('Button two');
});
it('should snapshot a locator inside a frameset frame', async ({ page, server }) => {
@@ -748,8 +748,8 @@ it('should snapshot a locator inside a frameset frame', async ({ page, server })
- generic [ref=f1e1]: Hi, I'm frame
`);
- await expect(page.locator('aria-ref=f1e1')).toHaveText(`Hi, I'm frame`);
- const resolved = await page.locator('aria-ref=f1e1').normalize();
+ await expect(page.getByRef('f1e1')).toHaveText(`Hi, I'm frame`);
+ const resolved = await page.getByRef('f1e1').normalize();
expect(resolved.toString()).toBe(`locator('frame').first().contentFrame().locator('body')`);
});
@@ -771,10 +771,10 @@ it('should stitch iframes inside a frameset frame', async ({ page, server }) =>
- iframe [ref=f1e3]:
- button "In iframe" [ref=f2e2]
`);
- await expect(page.locator('aria-ref=f1e2')).toHaveText('In frame');
- await expect(page.locator('aria-ref=f2e2')).toHaveText('In iframe');
+ await expect(page.getByRef('f1e2')).toHaveText('In frame');
+ await expect(page.getByRef('f2e2')).toHaveText('In iframe');
- const resolved = await page.locator('aria-ref=f2e2').normalize();
+ const resolved = await page.getByRef('f2e2').normalize();
expect(resolved.toString()).toBe(`locator('frame').contentFrame().locator('iframe').contentFrame().getByRole('button', { name: 'In iframe' })`);
});
@@ -798,7 +798,7 @@ it('should stitch nested frameset documents', async ({ page, server }) => {
- iframe [ref=f1e3]:
- button "Leaf button" [ref=f2e2]
`);
- await expect(page.locator('aria-ref=f2e2')).toHaveText('Leaf button');
+ await expect(page.getByRef('f2e2')).toHaveText('Leaf button');
});
it('should collapse inline generic nodes', async ({ page }) => {
diff --git a/tests/page/page-aria-snapshot-json.spec.ts b/tests/page/page-aria-snapshot-json.spec.ts
index 946fc81fa1..d8b4ea8fe4 100644
--- a/tests/page/page-aria-snapshot-json.spec.ts
+++ b/tests/page/page-aria-snapshot-json.spec.ts
@@ -113,7 +113,7 @@ it('should generate refs in ai mode', async ({ page }) => {
],
},
]);
- await expect(page.locator('aria-ref=e2')).toHaveText('One');
+ await expect(page.getByRef('e2')).toHaveText('One');
});
it('should mark clickable elements with cursor in ai mode', async ({ page }) => {