##### Released APIs: [v1.2.0](https://github.com/GoogleChrome/puppeteer/blob/v1.2.0/docs/api.md) | [v1.1.1](https://github.com/GoogleChrome/puppeteer/blob/v1.1.1/docs/api.md) | [v1.1.0](https://github.com/GoogleChrome/puppeteer/blob/v1.1.0/docs/api.md) | [v1.0.0](https://github.com/GoogleChrome/puppeteer/blob/v1.0.0/docs/api.md) | [v0.13.0](https://github.com/GoogleChrome/puppeteer/blob/v0.13.0/docs/api.md) | [v0.12.0](https://github.com/GoogleChrome/puppeteer/blob/v0.12.0/docs/api.md) | [v0.11.0](https://github.com/GoogleChrome/puppeteer/blob/v0.11.0/docs/api.md) | [v0.10.2](https://github.com/GoogleChrome/puppeteer/blob/v0.10.2/docs/api.md) | [v0.10.1](https://github.com/GoogleChrome/puppeteer/blob/v0.10.1/docs/api.md) | [v0.10.0](https://github.com/GoogleChrome/puppeteer/blob/v0.10.0/docs/api.md) | [v0.9.0](https://github.com/GoogleChrome/puppeteer/blob/v0.9.0/docs/api.md) # Puppeteer API v1.2.0-post \*\*NOT RELEASED\*\* > **NOTE** This version of API **is expected to be released** on **April 12, 2018**. ##### Table of Contents - [Overview](#overview) - [Environment Variables](#environment-variables) - [class: Puppeteer](#class-puppeteer) * [puppeteer.connect(options)](#puppeteerconnectoptions) * [puppeteer.createBrowserFetcher([options])](#puppeteercreatebrowserfetcheroptions) * [puppeteer.defaultArgs()](#puppeteerdefaultargs) * [puppeteer.executablePath()](#puppeteerexecutablepath) * [puppeteer.launch([options])](#puppeteerlaunchoptions) - [class: BrowserFetcher](#class-browserfetcher) * [browserFetcher.canDownload(revision)](#browserfetchercandownloadrevision) * [browserFetcher.download(revision[, progressCallback])](#browserfetcherdownloadrevision-progresscallback) * [browserFetcher.localRevisions()](#browserfetcherlocalrevisions) * [browserFetcher.platform()](#browserfetcherplatform) * [browserFetcher.remove(revision)](#browserfetcherremoverevision) * [browserFetcher.revisionInfo(revision)](#browserfetcherrevisioninforevision) - [class: Browser](#class-browser) * [event: 'disconnected'](#event-disconnected) * [event: 'targetchanged'](#event-targetchanged) * [event: 'targetcreated'](#event-targetcreated) * [event: 'targetdestroyed'](#event-targetdestroyed) * [browser.close()](#browserclose) * [browser.disconnect()](#browserdisconnect) * [browser.newPage()](#browsernewpage) * [browser.pages()](#browserpages) * [browser.process()](#browserprocess) * [browser.targets()](#browsertargets) * [browser.userAgent()](#browseruseragent) * [browser.version()](#browserversion) * [browser.wsEndpoint()](#browserwsendpoint) - [class: Page](#class-page) * [event: 'console'](#event-console) * [event: 'dialog'](#event-dialog) * [event: 'domcontentloaded'](#event-domcontentloaded) * [event: 'error'](#event-error) * [event: 'frameattached'](#event-frameattached) * [event: 'framedetached'](#event-framedetached) * [event: 'framenavigated'](#event-framenavigated) * [event: 'load'](#event-load) * [event: 'metrics'](#event-metrics) * [event: 'pageerror'](#event-pageerror) * [event: 'request'](#event-request) * [event: 'requestfailed'](#event-requestfailed) * [event: 'requestfinished'](#event-requestfinished) * [event: 'response'](#event-response) * [page.$(selector)](#pageselector) * [page.$$(selector)](#pageselector) * [page.$$eval(selector, pageFunction[, ...args])](#pageevalselector-pagefunction-args) * [page.$eval(selector, pageFunction[, ...args])](#pageevalselector-pagefunction-args) * [page.$x(expression)](#pagexexpression) * [page.addScriptTag(options)](#pageaddscripttagoptions) * [page.addStyleTag(options)](#pageaddstyletagoptions) * [page.authenticate(credentials)](#pageauthenticatecredentials) * [page.bringToFront()](#pagebringtofront) * [page.click(selector[, options])](#pageclickselector-options) * [page.close()](#pageclose) * [page.content()](#pagecontent) * [page.cookies(...urls)](#pagecookiesurls) * [page.coverage](#pagecoverage) * [page.deleteCookie(...cookies)](#pagedeletecookiecookies) * [page.emulate(options)](#pageemulateoptions) * [page.emulateMedia(mediaType)](#pageemulatemediamediatype) * [page.evaluate(pageFunction, ...args)](#pageevaluatepagefunction-args) * [page.evaluateHandle(pageFunction, ...args)](#pageevaluatehandlepagefunction-args) * [page.evaluateOnNewDocument(pageFunction, ...args)](#pageevaluateonnewdocumentpagefunction-args) * [page.exposeFunction(name, puppeteerFunction)](#pageexposefunctionname-puppeteerfunction) * [page.focus(selector)](#pagefocusselector) * [page.frames()](#pageframes) * [page.goBack(options)](#pagegobackoptions) * [page.goForward(options)](#pagegoforwardoptions) * [page.goto(url, options)](#pagegotourl-options) * [page.hover(selector)](#pagehoverselector) * [page.keyboard](#pagekeyboard) * [page.mainFrame()](#pagemainframe) * [page.metrics()](#pagemetrics) * [page.mouse](#pagemouse) * [page.pdf(options)](#pagepdfoptions) * [page.queryObjects(prototypeHandle)](#pagequeryobjectsprototypehandle) * [page.reload(options)](#pagereloadoptions) * [page.screenshot([options])](#pagescreenshotoptions) * [page.select(selector, ...values)](#pageselectselector-values) * [page.setCacheEnabled(enabled)](#pagesetcacheenabledenabled) * [page.setContent(html)](#pagesetcontenthtml) * [page.setCookie(...cookies)](#pagesetcookiecookies) * [page.setDefaultNavigationTimeout(timeout)](#pagesetdefaultnavigationtimeouttimeout) * [page.setExtraHTTPHeaders(headers)](#pagesetextrahttpheadersheaders) * [page.setJavaScriptEnabled(enabled)](#pagesetjavascriptenabledenabled) * [page.setOfflineMode(enabled)](#pagesetofflinemodeenabled) * [page.setRequestInterception(value)](#pagesetrequestinterceptionvalue) * [page.setUserAgent(userAgent)](#pagesetuseragentuseragent) * [page.setViewport(viewport)](#pagesetviewportviewport) * [page.tap(selector)](#pagetapselector) * [page.target()](#pagetarget) * [page.title()](#pagetitle) * [page.touchscreen](#pagetouchscreen) * [page.tracing](#pagetracing) * [page.type(selector, text[, options])](#pagetypeselector-text-options) * [page.url()](#pageurl) * [page.viewport()](#pageviewport) * [page.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#pagewaitforselectororfunctionortimeout-options-args) * [page.waitForFunction(pageFunction[, options[, ...args]])](#pagewaitforfunctionpagefunction-options-args) * [page.waitForNavigation(options)](#pagewaitfornavigationoptions) * [page.waitForSelector(selector[, options])](#pagewaitforselectorselector-options) * [page.waitForXPath(xpath[, options])](#pagewaitforxpathxpath-options) - [class: Keyboard](#class-keyboard) * [keyboard.down(key[, options])](#keyboarddownkey-options) * [keyboard.press(key[, options])](#keyboardpresskey-options) * [keyboard.sendCharacter(char)](#keyboardsendcharacterchar) * [keyboard.type(text, options)](#keyboardtypetext-options) * [keyboard.up(key)](#keyboardupkey) - [class: Mouse](#class-mouse) * [mouse.click(x, y, [options])](#mouseclickx-y-options) * [mouse.down([options])](#mousedownoptions) * [mouse.move(x, y, [options])](#mousemovex-y-options) * [mouse.up([options])](#mouseupoptions) - [class: Touchscreen](#class-touchscreen) * [touchscreen.tap(x, y)](#touchscreentapx-y) - [class: Tracing](#class-tracing) * [tracing.start(options)](#tracingstartoptions) * [tracing.stop()](#tracingstop) - [class: Dialog](#class-dialog) * [dialog.accept([promptText])](#dialogacceptprompttext) * [dialog.defaultValue()](#dialogdefaultvalue) * [dialog.dismiss()](#dialogdismiss) * [dialog.message()](#dialogmessage) * [dialog.type()](#dialogtype) - [class: ConsoleMessage](#class-consolemessage) * [consoleMessage.args()](#consolemessageargs) * [consoleMessage.text()](#consolemessagetext) * [consoleMessage.type()](#consolemessagetype) - [class: Frame](#class-frame) * [frame.$(selector)](#frameselector) * [frame.$$(selector)](#frameselector) * [frame.$$eval(selector, pageFunction[, ...args])](#frameevalselector-pagefunction-args) * [frame.$eval(selector, pageFunction[, ...args])](#frameevalselector-pagefunction-args) * [frame.$x(expression)](#framexexpression) * [frame.addScriptTag(options)](#frameaddscripttagoptions) * [frame.addStyleTag(options)](#frameaddstyletagoptions) * [frame.childFrames()](#framechildframes) * [frame.click(selector[, options])](#frameclickselector-options) * [frame.content()](#framecontent) * [frame.evaluate(pageFunction, ...args)](#frameevaluatepagefunction-args) * [frame.evaluateHandle(pageFunction, ...args)](#frameevaluatehandlepagefunction-args) * [frame.executionContext()](#frameexecutioncontext) * [frame.focus(selector)](#framefocusselector) * [frame.hover(selector)](#framehoverselector) * [frame.isDetached()](#frameisdetached) * [frame.name()](#framename) * [frame.parentFrame()](#frameparentframe) * [frame.select(selector, ...values)](#frameselectselector-values) * [frame.setContent(html)](#framesetcontenthtml) * [frame.tap(selector)](#frametapselector) * [frame.title()](#frametitle) * [frame.type(selector, text[, options])](#frametypeselector-text-options) * [frame.url()](#frameurl) * [frame.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#framewaitforselectororfunctionortimeout-options-args) * [frame.waitForFunction(pageFunction[, options[, ...args]])](#framewaitforfunctionpagefunction-options-args) * [frame.waitForSelector(selector[, options])](#framewaitforselectorselector-options) * [frame.waitForXPath(xpath[, options])](#framewaitforxpathxpath-options) - [class: ExecutionContext](#class-executioncontext) * [executionContext.evaluate(pageFunction, ...args)](#executioncontextevaluatepagefunction-args) * [executionContext.evaluateHandle(pageFunction, ...args)](#executioncontextevaluatehandlepagefunction-args) * [executionContext.frame()](#executioncontextframe) * [executionContext.queryObjects(prototypeHandle)](#executioncontextqueryobjectsprototypehandle) - [class: JSHandle](#class-jshandle) * [jsHandle.asElement()](#jshandleaselement) * [jsHandle.dispose()](#jshandledispose) * [jsHandle.executionContext()](#jshandleexecutioncontext) * [jsHandle.getProperties()](#jshandlegetproperties) * [jsHandle.getProperty(propertyName)](#jshandlegetpropertypropertyname) * [jsHandle.jsonValue()](#jshandlejsonvalue) - [class: ElementHandle](#class-elementhandle) * [elementHandle.$(selector)](#elementhandleselector) * [elementHandle.$$(selector)](#elementhandleselector) * [elementHandle.$x(expression)](#elementhandlexexpression) * [elementHandle.asElement()](#elementhandleaselement) * [elementHandle.boundingBox()](#elementhandleboundingbox) * [elementHandle.click([options])](#elementhandleclickoptions) * [elementHandle.contentFrame()](#elementhandlecontentframe) * [elementHandle.dispose()](#elementhandledispose) * [elementHandle.executionContext()](#elementhandleexecutioncontext) * [elementHandle.focus()](#elementhandlefocus) * [elementHandle.getProperties()](#elementhandlegetproperties) * [elementHandle.getProperty(propertyName)](#elementhandlegetpropertypropertyname) * [elementHandle.hover()](#elementhandlehover) * [elementHandle.jsonValue()](#elementhandlejsonvalue) * [elementHandle.press(key[, options])](#elementhandlepresskey-options) * [elementHandle.screenshot([options])](#elementhandlescreenshotoptions) * [elementHandle.tap()](#elementhandletap) * [elementHandle.toString()](#elementhandletostring) * [elementHandle.type(text[, options])](#elementhandletypetext-options) * [elementHandle.uploadFile(...filePaths)](#elementhandleuploadfilefilepaths) - [class: Request](#class-request) * [request.abort([errorCode])](#requestaborterrorcode) * [request.continue([overrides])](#requestcontinueoverrides) * [request.failure()](#requestfailure) * [request.frame()](#requestframe) * [request.headers()](#requestheaders) * [request.method()](#requestmethod) * [request.postData()](#requestpostdata) * [request.redirectChain()](#requestredirectchain) * [request.resourceType()](#requestresourcetype) * [request.respond(response)](#requestrespondresponse) * [request.response()](#requestresponse) * [request.url()](#requesturl) - [class: Response](#class-response) * [response.buffer()](#responsebuffer) * [response.fromCache()](#responsefromcache) * [response.fromServiceWorker()](#responsefromserviceworker) * [response.headers()](#responseheaders) * [response.json()](#responsejson) * [response.ok()](#responseok) * [response.request()](#responserequest) * [response.securityDetails()](#responsesecuritydetails) * [response.status()](#responsestatus) * [response.text()](#responsetext) * [response.url()](#responseurl) - [class: SecurityDetails](#class-securitydetails) * [securityDetails.issuer()](#securitydetailsissuer) * [securityDetails.protocol()](#securitydetailsprotocol) * [securityDetails.subjectName()](#securitydetailssubjectname) * [securityDetails.validFrom()](#securitydetailsvalidfrom) * [securityDetails.validTo()](#securitydetailsvalidto) - [class: Target](#class-target) * [target.createCDPSession()](#targetcreatecdpsession) * [target.page()](#targetpage) * [target.type()](#targettype) * [target.url()](#targeturl) - [class: CDPSession](#class-cdpsession) * [cdpSession.detach()](#cdpsessiondetach) * [cdpSession.send(method[, params])](#cdpsessionsendmethod-params) - [class: Coverage](#class-coverage) * [coverage.startCSSCoverage(options)](#coveragestartcsscoverageoptions) * [coverage.startJSCoverage(options)](#coveragestartjscoverageoptions) * [coverage.stopCSSCoverage()](#coveragestopcsscoverage) * [coverage.stopJSCoverage()](#coveragestopjscoverage) ### Overview Puppeteer is a Node library which provides a high-level API to control Chromium or Chrome over the DevTools Protocol. The Puppeteer API is hierarchical and mirrors the browser structure. On the following diagram, faded entities are not currently represented in Puppeteer. ![puppeteer overview](https://user-images.githubusercontent.com/746130/31592143-089f6f9a-b1db-11e7-9a20-16b7fc754fa1.png) - [`Puppeteer`](#class-puppeteer) communicates with the browser using [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/). - [`Browser`](#class-browser) instance can own multiple pages. - [`Page`](#class-page) has at least one frame: main frame. There might be other frames created by [iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) or [frame](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/frame) tags. - [`Frame`](#class-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](https://developer.chrome.com/extensions). (Diagram source: [link](https://docs.google.com/drawings/d/1Q_AM6KYs9kbyLZF-Lpp5mtpAWth73Cq8IKCsWYgi8MM/edit?usp=sharing)) ### Environment Variables Puppeteer looks for certain [environment variables](https://en.wikipedia.org/wiki/Environment_variable) to aid its operations. These variables can either be set in the environment or in 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. - `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 ### class: Puppeteer Puppeteer module provides a method to launch a Chromium instance. The following is a typical example of using Puppeteer to drive automation: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { const page = await browser.newPage(); await page.goto('https://www.google.com'); // other actions... await browser.close(); }); ``` #### puppeteer.connect(options) - `options` <[Object]> - `browserWSEndpoint` <[string]> a [browser websocket endpoint](#browserwsendpoint) to connect to. - `ignoreHTTPSErrors` <[boolean]> Whether to ignore HTTPS errors during navigation. Defaults to `false`. - `slowMo` <[number]> Slows down Puppeteer operations by the specified amount of milliseconds. Useful so that you can see what is going on. - returns: <[Promise]<[Browser]>> This methods attaches Puppeteer to an existing Chromium instance. #### puppeteer.createBrowserFetcher([options]) - `options` <[Object]> - `host` <[string]> A download host to be used. Defaults to `https://storage.googleapis.com`. - `path` <[string]> A path for the downloads folder. Defaults to `/.local-chromium`, where `` is puppeteer's package root. - `platform` <[string]> Possible values are: `mac`, `win32`, `win64`, `linux`. Defaults to the current platform. - returns: <[BrowserFetcher]> #### puppeteer.defaultArgs() - returns: <[Array]<[string]>> The default flags that Chromium will be launched with. #### puppeteer.executablePath() - returns: <[string]> A path where Puppeteer expects to find bundled Chromium. Chromium might not exist there if the download was skipped with [`PUPPETEER_SKIP_CHROMIUM_DOWNLOAD`](#environment-variables). #### puppeteer.launch([options]) - `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields: - `ignoreHTTPSErrors` <[boolean]> Whether to ignore HTTPS errors during navigation. Defaults to `false`. - `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`. - `executablePath` <[string]> Path to a Chromium or Chrome executable to run instead of the bundled Chromium. If `executablePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). - `slowMo` <[number]> Slows down Puppeteer operations by the specified amount of milliseconds. Useful so that you can see what is going on. - `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/). - `ignoreDefaultArgs` <[boolean]> Do not use [`puppeteer.defaultArgs()`](#puppeteerdefaultargs). 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`. - `userDataDir` <[string]> Path to a [User Data Directory](https://chromium.googlesource.com/chromium/src/+/master/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`. - returns: <[Promise]<[Browser]>> Promise which resolves to browser instance. The method launches a browser instance with given arguments. The browser will be closed when the parent node.js process is closed. > **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. > > If Google Chrome (rather than Chromium) is preferred, a [Chrome Canary](https://www.google.com/chrome/browser/canary.html) or [Dev Channel](https://www.chromium.org/getting-involved/dev-channel) build is suggested. > > In [puppeteer.launch([options])](#puppeteerlaunchoptions) above, any mention of Chromium also applies to Chrome. > > 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/+/lkcr/docs/chromium_browser_vs_google_chrome.md) describes some differences for Linux users. ### class: BrowserFetcher BrowserFetcher can download and manage different versions of Chromium. BrowserFetcher operates on revision strings that specify a precise version of Chromium, e.g. `"533271"`. Revision strings can be obtained from [omahaproxy.appspot.com](http://omahaproxy.appspot.com/). Example on how to use BrowserFetcher to download a specific version of Chromium and run Puppeteer against it: ```js const browserFetcher = puppeteer.createBrowserFetcher(); const revisionInfo = await browserFetcher.download('533271'); const browser = await puppeteer.launch({executablePath: revisionInfo.executablePath}) ``` > **NOTE** BrowserFetcher is not designed to work concurrently with other > instances of BrowserFetcher that share the same downloads directory. #### browserFetcher.canDownload(revision) - `revision` <[string]> a revision to check availability. - returns: <[Promise]<[boolean]>> returns `true` if the revision could be downloaded from the host. The method initiates a HEAD request to check if the revision is available. #### browserFetcher.download(revision[, progressCallback]) - `revision` <[string]> a revision to download. - `progressCallback` <[function]([number], [number])> A function that will be called with two arguments: - `downloadedBytes` <[number]> how many bytes have been downloaded - `totalBytes` <[number]> how large is the total download. - returns: <[Promise]<[Object]>> Resolves with revision information when the revision is downloaded and extracted - `revision` <[string]> the revision the info was created from - `folderPath` <[string]> path to the extracted revision folder - `executablePath` <[string]> path to the revision executable - `url` <[string]> URL this revision can be downloaded from - `local` <[boolean]> whether the revision is locally available on disk The method initiates a GET request to download the revision from the host. #### browserFetcher.localRevisions() - returns: <[Promise]<[Array]<[string]>>> A list of all revisions available locally on disk. #### browserFetcher.platform() - returns: <[string]> Returns one of `mac`, `linux`, `win32` or `win64`. #### browserFetcher.remove(revision) - `revision` <[string]> a revision to remove. The method will throw if the revision has not been downloaded. - returns: <[Promise]> Resolves when the revision has been removed. #### browserFetcher.revisionInfo(revision) - `revision` <[string]> a revision to get info for. - returns: <[Object]> - `revision` <[string]> the revision the info was created from - `folderPath` <[string]> path to the extracted revision folder - `executablePath` <[string]> path to the revision executable - `url` <[string]> URL this revision can be downloaded from - `local` <[boolean]> whether the revision is locally available on disk ### class: Browser * extends: [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter) A Browser is created when Puppeteer connects to a Chromium instance, either through [`puppeteer.launch`](#puppeteerlaunchoptions) or [`puppeteer.connect`](#puppeteerconnectoptions). An example of using a [Browser] to create a [Page]: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { const page = await browser.newPage(); await page.goto('https://example.com'); await browser.close(); }); ``` An example of disconnecting from and reconnecting to a [Browser]: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { // Store the endpoint to be able to reconnect to Chromium const browserWSEndpoint = browser.wsEndpoint(); // Disconnect puppeteer from Chromium browser.disconnect(); // Use the endpoint to reestablish a connection const browser2 = await puppeteer.connect({browserWSEndpoint}); // Close Chromium await browser2.close(); }); ``` #### event: 'disconnected' Emitted when Puppeteer gets disconnected from the Chromium instance. This might happen because of one of the following: - Chromium is closed or crashed - The [`browser.disconnect`](#browserdisconnect) method was called #### event: 'targetchanged' - <[Target]> Emitted when the url of a target changes. #### event: 'targetcreated' - <[Target]> Emitted when a target is created, for example when a new page is opened by [`window.open`](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) or [`browser.newPage`](#browsernewpage). #### event: 'targetdestroyed' - <[Target]> Emitted when a target is destroyed, for example when a page is closed. #### browser.close() - returns: <[Promise]> Closes Chromium and all of its pages (if any were opened). The [Browser] object itself is considered to be disposed and cannot be used anymore. #### 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. #### browser.newPage() - returns: <[Promise]<[Page]>> Promise which resolves to a new [Page] object. #### browser.pages() - returns: <[Promise]<[Array]<[Page]>>> Promise which resolves to an array of all open pages. #### browser.process() - returns: Spawned browser process. Returns `null` if the browser instance was created with [`puppeteer.connect`](#puppeteerconnectoptions) method. #### browser.targets() - returns: <[Array]<[Target]>> An array of all active targets. #### browser.userAgent() - returns: <[Promise]<[string]>> Promise which resolves to the browser's original user agent. > **NOTE** Pages can override browser user agent with [page.setUserAgent](#pagesetuseragentuseragent) #### browser.version() - returns: <[Promise]<[string]>> For headless Chromium, this is similar to `HeadlessChrome/61.0.3153.0`. For non-headless, this is similar to `Chrome/61.0.3153.0`. > **NOTE** the format of browser.version() might change with future releases of Chromium. #### browser.wsEndpoint() - returns: <[string]> Browser websocket url. Browser websocket endpoint which can be used as an argument to [puppeteer.connect](#puppeteerconnectoptions). The format is `ws://${host}:${port}/devtools/browser/` You can find the `webSocketDebuggerUrl` from `http://${host}:${port}/json/version`. Learn more about the [devtools protocol](https://chromedevtools.github.io/devtools-protocol) and the [browser endpoint](https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target). ### class: Page * extends: [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter) Page provides methods to interact with a single tab in Chromium. One [Browser] instance might have multiple [Page] instances. This example creates a page, navigates it to a URL, and then saves a screenshot: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { const page = await browser.newPage(); await page.goto('https://example.com'); await page.screenshot({path: 'screenshot.png'}); await browser.close(); }); ``` The Page class emits various events (described below) which can be handled using any of Node's native [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter) methods, such as `on`, `once` or `removeListener`. This example logs a message for a single page `load` event: ```js page.once('load', () => console.log('Page loaded!')); ``` To unsubscribe from events use the `removeListener` method: ```js function logRequest(interceptedRequest) { console.log('A request was made:', interceptedRequest.url()); } page.on('request', logRequest); // Sometime later... page.removeListener('request', logRequest); ``` #### event: 'console' - <[ConsoleMessage]> Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`. Also emitted if the page throws an error or a warning. The arguments passed into `console.log` appear as arguments on the event handler. An example of handling `console` event: ```js page.on('console', msg => { for (let i = 0; i < msg.args().length; ++i) console.log(`${i}: ${msg.args()[i]}`); }); page.evaluate(() => console.log('hello', 5, {foo: 'bar'})); ``` #### event: 'dialog' - <[Dialog]> Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Puppeteer can respond to the dialog via [Dialog]'s [accept](#dialogacceptprompttext) or [dismiss](#dialogdismiss) methods. #### event: 'domcontentloaded' Emitted when the JavaScript [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event is dispatched. #### event: 'error' - <[Error]> Emitted when the page crashes. > **NOTE** `error` event has a special meaning in Node, see [error events](https://nodejs.org/api/events.html#events_error_events) for details. #### event: 'frameattached' - <[Frame]> Emitted when a frame is attached. #### event: 'framedetached' - <[Frame]> Emitted when a frame is detached. #### event: 'framenavigated' - <[Frame]> Emitted when a frame is navigated to a new url. #### event: 'load' Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched. #### event: 'metrics' - <[Object]> - `title` <[string]> The title passed to `console.timeStamp`. - `metrics` <[Object]> Object containing metrics as key/value pairs. The values of metrics are of <[number]> type. Emitted when the JavaScript code makes a call to `console.timeStamp`. For the list of metrics see `page.metrics`. #### event: 'pageerror' - <[Error]> The exception message Emitted when an uncaught exception happens within the page. #### event: 'request' - <[Request]> Emitted when a page issues a request. The [request] object is read-only. In order to intercept and mutate requests, see `page.setRequestInterception`. #### event: 'requestfailed' - <[Request]> Emitted when a request fails, for example by timing out. #### event: 'requestfinished' - <[Request]> Emitted when a request finishes successfully. #### event: 'response' - <[Response]> Emitted when a [response] is received. #### page.$(selector) - `selector` <[string]> A [selector] to query page for - returns: <[Promise]> The method runs `document.querySelector` within the page. If no element matches the selector, the return value resolve to `null`. Shortcut for [page.mainFrame().$(selector)](#frameselector). #### page.$$(selector) - `selector` <[string]> A [selector] to query page for - returns: <[Promise]<[Array]<[ElementHandle]>>> The method runs `document.querySelectorAll` within the page. If no elements match the selector, the return value resolve to `[]`. Shortcut for [page.mainFrame().$$(selector)](#frameselector-1). #### page.$$eval(selector, pageFunction[, ...args]) - `selector` <[string]> A [selector] to query frame for - `pageFunction` <[function]> Function to be evaluated in browser context - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction` - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction` This method runs `document.querySelectorAll` within the page and passes it as the first argument to `pageFunction`. If `pageFunction` returns a [Promise], then `page.$$eval` would wait for the promise to resolve and return its value. Examples: ```js const divsCounts = await page.$$eval('div', divs => divs.length); ``` #### page.$eval(selector, pageFunction[, ...args]) - `selector` <[string]> A [selector] to query page for - `pageFunction` <[function]> Function to be evaluated in browser context - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction` - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction` This method runs `document.querySelector` within the page 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 `page.$eval` would wait for the promise to resolve and return its value. Examples: ```js 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', e => e.outerHTML); ``` Shortcut for [page.mainFrame().$eval(selector, pageFunction)](#frameevalselector-pagefunction-args). #### page.$x(expression) - `expression` <[string]> Expression to [evaluate](https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate). - returns: <[Promise]<[Array]<[ElementHandle]>>> The method evaluates the XPath expression. Shortcut for [page.mainFrame().$x(expression)](#frameexpression) #### page.addScriptTag(options) - `options` <[Object]> - `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. - 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 `