From 86dd29a15e38a6d61df1d998ea1e84da15c1bc6b Mon Sep 17 00:00:00 2001 From: Yury Semikhatsky Date: Mon, 6 Feb 2023 13:32:00 -0800 Subject: [PATCH] docs: custom selectors registration (#20687) https://github.com/microsoft/playwright/issues/20424 --- docs/src/api/class-selectors.md | 22 +++++++------ docs/src/extensibility.md | 39 ++++++++++++++--------- packages/playwright-core/types/types.d.ts | 6 ++-- 3 files changed, 40 insertions(+), 27 deletions(-) diff --git a/docs/src/api/class-selectors.md b/docs/src/api/class-selectors.md index 897f0fab4d450..a068414a384f0 100644 --- a/docs/src/api/class-selectors.md +++ b/docs/src/api/class-selectors.md @@ -7,6 +7,8 @@ information. ## async method: Selectors.register * since: v1.8 +Selectors must be registered before creating the page. + **Usage** An example of registering selector engine that queries elements based on a tag name: @@ -37,8 +39,8 @@ const { selectors, firefox } = require('playwright'); // Or 'chromium' or 'webk // Use the selector prefixed with its name. const button = page.locator('tag=button'); - // Combine it with other selector engines. - await page.locator('tag=div >> text="Click me"').click(); + // We can combine it with built-in locators. + await page.locator('tag=div').getByText('Click me').click(); // Can use it in any methods supporting selectors. const buttonCount = await page.locator('tag=button').count(); @@ -65,8 +67,8 @@ Page page = browser.newPage(); page.setContent("
"); // Use the selector prefixed with its name. Locator button = page.locator("tag=button"); -// Combine it with other selector engines. -page.locator("tag=div >> text=\"Click me\"").click(); +// Combine it with built-in locators. +page.locator("tag=div").getByText("Click me").click(); // Can use it in any methods supporting selectors. int buttonCount = (int) page.locator("tag=button").count(); browser.close(); @@ -97,8 +99,8 @@ async def run(playwright): # Use the selector prefixed with its name. button = await page.query_selector('tag=button') - # Combine it with other selector engines. - await page.locator('tag=div >> text="Click me"').click() + # Combine it with built-in locators. + await page.locator('tag=div').get_by_text('Click me').click() # Can use it in any methods supporting selectors. button_count = await page.locator('tag=button').count() print(button_count) @@ -135,8 +137,8 @@ def run(playwright): # Use the selector prefixed with its name. button = page.locator('tag=button') - # Combine it with other selector engines. - page.locator('tag=div >> text="Click me"').click() + # Combine it with built-in locators. + page.locator('tag=div').get_by_text('Click me').click() # Can use it in any methods supporting selectors. button_count = page.locator('tag=button').count() print(button_count) @@ -170,8 +172,8 @@ var page = await browser.NewPageAsync(); await page.SetContentAsync("
"); // Use the selector prefixed with its name. var button = page.Locator("tag=button"); -// Combine it with other selector engines. -await page.Locator("tag=div >> text=\"Click me\"").ClickAsync(); +// Combine it with built-in locators. +await page.Locator("tag=div").GetByText("Click me").ClickAsync(); // Can use it in any methods supporting selectors. int buttonCount = await page.Locator("tag=button").CountAsync(); ``` diff --git a/docs/src/extensibility.md b/docs/src/extensibility.md index e8f21c64fb08f..1d5ca43d6a1e5 100644 --- a/docs/src/extensibility.md +++ b/docs/src/extensibility.md @@ -22,9 +22,13 @@ tampering with the global objects, for example altering `Node.prototype` methods content scripts. Note that running as a content script is not guaranteed when the engine is used together with other custom engines. +Selectors must be registered before creating the page. + An example of registering selector engine that queries elements based on a tag name: ```js +import { test, expect } from '@playwright/test'; + // Must be a function that evaluates to a selector engine instance. const createTagNameEngine = () => ({ // Returns the first element matching given selector in the root's subtree. @@ -38,18 +42,23 @@ const createTagNameEngine = () => ({ } }); -// Register the engine. Selectors will be prefixed with "tag=". -await selectors.register('tag', createTagNameEngine); +// Register selectors before any page is created. +test.beforeAll(async ({ playwright }) => { + // Register the engine. Selectors will be prefixed with "tag=". + await playwright.selectors.register('tag', createTagNameEngine); +}); -// Now we can use 'tag=' selectors. -const button = page.locator('tag=button'); -await button.click(); +test('selector engine test', async ({ page }) => { + // Now we can use 'tag=' selectors. + const button = page.locator('tag=button'); + await button.click(); -// We can combine it with other selector engines using `>>` combinator. -await page.locator('tag=div >> span >> "Click me"').click(); + // We can combine it with built-in locators. + await page.locator('tag=div').getByText('Click me').click(); -// We can use it in any methods supporting selectors. -const buttonCount = await page.locator('tag=button').count(); + // We can use it in any methods supporting selectors. + await expect(page.locator('tag=button')).toHaveCount(3); +}); ``` ```java @@ -73,8 +82,8 @@ playwright.selectors().register("tag", createTagNameEngine); Locator button = page.locator("tag=button"); button.click(); -// We can combine it with other selector engines using ">>" combinator. -page.locator("tag=div >> span >> \"Click me\"").click(); +// We can combine it with built-in locators. +page.locator("tag=div").getByText("Click me").click(); // We can use it in any methods supporting selectors. int buttonCount = (int) page.locator("tag=button").count(); @@ -102,8 +111,8 @@ await playwright.selectors.register("tag", tag_selector) button = page.locator("tag=button") await button.click() -# we can combine it with other selector engines using `>>` combinator. -await page.locator("tag=div >> span >> \"click me\"").click() +# we can combine it with built-in locators. +await page.locator("tag=div").get_by_text("click me").click() # we can use it in any methods supporting selectors. button_count = await page.locator("tag=button").count() @@ -131,8 +140,8 @@ playwright.selectors.register("tag", tag_selector) button = page.locator("tag=button") button.click() -# we can combine it with other selector engines using `>>` combinator. -page.locator("tag=div >> span >> \"click me\"").click() +# we can combine it with built-in locators. +page.locator("tag=div").get_by_text("click me").click() # we can use it in any methods supporting selectors. button_count = page.locator("tag=button").count() diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts index 19536f3b01b42..a78848f5af89c 100644 --- a/packages/playwright-core/types/types.d.ts +++ b/packages/playwright-core/types/types.d.ts @@ -18043,6 +18043,8 @@ export interface Route { */ export interface Selectors { /** + * Selectors must be registered before creating the page. + * * **Usage** * * An example of registering selector engine that queries elements based on a tag name: @@ -18073,8 +18075,8 @@ export interface Selectors { * * // Use the selector prefixed with its name. * const button = page.locator('tag=button'); - * // Combine it with other selector engines. - * await page.locator('tag=div >> text="Click me"').click(); + * // We can combine it with built-in locators. + * await page.locator('tag=div').getByText('Click me').click(); * // Can use it in any methods supporting selectors. * const buttonCount = await page.locator('tag=button').count(); *