docs: custom selectors registration (#20687)

https://github.com/microsoft/playwright/issues/20424

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("<div><button>Click me</button></div>");
 // 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("<div><button>Click me</button></div>");
 // 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();
 ```

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()

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();
    *