feat: use an xpath query handler (#8730)

docs/api/index.md

@@ -62,7 +62,7 @@ sidebar_label: API
 ## Interfaces
 
 | Interface                                                                   | Description                                                                                                                                                                                         |
-| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [BoundingBox](./puppeteer.boundingbox.md)                                   |                                                                                                                                                                                                     |
 | [BoxModel](./puppeteer.boxmodel.md)                                         |                                                                                                                                                                                                     |
 | [BrowserConnectOptions](./puppeteer.browserconnectoptions.md)               | Generic browser options that can be passed when launching any browser or when connecting to an existing browser instance.                                                                           |
@@ -81,7 +81,7 @@ sidebar_label: API
 | [CoverageEntry](./puppeteer.coverageentry.md)                               | The CoverageEntry class represents one entry of the coverage report.                                                                                                                                |
 | [Credentials](./puppeteer.credentials.md)                                   |                                                                                                                                                                                                     |
 | [CSSCoverageOptions](./puppeteer.csscoverageoptions.md)                     | Set of configurable options for CSS coverage.                                                                                                                                                       |
-| [CustomQueryHandler](./puppeteer.customqueryhandler.md)                     | Contains two functions <code>queryOne</code> and <code>queryAll</code> that can be [registered](./puppeteer.registercustomqueryhandler.md) as alternative querying strategies. The functions <code>queryOne</code> and <code>queryAll</code> are executed in the page context. <code>queryOne</code> should take an <code>Element</code> and a selector string as argument and return a single <code>Element</code> or <code>null</code> if no element is found. <code>queryAll</code> takes the same arguments but should instead return a <code>NodeListOf&lt;Element&gt;</code> or <code>Array&lt;Element&gt;</code> with all the elements that match the given query selector. |
+| [CustomQueryHandler](./puppeteer.customqueryhandler.md)                     |                                                                                                                                                                                                     |
 | [Device](./puppeteer.device.md)                                             |                                                                                                                                                                                                     |
 | [FrameAddScriptTagOptions](./puppeteer.frameaddscripttagoptions.md)         |                                                                                                                                                                                                     |
 | [FrameAddStyleTagOptions](./puppeteer.frameaddstyletagoptions.md)           |                                                                                                                                                                                                     |

docs/api/puppeteer.customqueryhandler.md

@@ -4,8 +4,6 @@ sidebar_label: CustomQueryHandler
 
 # CustomQueryHandler interface
 
-Contains two functions `queryOne` and `queryAll` that can be [registered](./puppeteer.registercustomqueryhandler.md) as alternative querying strategies. The functions `queryOne` and `queryAll` are executed in the page context. `queryOne` should take an `Element` and a selector string as argument and return a single `Element` or `null` if no element is found. `queryAll` takes the same arguments but should instead return a `NodeListOf<Element>` or `Array<Element>` with all the elements that match the given query selector.
-
 **Signature:**
 
 ```typescript
@@ -15,6 +13,6 @@ export interface CustomQueryHandler
 ## Properties
 
 | Property                                                | Modifiers | Type                                              | Description       |
-| ------------------------------------------------------- | --------- | ---------------------------------------------------- | ----------------- |
+| ------------------------------------------------------- | --------- | ------------------------------------------------- | ----------------- |
-| [queryAll?](./puppeteer.customqueryhandler.queryall.md) |           | (element: Node, selector: string) =&gt; Node\[\]     | <i>(Optional)</i> |
+| [queryAll?](./puppeteer.customqueryhandler.queryall.md) |           | (node: Node, selector: string) =&gt; Node\[\]     | <i>(Optional)</i> |
-| [queryOne?](./puppeteer.customqueryhandler.queryone.md) |           | (element: Node, selector: string) =&gt; Node \| null | <i>(Optional)</i> |
+| [queryOne?](./puppeteer.customqueryhandler.queryone.md) |           | (node: Node, selector: string) =&gt; Node \| null | <i>(Optional)</i> |

docs/api/puppeteer.customqueryhandler.queryall.md

@@ -8,6 +8,6 @@ sidebar_label: CustomQueryHandler.queryAll
 
 ```typescript
 interface CustomQueryHandler {
-  queryAll?: (element: Node, selector: string) => Node[];
+  queryAll?: (node: Node, selector: string) => Node[];
 }
 ```

docs/api/puppeteer.customqueryhandler.queryone.md

@@ -8,6 +8,6 @@ sidebar_label: CustomQueryHandler.queryOne
 
 ```typescript
 interface CustomQueryHandler {
-  queryOne?: (element: Node, selector: string) => Node | null;
+  queryOne?: (node: Node, selector: string) => Node | null;
 }
 ```

docs/api/puppeteer.elementhandle._x.md

@@ -4,7 +4,11 @@ sidebar_label: ElementHandle.$x
 
 # ElementHandle.$x() method
 
-The method evaluates the XPath expression relative to the elementHandle. If there are no such elements, the method will resolve to an empty array.
+> Warning: This API is now obsolete.
+>
+> Use [ElementHandle.$$()](./puppeteer.elementhandle.__.md) with the `xpath` prefix.
+>
+> The method evaluates the XPath expression relative to the elementHandle. If there are no such elements, the method will resolve to an empty array.
 
 **Signature:**
 

docs/api/puppeteer.elementhandle.md

@@ -42,12 +42,12 @@ The constructor for this class is marked as internal. Third-party code should no
 ## Methods
 
 | Method                                                                                       | Modifiers | Description                                                                                                                                                                                                                                                                                                                                                                                                          |
-| -------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| -------------------------------------------------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [$(selector)](./puppeteer.elementhandle._.md)                                                |           | Runs <code>element.querySelector</code> within the page.                                                                                                                                                                                                                                                                                                                                                             |
 | [$$(selector)](./puppeteer.elementhandle.__.md)                                              |           | Runs <code>element.querySelectorAll</code> within the page.                                                                                                                                                                                                                                                                                                                                                          |
 | [$$eval(selector, pageFunction, args)](./puppeteer.elementhandle.__eval.md)                  |           | <p>This method runs <code>document.querySelectorAll</code> within the element and passes it as the first argument to <code>pageFunction</code>. If there's no element matching <code>selector</code>, the method throws an error.</p><p>If <code>pageFunction</code> returns a Promise, then <code>frame.$$eval</code> would wait for the promise to resolve and return its value.</p>                               |
 | [$eval(selector, pageFunction, args)](./puppeteer.elementhandle._eval.md)                    |           | <p>This method runs <code>document.querySelector</code> within the element and passes it as the first argument to <code>pageFunction</code>. If there's no element matching <code>selector</code>, the method throws an error.</p><p>If <code>pageFunction</code> returns a Promise, then <code>frame.$eval</code> would wait for the promise to resolve and return its value.</p>                                   |
-| [$x(expression)](./puppeteer.elementhandle._x.md)                                            |           | The method evaluates the XPath expression relative to the elementHandle. If there are no such elements, the method will resolve to an empty array.                                                                                                                                                                                                                                                                                                                            |
+| [$x(expression)](./puppeteer.elementhandle._x.md)                                            |           |                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | [asElement()](./puppeteer.elementhandle.aselement.md)                                        |           |                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | [boundingBox()](./puppeteer.elementhandle.boundingbox.md)                                    |           | This method returns the bounding box of the element (relative to the main frame), or <code>null</code> if the element is not visible.                                                                                                                                                                                                                                                                                |
 | [boxModel()](./puppeteer.elementhandle.boxmodel.md)                                          |           | This method returns boxes of the element, or <code>null</code> if the element is not visible.                                                                                                                                                                                                                                                                                                                        |
@@ -69,26 +69,4 @@ The constructor for this class is marked as internal. Third-party code should no
 | [type(text, options)](./puppeteer.elementhandle.type.md)                                     |           | <p>Focuses the element, and then sends a <code>keydown</code>, <code>keypress</code>/<code>input</code>, and <code>keyup</code> event for each character in the text.</p><p>To press a special key, like <code>Control</code> or <code>ArrowDown</code>, use [ElementHandle.press()](./puppeteer.elementhandle.press.md).</p>                                                                                        |
 | [uploadFile(this, filePaths)](./puppeteer.elementhandle.uploadfile.md)                       |           | This method expects <code>elementHandle</code> to point to an [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).                                                                                                                                                                                                                                                                      |
 | [waitForSelector(selector, options)](./puppeteer.elementhandle.waitforselector.md)           |           | <p>Wait for the <code>selector</code> to appear within the element. If at the moment of calling the method the <code>selector</code> already exists, the method will return immediately. If the <code>selector</code> doesn't appear after the <code>timeout</code> milliseconds of waiting, the function will throw.</p><p>This method does not work across navigations or if the element is detached from DOM.</p> |
-| [waitForXPath(xpath, options)](./puppeteer.elementhandle.waitforxpath.md)                    |           | <p>Wait for the <code>xpath</code> within the element. If at the moment of calling the method the <code>xpath</code> already exists, the method will return immediately. If the <code>xpath</code> doesn't appear after the <code>timeout</code> milliseconds of waiting, the function will throw.</p><p>If <code>xpath</code> starts with <code>//</code> instead of <code>.//</code>, the dot will be appended automatically.</p><p>This method works across navigation</p> |
+| [waitForXPath(xpath, options)](./puppeteer.elementhandle.waitforxpath.md)                    |           |                                                                                                                                                                                                                                                                                                                                                                                                                      |
-
-```ts
-const puppeteer = require('puppeteer');
-(async () => {
-  const browser = await puppeteer.launch();
-  const page = await browser.newPage();
-  let currentURL;
-  page
-    .waitForXPath('//img')
-    .then(() => console.log('First URL with image: ' + currentURL));
-  for (currentURL of [
-    'https://example.com',
-    'https://google.com',
-    'https://bbc.com',
-  ]) {
-    await page.goto(currentURL);
-  }
-  await browser.close();
-})();
-```
-
-|

docs/api/puppeteer.elementhandle.waitforxpath.md

@@ -4,31 +4,35 @@ sidebar_label: ElementHandle.waitForXPath
 
 # ElementHandle.waitForXPath() method
 
-Wait for the `xpath` within the element. If at the moment of calling the method the `xpath` already exists, the method will return immediately. If the `xpath` doesn't appear after the `timeout` milliseconds of waiting, the function will throw.
+> Warning: This API is now obsolete.
-
+>
-If `xpath` starts with `//` instead of `.//`, the dot will be appended automatically.
+> Use [ElementHandle.waitForSelector()](./puppeteer.elementhandle.waitforselector.md) with the `xpath` prefix.
-
+>
-This method works across navigation
+> Wait for the `xpath` within the element. If at the moment of calling the method the `xpath` already exists, the method will return immediately. If the `xpath` doesn't appear after the `timeout` milliseconds of waiting, the function will throw.
-
+>
-```ts
+> If `xpath` starts with `//` instead of `.//`, the dot will be appended automatically.
-const puppeteer = require('puppeteer');
+>
-(async () => {
+> This method works across navigation
-  const browser = await puppeteer.launch();
+>
-  const page = await browser.newPage();
+> ```ts
-  let currentURL;
+> const puppeteer = require('puppeteer');
-  page
+> (async () => {
-    .waitForXPath('//img')
+>   const browser = await puppeteer.launch();
-    .then(() => console.log('First URL with image: ' + currentURL));
+>   const page = await browser.newPage();
-  for (currentURL of [
+>   let currentURL;
-    'https://example.com',
+>   page
-    'https://google.com',
+>     .waitForXPath('//img')
-    'https://bbc.com',
+>     .then(() => console.log('First URL with image: ' + currentURL));
-  ]) {
+>   for (currentURL of [
-    await page.goto(currentURL);
+>     'https://example.com',
-  }
+>     'https://google.com',
-  await browser.close();
+>     'https://bbc.com',
-})();
+>   ]) {
-```
+>     await page.goto(currentURL);
+>   }
+>   await browser.close();
+> })();
+> ```
 
 **Signature:**
 

docs/api/puppeteer.frame.waitforxpath.md

@@ -4,6 +4,14 @@ sidebar_label: Frame.waitForXPath
 
 # Frame.waitForXPath() method
 
+> Warning: This API is now obsolete.
+>
+> Use [Frame.waitForSelector()](./puppeteer.frame.waitforselector.md) with the `xpath` prefix.
+>
+> Wait for the `xpath` to appear in page. If at the moment of calling the method the `xpath` already exists, the method will return immediately. If the xpath doesn't appear after the `timeout` milliseconds of waiting, the function will throw.
+>
+> For a code example, see the example for [Frame.waitForSelector()](./puppeteer.frame.waitforselector.md). That function behaves identically other than taking a CSS selector rather than an XPath.
+
 **Signature:**
 
 ```typescript
