diff --git a/packages/puppeteer-core/src/common/Page.ts b/packages/puppeteer-core/src/common/Page.ts index 7c265d3b..b28fc475 100644 --- a/packages/puppeteer-core/src/common/Page.ts +++ b/packages/puppeteer-core/src/common/Page.ts @@ -336,47 +336,20 @@ export class CDPPage extends Page { } /** - * @returns `true` if drag events are being intercepted, `false` otherwise. + * @internal */ + _client(): CDPSession { + return this.#client; + } + override isDragInterceptionEnabled(): boolean { return this.#userDragInterceptionEnabled; } - /** - * @returns `true` if the page has JavaScript enabled, `false` otherwise. - */ override isJavaScriptEnabled(): boolean { return this.#javascriptEnabled; } - /** - * This method is typically coupled with an action that triggers file - * choosing. - * - * :::caution - * - * This must be called before the file chooser is launched. It will not return - * a currently active file chooser. - * - * ::: - * - * @remarks - * In non-headless Chromium, this method results in the native file picker - * dialog `not showing up` for the user. - * - * @example - * The following example clicks a button that issues a file chooser - * and then responds with `/tmp/myfile.pdf` as if a user has selected this file. - * - * ```ts - * const [fileChooser] = await Promise.all([ - * page.waitForFileChooser(), - * page.click('#upload-file-button'), - * // some button that triggers file selection - * ]); - * await fileChooser.accept(['/tmp/myfile.pdf']); - * ``` - */ override waitForFileChooser( options: WaitTimeoutOptions = {} ): Promise { @@ -403,19 +376,6 @@ export class CDPPage extends Page { }); } - /** - * Sets the page's geolocation. - * - * @remarks - * Consider using {@link BrowserContext.overridePermissions} to grant - * permissions for the page to read its geolocation. - * - * @example - * - * ```ts - * await page.setGeolocation({latitude: 59.95, longitude: 30.31667}); - * ``` - */ override async setGeolocation(options: GeolocationOptions): Promise { const {longitude, latitude, accuracy = 0} = options; if (longitude < -180 || longitude > 180) { @@ -440,30 +400,14 @@ export class CDPPage extends Page { }); } - /** - * @returns A target this page was created from. - */ override target(): Target { return this.#target; } - /** - * @internal - */ - _client(): CDPSession { - return this.#client; - } - - /** - * Get the browser the page belongs to. - */ override browser(): Browser { return this.#target.browser(); } - /** - * Get the browser context that the page belongs to. - */ override browserContext(): BrowserContext { return this.#target.browserContext(); } @@ -487,12 +431,6 @@ export class CDPPage extends Page { } } - /** - * @returns The page's main frame. - * - * @remarks - * Page is guaranteed to have a main frame which persists during navigations. - */ override mainFrame(): Frame { return this.#frameManager.mainFrame(); } @@ -517,75 +455,18 @@ export class CDPPage extends Page { return this.#accessibility; } - /** - * @returns An array of all frames attached to the page. - */ override frames(): Frame[] { return this.#frameManager.frames(); } - /** - * @returns all of the dedicated {@link - * https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API | - * WebWorkers} associated with the page. - * - * @remarks - * This does not contain ServiceWorkers - */ override workers(): WebWorker[] { return Array.from(this.#workers.values()); } - /** - * Activating request interception enables {@link HTTPRequest.abort}, - * {@link HTTPRequest.continue} and {@link HTTPRequest.respond} methods. This - * provides the capability to modify network requests that are made by a page. - * - * Once request interception is enabled, every request will stall unless it's - * continued, responded or aborted; or completed using the browser cache. - * - * Enabling request interception disables page caching. - * - * See the - * {@link https://pptr.dev/next/guides/request-interception|Request interception guide} - * for more details. - * - * @example - * An example of a naïve request interceptor that aborts all image requests: - * - * ```ts - * const puppeteer = require('puppeteer'); - * (async () => { - * const browser = await puppeteer.launch(); - * const page = await browser.newPage(); - * await page.setRequestInterception(true); - * page.on('request', interceptedRequest => { - * if ( - * interceptedRequest.url().endsWith('.png') || - * interceptedRequest.url().endsWith('.jpg') - * ) - * interceptedRequest.abort(); - * else interceptedRequest.continue(); - * }); - * await page.goto('https://example.com'); - * await browser.close(); - * })(); - * ``` - * - * @param value - Whether to enable request interception. - */ override async setRequestInterception(value: boolean): Promise { return this.#frameManager.networkManager.setRequestInterception(value); } - /** - * @param enabled - Whether to enable drag interception. - * - * @remarks - * Activating drag interception enables the `Input.drag`, - * methods This provides the capability to capture drag events emitted - * on the page, which can then be used to simulate drag-and-drop. - */ override async setDragInterception(enabled: boolean): Promise { this.#userDragInterceptionEnabled = enabled; return this.#client.send('Input.setInterceptDrags', {enabled}); @@ -603,125 +484,30 @@ export class CDPPage extends Page { ); } - /** - * This setting will change the default maximum navigation time for the - * following methods and related shortcuts: - * - * - {@link Page.goBack | page.goBack(options)} - * - * - {@link Page.goForward | page.goForward(options)} - * - * - {@link Page.goto | page.goto(url,options)} - * - * - {@link Page.reload | page.reload(options)} - * - * - {@link Page.setContent | page.setContent(html,options)} - * - * - {@link Page.waitForNavigation | page.waitForNavigation(options)} - * @param timeout - Maximum navigation time in milliseconds. - */ override setDefaultNavigationTimeout(timeout: number): void { this.#timeoutSettings.setDefaultNavigationTimeout(timeout); } - /** - * @param timeout - Maximum time in milliseconds. - */ override setDefaultTimeout(timeout: number): void { this.#timeoutSettings.setDefaultTimeout(timeout); } - /** - * @returns Maximum time in milliseconds. - */ override getDefaultTimeout(): number { return this.#timeoutSettings.timeout(); } - /** - * Runs `document.querySelector` within the page. If no element matches the - * selector, the return value resolves to `null`. - * - * @param selector - A `selector` to query page for - * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector} - * to query page for. - */ override async $( selector: Selector ): Promise> | null> { return this.mainFrame().$(selector); } - /** - * The method runs `document.querySelectorAll` within the page. If no elements - * match the selector, the return value resolves to `[]`. - * @remarks - * Shortcut for {@link Frame.$$ | Page.mainFrame().$$(selector) }. - * @param selector - A `selector` to query page for - */ override async $$( selector: Selector ): Promise>>> { return this.mainFrame().$$(selector); } - /** - * @remarks - * - * The only difference between {@link Page.evaluate | page.evaluate} and - * `page.evaluateHandle` is that `evaluateHandle` will return the value - * wrapped in an in-page object. - * - * If the function passed to `page.evaluteHandle` returns a Promise, the - * function will wait for the promise to resolve and return its value. - * - * You can pass a string instead of a function (although functions are - * recommended as they are easier to debug and use with TypeScript): - * - * @example - * - * ```ts - * const aHandle = await page.evaluateHandle('document'); - * ``` - * - * @example - * {@link JSHandle} instances can be passed as arguments to the `pageFunction`: - * - * ```ts - * const aHandle = await page.evaluateHandle(() => document.body); - * const resultHandle = await page.evaluateHandle( - * body => body.innerHTML, - * aHandle - * ); - * console.log(await resultHandle.jsonValue()); - * await resultHandle.dispose(); - * ``` - * - * Most of the time this function returns a {@link JSHandle}, - * but if `pageFunction` returns a reference to an element, - * you instead get an {@link ElementHandle} back: - * - * @example - * - * ```ts - * const button = await page.evaluateHandle(() => - * document.querySelector('button') - * ); - * // can call `click` because `button` is an `ElementHandle` - * await button.click(); - * ``` - * - * The TypeScript definitions assume that `evaluateHandle` returns - * a `JSHandle`, but if you know it's going to return an - * `ElementHandle`, pass it as the generic argument: - * - * ```ts - * const button = await page.evaluateHandle(...); - * ``` - * - * @param pageFunction - a function that is run within the page - * @param args - arguments to be passed to the pageFunction - */ override async evaluateHandle< Params extends unknown[], Func extends EvaluateFunc = EvaluateFunc @@ -733,29 +519,6 @@ export class CDPPage extends Page { return context.evaluateHandle(pageFunction, ...args); } - /** - * This method iterates the JavaScript heap and finds all objects with the - * given prototype. - * - * @example - * - * ```ts - * // Create a Map object - * await page.evaluate(() => (window.map = new Map())); - * // Get a handle to the Map object prototype - * const mapPrototype = await page.evaluateHandle(() => Map.prototype); - * // Query all map instances into an array - * const mapInstances = await page.queryObjects(mapPrototype); - * // Count amount of map objects in heap - * const count = await page.evaluate(maps => maps.length, mapInstances); - * await mapInstances.dispose(); - * await mapPrototype.dispose(); - * ``` - * - * @param prototypeHandle - a handle to the object prototype. - * @returns Promise which resolves to a handle to an array of objects with - * this prototype. - */ override async queryObjects( prototypeHandle: JSHandle ): Promise> { @@ -772,68 +535,6 @@ export class CDPPage extends Page { return createJSHandle(context, response.objects) as HandleFor; } - /** - * This method runs `document.querySelector` within the page and passes the - * result as the first argument to the `pageFunction`. - * - * @remarks - * - * If no element is found matching `selector`, the method will throw an error. - * - * If `pageFunction` returns a promise `$eval` will wait for the promise to - * resolve and then return its value. - * - * @example - * - * ```ts - * const searchValue = await page.$eval('#search', el => el.value); - * const preloadHref = await page.$eval('link[rel=preload]', el => el.href); - * const html = await page.$eval('.main-container', el => el.outerHTML); - * ``` - * - * If you are using TypeScript, you may have to provide an explicit type to the - * first argument of the `pageFunction`. - * By default it is typed as `Element`, but you may need to provide a more - * specific sub-type: - * - * @example - * - * ```ts - * // if you don't provide HTMLInputElement here, TS will error - * // as `value` is not on `Element` - * const searchValue = await page.$eval( - * '#search', - * (el: HTMLInputElement) => el.value - * ); - * ``` - * - * The compiler should be able to infer the return type - * from the `pageFunction` you provide. If it is unable to, you can use the generic - * type to tell the compiler what return type you expect from `$eval`: - * - * @example - * - * ```ts - * // The compiler can infer the return type in this case, but if it can't - * // or if you want to be more explicit, provide it as the generic type. - * const searchValue = await page.$eval( - * '#search', - * (el: HTMLInputElement) => el.value - * ); - * ``` - * - * @param selector - the - * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector} - * to query for - * @param pageFunction - the function to be evaluated in the page context. - * Will be passed the result of `document.querySelector(selector)` as its - * first argument. - * @param args - any additional arguments to pass through to `pageFunction`. - * - * @returns The result of calling `pageFunction`. If it returns an element it - * is wrapped in an {@link ElementHandle}, else the raw value itself is - * returned. - */ override async $eval< Selector extends string, Params extends unknown[], @@ -848,68 +549,6 @@ export class CDPPage extends Page { return this.mainFrame().$eval(selector, pageFunction, ...args); } - /** - * This method runs `Array.from(document.querySelectorAll(selector))` within - * the page and passes the result as the first argument to the `pageFunction`. - * - * @remarks - * If `pageFunction` returns a promise `$$eval` will wait for the promise to - * resolve and then return its value. - * - * @example - * - * ```ts - * // get the amount of divs on the page - * const divCount = await page.$$eval('div', divs => divs.length); - * - * // get the text content of all the `.options` elements: - * const options = await page.$$eval('div > span.options', options => { - * return options.map(option => option.textContent); - * }); - * ``` - * - * If you are using TypeScript, you may have to provide an explicit type to the - * first argument of the `pageFunction`. - * By default it is typed as `Element[]`, but you may need to provide a more - * specific sub-type: - * - * @example - * - * ```ts - * // if you don't provide HTMLInputElement here, TS will error - * // as `value` is not on `Element` - * await page.$$eval('input', (elements: HTMLInputElement[]) => { - * return elements.map(e => e.value); - * }); - * ``` - * - * The compiler should be able to infer the return type - * from the `pageFunction` you provide. If it is unable to, you can use the generic - * type to tell the compiler what return type you expect from `$$eval`: - * - * @example - * - * ```ts - * // The compiler can infer the return type in this case, but if it can't - * // or if you want to be more explicit, provide it as the generic type. - * const allInputValues = await page.$$eval( - * 'input', - * (elements: HTMLInputElement[]) => elements.map(e => e.textContent) - * ); - * ``` - * - * @param selector - the - * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector} - * to query for - * @param pageFunction - the function to be evaluated in the page context. - * Will be passed the result of - * `Array.from(document.querySelectorAll(selector))` as its first argument. - * @param args - any additional arguments to pass through to `pageFunction`. - * - * @returns The result of calling `pageFunction`. If it returns an element it - * is wrapped in an {@link ElementHandle}, else the raw value itself is - * returned. - */ override async $$eval< Selector extends string, Params extends unknown[], @@ -924,24 +563,10 @@ export class CDPPage extends Page { return this.mainFrame().$$eval(selector, pageFunction, ...args); } - /** - * The method evaluates the XPath expression relative to the page document as - * its context node. If there are no such elements, the method resolves to an - * empty array. - * - * @remarks - * Shortcut for {@link Frame.$x | Page.mainFrame().$x(expression) }. - * - * @param expression - Expression to evaluate - */ override async $x(expression: string): Promise>> { return this.mainFrame().$x(expression); } - /** - * If no URLs are specified, this method returns cookies for the current page - * URL. If URLs are specified, only cookies for those URLs are returned. - */ override async cookies( ...urls: string[] ): Promise { @@ -976,13 +601,6 @@ export class CDPPage extends Page { } } - /** - * @example - * - * ```ts - * await page.setCookie(cookieObject1, cookieObject2); - * ``` - */ override async setCookie( ...cookies: Protocol.Network.CookieParam[] ): Promise { @@ -1009,33 +627,12 @@ export class CDPPage extends Page { } } - /** - * Adds a `