fix: Locator.evaluateHandle types (#26469)

Fixes https://github.com/microsoft/playwright/issues/26449

packages/playwright-core/types/types.d.ts

@@ -10420,6 +10420,62 @@ export interface Locator {
   evaluate<R, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, void, R>, options?: {
     timeout?: number;
   }): Promise<R>;
+  /**
+   * Execute JavaScript code in the page, taking the matching element as an argument, and return a {@link JSHandle} with
+   * the result.
+   *
+   * **Details**
+   *
+   * Returns the return value of `pageFunction` as a{@link JSHandle}, called with the matching element as a first
+   * argument, and `arg` as a second argument.
+   *
+   * The only difference between
+   * [locator.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate)
+   * and
+   * [locator.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle)
+   * is that
+   * [locator.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle)
+   * returns {@link JSHandle}.
+   *
+   * If `pageFunction` returns a [Promise], this method will wait for the promise to resolve and return its value.
+   *
+   * If `pageFunction` throws or rejects, this method throws.
+   *
+   * See [page.evaluateHandle(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate-handle) for
+   * more details.
+   * @param pageFunction Function to be evaluated in the page context.
+   * @param arg Optional argument to pass to `pageFunction`.
+   * @param options
+   */
+  evaluateHandle<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, Arg, R>, arg: Arg): Promise<SmartHandle<R>>;
+  /**
+   * Execute JavaScript code in the page, taking the matching element as an argument, and return a {@link JSHandle} with
+   * the result.
+   *
+   * **Details**
+   *
+   * Returns the return value of `pageFunction` as a{@link JSHandle}, called with the matching element as a first
+   * argument, and `arg` as a second argument.
+   *
+   * The only difference between
+   * [locator.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate)
+   * and
+   * [locator.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle)
+   * is that
+   * [locator.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle)
+   * returns {@link JSHandle}.
+   *
+   * If `pageFunction` returns a [Promise], this method will wait for the promise to resolve and return its value.
+   *
+   * If `pageFunction` throws or rejects, this method throws.
+   *
+   * See [page.evaluateHandle(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate-handle) for
+   * more details.
+   * @param pageFunction Function to be evaluated in the page context.
+   * @param arg Optional argument to pass to `pageFunction`.
+   * @param options
+   */
+  evaluateHandle<R, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, void, R>): Promise<SmartHandle<R>>;
   /**
    * Execute JavaScript code in the page, taking all matching elements as an argument.
    *
@@ -11028,43 +11084,6 @@ export interface Locator {
    */
   elementHandles(): Promise<Array<ElementHandle>>;
 
