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: add Locator.description() getter (#37870)
Yury Semikhatsky1604a2e25564
diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.mdindex 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.14diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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);+});