feat: use an xpath query handler (#8730)

puppeteer · Aug 4, 2022 · 5cf9b4d · 5cf9b4d
1 parent 49193cb
commit 5cf9b4d
Show file tree

Hide file tree

Showing 17 changed files with 426 additions and 383 deletions.
diff --git a/docs/api/index.md b/docs/api/index.md
diff --git a/docs/api/puppeteer.customqueryhandler.md b/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
@@ -14,7 +12,7 @@ export interface CustomQueryHandler
 
 ## Properties
 
-| Property                                                | Modifiers | Type                                                 | Description       |
-| ------------------------------------------------------- | --------- | ---------------------------------------------------- | ----------------- |
-| [queryAll?](./puppeteer.customqueryhandler.queryall.md) |           | (element: Node, selector: string) =&gt; Node\[\]     | <i>(Optional)</i> |
-| [queryOne?](./puppeteer.customqueryhandler.queryone.md) |           | (element: Node, selector: string) =&gt; Node \| null | <i>(Optional)</i> |
+| Property                                                | Modifiers | Type                                              | Description       |
+| ------------------------------------------------------- | --------- | ------------------------------------------------- | ----------------- |
+| [queryAll?](./puppeteer.customqueryhandler.queryall.md) |           | (node: Node, selector: string) =&gt; Node\[\]     | <i>(Optional)</i> |
+| [queryOne?](./puppeteer.customqueryhandler.queryone.md) |           | (node: Node, selector: string) =&gt; Node \| null | <i>(Optional)</i> |
diff --git a/docs/api/puppeteer.customqueryhandler.queryall.md b/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[];
 }
 ```
diff --git a/docs/api/puppeteer.customqueryhandler.queryone.md b/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;
 }
 ```
diff --git a/docs/api/puppeteer.elementhandle._x.md b/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:**
 

diff --git a/docs/api/puppeteer.elementhandle.md b/docs/api/puppeteer.elementhandle.md
diff --git a/docs/api/puppeteer.elementhandle.waitforxpath.md b/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.
-
-If `xpath` starts with `//` instead of `.//`, the dot will be appended automatically.
-
-This method works across navigation
-
-```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();
-})();
-```
+> Warning: This API is now obsolete.
+>
+> Use [ElementHandle.waitForSelector()](./puppeteer.elementhandle.waitforselector.md) 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 function will throw.
+>
+> If `xpath` starts with `//` instead of `.//`, the dot will be appended automatically.
+>
+> This method works across navigation
+>
+> ```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();
+> })();
+> ```
 
 **Signature:**
 

diff --git a/docs/api/puppeteer.frame.waitforxpath.md b/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&lt;[ElementHandle](./puppeteer.elementhandle.md)&lt;Node&gt; \| null&gt;
-
-## 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.
diff --git a/src/common/AriaQueryHandler.ts b/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);

diff --git a/src/common/DOMWorld.ts b/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} = {},

diff --git a/src/common/ElementHandle.ts b/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();
-    assert(frame);
-    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, {
-      ...options,
-      root: adoptedRoot,
-    });
-    await adoptedRoot.dispose();
-    if (!handle) {
-      return null;
+    if (xpath.startsWith('//')) {
+      xpath = `.${xpath}`;
     }
-    const mainExecutionContext = await frame._mainWorld.executionContext();
-    const result = await mainExecutionContext._adoptElementHandle(handle);
-    await handle.dispose();
-    return result;
+    return this.waitForSelector(`xpath/${xpath}`, options);
   }
 
   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) => {
-      const doc = element.ownerDocument || document;
-      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;
-    }, 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);
-      }
+    if (expression.startsWith('//')) {
+      expression = `.${expression}`;
     }
-    return result;
+    return this.$$(`xpath/${expression}`);
   }
 
   /**

diff --git a/src/common/FrameManager.ts b/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 (!handle) {
-      return null;
+    if (xpath.startsWith('//')) {
+      xpath = `.${xpath}`;
     }
-    const mainExecutionContext = await this._mainWorld.executionContext();
-    const result = await mainExecutionContext._adoptElementHandle(handle);
-    await handle.dispose();
-    return result;
+    return this.waitForSelector(`xpath/${xpath}`, options);
   }
 
   /**