-  /**
-   * Execute JavaScript code in the page, taking the matching element as an argument, and return a {@link JSHandle} with
-   * the result.
-   *
-   * **Details**
-   *
-   * Returns the return value of `pageFunction` as a{@link JSHandle}, called with the matching element as a first
-   * argument, and `arg` as a second argument.
-   *
-   * The only difference between
-   * [locator.evaluate(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate)
-   * and
-   * [locator.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle)
-   * is that
-   * [locator.evaluateHandle(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle)
-   * returns {@link JSHandle}.
-   *
-   * If `pageFunction` returns a [Promise], this method will wait for the promise to resolve and return its value.
-   *
-   * If `pageFunction` throws or rejects, this method throws.
-   *
-   * See [page.evaluateHandle(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#page-evaluate-handle) for
-   * more details.
-   * @param pageFunction Function to be evaluated in the page context.
-   * @param arg Optional argument to pass to `pageFunction`.
-   * @param options
-   */
-  evaluateHandle(pageFunction: Function|string, arg?: EvaluationArgument, options?: {
-    /**
-     * Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `actionTimeout`
-     * option in the config, or by using the
-     * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)
-     * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
-     */
-    timeout?: number;
-  }): Promise<JSHandle>;
-
   /**
    * Set a value to the input field.
    *

utils/generate_types/overrides.d.ts

@@ -152,6 +152,8 @@ export interface Locator {
   evaluate<R, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, void, R>, options?: {
     timeout?: number;
   }): Promise<R>;
+  evaluateHandle<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, Arg, R>, arg: Arg): Promise<SmartHandle<R>>;
+  evaluateHandle<R, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E, void, R>): Promise<SmartHandle<R>>;
   evaluateAll<R, Arg, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E[], Arg, R>, arg: Arg): Promise<R>;
   evaluateAll<R, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E[], void, R>): Promise<R>;
   elementHandle(options?: {

utils/generate_types/test/test.ts

@@ -498,6 +498,60 @@ playwright.chromium.launch().then(async browser => {
     const assertion: AssertType<{a: number, b: string, c: boolean, d: number}, typeof value> = true;
   }
 
+  {
+    const handle = await page.locator('body').evaluateHandle(() => ([{a: '123'}]));
+    const value = await handle.evaluate(h => h[1].a);
+    const assertion: AssertType<string, typeof value> = true;
+  }
+  {
+    const handle = await page.locator('body').evaluateHandle(() => ([{a: '123'}]));
+    const value = await handle.evaluate((h, p) => ({ a: h[1].a, p}), 123);
+    const assertion: AssertType<{a: string, p: number}, typeof value> = true;
+  }
+  {
+    const handle = await page.locator('body').evaluateHandle(() => ([{a: '123'}]));
+    const value = await handle.evaluate((h: ({a: string, b: number})[]) => h[1].b);
+    const assertion: AssertType<number, typeof value> = true;
+  }
+  {
+    const handle = await page.locator('body').evaluateHandle(() => ([{a: '123'}]));
+    const value = await handle.evaluate((h: ({a: string, b: number})[], prop) => h[1][prop], 'b' as const);
+    const assertion: AssertType<number, typeof value> = true;
+  }
+  {
+    const handle = await page.locator('body').evaluateHandle(() => ([{a: '123'}]));
+    const value = await handle.evaluateHandle(h => h[1].a);
+    const assertion: AssertType<playwright.JSHandle<string>, typeof value> = true;
+  }
+  {
+    const handle = await page.locator('body').evaluateHandle(() => ([{a: '123'}]));
+    const value = await handle.evaluateHandle((h, p) => ({ a: h[1].a, p}), 123);
+    const assertion: AssertType<playwright.JSHandle<{a: string, p: number}>, typeof value> = true;
+  }
+  {
+    const handle = await page.locator('body').evaluateHandle(() => ([{a: '123'}]));
+    const value = await handle.evaluateHandle((h: ({a: string, b: number})[]) => h[1].b);
+    const assertion: AssertType<playwright.JSHandle<number>, typeof value> = true;
+  }
+  {
+    const handle = await page.locator('body').evaluateHandle(e => {
+      const assertion1: AssertType<HTMLElement, typeof e> = true;
+      const assertion2: AssertType<SVGElement, typeof e> = true;
+      return e.nodeName;
+    });
+    const value = await handle.evaluate(e => e);
+    const assertion: AssertType<string, typeof value> = true;
+  }{
+    const handle = await page.locator('body').evaluateHandle(() => 3);
+    const value = await page.evaluate(([a, b, c, d]) => ({a, b, c, d}), wrap(handle));
+    const assertion: AssertType<{a: number, b: string, c: boolean, d: number}, typeof value> = true;
+  }
+  {
+    const handle = await page.locator('body').evaluateHandle(() => 3);
+    const h = await page.locator('body').evaluateHandle((_, [a, b, c, d]) => ({a, b, c, d}), wrap(handle));
+    const value = await h.evaluate(h => h);
+    const assertion: AssertType<{a: number, b: string, c: boolean, d: number}, typeof value> = true;
+  }
   {
     const handle = await page.evaluateHandle(() => ([{a: '123'}]));
     const value = await handle.evaluate(h => h[1].a);