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): revert Locator.toCode() back to Locator.normalize() (#39754)
Pavel Feldman12a32e240a8f
diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.mdindex c8f3570acd..8adf3be214 100644--- a/docs/src/api/class-locator.md+++ b/docs/src/api/class-locator.md@@ -1803,6 +1803,13 @@ var banana = await page.GetByRole(AriaRole.Listitem).Last(1);### option: Locator.locator.hasNotText = %%-locator-option-has-not-text-%%* since: v1.33+## async method: Locator.normalize+* since: v1.59+- returns: <[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.+## method: Locator.nth* since: v1.14- returns: <[Locator]>@@ -2561,12 +2568,6 @@ If you need to assert text on the page, prefer [`method: LocatorAssertions.toHav### option: Locator.textContent.timeout = %%-input-timeout-js-%%* since: v1.14-## async method: Locator.toCode-* since: v1.59-- returns: <[string]>--Returns a code string for a locator that uses best practices for referencing the matched element, prioritizing test ids, aria roles, and other user-facing attributes over CSS selectors.-## method: Locator.toString* since: v1.57* langs: jsdiff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.tsindex 86882d9abc..2ce8dbcaaf 100644--- a/packages/playwright-client/types/types.d.ts+++ b/packages/playwright-client/types/types.d.ts@@ -14209,6 +14209,13 @@ export interface Locator {hasText?: string|RegExp;}): 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.+ */+ normalize(): Promise<Locator>;+/*** Returns locator to the n-th matching element. It's zero based, `nth(0)` selects the first element.*@@ -14793,12 +14800,6 @@ export interface Locator {timeout?: number;}): Promise<null|string>;- /**- * Returns a code string for a locator that uses best practices for referencing the matched element, prioritizing test- * ids, aria roles, and other user-facing attributes over CSS selectors.- */- toCode(): Promise<string>;-/*** Focuses the element, and then sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the* text.diff --git a/packages/playwright-core/src/client/locator.ts b/packages/playwright-core/src/client/locator.tsindex d92813f36e..4d29ce7dcf 100644--- a/packages/playwright-core/src/client/locator.ts+++ b/packages/playwright-core/src/client/locator.ts@@ -254,9 +254,9 @@ export class Locator implements api.Locator {return await this._frame._queryCount(this._selector, _options);}- async toCode(): Promise<string> {+ async normalize(): Promise<Locator> {const { resolvedSelector } = await this._frame._channel.resolveSelector({ selector: this._selector });- return new Locator(this._frame, resolvedSelector).toString();+ return new Locator(this._frame, resolvedSelector);}async getAttribute(name: string, options?: TimeoutOptions): Promise<string | null> {diff --git a/packages/playwright-core/src/tools/backend/tab.ts b/packages/playwright-core/src/tools/backend/tab.tsindex c28edd06c8..53d10cc633 100644--- a/packages/playwright-core/src/tools/backend/tab.ts+++ b/packages/playwright-core/src/tools/backend/tab.ts@@ -449,8 +449,8 @@ export class Tab extends EventEmitter<TabEventsInterface> {let locator = this.page.locator(`aria-ref=${param.ref}`);if (param.element)locator = locator.describe(param.element);- const resolved = await locator.toCode();- return { locator, resolved };+ const resolved = await locator.normalize();+ return { locator, resolved: resolved.toString() };} catch (e) {throw new Error(`Ref ${param.ref} not found in the current page snapshot. Try capturing new snapshot.`);}diff --git a/packages/playwright-core/src/tools/backend/verify.ts b/packages/playwright-core/src/tools/backend/verify.tsindex 60b65272a4..48f012216c 100644--- a/packages/playwright-core/src/tools/backend/verify.ts+++ b/packages/playwright-core/src/tools/backend/verify.ts@@ -37,7 +37,7 @@ const verifyElement = defineTabTool({for (const frame of tab.page.frames()) {const locator = frame.getByRole(params.role as Parameters<playwright.Frame['getByRole']>[0], { name: params.accessibleName });if (await locator.count() > 0) {- const resolved = await locator.toCode();+ const resolved = await locator.normalize();response.addCode(`await expect(page.${resolved}).toBeVisible();`);response.addTextResult('Done');return;@@ -63,7 +63,7 @@ const verifyText = defineTabTool({for (const frame of tab.page.frames()) {const locator = frame.getByText(params.text).filter({ visible: true });if (await locator.count() > 0) {- const resolved = await locator.toCode();+ const resolved = await locator.normalize();response.addCode(`await expect(page.${resolved}).toBeVisible();`);response.addTextResult('Done');return;diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.tsindex 86882d9abc..2ce8dbcaaf 100644--- a/packages/playwright-core/types/types.d.ts+++ b/packages/playwright-core/types/types.d.ts@@ -14209,6 +14209,13 @@ export interface Locator {hasText?: string|RegExp;}): 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.+ */+ normalize(): Promise<Locator>;+/*** Returns locator to the n-th matching element. It's zero based, `nth(0)` selects the first element.*@@ -14793,12 +14800,6 @@ export interface Locator {timeout?: number;}): Promise<null|string>;- /**- * Returns a code string for a locator that uses best practices for referencing the matched element, prioritizing test- * ids, aria roles, and other user-facing attributes over CSS selectors.- */- toCode(): Promise<string>;-/*** Focuses the element, and then sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the* text.diff --git a/tests/page/page-aria-snapshot-ai.spec.ts b/tests/page/page-aria-snapshot-ai.spec.tsindex a4a0bc6753..55dc17bf31 100644--- a/tests/page/page-aria-snapshot-ai.spec.ts+++ b/tests/page/page-aria-snapshot-ai.spec.ts@@ -92,20 +92,20 @@ it('should stitch all frame snapshots', async ({ page, server }) => {expect(href3).toBe(server.PREFIX + '/frames/frame.html');{- const resolved = await page.locator('aria-ref=e1').toCode();- expect(resolved).toBe(`locator('body')`);+ const resolved = await page.locator('aria-ref=e1').normalize();+ expect(resolved.toString()).toBe(`locator('body')`);}{- const resolved = await page.locator('aria-ref=f4e2').toCode();- expect(resolved).toBe(`locator('iframe[name="2frames"]').contentFrame().locator('iframe[name="dos"]').contentFrame().getByText('Hi, I\\'m frame')`);+ const resolved = await page.locator('aria-ref=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').toCode();- expect(resolved).toBe(`locator('iframe[name=\"2frames\"]').contentFrame().locator('iframe[name=\"uno\"]').contentFrame().getByText('Hi, I\\'m frame')`);+ const resolved = await page.locator('aria-ref=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').toCode().catch(e => e);+ const error = await page.locator('aria-ref=e1000').normalize().catch(e => e);expect(error.message).toContain(`No element matching aria-ref=e1000`);}});