BrowserContext instance defines a browsing session and can own multiple pages.

Page has at least one frame: main frame. There might be other frames created by iframe or frame tags.

Frame has at least one execution context - the default execution context - where the frame's JavaScript is executed. A Frame might have additional execution contexts that are associated with extensions.

Worker has a single execution context and facilitates interacting with WebWorkers.

Environment Variables

Puppeteer looks for certain environment variables to aid its operations.
If puppeteer doesn't find them in the environment, a lowercased variant of these variables will be used from the npm config.

HTTP_PROXY, HTTPS_PROXY, NO_PROXY - defines HTTP proxy settings that are used to download and run Chromium.

PUPPETEER_SKIP_CHROMIUM_DOWNLOAD - do not download bundled Chromium during installation step.

PUPPETEER_DOWNLOAD_HOST - overwrite host part of URL that is used to download Chromium

PUPPETEER_CHROMIUM_REVISION - specify a certain version of chrome you'd like puppeteer to use during the installation step.

NOTE PUPPETEER_* env variables are not accounted for in the puppeteer-core package.

Error handling

Puppeteer methods might throw errors if they are unable to fufill a request. For example, page.waitForSelector(selector[, options])
might fail if the selector doesn't match any nodes during the given timeframe.

For certain types of errors Puppeteer uses specific error classes.
These classes are available via require('puppeteer/Errors').

isLandscape <boolean> Specifies if viewport is in landscape mode. Defaults to false.

args <Array<string>> Additional arguments to pass to the browser instance. The list of Chromium flags can be found here.

ignoreDefaultArgs <(boolean|<Array<string>>)> If true, then do not use puppeteer.defaultArgs(). If an array is given, then filter out the given default arguments. Dangerous option; use with care. Defaults to false.

handleSIGINT <boolean> Close the browser process on Ctrl-C. Defaults to true.

handleSIGTERM <boolean> Close the browser process on SIGTERM. Defaults to true.

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.

NOTE Puppeteer can also be used to control the Chrome browser, but it works best with the version of Chromium it is bundled with. There is no guarantee it will work with any other version. Use executablePath option with extreme caution.

constpuppeteer=require('puppeteer');
puppeteer.launch().then(asyncbrowser=> {
// Store the endpoint to be able to reconnect to ChromiumconstbrowserWSEndpoint=browser.wsEndpoint();
// Disconnect puppeteer from Chromiumbrowser.disconnect();
// Use the endpoint to reestablish a connectionconstbrowser2=awaitpuppeteer.connect({browserWSEndpoint});
// Close Chromiumawaitbrowser2.close();
});

event: 'disconnected'

Emitted when Puppeteer gets disconnected from the Chromium instance. This might happen because of one of the following:

browser.createIncognitoBrowserContext()

Creates a new incognito browser context. This won't share cookies/cache with other browser contexts.

constbrowser=awaitpuppeteer.launch();
// Create a new incognito browser context.constcontext=awaitbrowser.createIncognitoBrowserContext();
// Create a new page in a pristine context.constpage=awaitcontext.newPage();
// Do stuffawaitpage.goto('https://example.com');

browser.disconnect()

Disconnects Puppeteer from the browser, but leaves the Chromium process running. After calling disconnect, the Browser object is considered disposed and cannot be used anymore.

class: BrowserContext

BrowserContexts provide a way to operate multiple independent browser sessions. When a browser is launched, it has
a single BrowserContext used by default. The method browser.newPage() creates a page in the default browser context.

If a page opens another page, e.g. with a window.open call, the popup will belong to the parent page's browser
context.

delay <number> Time to wait between mousedown and mouseup in milliseconds. Defaults to 0.

returns: <Promise> Promise which resolves when the element matching selector is successfully clicked. The Promise will be rejected if there is no element matching selector.

This method fetches an element with selector, scrolls it into view if needed, and then uses page.mouse to click in the center of the element.
If there's no element matching selector, the method throws an error.

Bear in mind that if click() triggers a navigation event and there's a separate page.waitForNavigation() promise to be resolved, you may end up with a race condition that yields unexpected results. The correct pattern for click and wait for navigation is the following:

To aid emulation, puppeteer provides a list of device descriptors which can be obtained via the require('puppeteer/DeviceDescriptors') command.
Below is an example of emulating an iPhone 6 in puppeteer:

page.exposeFunction(name, puppeteerFunction)

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.

waitUntil <string|Array<string>> When to consider navigation succeeded, defaults to load. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:

load - consider navigation to be finished when the load event is fired.

domcontentloaded - consider navigation to be finished when the DOMContentLoaded event is fired.

