puppeteer/docs/api.md

Puppeteer API

Table of Contents

• class: Browser
  • new Browser([options])
  • browser.close()
  • browser.closePage()
  • browser.newPage()
  • browser.version()
• class: Page
  • page.addScriptTag(url)
  • page.click()
  • page.close()
  • page.evaluate(fun, args)
  • page.evaluateOnInitialized(fun, args)
  • page.focus()
  • page.frames()
  • page.httpHeaders()
  • page.injectFile(filePath)
  • page.mainFrame()
  • page.navigate(url, options)
  • page.plainText()
  • page.printToPDF(filePath[, options])
  • page.screenshot([options])
  • page.setContent(html)
  • page.setHTTPHeaders(headers)
  • page.setInPageCallback(name, callback)
  • page.setRequestInterceptor()
  • page.setUserAgent(userAgent)
  • page.setViewportSize(size)
  • page.title()
  • page.type()
  • page.uploadFile(selector, ...filePaths)
  • page.url()
  • page.userAgent()
  • page.viewportSize()
  • page.waitFor(selector)
• class: Dialog
  • dialog.accept()
  • dialog.dismiss()
  • dialog.message()
• class: Frame
  • frame.childFrames()
  • frame.evaluate(fun, args)
  • frame.isDetached()
  • frame.isMainFrame()
  • frame.name()
  • frame.parentFrame()
  • frame.securityOrigin()
  • frame.url()
  • frame.waitFor(selector)
• class: Request
  • request.response()
• class: Response
  • response.request()
• class: InterceptedRequest
  • interceptedRequest.abort()
  • interceptedRequest.continue()
  • interceptedRequest.isHandled()
• class: Headers
  • headers.append()
  • headers.delete()
  • headers.entries()
  • headers.get()
  • headers.has()
  • headers.keys()
  • headers.set()
  • headers.values()
• class: Body
  • body.arrayBuffer()
  • body.bodyUsed()
  • body.buffer()
  • body.json()
  • body.text()

class: Browser

Browser manages a browser instance, creating it with a predefined settings, opening and closing pages. Instantiating Browser class does not necessarily result in launching browser; the instance will be launched when the need will arise.

new Browser([options])

• options <Object> Set of configurable options to set on the browser. Can have the following fields:
  • headless <boolean> Wether to run chromium in headless mode. Defaults to true.
  • remoteDebuggingPort <number> Specify a remote debugging port to open on chromium instance. Defaults to 9229.
  • executablePath <string> Path to a chromium executable to run instead of bundled chromium.
  • args <Array<string>> Additional arguments to pass to the chromium instance. List of chromium flags could be found here.

browser.close()

Closes chromium application with all the pages (if any were opened). The browser object itself is considered to be disposed and could not be used anymore.

browser.closePage()

• returns: <Promise>

browser.newPage()

• returns: <Promise<Page>>

Create a new page in browser and returns a promise which gets resolved with a Page object.

browser.version()

• returns: <Promise<string>>

class: Page

Page provides interface to interact with a tab in a browser. Pages are created by browser:

var browser = new Browser();
browser.newPage().then(page => {
	...
});

Pages could be closed by page.close() method.

page.addScriptTag(url)

• url <string> Url of a script to be added
• returns: <Promise> Promise which resolves as the script gets added and loads.

page.click()

page.close()

• returns: <Promise> Returns promise which resolves when page gets closed.

page.evaluate(fun, args)

• fun <function> Function to be evaluated in browser context
• args <Array<string>> Arguments to pass to fun
• returns: <Promise<Object>> Promise which resolves to function return value

page.evaluateOnInitialized(fun, args)

• fun <function> Function to be evaluated in browser context
• args <Array<string>> Arguments to pass to fun
• returns: <Promise<Object>> Promise which resolves to function

page.focus()

page.frames()

page.httpHeaders()

• returns: <Object> Key-value set of additional http headers, which will be sent with every request.

page.injectFile(filePath)

• url <string> Path to the javascript file to be injected into page.
• returns: <Promise> Promise which resolves when file gets successfully evaluated in page.

page.mainFrame()

page.navigate(url, options)

