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: Expose types and documentation for `Locator.toString` (#38633)
Chris1a51420afad0
diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.mdindex 042c08bb99..8d0091486b 100644--- a/docs/src/api/class-locator.md+++ b/docs/src/api/class-locator.md@@ -628,20 +628,13 @@ Locator description.## method: Locator.description* since: v1.57+* langs: python, java, csharp- returns: <[null]|[string]>-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.+Returns locator description previously set with [`method: Locator.describe`]. Returns `null` if no custom description has been set.**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 asyncbutton = page.get_by_role("button").describe("Subscribe button")print(button.description()) # "Subscribe button"@@ -674,6 +667,23 @@ var input = Page.GetByRole(AriaRole.Textbox);Console.WriteLine(input.Description()); // null```+## method: Locator.description+* since: v1.57+* langs: js+- returns: <[null]|[string]>++Returns locator description previously set with [`method: Locator.describe`]. Returns `null` if no custom description has been set. Prefer [`method: Locator.toString`] for a human-readable representation, as it uses the description when available.++**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+```+## async method: Locator.dispatchEvent* since: v1.14@@ -2534,6 +2544,13 @@ If you need to assert text on the page, prefer [`method: LocatorAssertions.toHav### option: Locator.textContent.timeout = %%-input-timeout-js-%%* since: v1.14+## method: Locator.toString+* since: v1.57+* langs: js+- returns: <[string]>++Returns a human-readable representation of the locator, using the [`method: Locator.description`] if one exists; otherwise, it generates a string based on the locator's selector.+## async method: Locator.type* since: v1.14* deprecated: In most cases, you should use [`method: Locator.fill`] instead. You only need to press keys one by one if there is special keyboard handling on the page - in this case use [`method: Locator.pressSequentially`].diff --git a/docs/src/release-notes-js.md b/docs/src/release-notes-js.mdindex 2ab8bccdd4..3347b70b8b 100644--- a/docs/src/release-notes-js.md+++ b/docs/src/release-notes-js.md@@ -69,7 +69,7 @@ After 3 years of being deprecated, we removed `page.accessibility` from our API.- New property [`property: TestConfig.tag`] adds a tag to all tests in this run. This is useful when using [merge-reports](./test-sharding.md#merging-reports-from-multiple-shards).- [`event: Worker.console`] event is emitted when JavaScript within the worker calls one of console API methods, e.g. console.log or console.dir. [`method: Worker.waitForEvent`] can be used to wait for it.-- [`method: Locator.description`] returns locator description previously set with [`method: Locator.describe`], and `Locator.toString()` now uses the description when available.+- [`method: Locator.description`] returns locator description previously set with [`method: Locator.describe`], and [`method: Locator.toString`] now uses the description when available.- New option [`option: Locator.click.steps`] in [`method: Locator.click`] and [`method: Locator.dragTo`] that configures the number of `mousemove` events emitted while moving the mouse pointer to the target element.- Network requests issued by [Service Workers](./service-workers.md#network-events-and-routing) are now reported and can be routed through the [BrowserContext](./api/class-browsercontext.md), only in Chromium. You can opt out using the `PLAYWRIGHT_DISABLE_SERVICE_WORKER_NETWORK` environment variable.- Console messages from Service Workers are dispatched through [`event: Worker.console`]. You can opt out of this using the `PLAYWRIGHT_DISABLE_SERVICE_WORKER_CONSOLE` environment variable.diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.tsindex 002616f81a..c37c74ae8a 100644--- a/packages/playwright-client/types/types.d.ts+++ b/packages/playwright-client/types/types.d.ts@@ -12644,6 +12644,12 @@ export interface Locator {elementHandle(options?: {timeout?: number;}): Promise<null|ElementHandle<SVGElement | HTMLElement>>;+ /**+ * Returns a human-readable representation of the locator, using the+ * [locator.description()](https://playwright.dev/docs/api/class-locator#locator-description) if one exists;+ * otherwise, it generates a string based on the locator's selector.+ */+ toString(): string;/*** When the locator points to a list of elements, this returns an array of locators, pointing to their respective* elements.@@ -13198,8 +13204,9 @@ export interface Locator {/*** Returns locator description previously set with* [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.+ * no custom description has been set. Prefer+ * [locator.toString()](https://playwright.dev/docs/api/class-locator#locator-to-string) for a human-readable+ * representation, as it uses the description when available.** **Usage***diff --git a/packages/playwright-core/src/utils/isomorphic/locatorGenerators.ts b/packages/playwright-core/src/utils/isomorphic/locatorGenerators.tsindex ae58852331..01d29f3eae 100644--- a/packages/playwright-core/src/utils/isomorphic/locatorGenerators.ts+++ b/packages/playwright-core/src/utils/isomorphic/locatorGenerators.ts@@ -37,7 +37,7 @@ export interface LocatorFactory {chainLocators(locators: string[]): string;}-export function asLocatorDescription(lang: Language, selector: string): string | undefined {+export function asLocatorDescription(lang: Language, selector: string): string {try {const parsed = parseSelector(selector);const customDescription = parseCustomDescription(parsed);diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.tsindex 002616f81a..c37c74ae8a 100644--- a/packages/playwright-core/types/types.d.ts+++ b/packages/playwright-core/types/types.d.ts@@ -12644,6 +12644,12 @@ export interface Locator {elementHandle(options?: {timeout?: number;}): Promise<null|ElementHandle<SVGElement | HTMLElement>>;+ /**+ * Returns a human-readable representation of the locator, using the+ * [locator.description()](https://playwright.dev/docs/api/class-locator#locator-description) if one exists;+ * otherwise, it generates a string based on the locator's selector.+ */+ toString(): string;/*** When the locator points to a list of elements, this returns an array of locators, pointing to their respective* elements.@@ -13198,8 +13204,9 @@ export interface Locator {/*** Returns locator description previously set with* [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.+ * no custom description has been set. Prefer+ * [locator.toString()](https://playwright.dev/docs/api/class-locator#locator-to-string) for a human-readable+ * representation, as it uses the description when available.** **Usage***diff --git a/utils/doclint/missingDocs.js b/utils/doclint/missingDocs.jsindex 8467be9e0c..856c4f0210 100644--- a/utils/doclint/missingDocs.js+++ b/utils/doclint/missingDocs.js@@ -118,7 +118,9 @@ function listMethods(rootNames, apiFileName) {* @param {string} methodName*/function shouldSkipMethodByName(className, methodName) {- if (methodName.startsWith('_') || methodName === 'T' || methodName === 'toString')+ if (methodName.startsWith('_') || methodName === 'T')+ return true;+ if (methodName === 'toString' && className !== 'Locator')return true;if (EventEmitter.prototype.hasOwnProperty(methodName))return true;diff --git a/utils/generate_types/overrides.d.ts b/utils/generate_types/overrides.d.tsindex b50bb7a641..57822056cb 100644--- a/utils/generate_types/overrides.d.ts+++ b/utils/generate_types/overrides.d.ts@@ -200,6 +200,7 @@ export interface Locator {elementHandle(options?: {timeout?: number;}): Promise<null|ElementHandle<SVGElement | HTMLElement>>;+ toString(): string;}export interface BrowserType<Unused = {}> {