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

Raw Blame History

Puppeteer API

class: Browser
class: Page
class: Dialog
class: Frame
class: Request
class: Response
class: InterceptedRequest
class: Headers
class: Body

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

returns: <Promise<Page>>

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

browser.stderr

<stream.Readable>

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

browser.stdout

<stream.Readable>

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

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

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)

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)

interceptor <function> Callback function which accepts a single argument of type <InterceptedRequest>.

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

<string>

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

<Headers>

Contains the associated Headers object of the request.

request.method

<string>

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

request.response()

request.url

<string>

Contains the URL of the request.

class: Response

response.headers

<Headers>

Contains the Headers object associated with the response.

response.ok

<boolean>

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

response.request()

response.status

<number>

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

response.statusText

<string>

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

response.url

<string>

Contains the URL of the response.

class: InterceptedRequest

interceptedRequest.abort()

interceptedRequest.continue()

interceptedRequest.headers

<Headers>

Contains the Headers object associated with the request.

interceptedRequest.isHandled()

interceptedRequest.method

<string>