Skip to content

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

feat(api): return language-specific locator code from resolveSelector (#43175)

Pavel Feldmand469960fdfc4
diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.md
index b9f4e062f8..a6c731b4e3 100644
--- a/docs/src/api/class-locator.md
+++ b/docs/src/api/class-locator.md
@@ -2036,6 +2036,50 @@ var banana = page.GetByRole(AriaRole.Listitem).Last;
Returns a new locator that uses best practices for referencing the matched element, prioritizing test ids,
aria roles, and other user-facing attributes over CSS selectors. This is useful for converting implementation-detail selectors into more resilient, human-readable locators.
+**Usage**
+
+An agent can pick an element by its ref from an [`method: Page.ariaSnapshot`] taken in the `"ai"` mode. Refs only
+work for the latest snapshot. Normalize the ref locator and convert it to a string to get resilient locator code
+in your language, the same way `codegen` does.
+
+Consider the following aria snapshot.
+
+```yaml
+- button "Submit" [ref=e2]
+```
+
+You can turn the ref into locator code:
+
+```js
+const normalized = await page.getByRef('e2').normalize();
+console.log(normalized.toString());
+// getByRole('button', { name: 'Submit' })
+```
+
+```python async
+normalized = await page.get_by_ref("e2").normalize()
+print(str(normalized))
+# get_by_role("button", name="Submit")
+```
+
+```python sync
+normalized = page.get_by_ref("e2").normalize()
+print(str(normalized))
+# get_by_role("button", name="Submit")
+```
+
+```java
+Locator normalized = page.getByRef("e2").normalize();
+System.out.println(normalized.toString());
+// getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Submit"))
+```
+
+```csharp
+var normalized = await page.GetByRef("e2").NormalizeAsync();
+Console.WriteLine(normalized.ToString());
+// GetByRole(AriaRole.Button, new() { Name = "Submit" })
+```
+
## method: Locator.nth
* since: v1.14
- returns: <[Locator]>
diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts
index 525870b63e..5d89ffc88d 100644
--- a/packages/playwright-client/types/types.d.ts
+++ b/packages/playwright-client/types/types.d.ts
@@ -16495,6 +16495,24 @@ export interface Locator {
* Returns a new locator that uses best practices for referencing the matched element, prioritizing test ids, aria
* roles, and other user-facing attributes over CSS selectors. This is useful for converting implementation-detail
* selectors into more resilient, human-readable locators.
+ *
+ * **Usage**
+ *
+ * An agent can pick an element by its ref from an
+ * [page.ariaSnapshot([options])](https://playwright.dev/docs/api/class-page#page-aria-snapshot) taken in the `"ai"`
+ * mode. Refs only work for the latest snapshot. Normalize the ref locator and convert it to a string to get resilient
+ * locator code in your language, the same way `codegen` does.
+ *
+ * Consider the following aria snapshot.
+ *
+ * You can turn the ref into locator code:
+ *
+ * ```js
+ * const normalized = await page.getByRef('e2').normalize();
+ * console.log(normalized.toString());
+ * // getByRole('button', { name: 'Submit' })
+ * ```
+ *
*/
normalize(): Promise<Locator>;
diff --git a/packages/playwright-core/src/client/channels.d.ts b/packages/playwright-core/src/client/channels.d.ts
index 15b4b01d30..2b95064f65 100644
--- a/packages/playwright-core/src/client/channels.d.ts
+++ b/packages/playwright-core/src/client/channels.d.ts
@@ -2626,12 +2626,14 @@ export type FrameFrameElementResult = {
};
export type FrameResolveSelectorParams = {
selector: string,
+ sdkLanguage?: SDKLanguage,
};
export type FrameResolveSelectorOptions = {
-
+ sdkLanguage?: SDKLanguage,
};
export type FrameResolveSelectorResult = {
resolvedSelector: string,
+ locatorCode?: string,
};
export type FrameHighlightParams = {
selector: string,
diff --git a/packages/playwright-core/src/server/channels.d.ts b/packages/playwright-core/src/server/channels.d.ts
index 9a4b8efd4f..6e5a31d79e 100644
--- a/packages/playwright-core/src/server/channels.d.ts
+++ b/packages/playwright-core/src/server/channels.d.ts
@@ -2627,12 +2627,14 @@ export type FrameFrameElementResult = {
};
export type FrameResolveSelectorParams = {
selector: string,
+ sdkLanguage?: SDKLanguage,
};
export type FrameResolveSelectorOptions = {
-
+ sdkLanguage?: SDKLanguage,
};
export type FrameResolveSelectorResult = {
resolvedSelector: string,
+ locatorCode?: string,
};
export type FrameHighlightParams = {
selector: string,
diff --git a/packages/playwright-core/src/server/dispatchers/frameDispatcher.ts b/packages/playwright-core/src/server/dispatchers/frameDispatcher.ts
index 5bc04e1d81..71881fa085 100644
--- a/packages/playwright-core/src/server/dispatchers/frameDispatcher.ts
+++ b/packages/playwright-core/src/server/dispatchers/frameDispatcher.ts
@@ -15,6 +15,7 @@
*/
import { renderFullTitleForCall } from '@isomorphic/protocolFormatter';
+import { asLocator } from '@isomorphic/locatorGenerators';
import { ExpectError, Frame } from '../frames';
import { Dispatcher } from './dispatcher';
import { ElementHandleDispatcher } from './elementHandlerDispatcher';
@@ -188,7 +189,9 @@ export class FrameDispatcher extends Dispatcher<Frame, channels.FrameChannel, Br
}
async resolveSelector(params: channels.FrameResolveSelectorParams, progress: Progress): Promise<channels.FrameResolveSelectorResult> {
- return await this._frame.resolveSelector(progress, params.selector);
+ const { resolvedSelector } = await this._frame.resolveSelector(progress, params.selector);
+ const locatorCode = params.sdkLanguage ? asLocator(params.sdkLanguage, resolvedSelector) : undefined;
+ return { resolvedSelector, locatorCode };
}
async getAttribute(params: channels.FrameGetAttributeParams, progress: Progress): Promise<channels.FrameGetAttributeResult> {
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index 525870b63e..5d89ffc88d 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -16495,6 +16495,24 @@ export interface Locator {
* Returns a new locator that uses best practices for referencing the matched element, prioritizing test ids, aria
* roles, and other user-facing attributes over CSS selectors. This is useful for converting implementation-detail
* selectors into more resilient, human-readable locators.
+ *
+ * **Usage**
+ *
+ * An agent can pick an element by its ref from an
+ * [page.ariaSnapshot([options])](https://playwright.dev/docs/api/class-page#page-aria-snapshot) taken in the `"ai"`
+ * mode. Refs only work for the latest snapshot. Normalize the ref locator and convert it to a string to get resilient
+ * locator code in your language, the same way `codegen` does.
+ *
+ * Consider the following aria snapshot.
+ *
+ * You can turn the ref into locator code:
+ *
+ * ```js
+ * const normalized = await page.getByRef('e2').normalize();
+ * console.log(normalized.toString());
+ * // getByRole('button', { name: 'Submit' })
+ * ```
+ *
*/
normalize(): Promise<Locator>;
diff --git a/packages/protocol/spec/frame.yml b/packages/protocol/spec/frame.yml
index ab4a3fb973..5647bc30b1 100644
--- a/packages/protocol/spec/frame.yml
+++ b/packages/protocol/spec/frame.yml
@@ -385,8 +385,10 @@ Frame:
internal: true
parameters:
selector: string
+ sdkLanguage: SDKLanguage?
returns:
resolvedSelector: string
+ locatorCode: string?
highlight:
internal: true
diff --git a/packages/protocol/src/validator.ts b/packages/protocol/src/validator.ts
index 6608d2edf0..a383a1f995 100644
--- a/packages/protocol/src/validator.ts
+++ b/packages/protocol/src/validator.ts
@@ -1433,9 +1433,11 @@ scheme.FrameFrameElementResult = tObject({
});
scheme.FrameResolveSelectorParams = tObject({
selector: tString,
+ sdkLanguage: tOptional(tType('SDKLanguage')),
});
scheme.FrameResolveSelectorResult = tObject({
resolvedSelector: tString,
+ locatorCode: tOptional(tString),
});
scheme.FrameHighlightParams = tObject({
selector: tString,
diff --git a/tests/library/locator-generator.spec.ts b/tests/library/locator-generator.spec.ts
index 8627e60f65..507b902343 100644
--- a/tests/library/locator-generator.spec.ts
+++ b/tests/library/locator-generator.spec.ts
@@ -912,3 +912,19 @@ it('asLocatorDescription invalid input', async () => {
expect.soft(asLocatorDescription('javascript', `following-sibling::*[1]`)).toBe(`following-sibling::*[1]`);
expect.soft(asLocatorDescription('javascript', `body >> internal:describe="desc" >> div`)).toBe(`locator('body').locator('div')`);
});
+
+it('resolveSelector returns locatorCode for sdkLanguage', async ({ page }) => {
+ await page.setContent(`<button id="submit">Submit</button>`);
+ expect(await page.ariaSnapshot({ mode: 'ai' })).toContain(`button "Submit" [ref=e2]`);
+ const channel = (page.mainFrame() as any)._channel;
+ const selector = 'aria-ref=e2';
+
+ const noLanguage = await channel.resolveSelector({ selector });
+ expect(noLanguage.resolvedSelector).toBe(`internal:role=button[name="Submit"i]`);
+ expect(noLanguage.locatorCode).toBe(undefined);
+
+ expect((await channel.resolveSelector({ selector, sdkLanguage: 'javascript' })).locatorCode).toBe(`getByRole('button', { name: 'Submit' })`);
+ expect((await channel.resolveSelector({ selector, sdkLanguage: 'python' })).locatorCode).toBe(`get_by_role("button", name="Submit")`);
+ expect((await channel.resolveSelector({ selector, sdkLanguage: 'java' })).locatorCode).toBe(`getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Submit"))`);
+ expect((await channel.resolveSelector({ selector, sdkLanguage: 'csharp' })).locatorCode).toBe(`GetByRole(AriaRole.Button, new() { Name = "Submit" })`);
+});