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