puppeteer/docs/api.md
Andrey Lushnikov 45c20c7dad [doclint] introduce class members
This patch unifies Documentation.Method with Documentation.Property,
making it possible to verify sorting order across methods and
properties.

References #14.
2017-07-13 23:02:43 -07:00

17 KiB

Puppeteer API

Table of Contents

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.
    • 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(page)

  • page <Page> A page to be closed.
  • returns: <Promise> Promise which resolves when the page is closed.

browser.newPage()

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

browser.stderr

A Readable Stream that represents the browser process's stderr.

browser.stdout

A Readable Stream that represents the browser process's stdout.

browser.version()

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(selector)

  • selector <string> A query selector of element to click. If there are multiple elements satisfying the selector, the first will be clicked.

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 <...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 <...string> Arguments to pass to fun
  • returns: <Promise<Object>> Promise which resolves to function

page.focus(selector)

  • selector <string> A query selector of element to focus. If there are multiple elements satisfying the selector, the first will be focused.

page.frames()

page.httpHeaders()

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

page.injectFile(filePath)

  • filePath <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()

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:
  • 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)

  • name <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(interceptor)

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()

page.type(text)

  • text <string> A text to type into a focused element.

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)

  • selector <string> A query selector to wait for on the page.

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.

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

class: Dialog

dialog.accept([promptText])

  • promptText <string> A text to enter in prompt. Does not cause any effects if the dialog type is not prompt.

dialog.dismiss()

dialog.message()

dialog.type

Dialog's type, could be one of the alert, beforeunload, confirm and prompt.

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.headers

Contains the associated Headers object of the request.

request.method

Contains the request's method (GET, POST, etc.)

request.response()

request.url

Contains the URL of the request.

class: Response

response.headers

Contains the Headers object associated with the response.

response.ok

Contains a boolean stating whether the response was successful (status in the range 200-299) or not.

response.request()

response.status

Contains the status code of the response (e.g., 200 for a success).

response.statusText

Contains the status message corresponding to the status code (e.g., OK for 200).

response.url

Contains the URL of the response.

class: InterceptedRequest

interceptedRequest.abort()

interceptedRequest.continue()

interceptedRequest.headers

Contains the Headers object associated with the request.

interceptedRequest.isHandled()

interceptedRequest.method

Contains the request's method (GET, POST, etc.)

interceptedRequest.postData

In case of a POST request, contains POST data.

interceptedRequest.url

Contains the URL of the request.

class: Headers

headers.append(name, value)

  • name <string> Case-insensetive header name.
  • value <string> Header value

If there's already a header with name name, the header gets overwritten.

headers.delete(name)

  • name <string> Case-insensetive name of the header to be deleted. If there's no header with such name, the method does nothing.

headers.entries()

headers.get(name)

  • name <string> Case-insensetive name of the header.
  • returns: <string> Header value of null, if there's no such header.

headers.has(name)

  • name <string> Case-insensetive name of the header.
  • returns: <boolean> Returns true if the header with such name exists, or false otherwise.

headers.keys()

headers.set(name, value)

  • name <string> Case-insensetive header name.
  • value <string> Header value

If there's already a header with name name, the header gets overwritten.

headers.values()

class: Body

body.arrayBuffer()

body.bodyUsed()

body.buffer()

body.json()

body.text()