networkidle0 - consider navigation to be finished when there are no more than 0 network connections for at least 500 ms.

networkidle2 - consider navigation to be finished when there are no more than 2 network connections for at least 500 ms.

returns: <Promise<?Response>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. If
can not go back, resolves to null.

Navigate to the previous page in history.

page.goForward(options)

options <Object> Navigation parameters which might have the following properties:

waitUntil <string|Array<string>> When to consider navigation succeeded, defaults to load. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:

load - consider navigation to be finished when the load event is fired.

domcontentloaded - consider navigation to be finished when the DOMContentLoaded event is fired.

networkidle0 - consider navigation to be finished when there are no more than 0 network connections for at least 500 ms.

networkidle2 - consider navigation to be finished when there are no more than 2 network connections for at least 500 ms.

returns: <Promise<?Response>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. If
can not go forward, resolves to null.

waitUntil <string|Array<string>> When to consider navigation succeeded, defaults to load. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:

load - consider navigation to be finished when the load event is fired.

domcontentloaded - consider navigation to be finished when the DOMContentLoaded event is fired.

networkidle0 - consider navigation to be finished when there are no more than 0 network connections for at least 500 ms.

networkidle2 - consider navigation to be finished when there are no more than 2 network connections for at least 500 ms.

returns: <Promise<?Response>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.

The page.goto will throw an error if:

there's an SSL error (e.g. in case of self-signed certificates).

target URL is invalid.

the timeout is exceeded during navigation.

the main resource failed to load.

NOTEpage.goto either throw or return a main resource response. The only exceptions are navigation to about:blank or navigation to the same URL with a different hash, which would succeed and return null.

NOTE Headless mode doesn't match any nodest navigating to a PDF document. See the upstream issue.

page.hover(selector)

selector <string> A selector to search for element to hover. If there are multiple elements satisfying the selector, tvailable via.

This method fetches an element with selector, scrolls it into view if needed, and then uses page.mouse to hover over the center of the element.
If a there's no element matching selector, the method throws an error.

preferCSSPageSize <boolean> Give any CSS @page size declared in the page priority over what is declared in width and height or format options. Defaults to false, which will scale the content to fit the paper size.

waitUntil <string|Array<string>> When to consider navigation succeeded, defaults to load. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:

load - consider navigation to be finished when the load event is fired.

domcontentloaded - consider navigation to be finished when the DOMContentLoaded event is fired.

networkidle0 - consider navigation to be finished when there are no more than 0 network connections for at least 500 ms.

networkidle2 - consider navigation to be finished when there are no more than 2 network connections for at least 500 ms.

returns: <Promise<Response>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.

page.screenshot([options])

options <Object> Options object which might have the following properties:

path <string> The file path to save the image to. The screenshot type will be inferred from file extension. If path is a relative path, then it is resolved relative to current working directory. If no path is provided, the image won't be saved to the disk.

type <string> Specify screenshot type, can be either jpeg or png. Defaults to 'png'.

quality <number> The quality of the image, between 0-100. Not applicable to png images.

fullPage <boolean> When true, takes a screenshot of the full scrollable page. Defaults to false.

clip <Object> An object which specifies clipping region of the page. Should have the following fields:

page.tap(selector)

This method fetches an element with selector, scrolls it into view if needed, and then uses page.touchscreen to tap in the center of the element.
If there's no element matching selector, the method throws an error.

page.waitForFunction(pageFunction[, options[, ...args]])

polling <string|number> An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values:

raf - to constantly execute pageFunction in requestAnimationFrame callback. This is the tightest polling mode which is suitable to observe styling changes.

mutation - to execute pageFunction on every DOM mutation.

timeout <number> maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.

waitUntil <string|Array<string>> When to consider navigation succeeded, defaults to load. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:

load - consider navigation to be finished when the load event is fired.

domcontentloaded - consider navigation to be finished when the DOMContentLoaded event is fired.

networkidle0 - consider navigation to be finished when there are no more than 0 network connections for at least 500 ms.

networkidle2 - consider navigation to be finished when there are no more than 2 network connections for at least 500 ms.

returns: <Promise<[?Response]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to History API usage, the navigation will resolve with null.

This resolves when the page navigates to a new URL or reloads. It is useful for when you run code
which will indirectly cause the page to navigate. Consider this example:

constnavigationPromise=page.waitForNavigation();
awaitpage.click('a.my-link'); // Clicking the link will indirectly cause a navigationawait navigationPromise; // The navigationPromise resolves after navigation has finished

NOTE Usage of the History API to change the URL is considered a navigation.

