From b5a124ff738a03fa7eb5755b441af5b773447449 Mon Sep 17 00:00:00 2001 From: Junyan Date: Fri, 26 May 2023 15:56:45 +0800 Subject: [PATCH] feat: Page.removeScriptToEvaluateOnNewDocument (#10250) Co-authored-by: Alex Rudenko --- docs/api/index.md | 1 + .../puppeteer.newdocumentscriptevaluation.md | 17 ++ .../puppeteer.page.evaluateonnewdocument.md | 7 +- docs/api/puppeteer.page.md | 179 +++++++++--------- ...age.removescripttoevaluateonnewdocument.md | 25 +++ packages/puppeteer-core/src/api/Page.ts | 24 ++- packages/puppeteer-core/src/common/Page.ts | 23 ++- test/TestExpectations.json | 32 ++-- test/src/evaluation.spec.ts | 24 +++ 9 files changed, 220 insertions(+), 112 deletions(-) create mode 100644 docs/api/puppeteer.newdocumentscriptevaluation.md create mode 100644 docs/api/puppeteer.page.removescripttoevaluateonnewdocument.md diff --git a/docs/api/index.md b/docs/api/index.md index b8feadafe02..eea71759880 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -98,6 +98,7 @@ sidebar_label: API | [MouseOptions](./puppeteer.mouseoptions.md) | | | [MouseWheelOptions](./puppeteer.mousewheeloptions.md) | | | [NetworkConditions](./puppeteer.networkconditions.md) | | +| [NewDocumentScriptEvaluation](./puppeteer.newdocumentscriptevaluation.md) | | | [Offset](./puppeteer.offset.md) | | | [PageEventObject](./puppeteer.pageeventobject.md) |

Denotes the objects received by callback functions for page events.

See [PageEmittedEvents](./puppeteer.pageemittedevents.md) for more detail on the events and when they are emitted.

| | [PDFMargin](./puppeteer.pdfmargin.md) | | diff --git a/docs/api/puppeteer.newdocumentscriptevaluation.md b/docs/api/puppeteer.newdocumentscriptevaluation.md new file mode 100644 index 00000000000..7e29978b089 --- /dev/null +++ b/docs/api/puppeteer.newdocumentscriptevaluation.md @@ -0,0 +1,17 @@ +--- +sidebar_label: NewDocumentScriptEvaluation +--- + +# NewDocumentScriptEvaluation interface + +#### Signature: + +```typescript +export interface NewDocumentScriptEvaluation +``` + +## Properties + +| Property | Modifiers | Type | Description | Default | +| ---------- | --------- | ------ | ----------- | ------- | +| identifier | | string | | | diff --git a/docs/api/puppeteer.page.evaluateonnewdocument.md b/docs/api/puppeteer.page.evaluateonnewdocument.md index 770fc870a7c..7f70366d86c 100644 --- a/docs/api/puppeteer.page.evaluateonnewdocument.md +++ b/docs/api/puppeteer.page.evaluateonnewdocument.md @@ -19,7 +19,10 @@ class Page { evaluateOnNewDocument< Params extends unknown[], Func extends (...args: Params) => unknown = (...args: Params) => unknown - >(pageFunction: Func | string, ...args: Params): Promise; + >( + pageFunction: Func | string, + ...args: Params + ): Promise; } ``` @@ -32,7 +35,7 @@ class Page { **Returns:** -Promise<void> +Promise<[NewDocumentScriptEvaluation](./puppeteer.newdocumentscriptevaluation.md)> ## Example diff --git a/docs/api/puppeteer.page.md b/docs/api/puppeteer.page.md index 55bc3f3b90c..84afbc8a909 100644 --- a/docs/api/puppeteer.page.md +++ b/docs/api/puppeteer.page.md @@ -74,92 +74,93 @@ page.off('request', logRequest); ## Methods -| Method | Modifiers | Description | -| ------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [$(selector)](./puppeteer.page._.md) | | Runs document.querySelector within the page. If no element matches the selector, the return value resolves to null. | -| [$$(selector)](./puppeteer.page.__.md) | | The method runs document.querySelectorAll within the page. If no elements match the selector, the return value resolves to []. | -| [$$eval(selector, pageFunction, args)](./puppeteer.page.__eval.md) | | This method runs Array.from(document.querySelectorAll(selector)) within the page and passes the result as the first argument to the pageFunction. | -| [$eval(selector, pageFunction, args)](./puppeteer.page._eval.md) | | This method runs document.querySelector within the page and passes the result as the first argument to the pageFunction. | -| [$x(expression)](./puppeteer.page._x.md) | | 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. | -| [addScriptTag(options)](./puppeteer.page.addscripttag.md) | | Adds a <script> tag into the page with the desired URL or content. | -| [addStyleTag(options)](./puppeteer.page.addstyletag.md) | |

Adds a <link rel="stylesheet"> tag into the page with the desired URL or a <style type="text/css"> tag with the content.

Shortcut for [page.mainFrame().addStyleTag(options)](./puppeteer.frame.addstyletag_1.md).

| -| [addStyleTag(options)](./puppeteer.page.addstyletag_1.md) | | | -| [addStyleTag(options)](./puppeteer.page.addstyletag_2.md) | | | -| [authenticate(credentials)](./puppeteer.page.authenticate.md) | | Provide credentials for HTTP authentication. | -| [bringToFront()](./puppeteer.page.bringtofront.md) | | Brings page to front (activates tab). | -| [browser()](./puppeteer.page.browser.md) | | Get the browser the page belongs to. | -| [browserContext()](./puppeteer.page.browsercontext.md) | | Get the browser context that the page belongs to. | -| [click(selector, options)](./puppeteer.page.click.md) | | This method fetches an element with selector, scrolls it into view if needed, and then uses [Page.mouse](./puppeteer.page.md) to click in the center of the element. If there's no element matching selector, the method throws an error. | -| [close(options)](./puppeteer.page.close.md) | | | -| [content()](./puppeteer.page.content.md) | | The full HTML contents of the page, including the DOCTYPE. | -| [cookies(urls)](./puppeteer.page.cookies.md) | | 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. | -| [createPDFStream(options)](./puppeteer.page.createpdfstream.md) | | Generates a PDF of the page with the print CSS media type. | -| [deleteCookie(cookies)](./puppeteer.page.deletecookie.md) | | | -| [emulate(device)](./puppeteer.page.emulate.md) | |

Emulates a given device's metrics and user agent.

To aid emulation, Puppeteer provides a list of known devices that can be via [KnownDevices](./puppeteer.knowndevices.md).

| -| [emulateCPUThrottling(factor)](./puppeteer.page.emulatecputhrottling.md) | | Enables CPU throttling to emulate slow CPUs. | -| [emulateIdleState(overrides)](./puppeteer.page.emulateidlestate.md) | | Emulates the idle state. If no arguments set, clears idle state emulation. | -| [emulateMediaFeatures(features)](./puppeteer.page.emulatemediafeatures.md) | | | -| [emulateMediaType(type)](./puppeteer.page.emulatemediatype.md) | | | -| [emulateNetworkConditions(networkConditions)](./puppeteer.page.emulatenetworkconditions.md) | |

This does not affect WebSockets and WebRTC PeerConnections (see https://crbug.com/563644). To set the page offline, you can use [Page.setOfflineMode()](./puppeteer.page.setofflinemode.md).

A list of predefined network conditions can be used by importing [PredefinedNetworkConditions](./puppeteer.predefinednetworkconditions.md).

| -| [emulateTimezone(timezoneId)](./puppeteer.page.emulatetimezone.md) | | | -| [emulateVisionDeficiency(type)](./puppeteer.page.emulatevisiondeficiency.md) | | Simulates the given vision deficiency on the page. | -| [evaluate(pageFunction, args)](./puppeteer.page.evaluate.md) | |

Evaluates a function in the page's context and returns the result.

If the function passed to page.evaluateHandle returns a Promise, the function will wait for the promise to resolve and return its value.

| -| [evaluateHandle(pageFunction, args)](./puppeteer.page.evaluatehandle.md) | | | -| [evaluateOnNewDocument(pageFunction, args)](./puppeteer.page.evaluateonnewdocument.md) | |

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. In this case, the function is invoked in the context of the newly attached frame.

The function is invoked after the document was created but before any of its scripts were run. This is useful to amend the JavaScript environment, e.g. to seed Math.random.

| -| [exposeFunction(name, pptrFunction)](./puppeteer.page.exposefunction.md) | |

The method adds a function called name on the page's window object. When called, the function executes puppeteerFunction in node.js and returns a Promise which resolves to the return value of puppeteerFunction.

If the puppeteerFunction returns a Promise, it will be awaited.

:::note

Functions installed via page.exposeFunction survive navigations.

:::note

| -| [focus(selector)](./puppeteer.page.focus.md) | | This method fetches an element with selector and focuses it. If there's no element matching selector, the method throws an error. | -| [frames()](./puppeteer.page.frames.md) | | An array of all frames attached to the page. | -| [getDefaultTimeout()](./puppeteer.page.getdefaulttimeout.md) | | Maximum time in milliseconds. | -| [goBack(options)](./puppeteer.page.goback.md) | | This method navigate to the previous page in history. | -| [goForward(options)](./puppeteer.page.goforward.md) | | This method navigate to the next page in history. | -| [goto(url, options)](./puppeteer.page.goto.md) | | | -| [hover(selector)](./puppeteer.page.hover.md) | | This method fetches an element with selector, scrolls it into view if needed, and then uses [Page.mouse](./puppeteer.page.md) to hover over the center of the element. If there's no element matching selector, the method throws an error. | -| [isClosed()](./puppeteer.page.isclosed.md) | | Indicates that the page has been closed. | -| [isDragInterceptionEnabled()](./puppeteer.page.isdraginterceptionenabled.md) | | true if drag events are being intercepted, false otherwise. | -| [isJavaScriptEnabled()](./puppeteer.page.isjavascriptenabled.md) | | true if the page has JavaScript enabled, false otherwise. | -| [isServiceWorkerBypassed()](./puppeteer.page.isserviceworkerbypassed.md) | | true if the service worker are being bypassed, false otherwise. | -| [mainFrame()](./puppeteer.page.mainframe.md) | | The page's main frame. | -| [metrics()](./puppeteer.page.metrics.md) | | Object containing metrics as key/value pairs. | -| [off(eventName, handler)](./puppeteer.page.off.md) | | | -| [on(eventName, handler)](./puppeteer.page.on.md) | |

Listen to page events.

:::note

This method exists to define event typings and handle proper wireup of cooperative request interception. Actual event listening and dispatching is delegated to [EventEmitter](./puppeteer.eventemitter.md).

:::

| -| [once(eventName, handler)](./puppeteer.page.once.md) | | | -| [pdf(options)](./puppeteer.page.pdf.md) | | Generates a PDF of the page with the print CSS media type. | -| [queryObjects(prototypeHandle)](./puppeteer.page.queryobjects.md) | | This method iterates the JavaScript heap and finds all objects with the given prototype. | -| [reload(options)](./puppeteer.page.reload.md) | | | -| [screenshot(options)](./puppeteer.page.screenshot.md) | | Captures screenshot of the current page. | -| [screenshot(options)](./puppeteer.page.screenshot_1.md) | | | -| [screenshot(options)](./puppeteer.page.screenshot_2.md) | | | -| [select(selector, values)](./puppeteer.page.select.md) | | Triggers a change and input event once all the provided options have been selected. If there's no <select> element matching selector, the method throws an error. | -| [setBypassCSP(enabled)](./puppeteer.page.setbypasscsp.md) | | Toggles bypassing page's Content-Security-Policy. | -| [setBypassServiceWorker(bypass)](./puppeteer.page.setbypassserviceworker.md) | | Toggles ignoring of service worker for each request. | -| [setCacheEnabled(enabled)](./puppeteer.page.setcacheenabled.md) | | Toggles ignoring cache for each request based on the enabled state. By default, caching is enabled. | -| [setContent(html, options)](./puppeteer.page.setcontent.md) | | Set the content of the page. | -| [setCookie(cookies)](./puppeteer.page.setcookie.md) | | | -| [setDefaultNavigationTimeout(timeout)](./puppeteer.page.setdefaultnavigationtimeout.md) | |

This setting will change the default maximum navigation time for the following methods and related shortcuts:

- [page.goBack(options)](./puppeteer.page.goback.md)

- [page.goForward(options)](./puppeteer.page.goforward.md)

- [page.goto(url,options)](./puppeteer.page.goto.md)

- [page.reload(options)](./puppeteer.page.reload.md)

- [page.setContent(html,options)](./puppeteer.page.setcontent.md)

- [page.waitForNavigation(options)](./puppeteer.page.waitfornavigation.md)

| -| [setDefaultTimeout(timeout)](./puppeteer.page.setdefaulttimeout.md) | | | -| [setDragInterception(enabled)](./puppeteer.page.setdraginterception.md) | | | -| [setExtraHTTPHeaders(headers)](./puppeteer.page.setextrahttpheaders.md) | |

The extra HTTP headers will be sent with every request the page initiates.

:::tip

All HTTP header names are lowercased. (HTTP headers are case-insensitive, so this shouldn’t impact your server code.)

:::

:::note

page.setExtraHTTPHeaders does not guarantee the order of headers in the outgoing requests.

:::

| -| [setGeolocation(options)](./puppeteer.page.setgeolocation.md) | | Sets the page's geolocation. | -| [setJavaScriptEnabled(enabled)](./puppeteer.page.setjavascriptenabled.md) | | | -| [setOfflineMode(enabled)](./puppeteer.page.setofflinemode.md) | |

Sets the network connection to offline.

It does not change the parameters used in [Page.emulateNetworkConditions()](./puppeteer.page.emulatenetworkconditions.md)

| -| [setRequestInterception(value)](./puppeteer.page.setrequestinterception.md) | |

Activating request interception enables [HTTPRequest.abort()](./puppeteer.httprequest.abort.md), [HTTPRequest.continue()](./puppeteer.httprequest.continue.md) and [HTTPRequest.respond()](./puppeteer.httprequest.respond.md) 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.

See the [Request interception guide](https://pptr.dev/next/guides/request-interception) for more details.

| -| [setUserAgent(userAgent, userAgentMetadata)](./puppeteer.page.setuseragent.md) | | | -| [setViewport(viewport)](./puppeteer.page.setviewport.md) | |

page.setViewport will resize the page. A lot of websites don't expect phones to change size, so you should set the viewport before navigating to the page.

In the case of multiple pages in a single browser, each page can have its own viewport size.

| -| [tap(selector)](./puppeteer.page.tap.md) | | This method fetches an element with selector, scrolls it into view if needed, and then uses [Page.touchscreen](./puppeteer.page.md) to tap in the center of the element. If there's no element matching selector, the method throws an error. | -| [target()](./puppeteer.page.target.md) | | A target this page was created from. | -| [title()](./puppeteer.page.title.md) | | The page's title | -| [type(selector, text, options)](./puppeteer.page.type.md) | |

Sends a keydown, keypress/input, and keyup event for each character in the text.

To press a special key, like Control or ArrowDown, use [Keyboard.press()](./puppeteer.keyboard.press.md).

| -| [url()](./puppeteer.page.url.md) | | The page's URL. | -| [viewport()](./puppeteer.page.viewport.md) | | Current page viewport settings. | -| [waitForDevicePrompt(options)](./puppeteer.page.waitfordeviceprompt.md) | |

This method is typically coupled with an action that triggers a device request from an api such as WebBluetooth.

:::caution

This must be called before the device request is made. It will not return a currently active device prompt.

:::

| -| [waitForFileChooser(options)](./puppeteer.page.waitforfilechooser.md) | |

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.

:::

| -| [waitForFrame(urlOrPredicate, options)](./puppeteer.page.waitforframe.md) | | | -| [waitForFunction(pageFunction, options, args)](./puppeteer.page.waitforfunction.md) | | Waits for a function to finish evaluating in the page's context. | -| [waitForNavigation(options)](./puppeteer.page.waitfornavigation.md) | | Waits for the page to navigate to a new URL or to reload. It is useful when you run code that will indirectly cause the page to navigate. | -| [waitForNetworkIdle(options)](./puppeteer.page.waitfornetworkidle.md) | | | -| [waitForRequest(urlOrPredicate, options)](./puppeteer.page.waitforrequest.md) | | | -| [waitForResponse(urlOrPredicate, options)](./puppeteer.page.waitforresponse.md) | | | -| [waitForSelector(selector, options)](./puppeteer.page.waitforselector.md) | | Wait for the selector to appear in page. If at the moment of calling the method the selector already exists, the method will return immediately. If the selector doesn't appear after the timeout milliseconds of waiting, the function will throw. | -| [waitForTimeout(milliseconds)](./puppeteer.page.waitfortimeout.md) | | | -| [waitForXPath(xpath, options)](./puppeteer.page.waitforxpath.md) | | Wait for the xpath to appear in page. If at the moment of calling the method the xpath already exists, the method will return immediately. If the xpath doesn't appear after the timeout milliseconds of waiting, the function will throw. | -| [workers()](./puppeteer.page.workers.md) | | All of the dedicated [WebWorkers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) associated with the page. | +| Method | Modifiers | Description | +| ---------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [$(selector)](./puppeteer.page._.md) | | Runs document.querySelector within the page. If no element matches the selector, the return value resolves to null. | +| [$$(selector)](./puppeteer.page.__.md) | | The method runs document.querySelectorAll within the page. If no elements match the selector, the return value resolves to []. | +| [$$eval(selector, pageFunction, args)](./puppeteer.page.__eval.md) | | This method runs Array.from(document.querySelectorAll(selector)) within the page and passes the result as the first argument to the pageFunction. | +| [$eval(selector, pageFunction, args)](./puppeteer.page._eval.md) | | This method runs document.querySelector within the page and passes the result as the first argument to the pageFunction. | +| [$x(expression)](./puppeteer.page._x.md) | | 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. | +| [addScriptTag(options)](./puppeteer.page.addscripttag.md) | | Adds a <script> tag into the page with the desired URL or content. | +| [addStyleTag(options)](./puppeteer.page.addstyletag.md) | |

Adds a <link rel="stylesheet"> tag into the page with the desired URL or a <style type="text/css"> tag with the content.

Shortcut for [page.mainFrame().addStyleTag(options)](./puppeteer.frame.addstyletag_1.md).

| +| [addStyleTag(options)](./puppeteer.page.addstyletag_1.md) | | | +| [addStyleTag(options)](./puppeteer.page.addstyletag_2.md) | | | +| [authenticate(credentials)](./puppeteer.page.authenticate.md) | | Provide credentials for HTTP authentication. | +| [bringToFront()](./puppeteer.page.bringtofront.md) | | Brings page to front (activates tab). | +| [browser()](./puppeteer.page.browser.md) | | Get the browser the page belongs to. | +| [browserContext()](./puppeteer.page.browsercontext.md) | | Get the browser context that the page belongs to. | +| [click(selector, options)](./puppeteer.page.click.md) | | This method fetches an element with selector, scrolls it into view if needed, and then uses [Page.mouse](./puppeteer.page.md) to click in the center of the element. If there's no element matching selector, the method throws an error. | +| [close(options)](./puppeteer.page.close.md) | | | +| [content()](./puppeteer.page.content.md) | | The full HTML contents of the page, including the DOCTYPE. | +| [cookies(urls)](./puppeteer.page.cookies.md) | | 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. | +| [createPDFStream(options)](./puppeteer.page.createpdfstream.md) | | Generates a PDF of the page with the print CSS media type. | +| [deleteCookie(cookies)](./puppeteer.page.deletecookie.md) | | | +| [emulate(device)](./puppeteer.page.emulate.md) | |

Emulates a given device's metrics and user agent.

To aid emulation, Puppeteer provides a list of known devices that can be via [KnownDevices](./puppeteer.knowndevices.md).

| +| [emulateCPUThrottling(factor)](./puppeteer.page.emulatecputhrottling.md) | | Enables CPU throttling to emulate slow CPUs. | +| [emulateIdleState(overrides)](./puppeteer.page.emulateidlestate.md) | | Emulates the idle state. If no arguments set, clears idle state emulation. | +| [emulateMediaFeatures(features)](./puppeteer.page.emulatemediafeatures.md) | | | +| [emulateMediaType(type)](./puppeteer.page.emulatemediatype.md) | | | +| [emulateNetworkConditions(networkConditions)](./puppeteer.page.emulatenetworkconditions.md) | |

This does not affect WebSockets and WebRTC PeerConnections (see https://crbug.com/563644). To set the page offline, you can use [Page.setOfflineMode()](./puppeteer.page.setofflinemode.md).

A list of predefined network conditions can be used by importing [PredefinedNetworkConditions](./puppeteer.predefinednetworkconditions.md).

| +| [emulateTimezone(timezoneId)](./puppeteer.page.emulatetimezone.md) | | | +| [emulateVisionDeficiency(type)](./puppeteer.page.emulatevisiondeficiency.md) | | Simulates the given vision deficiency on the page. | +| [evaluate(pageFunction, args)](./puppeteer.page.evaluate.md) | |

Evaluates a function in the page's context and returns the result.

If the function passed to page.evaluateHandle returns a Promise, the function will wait for the promise to resolve and return its value.

| +| [evaluateHandle(pageFunction, args)](./puppeteer.page.evaluatehandle.md) | | | +| [evaluateOnNewDocument(pageFunction, args)](./puppeteer.page.evaluateonnewdocument.md) | |

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. In this case, the function is invoked in the context of the newly attached frame.

The function is invoked after the document was created but before any of its scripts were run. This is useful to amend the JavaScript environment, e.g. to seed Math.random.

| +| [exposeFunction(name, pptrFunction)](./puppeteer.page.exposefunction.md) | |

The method adds a function called name on the page's window object. When called, the function executes puppeteerFunction in node.js and returns a Promise which resolves to the return value of puppeteerFunction.

If the puppeteerFunction returns a Promise, it will be awaited.

:::note

Functions installed via page.exposeFunction survive navigations.

:::note

| +| [focus(selector)](./puppeteer.page.focus.md) | | This method fetches an element with selector and focuses it. If there's no element matching selector, the method throws an error. | +| [frames()](./puppeteer.page.frames.md) | | An array of all frames attached to the page. | +| [getDefaultTimeout()](./puppeteer.page.getdefaulttimeout.md) | | Maximum time in milliseconds. | +| [goBack(options)](./puppeteer.page.goback.md) | | This method navigate to the previous page in history. | +| [goForward(options)](./puppeteer.page.goforward.md) | | This method navigate to the next page in history. | +| [goto(url, options)](./puppeteer.page.goto.md) | | | +| [hover(selector)](./puppeteer.page.hover.md) | | This method fetches an element with selector, scrolls it into view if needed, and then uses [Page.mouse](./puppeteer.page.md) to hover over the center of the element. If there's no element matching selector, the method throws an error. | +| [isClosed()](./puppeteer.page.isclosed.md) | | Indicates that the page has been closed. | +| [isDragInterceptionEnabled()](./puppeteer.page.isdraginterceptionenabled.md) | | true if drag events are being intercepted, false otherwise. | +| [isJavaScriptEnabled()](./puppeteer.page.isjavascriptenabled.md) | | true if the page has JavaScript enabled, false otherwise. | +| [isServiceWorkerBypassed()](./puppeteer.page.isserviceworkerbypassed.md) | | true if the service worker are being bypassed, false otherwise. | +| [mainFrame()](./puppeteer.page.mainframe.md) | | The page's main frame. | +| [metrics()](./puppeteer.page.metrics.md) | | Object containing metrics as key/value pairs. | +| [off(eventName, handler)](./puppeteer.page.off.md) | | | +| [on(eventName, handler)](./puppeteer.page.on.md) | |

Listen to page events.

:::note

This method exists to define event typings and handle proper wireup of cooperative request interception. Actual event listening and dispatching is delegated to [EventEmitter](./puppeteer.eventemitter.md).

:::

| +| [once(eventName, handler)](./puppeteer.page.once.md) | | | +| [pdf(options)](./puppeteer.page.pdf.md) | | Generates a PDF of the page with the print CSS media type. | +| [queryObjects(prototypeHandle)](./puppeteer.page.queryobjects.md) | | This method iterates the JavaScript heap and finds all objects with the given prototype. | +| [reload(options)](./puppeteer.page.reload.md) | | | +| [removeScriptToEvaluateOnNewDocument(identifier)](./puppeteer.page.removescripttoevaluateonnewdocument.md) | | Removes script that injected into page by Page.evaluateOnNewDocument. | +| [screenshot(options)](./puppeteer.page.screenshot.md) | | Captures screenshot of the current page. | +| [screenshot(options)](./puppeteer.page.screenshot_1.md) | | | +| [screenshot(options)](./puppeteer.page.screenshot_2.md) | | | +| [select(selector, values)](./puppeteer.page.select.md) | | Triggers a change and input event once all the provided options have been selected. If there's no <select> element matching selector, the method throws an error. | +| [setBypassCSP(enabled)](./puppeteer.page.setbypasscsp.md) | | Toggles bypassing page's Content-Security-Policy. | +| [setBypassServiceWorker(bypass)](./puppeteer.page.setbypassserviceworker.md) | | Toggles ignoring of service worker for each request. | +| [setCacheEnabled(enabled)](./puppeteer.page.setcacheenabled.md) | | Toggles ignoring cache for each request based on the enabled state. By default, caching is enabled. | +| [setContent(html, options)](./puppeteer.page.setcontent.md) | | Set the content of the page. | +| [setCookie(cookies)](./puppeteer.page.setcookie.md) | | | +| [setDefaultNavigationTimeout(timeout)](./puppeteer.page.setdefaultnavigationtimeout.md) | |

This setting will change the default maximum navigation time for the following methods and related shortcuts:

- [page.goBack(options)](./puppeteer.page.goback.md)

- [page.goForward(options)](./puppeteer.page.goforward.md)

- [page.goto(url,options)](./puppeteer.page.goto.md)

- [page.reload(options)](./puppeteer.page.reload.md)

- [page.setContent(html,options)](./puppeteer.page.setcontent.md)

- [page.waitForNavigation(options)](./puppeteer.page.waitfornavigation.md)

| +| [setDefaultTimeout(timeout)](./puppeteer.page.setdefaulttimeout.md) | | | +| [setDragInterception(enabled)](./puppeteer.page.setdraginterception.md) | | | +| [setExtraHTTPHeaders(headers)](./puppeteer.page.setextrahttpheaders.md) | |

The extra HTTP headers will be sent with every request the page initiates.

:::tip

All HTTP header names are lowercased. (HTTP headers are case-insensitive, so this shouldn’t impact your server code.)

:::

:::note

page.setExtraHTTPHeaders does not guarantee the order of headers in the outgoing requests.

:::

| +| [setGeolocation(options)](./puppeteer.page.setgeolocation.md) | | Sets the page's geolocation. | +| [setJavaScriptEnabled(enabled)](./puppeteer.page.setjavascriptenabled.md) | | | +| [setOfflineMode(enabled)](./puppeteer.page.setofflinemode.md) | |

Sets the network connection to offline.

It does not change the parameters used in [Page.emulateNetworkConditions()](./puppeteer.page.emulatenetworkconditions.md)

| +| [setRequestInterception(value)](./puppeteer.page.setrequestinterception.md) | |

Activating request interception enables [HTTPRequest.abort()](./puppeteer.httprequest.abort.md), [HTTPRequest.continue()](./puppeteer.httprequest.continue.md) and [HTTPRequest.respond()](./puppeteer.httprequest.respond.md) 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.

See the [Request interception guide](https://pptr.dev/next/guides/request-interception) for more details.

| +| [setUserAgent(userAgent, userAgentMetadata)](./puppeteer.page.setuseragent.md) | | | +| [setViewport(viewport)](./puppeteer.page.setviewport.md) | |

page.setViewport will resize the page. A lot of websites don't expect phones to change size, so you should set the viewport before navigating to the page.

In the case of multiple pages in a single browser, each page can have its own viewport size.

| +| [tap(selector)](./puppeteer.page.tap.md) | | This method fetches an element with selector, scrolls it into view if needed, and then uses [Page.touchscreen](./puppeteer.page.md) to tap in the center of the element. If there's no element matching selector, the method throws an error. | +| [target()](./puppeteer.page.target.md) | | A target this page was created from. | +| [title()](./puppeteer.page.title.md) | | The page's title | +| [type(selector, text, options)](./puppeteer.page.type.md) | |

Sends a keydown, keypress/input, and keyup event for each character in the text.

To press a special key, like Control or ArrowDown, use [Keyboard.press()](./puppeteer.keyboard.press.md).

| +| [url()](./puppeteer.page.url.md) | | The page's URL. | +| [viewport()](./puppeteer.page.viewport.md) | | Current page viewport settings. | +| [waitForDevicePrompt(options)](./puppeteer.page.waitfordeviceprompt.md) | |

This method is typically coupled with an action that triggers a device request from an api such as WebBluetooth.

:::caution

This must be called before the device request is made. It will not return a currently active device prompt.

:::

| +| [waitForFileChooser(options)](./puppeteer.page.waitforfilechooser.md) | |

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.

:::

| +| [waitForFrame(urlOrPredicate, options)](./puppeteer.page.waitforframe.md) | | | +| [waitForFunction(pageFunction, options, args)](./puppeteer.page.waitforfunction.md) | | Waits for a function to finish evaluating in the page's context. | +| [waitForNavigation(options)](./puppeteer.page.waitfornavigation.md) | | Waits for the page to navigate to a new URL or to reload. It is useful when you run code that will indirectly cause the page to navigate. | +| [waitForNetworkIdle(options)](./puppeteer.page.waitfornetworkidle.md) | | | +| [waitForRequest(urlOrPredicate, options)](./puppeteer.page.waitforrequest.md) | | | +| [waitForResponse(urlOrPredicate, options)](./puppeteer.page.waitforresponse.md) | | | +| [waitForSelector(selector, options)](./puppeteer.page.waitforselector.md) | | Wait for the selector to appear in page. If at the moment of calling the method the selector already exists, the method will return immediately. If the selector doesn't appear after the timeout milliseconds of waiting, the function will throw. | +| [waitForTimeout(milliseconds)](./puppeteer.page.waitfortimeout.md) | | | +| [waitForXPath(xpath, options)](./puppeteer.page.waitforxpath.md) | | Wait for the xpath to appear in page. If at the moment of calling the method the xpath already exists, the method will return immediately. If the xpath doesn't appear after the timeout milliseconds of waiting, the function will throw. | +| [workers()](./puppeteer.page.workers.md) | | All of the dedicated [WebWorkers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) associated with the page. | diff --git a/docs/api/puppeteer.page.removescripttoevaluateonnewdocument.md b/docs/api/puppeteer.page.removescripttoevaluateonnewdocument.md new file mode 100644 index 00000000000..ca3d45d3490 --- /dev/null +++ b/docs/api/puppeteer.page.removescripttoevaluateonnewdocument.md @@ -0,0 +1,25 @@ +--- +sidebar_label: Page.removeScriptToEvaluateOnNewDocument +--- + +# Page.removeScriptToEvaluateOnNewDocument() method + +Removes script that injected into page by Page.evaluateOnNewDocument. + +#### Signature: + +```typescript +class Page { + removeScriptToEvaluateOnNewDocument(identifier: string): Promise; +} +``` + +## Parameters + +| Parameter | Type | Description | +| ---------- | ------ | ----------------- | +| identifier | string | script identifier | + +**Returns:** + +Promise<void> diff --git a/packages/puppeteer-core/src/api/Page.ts b/packages/puppeteer-core/src/api/Page.ts index dd4c6a054dd..97946ca41c8 100644 --- a/packages/puppeteer-core/src/api/Page.ts +++ b/packages/puppeteer-core/src/api/Page.ts @@ -386,6 +386,13 @@ export interface PageEventObject { workerdestroyed: WebWorker; } +/** + * @public + */ +export interface NewDocumentScriptEvaluation { + identifier: string; +} + /** * Page provides methods to interact with a single tab or * {@link https://developer.chrome.com/extensions/background_pages | extension background page} @@ -2109,8 +2116,21 @@ export class Page extends EventEmitter { async evaluateOnNewDocument< Params extends unknown[], Func extends (...args: Params) => unknown = (...args: Params) => unknown - >(pageFunction: Func | string, ...args: Params): Promise; - async evaluateOnNewDocument(): Promise { + >( + pageFunction: Func | string, + ...args: Params + ): Promise; + async evaluateOnNewDocument(): Promise { + throw new Error('Not implemented'); + } + + /** + * Removes script that injected into page by Page.evaluateOnNewDocument. + * + * @param identifier - script identifier + */ + async removeScriptToEvaluateOnNewDocument(identifier: string): Promise; + async removeScriptToEvaluateOnNewDocument(): Promise { throw new Error('Not implemented'); } diff --git a/packages/puppeteer-core/src/common/Page.ts b/packages/puppeteer-core/src/common/Page.ts index aaa4767c44b..ef6f1fe9719 100644 --- a/packages/puppeteer-core/src/common/Page.ts +++ b/packages/puppeteer-core/src/common/Page.ts @@ -40,6 +40,7 @@ import { ScreenshotOptions, WaitForOptions, WaitTimeoutOptions, + NewDocumentScriptEvaluation, } from '../api/Page.js'; import {assert} from '../util/assert.js'; import { @@ -1288,10 +1289,26 @@ export class CDPPage extends Page { override async evaluateOnNewDocument< Params extends unknown[], Func extends (...args: Params) => unknown = (...args: Params) => unknown - >(pageFunction: Func | string, ...args: Params): Promise { + >( + pageFunction: Func | string, + ...args: Params + ): Promise { const source = evaluationString(pageFunction, ...args); - await this.#client.send('Page.addScriptToEvaluateOnNewDocument', { - source, + const {identifier} = await this.#client.send( + 'Page.addScriptToEvaluateOnNewDocument', + { + source, + } + ); + + return {identifier}; + } + + override async removeScriptToEvaluateOnNewDocument( + identifier: string + ): Promise { + await this.#client.send('Page.removeScriptToEvaluateOnNewDocument', { + identifier, }); } diff --git a/test/TestExpectations.json b/test/TestExpectations.json index 85445556b06..c627d0bb21c 100644 --- a/test/TestExpectations.json +++ b/test/TestExpectations.json @@ -17,6 +17,18 @@ "parameters": ["webDriverBiDi"], "expectations": ["PASS"] }, + { + "testIdPattern": "[evaluation.spec] Evaluation specs Page.evaluateOnNewDocument *", + "platforms": ["darwin", "linux", "win32"], + "parameters": ["webDriverBiDi"], + "expectations": ["SKIP"] + }, + { + "testIdPattern": "[evaluation.spec] Evaluation specs Page.removeScriptToEvaluateOnNewDocument *", + "platforms": ["darwin", "linux", "win32"], + "parameters": ["webDriverBiDi"], + "expectations": ["SKIP"] + }, { "testIdPattern": "[EventEmitter.spec] EventEmitter *", "platforms": ["darwin", "linux", "win32"], @@ -294,15 +306,15 @@ "expectations": ["SKIP"] }, { - "testIdPattern": "[evaluation.spec] Evaluation specs Page.evaluateOnNewDocument should evaluate before anything else on the page", + "testIdPattern": "[evaluation.spec] Evaluation specs Page.evaluateOnNewDocument *", "platforms": ["darwin", "linux", "win32"], - "parameters": ["webDriverBiDi"], + "parameters": ["cdp", "firefox"], "expectations": ["SKIP"] }, { - "testIdPattern": "[evaluation.spec] Evaluation specs Page.evaluateOnNewDocument should work with CSP", + "testIdPattern": "[evaluation.spec] Evaluation specs Page.removeScriptToEvaluateOnNewDocument *", "platforms": ["darwin", "linux", "win32"], - "parameters": ["webDriverBiDi"], + "parameters": ["cdp", "firefox"], "expectations": ["SKIP"] }, { @@ -905,18 +917,6 @@ "parameters": ["cdp", "firefox"], "expectations": ["SKIP"] }, - { - "testIdPattern": "[evaluation.spec] Evaluation specs Page.evaluateOnNewDocument should evaluate before anything else on the page", - "platforms": ["darwin", "linux", "win32"], - "parameters": ["cdp", "firefox"], - "expectations": ["SKIP"] - }, - { - "testIdPattern": "[evaluation.spec] Evaluation specs Page.evaluateOnNewDocument should work with CSP", - "platforms": ["darwin", "linux", "win32"], - "parameters": ["cdp", "firefox"], - "expectations": ["FAIL"] - }, { "testIdPattern": "[fixtures.spec] Fixtures dumpio option should work with pipe option", "platforms": ["darwin", "linux", "win32"], diff --git a/test/src/evaluation.spec.ts b/test/src/evaluation.spec.ts index fe7fa940cb7..7c683db569f 100644 --- a/test/src/evaluation.spec.ts +++ b/test/src/evaluation.spec.ts @@ -537,6 +537,30 @@ describe('Evaluation specs', function () { }); }); + describe('Page.removeScriptToEvaluateOnNewDocument', function () { + it('should remove new document script', async () => { + const {page, server} = getTestState(); + + const {identifier} = await page.evaluateOnNewDocument(function () { + (globalThis as any).injected = 123; + }); + await page.goto(server.PREFIX + '/tamperable.html'); + expect( + await page.evaluate(() => { + return (globalThis as any).result; + }) + ).toBe(123); + + await page.removeScriptToEvaluateOnNewDocument(identifier); + await page.reload(); + expect( + await page.evaluate(() => { + return (globalThis as any).result || null; + }) + ).toBe(null); + }); + }); + describe('Frame.evaluate', function () { it('should have different execution contexts', async () => { const {page, server} = getTestState();