• url <string> URL to navigate page to
• options <Object> Navigation parameters which might have the following properties:
  • maxTime <number> Maximum navigation time in milliseconds, defaults to 30 seconds.
  • waitFor <string> When to consider navigation succeeded, defaults to load. Could be either:
    • load - consider navigation to be finished when the load event is fired.
    • networkidle - consider navigation to be finished when the network activity stays "idle" for at least networkIdleTimeoutms.
  • networkIdleInflight <number> Maximum amount of inflight requests which are considered "idle". Takes effect only with waitFor: 'networkidle' parameter.
  • networkIdleTimeout <number> A timeout to wait before completing navigation. Takes effect only with waitFor: 'networkidle' parameter.
• 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.navigate will throw an error if:

• there's an SSL error (e.g. in case of self-signed certificates).
• target URL is invalid.
• the maxTime is exceeded during navigation.

page.plainText()

• returns: <Promise<string>> Returns page's inner text.

page.printToPDF(filePath[, options])

• filePath <string> The file path to save the image to. The screenshot type will be inferred from file extension
• options <Object> Options object which might have the following properties:
  • scale <number>
  • displayHeaderFooter <boolean>
  • printBackground <boolean>
  • landscape <boolean>
  • pageRanges <string>
  • format <string>
  • width <number>
  • height <number>
• returns: <Promise> Promise which resolves when the PDF is saved.

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.
  • type <string> Specify screenshot type, could be either jpeg or 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.
  • clip <Object> An object which specifies clipping region of the page. Should have the following fields:
    • x <number> x-coordinate of top-left corner of clip area
    • y <number> y-coordinate of top-left corner of clip area
    • width <number> width of clipping area
    • height <number> height of clipping area
• returns: <Promise<Buffer>> Promise which resolves to buffer with captured screenshot

page.setContent(html)

• html <string> HTML markup to assign to the page.
• returns: <Promise> Promise which resolves when the content is successfully assigned.

page.setHTTPHeaders(headers)

• headers <Object> Key-value set of additional http headers to be sent with every request.
• returns: <Promise> Promise which resolves when additional headers are installed

page.setInPageCallback(name, callback)

• url <string> Name of the callback to be assigned on window object
• callback <function> Callback function which will be called in node.js
• returns: <Promise> Promise which resolves when callback is successfully initialized

page.setRequestInterceptor()

page.setUserAgent(userAgent)

• userAgent <string> Specific user agent to use in this page
• returns: <Promise> Promise which resolves when the user agent is set.

page.setViewportSize(size)

• size <Object> An object with two fields:
  • width <number> Specify page's width in pixels.
  • height <number> Specify page's height in pixels.
• returns: <Promise> Promise which resolves when the dimensions are updated.

page.title()

• returns: <Promise<string>> Returns page's title.

page.type()

page.uploadFile(selector, ...filePaths)

• selector <string> A query selector to a file input
• ...filePaths <string> Sets the value of the file input these paths
• returns: <Promise> Promise which resolves when the value is set.

page.url()

• returns: <Promise<string>> Promise which resolves with the current page url.

page.userAgent()

• returns: <string> Returns user agent.

page.viewportSize()

• returns: <Object> An object with two fields:
  • width <number> Page's width in pixels.
  • height <number> Page's height in pixels.

page.waitFor(selector)

Shortcut for page.mainFrame().waitFor(selector).

class: Dialog

dialog.accept()

dialog.dismiss()

dialog.message()

class: Frame

frame.childFrames()

frame.evaluate(fun, args)

• fun <function> Function to be evaluated in browser context
• args <Array<string>> Arguments to pass to fun
• returns: <Promise<Object>> Promise which resolves to function return value

frame.isDetached()

frame.isMainFrame()

frame.name()

frame.parentFrame()

frame.securityOrigin()

frame.url()

frame.waitFor(selector)

• selector <string> CSS selector of awaited element,
• returns: <Promise> Promise which resolves when element specified by selector string is added to DOM.

class: Request

request.response()

class: Response

response.request()

class: InterceptedRequest

interceptedRequest.abort()

interceptedRequest.continue()

interceptedRequest.isHandled()

class: Headers

headers.append()

headers.delete()

headers.entries()

headers.get()

headers.has()

headers.keys()

headers.set()

headers.values()

class: Body

body.arrayBuffer()

body.bodyUsed()

body.buffer()

body.json()

body.text()