Skip to content

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

feat: add Locator.description() getter (#37870)

Yury Semikhatsky1604a2e25564
diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.md
index a5a92939bc..ac86bae5ab 100644
--- a/docs/src/api/class-locator.md
+++ b/docs/src/api/class-locator.md
@@ -620,6 +620,54 @@ await button.ClickAsync();
Locator description.
+## method: Locator.description
+* since: v1.57
+- returns: <[null]|[string]>
+
+Returns locator description previously set with [`method: Locator.describe`].
+
+**Usage**
+
+```js
+const button = page.getByRole('button').describe('Subscribe button');
+console.log(button.description()); // "Subscribe button"
+
+const input = page.getByRole('textbox');
+console.log(input.description()); // null
+```
+
+```python async
+button = page.get_by_role("button").describe("Subscribe button")
+print(button.description()) # "Subscribe button"
+
+input = page.get_by_role("textbox")
+print(input.description()) # None
+```
+
+```python sync
+button = page.get_by_role("button").describe("Subscribe button")
+print(button.description()) # "Subscribe button"
+
+input = page.get_by_role("textbox")
+print(input.description()) # None
+```
+
+```java
+Locator button = page.getByRole(AriaRole.BUTTON).describe("Subscribe button");
+System.out.println(button.description()); // "Subscribe button"
+
+Locator input = page.getByRole(AriaRole.TEXTBOX);
+System.out.println(input.description()); // null
+```
+
+```csharp
+var button = Page.GetByRole(AriaRole.Button).Describe("Subscribe button");
+Console.WriteLine(button.Description()); // "Subscribe button"
+
+var input = Page.GetByRole(AriaRole.Textbox);
+Console.WriteLine(input.Description()); // null
+```
+
## async method: Locator.dispatchEvent
* since: v1.14
diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts
index a04bcc1fc1..28c4b14a9e 100644
--- a/packages/playwright-client/types/types.d.ts
+++ b/packages/playwright-client/types/types.d.ts
@@ -12936,6 +12936,23 @@ export interface Locator {
*/
describe(description: string): Locator;
+ /**
+ * Returns locator description previously set with
+ * [locator.describe(description)](https://playwright.dev/docs/api/class-locator#locator-describe).
+ *
+ * **Usage**
+ *
+ * ```js
+ * const button = page.getByRole('button').describe('Subscribe button');
+ * console.log(button.description()); // "Subscribe button"
+ *
+ * const input = page.getByRole('textbox');
+ * console.log(input.description()); // null
+ * ```
+ *
+ */
+ description(): null|string;
+
/**
* Programmatically dispatch an event on the matching element.
*
diff --git a/packages/playwright-core/src/client/locator.ts b/packages/playwright-core/src/client/locator.ts
index fd889c75f3..db745c5d30 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 } from '../utils/isomorphic/locatorGenerators';
+import { asLocator, 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';
@@ -217,6 +217,10 @@ export class Locator implements api.Locator {
return new Locator(this._frame, this._selector + ' >> internal:describe=' + JSON.stringify(description));
}
+ description(): string | null {
+ return locatorCustomDescription(this._selector) || null;
+ }
+
first(): Locator {
return new Locator(this._frame, this._selector + ' >> nth=0');
}
diff --git a/packages/playwright-core/src/utils/isomorphic/locatorGenerators.ts b/packages/playwright-core/src/utils/isomorphic/locatorGenerators.ts
index 58459d8ae9..ae58852331 100644
--- a/packages/playwright-core/src/utils/isomorphic/locatorGenerators.ts
+++ b/packages/playwright-core/src/utils/isomorphic/locatorGenerators.ts
@@ -40,12 +40,9 @@ export interface LocatorFactory {
export function asLocatorDescription(lang: Language, selector: string): string | undefined {
try {
const parsed = parseSelector(selector);
- const lastPart = parsed.parts[parsed.parts.length - 1];
- if (lastPart?.name === 'internal:describe') {
- const description = JSON.parse(lastPart.body as string);
- if (typeof description === 'string')
- return description;
- }
+ const customDescription = parseCustomDescription(parsed);
+ if (customDescription)
+ return customDescription;
return innerAsLocators(new generators[lang](), parsed, false, 1)[0];
} catch (e) {
// Tolerate invalid input.
@@ -53,6 +50,25 @@ export function asLocatorDescription(lang: Language, selector: string): string |
}
}
+export function locatorCustomDescription(selector: string): string | undefined {
+ try {
+ const parsed = parseSelector(selector);
+ return parseCustomDescription(parsed);
+ } catch (e) {
+ return undefined;
+ }
+}
+
+function parseCustomDescription(parsed: ParsedSelector): string | undefined {
+ const lastPart = parsed.parts[parsed.parts.length - 1];
+ if (lastPart?.name === 'internal:describe') {
+ const description = JSON.parse(lastPart.body as string);
+ if (typeof description === 'string')
+ return description;
+ }
+ return undefined;
+}
+
export function asLocator(lang: Language, selector: string, isFrameLocator: boolean = false): string {
return asLocators(lang, selector, isFrameLocator, 1)[0];
}
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index a04bcc1fc1..28c4b14a9e 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -12936,6 +12936,23 @@ export interface Locator {
*/
describe(description: string): Locator;
+ /**
+ * Returns locator description previously set with
+ * [locator.describe(description)](https://playwright.dev/docs/api/class-locator#locator-describe).
+ *
+ * **Usage**
+ *
+ * ```js
+ * const button = page.getByRole('button').describe('Subscribe button');
+ * console.log(button.description()); // "Subscribe button"
+ *
+ * const input = page.getByRole('textbox');
+ * console.log(input.description()); // null
+ * ```
+ *
+ */
+ description(): null|string;
+
/**
* Programmatically dispatch an event on the matching element.
*
diff --git a/tests/page/locator-convenience.spec.ts b/tests/page/locator-convenience.spec.ts
index d63b890fd9..ec81f47d75 100644
--- a/tests/page/locator-convenience.spec.ts
+++ b/tests/page/locator-convenience.spec.ts
@@ -193,3 +193,32 @@ it('should return page', async ({ page, server }) => {
const inFrame = page.frames()[1].locator('div');
expect(inFrame.page()).toBe(page);
});
+
+it('description should return null for locator without description', async ({ page }) => {
+ const locator = page.locator('button');
+ expect(locator.description()).toBe(null);
+});
+
+it('description should return description for locator with simple description', async ({ page }) => {
+ const locator = page.locator('button').describe('Submit button');
+ expect(locator.description()).toBe('Submit button');
+});
+
+it('description should return description with special characters', async ({ page }) => {
+ const locator = page.locator('div').describe('Button with "quotes" and \'apostrophes\'');
+ expect(locator.description()).toBe('Button with "quotes" and \'apostrophes\'');
+});
+
+it('description should return description for chained locators', async ({ page }) => {
+ const locator = page.locator('form').locator('input').describe('Form input field');
+ expect(locator.description()).toBe('Form input field');
+});
+
+it('description should return description for locator with multiple describe calls', async ({ page }) => {
+ const locator1 = page.locator('foo').describe('First description');
+ expect(locator1.description()).toBe('First description');
+ const locator2 = locator1.locator('button').describe('Second description');
+ expect(locator2.description()).toBe('Second description');
+ const locator3 = locator2.locator('button');
+ expect(locator3.description()).toBe(null);
+});