page.waitForSelector(selector[, options])

visible <boolean> wait for element to be present in DOM and to be visible, i.e. to not have display: none or visibility: hidden CSS properties. Defaults to false.

hidden <boolean> wait for element to not be found in the DOM or to be hidden, i.e. have display: none or visibility: hidden CSS properties. Defaults to false.

timeout <number> maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.

returns: <Promise<ElementHandle>> Promise which resolves when element specified by selector string is added to DOM.

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.

page.waitForXPath(xpath[, options])

visible <boolean> wait for element to be present in DOM and to be visible, i.e. to not have display: none or visibility: hidden CSS properties. Defaults to false.

hidden <boolean> wait for element to not be found in the DOM or to be hidden, i.e. have display: none or visibility: hidden CSS properties. Defaults to false.

timeout <number> maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.

returns: <Promise<ElementHandle>> Promise which resolves when element specified by xpath string is added to DOM.

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.

If key is a single character and no modifier keys besides Shift are being held down, a keypress/input event will also generated. The text option can be specified to force an input event to be generated.

If key is a modifier key, Shift, Meta, Control, or Alt, subsequent key presses will be sent with that modifier active. To release the modifier key, use keyboard.up.

If key is a single character and no modifier keys besides Shift are being held down, a keypress/input event will also generated. The text option can be specified to force an input event to be generated.

NOTE Modifier keys DO effect keyboard.press. Holding down Shift will type the text in upper case.

delay <number> Time to wait between mousedown and mouseup in milliseconds. Defaults to 0.

returns: <Promise> Promise which resolves when the element matching selector is successfully clicked. The Promise will be rejected if there is no element matching selector.

This method fetches an element with selector, scrolls it into view if needed, and then uses page.mouse to click in the center of the element.
If there's no element matching selector, the method throws an error.

Bear in mind that if click() triggers a navigation event and there's a separate page.waitForNavigation() promise to be resolved, you may end up with a race condition that yields unexpected results. The correct pattern for click and wait for navigation is the following:

This method fetches an element with selector, scrolls it into view if needed, and then uses page.mouse to hover over the center of the element.
If there's no element matching selector, the method throws an error.

frame.tap(selector)

This method fetches an element with selector, scrolls it into view if needed, and then uses page.touchscreen to tap in the center of the element.
If there's no element matching selector, the method throws an error.

frame.waitForFunction(pageFunction[, options[, ...args]])

polling <string|number> An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values:

raf - to constantly execute pageFunction in requestAnimationFrame callback. This is the tightest polling mode which is suitable to observe styling changes.

mutation - to execute pageFunction on every DOM mutation.

timeout <number> maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.

frame.waitForSelector(selector[, options])

visible <boolean> wait for element to be present in DOM and to be visible, i.e. to not have display: none or visibility: hidden CSS properties. Defaults to false.

hidden <boolean> wait for element to not be found in the DOM or to be hidden, i.e. have display: none or visibility: hidden CSS properties. Defaults to false.

timeout <number> maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.

returns: <Promise<ElementHandle>> Promise which resolves when element specified by selector string is added to DOM.

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.

frame.waitForXPath(xpath[, options])

visible <boolean> wait for element to be present in DOM and to be visible, i.e. to not have display: none or visibility: hidden CSS properties. Defaults to false.

hidden <boolean> wait for element to not be found in the DOM or to be hidden, i.e. have display: none or visibility: hidden CSS properties. Defaults to false.

timeout <number> maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.

returns: <Promise<ElementHandle>> Promise which resolves when element specified by xpath string is added to DOM.

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.

If key is a single character and no modifier keys besides Shift are being held down, a keypress/input event will also be generated. The text option can be specified to force an input event to be generated.

NOTE Modifier keys DO effect elementHandle.press. Holding down Shift will type the text in upper case.

Continues request with optional request overrides. To use this, request interception should be enabled with page.setRequestInterception.
Exception is immediately thrown if the request interception is not enabled.

request.resourceType()

Contains the request's resource type as it was perceived by the rendering engine.
ResourceType will be one of the following: document, stylesheet, image, media, font, script, texttrack, xhr, fetch, eventsource, websocket, manifest, other.

NOTE Anonymous scripts are ones that don't have an associated url. These are scripts that are dynamically created on the page using eval or new Function. If reportAnonymousScripts is set to true, anonymous scripts will have __puppeteer_evaluation_script__ as their URL.

coverage.stopCSSCoverage()

returns: <Promise<Array<Object>>> Promise that resolves to the array of coverage reports for all stylesheets