@@ -25,9 +33,3 @@ class Frame {
 **Returns:**
 
 Promise<[ElementHandle](./puppeteer.elementhandle.md)<Node> \| null>
-
-## Remarks
-
-Wait for the `xpath` to appear in page. If at the moment of calling the method the `xpath` already exists, the method will return immediately. If the xpath doesn't appear after the `timeout` milliseconds of waiting, the function will throw.
-
-For a code example, see the example for [Frame.waitForSelector()](./puppeteer.frame.waitforselector.md). That function behaves identically other than taking a CSS selector rather than an XPath.

src/common/AriaQueryHandler.ts

@@ -114,7 +114,7 @@ const waitFor = async (
   return (await domWorld._waitForSelectorInPage(
     (_: Element, selector: string) => {
       return (
-        globalThis as any as unknown as {
+        globalThis as unknown as {
           ariaQuerySelector(selector: string): void;
         }
       ).ariaQuerySelector(selector);

src/common/DOMWorld.ts

@@ -717,52 +717,6 @@ export class DOMWorld {
     return elementHandle;
   }
 
-  async waitForXPath(
-    xpath: string,
-    options: WaitForSelectorOptions
-  ): Promise<ElementHandle<Node> | null> {
-    const {
-      visible: waitForVisible = false,
-      hidden: waitForHidden = false,
-      timeout = this.#timeoutSettings.timeout(),
-    } = options;
-    const polling = waitForVisible || waitForHidden ? 'raf' : 'mutation';
-    const title = `XPath \`${xpath}\`${waitForHidden ? ' to be hidden' : ''}`;
-    function predicate(
-      root: Element | Document,
-      xpath: string,
-      waitForVisible: boolean,
-      waitForHidden: boolean
-    ): Node | null | boolean {
-      const node = document.evaluate(
-        xpath,
-        root,
-        null,
-        XPathResult.FIRST_ORDERED_NODE_TYPE,
-        null
-      ).singleNodeValue;
-      return checkWaitForOptions(node, waitForVisible, waitForHidden);
-    }
-    const waitTaskOptions: WaitTaskOptions = {
-      domWorld: this,
-      predicateBody: makePredicateString(predicate),
-      predicateAcceptsContextElement: true,
-      title,
-      polling,
-      timeout,
-      args: [xpath, waitForVisible, waitForHidden],
-      root: options.root,
-    };
-    const waitTask = new WaitTask(waitTaskOptions);
-    const jsHandle = await waitTask.promise;
-    const elementHandle = jsHandle.asElement();
-    if (!elementHandle) {
-      await jsHandle.dispose();
-      return null;
-    }
-    return elementHandle;
-  }
-
   waitForFunction(
     pageFunction: Function | string,
     options: {polling?: string | number; timeout?: number} = {},

src/common/ElementHandle.ts

@@ -140,6 +140,8 @@ export class ElementHandle<
   }
 
   /**
+   * @deprecated Use {@link ElementHandle.waitForSelector} with the `xpath` prefix.
+   *
    * Wait for the `xpath` within the element. If at the moment of calling the
    * method the `xpath` already exists, the method will return immediately. If
    * the `xpath` doesn't appear after the `timeout` milliseconds of waiting, the
@@ -197,27 +199,10 @@ export class ElementHandle<
       timeout?: number;
     } = {}
   ): Promise<ElementHandle<Node> | null> {
-    const frame = this._context.frame();
+    if (xpath.startsWith('//')) {
-    assert(frame);
+      xpath = `.${xpath}`;
-    const secondaryContext = await frame._secondaryWorld.executionContext();
-    const adoptedRoot = await secondaryContext._adoptElementHandle(this);
-    xpath = xpath.startsWith('//') ? '.' + xpath : xpath;
-    if (!xpath.startsWith('.//')) {
-      await adoptedRoot.dispose();
-      throw new Error('Unsupported xpath expression: ' + xpath);
     }
-    const handle = await frame._secondaryWorld.waitForXPath(xpath, {
+    return this.waitForSelector(`xpath/${xpath}`, options);
-      ...options,
-      root: adoptedRoot,
-    });
-    await adoptedRoot.dispose();
-    if (!handle) {
-      return null;
-    }
-    const mainExecutionContext = await frame._mainWorld.executionContext();
-    const result = await mainExecutionContext._adoptElementHandle(handle);
-    await handle.dispose();
-    return result;
   }
 
   override asElement(): ElementHandle<ElementType> | null {
@@ -964,36 +949,17 @@ export class ElementHandle<
   }
 
   /**
+   * @deprecated Use {@link ElementHandle.$$} with the `xpath` prefix.
+   *
    * The method evaluates the XPath expression relative to the elementHandle.
    * If there are no such elements, the method will resolve to an empty array.
    * @param expression - Expression to {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate | evaluate}
    */
   async $x(expression: string): Promise<Array<ElementHandle<Node>>> {
-    const arrayHandle = await this.evaluateHandle((element, expression) => {
+    if (expression.startsWith('//')) {
-      const doc = element.ownerDocument || document;
+      expression = `.${expression}`;
-      const iterator = doc.evaluate(
-        expression,
-        element,
-        null,
-        XPathResult.ORDERED_NODE_ITERATOR_TYPE
-      );
-      const array = [];
-      let item;
-      while ((item = iterator.iterateNext())) {
-        array.push(item);
     }
-      return array;
+    return this.$$(`xpath/${expression}`);
-    }, expression);
-    const properties = await arrayHandle.getProperties();
-    await arrayHandle.dispose();
-    const result = [];
-    for (const property of properties.values()) {
-      const elementHandle = property.asElement();
-      if (elementHandle) {
-        result.push(elementHandle);
-      }
-    }
-    return result;
   }
 
   /**

src/common/FrameManager.ts

@@ -1374,7 +1374,8 @@ export class Frame {
   }
 
   /**
-   * @remarks
+   * @deprecated Use {@link Frame.waitForSelector} with the `xpath` prefix.
+   *
    * Wait for the `xpath` to appear in page. If at the moment of calling the
    * method the `xpath` already exists, the method will return immediately. If
    * the xpath doesn't appear after the `timeout` milliseconds of waiting, the
@@ -1392,14 +1393,10 @@ export class Frame {
     xpath: string,
     options: WaitForSelectorOptions = {}
   ): Promise<ElementHandle<Node> | null> {
-    const handle = await this._secondaryWorld.waitForXPath(xpath, options);
+    if (xpath.startsWith('//')) {
-    if (!handle) {
+      xpath = `.${xpath}`;
-      return null;
     }
-    const mainExecutionContext = await this._mainWorld.executionContext();
+    return this.waitForSelector(`xpath/${xpath}`, options);
-    const result = await mainExecutionContext._adoptElementHandle(handle);
-    await handle.dispose();
-    return result;
   }
 
   /**

src/common/QueryHandler.ts

@@ -19,47 +19,66 @@ import {DOMWorld, WaitForSelectorOptions} from './DOMWorld.js';
 import {ElementHandle} from './ElementHandle.js';
 import {JSHandle} from './JSHandle.js';
 
+/**
+ * @public
+ */
+export interface CustomQueryHandler {
+  /**
+   * @returns A {@link Node} matching the given {@link selector} from {@link node}.
+   */
+  queryOne?: (node: Node, selector: string) => Node | null;
+  /**
+   * @returns Some {@link Node}s matching the given {@link selector} from {@link node}.
+   */
+  queryAll?: (node: Node, selector: string) => Node[];
+}
+
 /**
  * @internal
  */
 export interface InternalQueryHandler {
+  /**
+   * Queries for a single node given a selector and {@link ElementHandle}.
+   *
+   * Akin to {@link Window.prototype.querySelector}.
+   */
   queryOne?: (
     element: ElementHandle<Node>,
     selector: string
   ) => Promise<ElementHandle<Node> | null>;
+  /**
+   * Queries for multiple nodes given a selector and {@link ElementHandle}.
+   *
+   * Akin to {@link Window.prototype.querySelectorAll}.
+   */
   queryAll?: (
     element: ElementHandle<Node>,
     selector: string
   ) => Promise<Array<ElementHandle<Node>>>;
-
+  /**
+   * Queries for multiple nodes given a selector and {@link ElementHandle}.
+   * Unlike {@link queryAll}, this returns a handle to a node array.
+   *
+   * Akin to {@link Window.prototype.querySelectorAll}.
+   */
+  queryAllArray?: (
+    element: ElementHandle<Node>,
+    selector: string
+  ) => Promise<JSHandle<Node[]>>;
+  /**
+   * Waits until a single node appears for a given selector and
+   * {@link ElementHandle}.
+   *
+   * Akin to {@link Window.prototype.querySelectorAll}.
+   */
   waitFor?: (
     domWorld: DOMWorld,
     selector: string,
     options: WaitForSelectorOptions
   ) => Promise<ElementHandle<Node> | null>;
-  queryAllArray?: (
-    element: ElementHandle<Node>,
-    selector: string
-  ) => Promise<JSHandle<Node[]>>;
 }
 
-/**
+function internalizeCustomQueryHandler(
- * Contains two functions `queryOne` and `queryAll` that can
- * be {@link registerCustomQueryHandler | registered}
- * as alternative querying strategies. The functions `queryOne` and `queryAll`
- * are executed in the page context.  `queryOne` should take an `Element` and a
- * selector string as argument and return a single `Element` or `null` if no
- * element is found. `queryAll` takes the same arguments but should instead
- * return a `NodeListOf<Element>` or `Array<Element>` with all the elements
- * that match the given query selector.
- * @public
- */
-export interface CustomQueryHandler {
-  queryOne?: (element: Node, selector: string) => Node | null;
-  queryAll?: (element: Node, selector: string) => Node[];
-}
-
-function createInternalQueryHandler(
   handler: CustomQueryHandler
 ): InternalQueryHandler {
   const internalHandler: InternalQueryHandler = {};
@@ -114,7 +133,7 @@ function createInternalQueryHandler(
   return internalHandler;
 }
 
-const defaultHandler = createInternalQueryHandler({
+const defaultHandler = internalizeCustomQueryHandler({
   queryOne: (element, selector) => {
     if (!('querySelector' in element)) {
       throw new Error(
@@ -141,7 +160,7 @@ const defaultHandler = createInternalQueryHandler({
   },
 });
 
-const pierceHandler = createInternalQueryHandler({
+const pierceHandler = internalizeCustomQueryHandler({
   queryOne: (element, selector) => {
     let found: Node | null = null;
     const search = (root: Node) => {
@@ -191,11 +210,46 @@ const pierceHandler = createInternalQueryHandler({
   },
 });
 
-const builtInHandlers = new Map([
+const xpathHandler = internalizeCustomQueryHandler({
-  ['aria', ariaHandler],
+  queryOne: (element, selector) => {
-  ['pierce', pierceHandler],
+    const doc = element.ownerDocument || document;
+    const result = doc.evaluate(
+      selector,
+      element,
+      null,
+      XPathResult.FIRST_ORDERED_NODE_TYPE
+    );
+    return result.singleNodeValue;
+  },
+
+  queryAll: (element, selector) => {
+    const doc = element.ownerDocument || document;
+    const iterator = doc.evaluate(
+      selector,
+      element,
+      null,
+      XPathResult.ORDERED_NODE_ITERATOR_TYPE
+    );
+    const array: Node[] = [];
+    let item;
+    while ((item = iterator.iterateNext())) {
+      array.push(item);
+    }
+    return array;
+  },
+});
+
+interface RegisteredQueryHandler {
+  handler: InternalQueryHandler;
+  transformSelector?: (selector: string) => string;
+}
+
+const INTERNAL_QUERY_HANDLERS = new Map<string, RegisteredQueryHandler>([
+  ['aria', {handler: ariaHandler}],
+  ['pierce', {handler: pierceHandler}],
+  ['xpath', {handler: xpathHandler}],
 ]);
-const queryHandlers = new Map(builtInHandlers);
+const QUERY_HANDLERS = new Map<string, RegisteredQueryHandler>();
 
 /**
  * Registers a {@link CustomQueryHandler | custom query handler}.
@@ -222,7 +276,10 @@ export function registerCustomQueryHandler(
   name: string,
   handler: CustomQueryHandler
 ): void {
-  if (queryHandlers.get(name)) {
+  if (INTERNAL_QUERY_HANDLERS.has(name)) {
+    throw new Error(`A query handler named "${name}" already exists`);
+  }
+  if (QUERY_HANDLERS.has(name)) {
     throw new Error(`A custom query handler named "${name}" already exists`);
   }
 
@@ -231,9 +288,7 @@ export function registerCustomQueryHandler(
     throw new Error(`Custom query handler names may only contain [a-zA-Z]`);
   }
 
-  const internalHandler = createInternalQueryHandler(handler);
+  QUERY_HANDLERS.set(name, {handler: internalizeCustomQueryHandler(handler)});
-
-  queryHandlers.set(name, internalHandler);
 }
 
 /**
@@ -242,9 +297,7 @@ export function registerCustomQueryHandler(
  * @public
  */
 export function unregisterCustomQueryHandler(name: string): void {
-  if (queryHandlers.has(name) && !builtInHandlers.has(name)) {
+  QUERY_HANDLERS.delete(name);
-    queryHandlers.delete(name);
-  }
 }
 
 /**
@@ -253,9 +306,7 @@ export function unregisterCustomQueryHandler(name: string): void {
  * @public
  */
 export function customQueryHandlerNames(): string[] {
-  return [...queryHandlers.keys()].filter(name => {
+  return [...QUERY_HANDLERS.keys()];
-    return !builtInHandlers.has(name);
-  });
 }
 
 /**
@@ -264,9 +315,11 @@ export function customQueryHandlerNames(): string[] {
  * @public
  */
 export function clearCustomQueryHandlers(): void {
-  customQueryHandlerNames().forEach(unregisterCustomQueryHandler);
+  QUERY_HANDLERS.clear();
 }
 
+const CUSTOM_QUERY_SEPARATORS = ['=', '/'];
+
 /**
  * @internal
  */
@@ -274,23 +327,22 @@ export function getQueryHandlerAndSelector(selector: string): {
   updatedSelector: string;
   queryHandler: InternalQueryHandler;
 } {
-  const hasCustomQueryHandler = /^[a-zA-Z]+\//.test(selector);
+  for (const handlerMap of [QUERY_HANDLERS, INTERNAL_QUERY_HANDLERS]) {
-  if (!hasCustomQueryHandler) {
+    for (const [
+      name,
+      {handler: queryHandler, transformSelector},
+    ] of handlerMap) {
+      for (const separator of CUSTOM_QUERY_SEPARATORS) {
+        const prefix = `${name}${separator}`;
+        if (selector.startsWith(prefix)) {
+          selector = selector.slice(prefix.length);
+          if (transformSelector) {
+            selector = transformSelector(selector);
+          }
+          return {updatedSelector: selector, queryHandler};
+        }
+      }
+    }
+  }
   return {updatedSelector: selector, queryHandler: defaultHandler};
-  }
-
-  const index = selector.indexOf('/');
-  const name = selector.slice(0, index);
-  const updatedSelector = selector.slice(index + 1);
-  const queryHandler = queryHandlers.get(name);
-  if (!queryHandler) {
-    throw new Error(
-      `Query set to use "${name}", but no query handler of that name was found`
-    );
-  }
-
-  return {
-    updatedSelector,
-    queryHandler,
-  };
 }

test/src/elementhandle.spec.ts

@@ -319,12 +319,12 @@ describe('ElementHandle specs', function () {
         </div>`
       );
 
-      const el2 = (await page.waitForSelector(
+      const el1 = (await page.waitForSelector(
         '#el1'
       )) as ElementHandle<HTMLDivElement>;
 
       for (const path of ['//div', './/div']) {
-        const e = (await el2.waitForXPath(
+        const e = (await el1.waitForXPath(
           path
         )) as ElementHandle<HTMLDivElement>;
         expect(
@@ -423,10 +423,8 @@ describe('ElementHandle specs', function () {
         await page.$('getById/foo');
         throw new Error('Custom query handler name not set - throw expected');
       } catch (error) {
-        expect(error).toStrictEqual(
+        expect(error).not.toStrictEqual(
-          new Error(
+          new Error('Custom query handler name not set - throw expected')
-            'Query set to use "getById", but no query handler of that name was found'
-          )
         );
       }
       const handlerNamesAfterUnregistering =

test/src/queryhandler.spec.ts

@@ -0,0 +1,160 @@
+/**
+ * Copyright 2018 Google Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import expect from 'expect';
+import {ElementHandle} from '../../lib/cjs/puppeteer/common/ElementHandle.js';
+import {
+  getTestState,
+  setupTestBrowserHooks,
+  setupTestPageAndContextHooks,
+} from './mocha-utils.js';
+
+describe('Query handler tests', function () {
+  setupTestBrowserHooks();
+  setupTestPageAndContextHooks();
+
+  describe('Pierce selectors', function () {
+    beforeEach(async () => {
+      const {page} = getTestState();
+      await page.setContent(
+        `<script>
+         const div = document.createElement('div');
+         const shadowRoot = div.attachShadow({mode: 'open'});
+         const div1 = document.createElement('div');
+         div1.textContent = 'Hello';
+         div1.className = 'foo';
+         const div2 = document.createElement('div');
+         div2.textContent = 'World';
+         div2.className = 'foo';
+         shadowRoot.appendChild(div1);
+         shadowRoot.appendChild(div2);
+         document.documentElement.appendChild(div);
+         </script>`
+      );
+    });
+    it('should find first element in shadow', async () => {
+      const {page} = getTestState();
+      const div = (await page.$('pierce/.foo')) as ElementHandle<HTMLElement>;
+      const text = await div.evaluate(element => {
+        return element.textContent;
+      });
+      expect(text).toBe('Hello');
+    });
+    it('should find all elements in shadow', async () => {
+      const {page} = getTestState();
+      const divs = (await page.$$('pierce/.foo')) as Array<
+        ElementHandle<HTMLElement>
+      >;
+      const text = await Promise.all(
+        divs.map(div => {
+          return div.evaluate(element => {
+            return element.textContent;
+          });
+        })
+      );
+      expect(text.join(' ')).toBe('Hello World');
+    });
+    it('should find first child element', async () => {
+      const {page} = getTestState();
+      const parentElement = (await page.$('html > div'))!;
+      const childElement = (await parentElement.$(
+        'pierce/div'
+      )) as ElementHandle<HTMLElement>;
+      const text = await childElement.evaluate(element => {
+        return element.textContent;
+      });
+      expect(text).toBe('Hello');
+    });
+    it('should find all child elements', async () => {
+      const {page} = getTestState();
+      const parentElement = (await page.$('html > div'))!;
+      const childElements = (await parentElement.$$('pierce/div')) as Array<
+        ElementHandle<HTMLElement>
+      >;
+      const text = await Promise.all(
+        childElements.map(div => {
+          return div.evaluate(element => {
+            return element.textContent;
+          });
+        })
+      );
+      expect(text.join(' ')).toBe('Hello World');
+    });
+  });
+
+  describe('XPath selectors', function () {
+    describe('in Page', function () {
+      it('should query existing element', async () => {
+        const {page} = getTestState();
+
+        await page.setContent('<section>test</section>');
+
+        expect(await page.$('xpath/html/body/section')).toBeTruthy();
+        expect((await page.$$('xpath/html/body/section')).length).toBe(1);
+      });
+      it('should return empty array for non-existing element', async () => {
+        const {page} = getTestState();
+
+        expect(
+          await page.$('xpath/html/body/non-existing-element')
+        ).toBeFalsy();
+        expect(
+          (await page.$$('xpath/html/body/non-existing-element')).length
+        ).toBe(0);
+      });
+      it('should return first element', async () => {
+        const {page} = getTestState();
+
+        await page.setContent('<div>a</div><div></div>');
+
+        const element = await page.$('xpath/html/body/div');
+        expect(
+          await element?.evaluate(e => {
+            return e.textContent === 'a';
+          })
+        ).toBeTruthy();
+      });
+      it('should return multiple elements', async () => {
+        const {page} = getTestState();
+
+        await page.setContent('<div></div><div></div>');
+
+        const elements = await page.$$('xpath/html/body/div');
+        expect(elements.length).toBe(2);
+      });
+    });
+    describe('in ElementHandles', function () {
+      it('should query existing element', async () => {
+        const {page} = getTestState();
+
+        await page.setContent('<div class="a">a<span></span></div>');
+
+        const elementHandle = (await page.$('div'))!;
+        expect(await elementHandle.$(`xpath/span`)).toBeTruthy();
+        expect((await elementHandle.$$(`xpath/span`)).length).toBe(1);
+      });
+
+      it('should return null for non-existing element', async () => {
+        const {page} = getTestState();
+
+        await page.setContent('<div class="a">a</div>');
+
+        const elementHandle = (await page.$('div'))!;
+        expect(await elementHandle.$(`xpath/span`)).toBeFalsy();
+        expect((await elementHandle.$$(`xpath/span`)).length).toBe(0);
+      });
+    });
+  });
+});

test/src/queryselector.spec.ts

@@ -14,13 +14,12 @@
  * limitations under the License.
  */
 import expect from 'expect';
+import {CustomQueryHandler} from '../../lib/cjs/puppeteer/common/QueryHandler.js';
 import {
   getTestState,
   setupTestBrowserHooks,
   setupTestPageAndContextHooks,
 } from './mocha-utils.js';
-import {CustomQueryHandler} from '../../lib/cjs/puppeteer/common/QueryHandler.js';
-import {ElementHandle} from '../../lib/cjs/puppeteer/common/ElementHandle.js';
 
 describe('querySelector', function () {
   setupTestBrowserHooks();
@@ -79,75 +78,6 @@ describe('querySelector', function () {
     });
   });
 
-  describe('pierceHandler', function () {
-    beforeEach(async () => {
-      const {page} = getTestState();
-      await page.setContent(
-        `<script>
-        const div = document.createElement('div');
-        const shadowRoot = div.attachShadow({mode: 'open'});
-        const div1 = document.createElement('div');
-        div1.textContent = 'Hello';
-        div1.className = 'foo';
-        const div2 = document.createElement('div');
-        div2.textContent = 'World';
-        div2.className = 'foo';
-        shadowRoot.appendChild(div1);
-        shadowRoot.appendChild(div2);
-        document.documentElement.appendChild(div);
-        </script>`
-      );
-    });
-    it('should find first element in shadow', async () => {
-      const {page} = getTestState();
-      const div = (await page.$('pierce/.foo')) as ElementHandle<HTMLElement>;
-      const text = await div.evaluate(element => {
-        return element.textContent;
-      });
-      expect(text).toBe('Hello');
-    });
-    it('should find all elements in shadow', async () => {
-      const {page} = getTestState();
-      const divs = (await page.$$('pierce/.foo')) as Array<
-        ElementHandle<HTMLElement>
-      >;
-      const text = await Promise.all(
-        divs.map(div => {
-          return div.evaluate(element => {
-            return element.textContent;
-          });
-        })
-      );
-      expect(text.join(' ')).toBe('Hello World');
-    });
-    it('should find first child element', async () => {
-      const {page} = getTestState();
-      const parentElement = (await page.$('html > div'))!;
-      const childElement = (await parentElement.$(
-        'pierce/div'
-      )) as ElementHandle<HTMLElement>;
-      const text = await childElement.evaluate(element => {
-        return element.textContent;
-      });
-      expect(text).toBe('Hello');
-    });
-    it('should find all child elements', async () => {
-      const {page} = getTestState();
-      const parentElement = (await page.$('html > div'))!;
-      const childElements = (await parentElement.$$('pierce/div')) as Array<
-        ElementHandle<HTMLElement>
-      >;
-      const text = await Promise.all(
-        childElements.map(div => {
-          return div.evaluate(element => {
-            return element.textContent;
-          });
-        })
-      );
-      expect(text.join(' ')).toBe('Hello World');
-    });
-  });
-
   // The tests for $$eval are repeated later in this file in the test group 'QueryAll'.
   // This is done to also test a query handler where QueryAll returns an Element[]
   // as opposed to NodeListOf<Element>.
@@ -256,7 +186,7 @@ describe('querySelector', function () {
     });
   });
 
-  describe('Path.$x', function () {
+  describe('Page.$x', function () {
     it('should query existing element', async () => {
       const {page} = getTestState();
 

test/src/waittask.spec.ts

@@ -735,7 +735,7 @@ describe('waittask specs', function () {
       });
       expect(error).toBeInstanceOf(puppeteer.errors.TimeoutError);
       expect(error?.message).toContain(
-        'waiting for XPath `//div` failed: timeout'
+        'waiting for selector `.//div` failed: timeout 10ms exceeded'
       );
     });
     itFailsFirefox('should run in specified frame', async () => {