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
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.mdindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.ymlindex ab4a3fb973..5647bc30b1 100644--- a/packages/protocol/spec/frame.yml+++ b/packages/protocol/spec/frame.yml@@ -385,8 +385,10 @@ Frame:internal: trueparameters:selector: string+ sdkLanguage: SDKLanguage?returns:resolvedSelector: string+ locatorCode: string?highlight:internal: truediff --git a/packages/protocol/src/validator.ts b/packages/protocol/src/validator.tsindex 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.tsindex 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" })`);+});