feat(puppeteer): v1.19 (#37084)

types/puppeteer/index.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for puppeteer 1.12
+// Type definitions for puppeteer 1.19
 // Project: https://github.com/GoogleChrome/puppeteer#readme
 // Definitions by: Marvin Hagemeister <https://github.com/marvinhagemeister>
 //                 Christopher Deutsch <https://github.com/cdeutsch>
@@ -13,6 +13,11 @@
 import { EventEmitter } from "events";
 import { ChildProcess } from "child_process";
 
+import * as errors from "./Errors";
+import * as devices from "./DeviceDescriptors";
+
+export { errors, devices };
+
 /** Wraps a DOM element into an ElementHandle instance */
 export type WrapElementHandle<X> = X extends Element ? ElementHandle<X> : X;
 
@@ -215,6 +220,31 @@ export interface Evalable {
   ): Promise<WrapElementHandle<R>>;
 }
 
+export interface JSEvalable {
+    /**
+     * Evaluates a function in the browser context.
+     * If the function, passed to the frame.evaluate, returns a Promise, then frame.evaluate would wait for the promise to resolve and return its value.
+     * If the function passed into frame.evaluate returns a non-Serializable value, then frame.evaluate resolves to undefined.
+     * @param fn Function to be evaluated in browser context
+     * @param args Arguments to pass to `fn`
+     */
+    evaluate<T extends EvaluateFn>(
+      pageFunction: T,
+      ...args: SerializableOrJSHandle[],
+    ): Promise<EvaluateFnReturnType<T>>;
+    /**
+     * The only difference between `evaluate` and `evaluateHandle` is that `evaluateHandle` returns in-page object (`JSHandle`).
+     * If the function, passed to the `evaluateHandle`, returns a `Promise`, then `evaluateHandle` would wait for the
+     * promise to resolve and return its value.
+     * @param fn Function to be evaluated in browser context
+     * @param args Arguments to pass to `fn`
+     */
+    evaluateHandle(
+      pageFunction: (...args: any[]) => any,
+      ...args: SerializableOrJSHandle[],
+    ): Promise<JSHandle>;
+  }
+
 /** Keyboard provides an api for managing a virtual keyboard. */
 export interface Keyboard {
   /**
@@ -375,29 +405,6 @@ export interface ConsoleMessage {
   type(): ConsoleMessageType;
 }
 
-export type PageEvents =
-  | "close"
-  | "console"
-  | "dialog"
-  | "error"
-  | "frameattached"
-  | "framedetached"
-  | "framenavigated"
-  | "load"
-  | "pageerror"
-  | "request"
-  | "requestfailed"
-  | "requestfinished"
-  | "response"
-  | "workercreated"
-  | "workerdestroyed";
-
-export type BrowserEvents =
-  | "disconnected"
-  | "targetchanged"
-  | "targetcreated"
-  | "targetdestroyed";
-
 export interface AuthOptions {
   username: string;
   password: string;
@@ -742,28 +749,7 @@ export interface Box {
  * The Worker class represents a WebWorker.
  * The events workercreated and workerdestroyed are emitted on the page object to signal the worker lifecycle.
  */
-export interface Worker {
-  /**
-   * If the function passed to the `worker.evaluate` returns a Promise,
-   * then `worker.evaluate` would wait for the promise to resolve and return its value.
-   *
-   * If the function passed to the `worker.evaluate` returns a non-Serializable value,
-   * then `worker.evaluate` resolves to `undefined`.
-   */
-  evaluate<T extends EvaluateFn>(
-    pageFunction: T,
-    ...args: SerializableOrJSHandle[],
-  ): Promise<EvaluateFnReturnType<T>>;
-
-  /**
-   * The only difference between `worker.evaluate` and `worker.evaluateHandle` is
-   * that `worker.evaluateHandle` returns in-page object (JSHandle).
-   */
-  evaluateHandle<T>(
-    pageFunction: (...args: any[]) => T | Promise<T>,
-    ...args: SerializableOrJSHandle[],
-  ): Promise<T>;
-
+export interface Worker extends JSEvalable {
   executionContext(): Promise<ExecutionContext>;
 
   url(): string;
@@ -861,15 +847,7 @@ export interface ElementHandle<E extends Element = Element> extends JSHandle, Ev
 }
 
 /** The class represents a context for JavaScript execution. */
-export interface ExecutionContext {
-  evaluate<F extends EvaluateFn>(
-    fn: F,
-    ...args: SerializableOrJSHandle[]
-  ): Promise<EvaluateFnReturnType<F>>;
-  evaluateHandle(
-    fn: EvaluateFn,
-    ...args: SerializableOrJSHandle[]
-  ): Promise<JSHandle>;
+export interface ExecutionContext extends JSEvalable {
   queryObjects(prototypeHandle: JSHandle): JSHandle;
 }
 
@@ -1141,7 +1119,7 @@ export interface WaitForSelectorOptionsHidden extends WaitForSelectorOptions {
   hidden: true;
 }
 
-export interface FrameBase extends Evalable {
+export interface FrameBase extends Evalable, JSEvalable {
   /**
    * The method queries frame for the selector.
    * If there's no such element within the frame, the method will resolve to null.
@@ -1185,31 +1163,6 @@ export interface FrameBase extends Evalable {
    */
   goto(url: string, options?: DirectNavigationOptions): Promise<Response | null>;
 
-  /**
-   * Evaluates a function in the browser context.
-   * If the function, passed to the frame.evaluate, returns a Promise, then frame.evaluate would wait for the promise to resolve and return its value.
-   * If the function passed into frame.evaluate returns a non-Serializable value, then frame.evaluate resolves to undefined.
-   * @param fn Function to be evaluated in browser context
-   * @param args Arguments to pass to `fn`
-   */
-  evaluate<F extends EvaluateFn>(
-    fn: F,
-    ...args: SerializableOrJSHandle[]
-  ): Promise<EvaluateFnReturnType<F>>;
-
-  /**
-   * Evaluates a function in the page context.
-   * If the function, passed to the page.evaluateHandle, returns a Promise, then page.evaluateHandle
-   * would wait for the promise to resolve and return its value.
-   * @param fn The function to be evaluated in the page context.
-   * @param args The arguments to pass to the `fn`.
-   * @returns A promise which resolves to return value of `fn`.
-   */
-  evaluateHandle(
-    fn: EvaluateFn,
-    ...args: SerializableOrJSHandle[]
-  ): Promise<JSHandle>;
-
   /** This method fetches an element with selector and focuses it. */
   focus(selector: string): Promise<void>;
 
@@ -1513,6 +1466,11 @@ export interface SnapshopOptions {
    * @default true
    */
   interestingOnly?: boolean;
+  /**
+   * The root DOM element for the snapshot.
+   * @default document.body
+   */
+  root?: ElementHandle;
 }
 
 /**
@@ -1531,6 +1489,18 @@ export interface Accessibility {
   snapshot(options?: SnapshopOptions): Promise<AXNode>;
 }
 
+export interface FileChooser {
+  /**
+   * Accept the file chooser request with given paths.
+   * If some of the filePaths are relative paths, then they are resolved relative to the current working directory.
+   */
+  accept(filePaths: string[]): Promise<void>;
+  /** Closes the file chooser without selecting any files. */
+  cancel(): Promise<void>;
+  /** Whether file chooser allow for multiple file selection. */
+  isMultiple(): boolean;
+}
+
 /** Page provides methods to interact with a single tab in Chromium. One Browser instance might have multiple Page instances. */
 export interface Page extends EventEmitter, FrameBase {
   /**
@@ -1596,19 +1566,6 @@ export interface Page extends EventEmitter, FrameBase {
   /** Emulates the media. */
   emulateMedia(mediaType: MediaType | null): Promise<void>;
 
-  /**
-   * Evaluates a function in the page context.
-   * If the function, passed to the page.evaluateHandle, returns a Promise, then page.evaluateHandle
-   * would wait for the promise to resolve and return its value.
-   * @param fn The function to be evaluated in the page context.
-   * @param args The arguments to pass to the `fn`.
-   * @returns A promise which resolves to return value of `fn`.
-   */
-  evaluateHandle(
-    fn: EvaluateFn,
-    ...args: SerializableOrJSHandle[]
-  ): Promise<JSHandle>;
-
   /**
    * Adds a function which would be invoked in one of the following scenarios: whenever the page is navigated; whenever the child frame is attached or navigated.
    * The function is invoked after the document was created but before any of its scripts were run. This is useful to amend JavaScript environment, e.g. to seed Math.random.
@@ -1805,6 +1762,13 @@ export interface Page extends EventEmitter, FrameBase {
     options?: Timeoutable
   ): Promise<Response>;
 
+  /**
+   * In non-headless Chromium, this method results in the native file picker dialog not showing up for the user.
+   * This method is typically coupled with an action that triggers file choosing.
+   * This must be called before the file chooser is launched. It will not return a currently active file chooser.
+   */
+  waitForFileChooser(options?: Timeoutable): Promise<FileChooser>;
+
   /** This method returns all of the dedicated WebWorkers associated with the page. */
   workers(): Worker[];
 }
@@ -1862,6 +1826,9 @@ export interface Browser extends EventEmitter, TargetAwaiter {
    */
   disconnect(): void;
 
+  /** Indicates that the browser is connected. */
+  isConnected(): boolean;
+
   /**
    * Returns the default browser context.
    * The default browser context can not be closed.
@@ -2003,7 +1970,7 @@ export interface BrowserContextEventObj {
   targetdestroyed: Target;
 }
 
-export type TargetType = "page" | "background_page" | "service_worker" | "browser" | "other";
+export type TargetType = "page" | "background_page" | "shared_worker" | "service_worker" | "browser" | "other";
 
 export interface Target {
   /** Get the browser the target belongs to. */
@@ -2026,6 +1993,9 @@ export interface Target {
 
   /** Returns the target URL. */
   url(): string;
+
+  /** If the target is not of type `service_worker` or `shared_worker`, resolves `null`. */
+  worker(): Promise<Worker | null>;
 }
 
 export interface LaunchOptions extends ChromeArgOptions, BrowserOptions, Timeoutable {

types/puppeteer/puppeteer-tests.ts

@@ -9,6 +9,7 @@ import * as Devices from "puppeteer/DeviceDescriptors";
   const page = await browser.newPage();
   const snap = await page.accessibility.snapshot({
     interestingOnly: true,
+    root: undefined,
   });
   for (const child of snap.children) {
     console.log(child.name);
@@ -121,6 +122,7 @@ puppeteer.launch().then(async browser => {
 
   await page.emulateMedia("screen");
   await page.emulate(Devices['test']);
+  await page.emulate(puppeteer.devices['test']);
   await page.pdf({ path: "page.pdf" });
 
   await page.setRequestInterception(true);
@@ -643,3 +645,21 @@ puppeteer.launch().then(async browser => {
       await browserFetcher.remove(rev);
     }
 });
+
+(async () => {
+  const browser = await puppeteer.launch();
+  const page = await browser.newPage();
+  const url = page.workers()[0].url();
+  if (page.target().type() === 'shared_worker') {
+      const a: number = await (await page.target().worker())!.evaluate(() => 1);
+  }
+});
+
+(async () => {
+  const browser = await puppeteer.launch();
+  const page = await browser.newPage();
+  const fileChooser = await page.waitForFileChooser({ timeout: 999 });
+  await fileChooser.cancel();
+  const isMultiple: boolean = fileChooser.isMultiple();
+  await fileChooser.accept(['/foo/bar']);
+});