Skip to content

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

chore: locator.description improvements (#38183)

Yury Semikhatsky590d5d32a499
diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.md
index 4726d63292..a1f64a75b9 100644
--- a/docs/src/api/class-locator.md
+++ b/docs/src/api/class-locator.md
@@ -630,7 +630,7 @@ Locator description.
* since: v1.57
- returns: <[null]|[string]>
-Returns locator description previously set with [`method: Locator.describe`].
+Returns locator description previously set with [`method: Locator.describe`]. Returns `null` if no custom description has been set. Prefer `Locator.toString()` for a human-readable representation, as it uses the description when available.
**Usage**
diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts
index d07ab6fc6c..847a302c8f 100644
--- a/packages/playwright-client/types/types.d.ts
+++ b/packages/playwright-client/types/types.d.ts
@@ -12956,7 +12956,9 @@ export interface Locator {
/**
* Returns locator description previously set with
- * [locator.describe(description)](https://playwright.dev/docs/api/class-locator#locator-describe).
+ * [locator.describe(description)](https://playwright.dev/docs/api/class-locator#locator-describe). Returns `null` if
+ * no custom description has been set. Prefer `Locator.toString()` for a human-readable representation, as it uses the
+ * description when available.
*
* **Usage**
*
diff --git a/packages/playwright-core/src/client/locator.ts b/packages/playwright-core/src/client/locator.ts
index db745c5d30..86650c0034 100644
--- a/packages/playwright-core/src/client/locator.ts
+++ b/packages/playwright-core/src/client/locator.ts
@@ -15,7 +15,7 @@
*/
import { ElementHandle } from './elementHandle';
-import { asLocator, locatorCustomDescription } from '../utils/isomorphic/locatorGenerators';
+import { asLocatorDescription, locatorCustomDescription } from '../utils/isomorphic/locatorGenerators';
import { getByAltTextSelector, getByLabelSelector, getByPlaceholderSelector, getByRoleSelector, getByTestIdSelector, getByTextSelector, getByTitleSelector } from '../utils/isomorphic/locatorUtils';
import { escapeForTextSelector } from '../utils/isomorphic/stringUtils';
import { isString } from '../utils/isomorphic/rtti';
@@ -393,7 +393,7 @@ export class Locator implements api.Locator {
}
toString() {
- return asLocator('javascript', this._selector);
+ return asLocatorDescription('javascript', this._selector);
}
}
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index d07ab6fc6c..847a302c8f 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -12956,7 +12956,9 @@ export interface Locator {
/**
* Returns locator description previously set with
- * [locator.describe(description)](https://playwright.dev/docs/api/class-locator#locator-describe).
+ * [locator.describe(description)](https://playwright.dev/docs/api/class-locator#locator-describe). Returns `null` if
+ * no custom description has been set. Prefer `Locator.toString()` for a human-readable representation, as it uses the
+ * description when available.
*
* **Usage**
*
diff --git a/tests/page/locator-convenience.spec.ts b/tests/page/locator-convenience.spec.ts
index ec81f47d75..015c037781 100644
--- a/tests/page/locator-convenience.spec.ts
+++ b/tests/page/locator-convenience.spec.ts
@@ -222,3 +222,15 @@ it('description should return description for locator with multiple describe cal
const locator3 = locator2.locator('button');
expect(locator3.description()).toBe(null);
});
+
+it('toString() returns formatted locator', async ({ page }) => {
+ const locator = page.getByRole('button', { name: 'Submit' });
+ expect(locator.toString()).toBe(`getByRole('button', { name: 'Submit' })`);
+ expect(locator.description()).toBe(null);
+});
+
+it('toString() prefers description', async ({ page }) => {
+ const locator = page.getByRole('button', { name: 'Submit' }).describe('Submit button');
+ expect(locator.toString()).toBe(`Submit button`);
+ expect(locator.toString()).toBe(locator.description());
+});