docs: clarify the waitForXPath return type (#9541) (#9583)

docs/api/puppeteer.elementhandle.waitforxpath.md

@@ -64,7 +64,7 @@ class ElementHandle {
 
 Promise<[ElementHandle](./puppeteer.elementhandle.md)<Node> \| null>
 
-Promise which resolves when element specified by xpath string is added to DOM. Resolves to `null` if waiting for `hidden: true` and xpath is not found in DOM.
+Promise which resolves when element specified by xpath string is added to DOM. Resolves to `null` if waiting for `hidden: true` and xpath is not found in DOM, otherwise resolves to `ElementHandle`.
 
 ## Remarks
 

docs/api/puppeteer.page.waitforxpath.md

@@ -34,27 +34,23 @@ import puppeteer from 'puppeteer';
 class Page {
   waitForXPath(
     xpath: string,
-    options?: {
-      visible?: boolean;
-      hidden?: boolean;
-      timeout?: number;
-    }
+    options?: WaitForSelectorOptions
   ): Promise<ElementHandle<Node> | null>;
 }
 ```
 
 ## Parameters
 
-| Parameter | Type                                                       | Description                                                                             |
-| --------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| xpath     | string                                                     | A [xpath](https://developer.mozilla.org/en-US/docs/Web/XPath) of an element to wait for |
-| options   | { visible?: boolean; hidden?: boolean; timeout?: number; } | <i>(Optional)</i> Optional waiting parameters                                           |
+| Parameter | Type                                                            | Description                                                                             |
+| --------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| xpath     | string                                                          | A [xpath](https://developer.mozilla.org/en-US/docs/Web/XPath) of an element to wait for |
+| options   | [WaitForSelectorOptions](./puppeteer.waitforselectoroptions.md) | <i>(Optional)</i> Optional waiting parameters                                           |
 
 **Returns:**
 
 Promise&lt;[ElementHandle](./puppeteer.elementhandle.md)&lt;Node&gt; \| null&gt;
 
-Promise which resolves when element specified by xpath string is added to DOM. Resolves to `null` if waiting for `hidden: true` and xpath is not found in DOM.
+Promise which resolves when element specified by xpath string is added to DOM. Resolves to `null` if waiting for `hidden: true` and xpath is not found in DOM, otherwise resolves to `ElementHandle`.
 
 ## Remarks
 

packages/puppeteer-core/src/api/Page.ts

@@ -2465,7 +2465,7 @@ export class Page extends EventEmitter {
    * @param options - Optional waiting parameters
    * @returns Promise which resolves when element specified by xpath string is
    * added to DOM. Resolves to `null` if waiting for `hidden: true` and xpath is
-   * not found in DOM.
+   * not found in DOM, otherwise resolves to `ElementHandle`.
    * @remarks
    * The optional Argument `options` have properties:
    *
@@ -2483,11 +2483,7 @@ export class Page extends EventEmitter {
    */
   waitForXPath(
     xpath: string,
-    options?: {
-      visible?: boolean;
-      hidden?: boolean;
-      timeout?: number;
-    }
+    options?: WaitForSelectorOptions
   ): Promise<ElementHandle<Node> | null>;
   waitForXPath(): Promise<ElementHandle<Node> | null> {
     throw new Error('Not implemented');

packages/puppeteer-core/src/common/ElementHandle.ts

@@ -381,7 +381,7 @@ export class ElementHandle<
    * @param options - Optional waiting parameters
    * @returns Promise which resolves when element specified by xpath string is
    * added to DOM. Resolves to `null` if waiting for `hidden: true` and xpath is
-   * not found in DOM.
+   * not found in DOM, otherwise resolves to `ElementHandle`.
    * @remarks
    * The optional Argument `options` have properties:
    *

packages/puppeteer-core/src/common/Page.ts

@@ -1631,11 +1631,7 @@ export class CDPPage extends Page {
 
   override waitForXPath(
     xpath: string,
-    options: {
-      visible?: boolean;
-      hidden?: boolean;
-      timeout?: number;
-    } = {}
+    options: WaitForSelectorOptions = {}
   ): Promise<ElementHandle<Node> | null> {
     return this.mainFrame().waitForXPath(xpath, options);
   }

test/src/waittask.spec.ts

@@ -15,7 +15,7 @@
  */
 
 import expect from 'expect';
-import {TimeoutError} from 'puppeteer';
+import {TimeoutError, ElementHandle} from 'puppeteer';
 import {isErrorLike} from 'puppeteer-core/internal/util/ErrorLike.js';
 import {
   createTimeout,
@@ -787,6 +787,22 @@ describe('waittask specs', function () {
       expect(await waitForXPath).toBe(true);
       expect(divHidden).toBe(true);
     });
+    it('hidden should return null if the element is not found', async () => {
+      const {page} = getTestState();
+
+      const waitForXPath = await page.waitForXPath('//div', {hidden: true});
+
+      expect(waitForXPath).toBe(null);
+    });
+    it('hidden should return an empty element handle if the element is found', async () => {
+      const {page} = getTestState();
+
+      await page.setContent(`<div style='display: none;'>text</div>`);
+
+      const waitForXPath = await page.waitForXPath('//div', {hidden: true});
+
+      expect(waitForXPath).toBeInstanceOf(ElementHandle);
+    });
     it('should return the element handle', async () => {
       const {page} = getTestState();