diff --git a/types/expect-puppeteer/index.d.ts b/types/expect-puppeteer/index.d.ts index 4d599f99fe..24675ee695 100644 --- a/types/expect-puppeteer/index.d.ts +++ b/types/expect-puppeteer/index.d.ts @@ -2,7 +2,7 @@ // Project: https://github.com/smooth-code/jest-puppeteer/tree/master/packages/expect-puppeteer // Definitions by: Josh Goldberg // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped -// TypeScript Version: 2.4 +// TypeScript Version: 2.8 /// diff --git a/types/jest-environment-puppeteer/index.d.ts b/types/jest-environment-puppeteer/index.d.ts index e22bee2f7d..79c25e32d8 100644 --- a/types/jest-environment-puppeteer/index.d.ts +++ b/types/jest-environment-puppeteer/index.d.ts @@ -2,7 +2,7 @@ // Project: https://github.com/smooth-code/jest-puppeteer/tree/master/packages/jest-environment-puppeteer // Definitions by: Josh Goldberg // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped -// TypeScript Version: 2.3 +// TypeScript Version: 2.8 import { Browser, Page } from "puppeteer"; diff --git a/types/puppeteer/index.d.ts b/types/puppeteer/index.d.ts index 4dea13760f..b9a812aaeb 100644 --- a/types/puppeteer/index.d.ts +++ b/types/puppeteer/index.d.ts @@ -1,15 +1,203 @@ -// Type definitions for puppeteer 1.3 +// Type definitions for puppeteer 1.5 // Project: https://github.com/GoogleChrome/puppeteer#readme // Definitions by: Marvin Hagemeister // Christopher Deutsch +// Konstantin Simon Maria Möllers // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped -// TypeScript Version: 2.3 +// TypeScript Version: 2.8 /// import { EventEmitter } from "events"; import { ChildProcess } from "child_process"; +/** Wraps a DOM element into an ElementHandle instance */ +export type WrapElementHandle = X extends Element ? ElementHandle : X; + +/** Unwraps a DOM element out of an ElementHandle instance */ +export type UnwrapElementHandle = X extends ElementHandle ? E : X; + +/** Defines `$eval` and `$$eval` for Page, Frame and ElementHandle. */ +export interface Evalable { + /** + * This method runs `document.querySelector` within the context and passes it as the first argument to `pageFunction`. + * If there's no element matching `selector`, the method throws an error. + * + * If `pageFunction` returns a Promise, then `$eval` would wait for the promise to resolve and return its value. + * + * @param selector A selector to query for + * @param pageFunction Function to be evaluated in browser context + * @returns Promise which resolves to the return value of pageFunction + */ + $eval( + selector: string, + pageFunction: (element: Element) => R | Promise, + ): Promise>; + + /** + * This method runs `document.querySelector` within the context and passes it as the first argument to `pageFunction`. + * If there's no element matching `selector`, the method throws an error. + * + * If `pageFunction` returns a Promise, then `$eval` would wait for the promise to resolve and return its value. + * + * @param selector A selector to query for + * @param pageFunction Function to be evaluated in browser context + * @param x1 First argument to pass to pageFunction + * @returns Promise which resolves to the return value of pageFunction + */ + $eval( + selector: string, + pageFunction: (element: Element, x1: UnwrapElementHandle) => R | Promise, + x1: X1, + ): Promise>; + + /** + * This method runs `document.querySelector` within the context and passes it as the first argument to `pageFunction`. + * If there's no element matching `selector`, the method throws an error. + * + * If `pageFunction` returns a Promise, then `$eval` would wait for the promise to resolve and return its value. + * + * @param selector A selector to query for + * @param pageFunction Function to be evaluated in browser context + * @param x1 First argument to pass to pageFunction + * @param x2 Second argument to pass to pageFunction + * @returns Promise which resolves to the return value of pageFunction + */ + $eval( + selector: string, + pageFunction: (element: Element, x1: UnwrapElementHandle, x2: UnwrapElementHandle) => R | Promise, + x1: X1, + x2: X2, + ): Promise>; + + /** + * This method runs `document.querySelector` within the context and passes it as the first argument to `pageFunction`. + * If there's no element matching `selector`, the method throws an error. + * + * If `pageFunction` returns a Promise, then `$eval` would wait for the promise to resolve and return its value. + * + * @param selector A selector to query for + * @param pageFunction Function to be evaluated in browser context + * @param x1 First argument to pass to pageFunction + * @param x2 Second argument to pass to pageFunction + * @param x3 Third argument to pass to pageFunction + * @returns Promise which resolves to the return value of pageFunction + */ + $eval( + selector: string, + pageFunction: (element: Element, x1: UnwrapElementHandle, x2: UnwrapElementHandle, x3: UnwrapElementHandle) => R | Promise, + x1: X1, + x2: X2, + x3: X3, + ): Promise>; + + /** + * This method runs `document.querySelector` within the context and passes it as the first argument to `pageFunction`. + * If there's no element matching `selector`, the method throws an error. + * + * If `pageFunction` returns a Promise, then `$eval` would wait for the promise to resolve and return its value. + * + * @param selector A selector to query for + * @param pageFunction Function to be evaluated in browser context + * @param args Arguments to pass to pageFunction + * @returns Promise which resolves to the return value of pageFunction + */ + $eval( + selector: string, + pageFunction: (element: Element, ...args: any[]) => R | Promise, + ...args: any[], + ): Promise>; + + /** + * This method runs `Array.from(document.querySelectorAll(selector))` within the context and passes it as the + * first argument to `pageFunction`. + * + * If `pageFunction` returns a Promise, then `$$eval` would wait for the promise to resolve and return its value. + * + * @param selector A selector to query for + * @param pageFunction Function to be evaluated in browser context + * @returns Promise which resolves to the return value of pageFunction + */ + $$eval( + selector: string, + pageFunction: (elements: Element[]) => R | Promise, + ): Promise>; + + /** + * This method runs `Array.from(document.querySelectorAll(selector))` within the context and passes it as the + * first argument to `pageFunction`. + * + * If `pageFunction` returns a Promise, then `$$eval` would wait for the promise to resolve and return its value. + * + * @param selector A selector to query for + * @param pageFunction Function to be evaluated in browser context + * @param x1 First argument to pass to pageFunction + * @returns Promise which resolves to the return value of pageFunction + */ + $$eval( + selector: string, + pageFunction: (elements: Element[], x1: UnwrapElementHandle) => R | Promise, + x1: X1, + ): Promise>; + + /** + * This method runs `Array.from(document.querySelectorAll(selector))` within the context and passes it as the + * first argument to `pageFunction`. + * + * If `pageFunction` returns a Promise, then `$$eval` would wait for the promise to resolve and return its value. + * + * @param selector A selector to query for + * @param pageFunction Function to be evaluated in browser context + * @param x1 First argument to pass to pageFunction + * @param x2 Second argument to pass to pageFunction + * @returns Promise which resolves to the return value of pageFunction + */ + $$eval( + selector: string, + pageFunction: (elements: Element[], x1: UnwrapElementHandle, x2: UnwrapElementHandle) => R | Promise, + x1: X1, + x2: X2, + ): Promise>; + + /** + * This method runs `Array.from(document.querySelectorAll(selector))` within the context and passes it as the + * first argument to `pageFunction`. + * + * If `pageFunction` returns a Promise, then `$$eval` would wait for the promise to resolve and return its value. + * + * @param selector A selector to query for + * @param pageFunction Function to be evaluated in browser context + * @param x1 First argument to pass to pageFunction + * @param x2 Second argument to pass to pageFunction + * @param x3 Third argument to pass to pageFunction + * @returns Promise which resolves to the return value of pageFunction + */ + $$eval( + selector: string, + pageFunction: (elements: Element[], x1: UnwrapElementHandle, x2: UnwrapElementHandle, x3: UnwrapElementHandle) => R | Promise, + x1: X1, + x2: X2, + x3: X3, + ): Promise>; + + /** + * This method runs `Array.from(document.querySelectorAll(selector))` within the context and passes it as the + * first argument to `pageFunction`. + * + * If `pageFunction` returns a Promise, then `$$eval` would wait for the promise to resolve and return its value. + * + * @param selector A selector to query for + * @param pageFunction Function to be evaluated in browser context + * @param args Arguments to pass to pageFunction + * @returns Promise which resolves to the return value of pageFunction + */ + $$eval( + selector: string, + pageFunction: (elements: Element[], ...args: any[]) => R | Promise, + ...args: any[] + ): Promise>; +} + /** Keyboard provides an api for managing a virtual keyboard. */ export interface Keyboard { /** @@ -147,7 +335,9 @@ export type PageEvents = | "request" | "requestfailed" | "requestfinished" - | "response"; + | "response" + | "workercreated" + | "workerdestroyed"; export type BrowserEvents = | "disconnected" @@ -452,22 +642,57 @@ export interface Box { y: number; } +/** + * 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( + pageFunction: (...args: any[]) => T | Promise, + ...args: any[], + ): Promise; + + /** + * The only difference between `worker.evaluate` and `worker.evaluateHandle` is + * that `worker.evaluateHandle` returns in-page object (JSHandle). + */ + evaluateHandle( + pageFunction: (...args: any[]) => T | Promise, + ...args: any[], + ): Promise; + + executionContext(): Promise; + + url(): string; +} + /** * Represents an in-page DOM element. ElementHandles can be created with the page.$ method. */ -export interface ElementHandle extends JSHandle { +export interface ElementHandle extends JSHandle, Evalable { /** - * The method runs element.querySelector within the page. If no element matches the selector, the return value resolve to null. + * The method runs element.querySelector within the page. + * If no element matches the selector, the return value resolve to null. * @param selector A selector to query element for * @since 0.13.0 */ $(selector: string): Promise; + /** - * The method runs element.querySelectorAll within the page. If no elements match the selector, the return value resolve to []. + * The method runs element.querySelectorAll within the page. + * If no elements match the selector, the return value resolve to []. * @param selector A selector to query element for * @since 0.13.0 */ $$(selector: string): Promise; + /** * @param selector XPath expression to evaluate. */ @@ -683,6 +908,10 @@ export interface Request { * All header names are lower-case. */ headers(): Headers; + + /** Whether this request is driving frame's navigation. */ + isNavigationRequest(): boolean; + /** Returns the request's method (GET, POST, etc.) */ method(): HttpMethod; @@ -761,46 +990,25 @@ export interface Response { url(): string; } -export interface FrameBase { +export interface FrameBase extends Evalable { /** - * The method runs document.querySelector within the page. - * If no element matches the selector, the return value resolve to null. + * The method queries frame for the selector. + * If there's no such element within the frame, the method will resolve to null. */ $(selector: string): Promise; + /** - * The method runs document.querySelectorAll within the page. If no elements match the selector, the return value resolve to []. + * The method runs document.querySelectorAll within the frame. + * If no elements match the selector, the return value resolve to []. */ $$(selector: string): Promise; + /** + * The method evaluates the XPath expression. * @param expression XPath expression to evaluate. */ $x(expression: string): Promise; - /** - * This method runs document.querySelector within the page and passes it as the first argument to `fn`. - * If there's no element matching selector, the method throws an error. - * If `fn` returns a Promise, then $eval would wait for the promise to resolve and return its value. - */ - $eval( - selector: string, - pageFunction: (element: Element, ...args: any[]) => any, - ...args: any[] - ): Promise; - - /** - * This method runs document.querySelectorAll within the page and passes it as the first argument to `fn`. - * If `fn` returns a Promise, then $$eval would wait for the promise to resolve and return its value. - * @param selector A selector to query frame for - * @param fn Function to be evaluated in browser context - * @param args Arguments to pass to pageFunction - * @returns Promise which resolves to the return value of pageFunction - */ - $$eval( - selector: string, - pageFunction: (elements: NodeListOf, ...args: any[]) => any, - ...args: any[] - ): Promise; - /** Adds a `