diff --git a/.eslintrc.js b/.eslintrc.js index a119974e1fed2..2c53f10bc4cf6 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -142,7 +142,7 @@ module.exports = { '@typescript-eslint/ban-ts-ignore': 0, /** * This is the default options (as per - * https://github.com/typescript-eslint/typescript-eslint/blob/master/packages/eslint-plugin/docs/rules/ban-types.md), + * https://github.com/typescript-eslint/typescript-eslint/blob/HEAD/packages/eslint-plugin/docs/rules/ban-types.md), * * Unfortunately there's no way to */ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a40178380d293..344b75fb24b3b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -292,12 +292,16 @@ The following steps are needed to update the Chromium version. ### Bisecting upstream changes -Sometimes, performing a Chromium roll causes tests to fail. To figure out the cause, you need to bisect Chromium revisions to figure out the earliest possible revision that changed the behavior. The script in `utils/bisect.js` can be helpful here. Given a Node.js script that calls `process.exit(1)` for bad revisions, run this from the Puppeteer repository’s root directory: +Sometimes, performing a Chromium roll causes tests to fail. To figure out the cause, you need to bisect Chromium revisions to figure out the earliest possible revision that changed the behavior. The script in `utils/bisect.js` can be helpful here. Given a pattern for one or more unit tests, it will automatically bisect the current range: ```sh node utils/bisect.js --good 686378 --bad 706915 script.js + +node utils/bisect.js --unit-test Response.fromCache ``` +By default, it will use the Chromium revision in `src/revisions.ts` from the `main` branch and from the working tree to determine the range to bisect. + ## Releasing to npm Releasing to npm consists of the following phases: diff --git a/README.md b/README.md index aab80dd1dee3b..38613e2fe951e 100644 --- a/README.md +++ b/README.md @@ -181,7 +181,7 @@ const browser = await puppeteer.launch({ executablePath: '/path/to/Chrome' }); You can also use Puppeteer with Firefox Nightly (experimental support). See [`Puppeteer.launch()`](https://github.com/puppeteer/puppeteer/blob/v10.2.0/docs/api.md#puppeteerlaunchoptions) for more information. -See [`this article`](https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/) for a description of the differences between Chromium and Chrome. [`This article`](https://chromium.googlesource.com/chromium/src/+/master/docs/chromium_browser_vs_google_chrome.md) describes some differences for Linux users. +See [`this article`](https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/) for a description of the differences between Chromium and Chrome. [`This article`](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/docs/chromium_browser_vs_google_chrome.md) describes some differences for Linux users. **3. Creates a fresh user profile** diff --git a/docs/api.md b/docs/api.md index ab1c2c6ec0d1e..e08a689e64210 100644 --- a/docs/api.md +++ b/docs/api.md @@ -75,7 +75,7 @@ * [event: 'targetdestroyed'](#event-targetdestroyed) * [browser.browserContexts()](#browserbrowsercontexts) * [browser.close()](#browserclose) - * [browser.createIncognitoBrowserContext()](#browsercreateincognitobrowsercontext) + * [browser.createIncognitoBrowserContext([options])](#browsercreateincognitobrowsercontextoptions) * [browser.defaultBrowserContext()](#browserdefaultbrowsercontext) * [browser.disconnect()](#browserdisconnect) * [browser.isConnected()](#browserisconnected) @@ -133,6 +133,7 @@ * [page.browser()](#pagebrowser) * [page.browserContext()](#pagebrowsercontext) * [page.click(selector[, options])](#pageclickselector-options) + * [page.client()](#pageclient) * [page.close([options])](#pagecloseoptions) * [page.content()](#pagecontent) * [page.cookies([...urls])](#pagecookiesurls) @@ -197,6 +198,7 @@ * [page.waitForFileChooser([options])](#pagewaitforfilechooseroptions) * [page.waitForFunction(pageFunction[, options[, ...args]])](#pagewaitforfunctionpagefunction-options-args) * [page.waitForNavigation([options])](#pagewaitfornavigationoptions) + * [page.waitForNetworkIdle([options])](#pagewaitfornetworkidleoptions) * [page.waitForRequest(urlOrPredicate[, options])](#pagewaitforrequesturlorpredicate-options) * [page.waitForResponse(urlOrPredicate[, options])](#pagewaitforresponseurlorpredicate-options) * [page.waitForSelector(selector[, options])](#pagewaitforselectorselector-options) @@ -306,7 +308,7 @@ * [elementHandle.boundingBox()](#elementhandleboundingbox) * [elementHandle.boxModel()](#elementhandleboxmodel) * [elementHandle.click([options])](#elementhandleclickoptions) - * [elementHandle.clickablePoint()](#elementhandleclickablepoint) + * [elementHandle.clickablePoint([offset])](#elementhandleclickablepointoffset) * [elementHandle.contentFrame()](#elementhandlecontentframe) * [elementHandle.dispose()](#elementhandledispose) * [elementHandle.drag(target)](#elementhandledragtarget) @@ -321,7 +323,7 @@ * [elementHandle.getProperties()](#elementhandlegetproperties) * [elementHandle.getProperty(propertyName)](#elementhandlegetpropertypropertyname) * [elementHandle.hover()](#elementhandlehover) - * [elementHandle.isIntersectingViewport()](#elementhandleisintersectingviewport) + * [elementHandle.isIntersectingViewport([options])](#elementhandleisintersectingviewportoptions) * [elementHandle.jsonValue()](#elementhandlejsonvalue) * [elementHandle.press(key[, options])](#elementhandlepresskey-options) * [elementHandle.screenshot([options])](#elementhandlescreenshotoptions) @@ -462,7 +464,7 @@ You will then need to call [`puppeteer.connect([options])`](#puppeteerconnectopt Puppeteer looks for certain [environment variables](https://en.wikipedia.org/wiki/Environment_variable) to aid its operations. If Puppeteer doesn't find them in the environment during the installation step, a lowercased variant of these variables will be used from the [npm config](https://docs.npmjs.com/cli/config). -- `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` - defines HTTP proxy settings that are used to download and run Chromium. +- `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` - defines HTTP proxy settings that are used to download and run the browser. - `PUPPETEER_SKIP_CHROMIUM_DOWNLOAD` - do not download bundled Chromium during installation step. - `PUPPETEER_DOWNLOAD_HOST` - overwrite URL prefix that is used to download Chromium. Note: this includes protocol and might even include path prefix. Defaults to `https://storage.googleapis.com`. - `PUPPETEER_DOWNLOAD_PATH` - overwrite the path for the downloads folder. Defaults to `/.local-chromium`, where `` is Puppeteer's package root. @@ -564,7 +566,7 @@ This methods attaches Puppeteer to an existing browser instance. - `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields: - `headless` <[boolean]> Whether to run browser in [headless mode](https://developers.google.com/web/updates/2017/04/headless-chrome). Defaults to `true` unless the `devtools` option is `true`. - `args` <[Array]<[string]>> Additional arguments to pass to the browser instance. The list of Chromium flags can be found [here](http://peter.sh/experiments/chromium-command-line-switches/). - - `userDataDir` <[string]> Path to a [User Data Directory](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md). + - `userDataDir` <[string]> Path to a [User Data Directory](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/docs/user_data_dir.md). - `devtools` <[boolean]> Whether to auto-open a DevTools panel for each tab. If this option is `true`, the `headless` option will be set `false`. - returns: <[Array]<[string]>> @@ -645,7 +647,7 @@ try { - `handleSIGHUP` <[boolean]> Close the browser process on SIGHUP. Defaults to `true`. - `timeout` <[number]> Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. - `dumpio` <[boolean]> Whether to pipe the browser process stdout and stderr into `process.stdout` and `process.stderr`. Defaults to `false`. - - `userDataDir` <[string]> Path to a [User Data Directory](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md). + - `userDataDir` <[string]> Path to a [User Data Directory](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/docs/user_data_dir.md). - `env` <[Object]> Specify environment variables that will be visible to the browser. Defaults to `process.env`. - `devtools` <[boolean]> Whether to auto-open a DevTools panel for each tab. If this option is `true`, the `headless` option will be set `false`. - `pipe` <[boolean]> Connects to the browser over a pipe instead of a WebSocket. Defaults to `false`. @@ -885,8 +887,10 @@ Closes Chromium and all of its pages (if any were opened). The [Browser] object During the process of closing the browser, Puppeteer attempts to delete the temp folder created exclusively for this browser instance. If this fails (either because a file in the temp folder is locked by another process or because of insufficient permissions) an error is logged. This implies that: a) the folder and/or its content is not fully deleted; and b) the connection with the browser is not properly disposed (see [browser.disconnect()](#browserdisconnect)). -#### browser.createIncognitoBrowserContext() - +#### browser.createIncognitoBrowserContext([options]) +- `options` <[Object]> Set of configurable options to set on the browserContext. Can have the following fields: + - `proxyServer` <[string]> Optional proxy server with optional port to use for all requests. Username and password can be set in [page.authenticate(credentials)](#pageauthenticatecredentials). + - `proxyBypassList` <[string]> Optional: Bypass the proxy for the given semi-colon-separated list of hosts. - returns: <[Promise]<[BrowserContext]>> Creates a new incognito browser context. This won't share cookies/cache with other browser contexts. @@ -1093,6 +1097,7 @@ Creates a new page in the browser context. - `'clipboard-read'` - `'clipboard-write'` - `'payment-handler'` + - `'persistent-storage'` - returns: <[Promise]> ```js @@ -1389,7 +1394,8 @@ Shortcut for [page.mainFrame().$x(expression)](#framexexpression) - `url` <[string]> URL of a script to be added. - `path` <[string]> Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). - `content` <[string]> Raw JavaScript content to be injected into frame. - - `type` <[string]> Script type. Use 'module' in order to load a JavaScript ES6 module. See [script](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) for more details. + - `type` <[string]> Script type. Use 'module' in order to load a Javascript ES6 module. See [script](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) for more details. + - `id` <[string]> id attribute to add to the script tag. - returns: <[Promise]<[ElementHandle]>> which resolves to the added tag when the script's onload fires or when the script content was injected into frame. Adds a `