549535e674
This patch adds docs/api.md file which contains API description for the puppeteer API. This patch adds the API outline, which doesn't not have explanations and samples.
210 lines
14 KiB
Markdown
210 lines
14 KiB
Markdown
# Puppeteer API
|
|
|
|
- [class: Browser](#class-browser)
|
|
- [new Browser([options])](#new-browseroptions)
|
|
- [browser.newPage()](#browsernewpage)
|
|
- [browser.closePage()](#browserclosepage)
|
|
- [browser.version()](#browserversion)
|
|
- [browser.close()](#browserclose)
|
|
- [class: Page](#class-page)
|
|
- [page.setBlockedURLs(patterns)](#pagesetblockedurlspatterns)
|
|
- [page.addScriptTag(url)](#pageaddscripttagurl)
|
|
- [page.injectFile(filePath)](#pageinjectfilefilepath)
|
|
- [page.setInPageCallback(name, callback)](#pagesetinpagecallbackname-callback)
|
|
- [page.setExtraHTTPHeaders(headers)](#pagesetextrahttpheadersheaders)
|
|
- [page.extraHTTPHeaders()](#pageextrahttpheaders)
|
|
- [page.setUserAgentOverride(userAgent)](#pagesetuseragentoverrideuseragent)
|
|
- [page.userAgentOverride()](#pageuseragentoverride)
|
|
- [page.handleDialog(accept, promptText)](#pagehandledialogaccept-prompttext)
|
|
- [page.url()](#pageurl)
|
|
- [page.setContent(html)](#pagesetcontenthtml)
|
|
- [page.navigate(url)](#pagenavigateurl)
|
|
- [page.setSize(size)](#pagesetsizesize)
|
|
- [page.size()](#pagesize)
|
|
- [page.evaluate(fun, args)](#pageevaluatefun-args)
|
|
- [page.evaluateAsync(fun, args)](#pageevaluateasyncfun-args)
|
|
- [page.evaluateOnInitialized(fun, args)](#pageevaluateoninitializedfun-args)
|
|
- [page.screenshot(type[, clipRect])](#pagescreenshottype-cliprect)
|
|
- [page.saveScreenshot(filePath[, clipRect])](#pagesavescreenshotfilepath-cliprect)
|
|
- [page.printToPDF(filePath[, options])](#pageprinttopdffilepath-options)
|
|
- [page.plainText()](#pageplaintext)
|
|
- [page.title()](#pagetitle)
|
|
- [page.close()](#pageclose)
|
|
|
|
### 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>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Set of configurable options to set on the browser. Can have the following fields:
|
|
- `headless` [<boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) Wether to run chromium in headless mode. Defaults to `true`.
|
|
- `remoteDebuggingPort` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) Specify a remote debugging port to open on chromium instance. Defaults to `9229`.
|
|
- `executablePath` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Path to a chromium executable to run instead of bundled chromium.
|
|
- `args` [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) Additional arguments to pass to the chromium instance. List of chromium flags could be found [here](http://peter.sh/experiments/chromium-command-line-switches/).
|
|
|
|
#### browser.newPage()
|
|
|
|
- returns: [<Promise<Page>>](http://todo)
|
|
|
|
Create a new page in browser and returns a promise which gets resolved with a Page object.
|
|
|
|
#### browser.closePage()
|
|
|
|
- returns: [<Promise>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise)
|
|
|
|
#### browser.version()
|
|
|
|
- returns: [<Promise<string>>]((https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type))
|
|
|
|
#### 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.
|
|
|
|
### class: Page
|
|
|
|
Page provides interface to interact with a tab in a browser. Pages are created by browser:
|
|
|
|
```javascript
|
|
var browser = new Browser();
|
|
browser.newPage().then(page => {
|
|
...
|
|
});
|
|
```
|
|
Pages could be closed by `page.close()` method.
|
|
|
|
#### page.setBlockedURLs(patterns)
|
|
|
|
- `patterns` [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
|
|
- returns: [<Promise>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves when blocked URLs have been successfully set.
|
|
|
|
#### page.addScriptTag(url)
|
|
|
|
- `url` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Url of a script to be added
|
|
- returns: [<Promise>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves as the script gets added and loads.
|
|
|
|
#### page.injectFile(filePath)
|
|
|
|
- `url` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Path to the javascript file to be injected into page.
|
|
- returns: [<Promise>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves when file gets successfully evaluated in page.
|
|
|
|
#### page.setInPageCallback(name, callback)
|
|
|
|
- `url` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Name of the callback to be assigned on window object
|
|
- `callback` [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) Callback function which will be called in node.js
|
|
- returns: [<Promise>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves when callback is successfully initialized
|
|
|
|
#### page.setExtraHTTPHeaders(headers)
|
|
|
|
- `headers` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Key-value set of additional http headers to be sent with every request.
|
|
- returns: [<Promise>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves when additional headers are installed
|
|
|
|
#### page.extraHTTPHeaders()
|
|
|
|
- returns: [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Key-value set of additional http headers, which will be sent with every request.
|
|
|
|
#### page.setUserAgentOverride(userAgent)
|
|
|
|
- `userAgent` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Specific user agent to use in this page
|
|
- returns: [<Promise>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves when the user agent is set.
|
|
|
|
#### page.userAgentOverride()
|
|
|
|
- returns: [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Returns user agent override, if any.
|
|
|
|
#### page.handleDialog(accept, promptText)
|
|
|
|
- `accept` [<boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) Wether accept or discard the dialog.
|
|
- `promptText` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Optional text to put inside the text prompt.
|
|
- returns: [<Promise>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves when the dialog is handled.
|
|
|
|
#### page.url()
|
|
|
|
- returns: [<Promise<string>>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Promise which resolves with the current page url.
|
|
|
|
#### page.setContent(html)
|
|
|
|
- `html` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) HTML markup to assign to the page.
|
|
- returns: [<Promise>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves when the content is successfully assigned.
|
|
|
|
#### page.navigate(url)
|
|
|
|
- `url` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) URL to navigate page to
|
|
- returns: [<Promise<boolean>>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) Promise which resolves when the page is navigated. The promise resolves to:
|
|
- `true` if the navigation succeeds and page's `load` event is fired.
|
|
- `false` if the navigation fails due to bad URL or SSL errors.
|
|
|
|
#### page.setSize(size)
|
|
|
|
- `size` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) An object with two fields:
|
|
- `width` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) Specify page's width in pixels.
|
|
- `height` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) Specify page's height in pixels.
|
|
- returns: [<Promise>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves when the dimensions are updated.
|
|
|
|
#### page.size()
|
|
|
|
- returns: [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) An object with two fields:
|
|
- `width` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) Page's width in pixels.
|
|
- `height` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) Page's height in pixels.
|
|
|
|
#### page.evaluate(fun, args)
|
|
|
|
- `fun` [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) Function to be evaluated in browser context
|
|
- `args` [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) Arguments to pass to `fun`
|
|
- returns: [<Promise<Object>>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves to function return value
|
|
|
|
#### page.evaluateAsync(fun, args)
|
|
|
|
- `fun` [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) Function to be evaluated in browser context
|
|
- `args` [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) Arguments to pass to `fun`
|
|
- returns: [<Promise<Object>>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves to function
|
|
|
|
#### page.evaluateOnInitialized(fun, args)
|
|
|
|
- `fun` [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) Function to be evaluated in browser context
|
|
- `args` [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) Arguments to pass to `fun`
|
|
- returns: [<Promise<Object>>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves to function
|
|
|
|
#### page.screenshot(type[, clipRect])
|
|
|
|
- `type` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Specify screenshot type, could be either `jpeg` or `png`.
|
|
- `clipRect` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) An object which specifies clipping region of the page. Should have the following fields:
|
|
- `x` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) x-coordinate of top-left corner of clip area
|
|
- `y` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) y-coordinate of top-left corner of clip area
|
|
- `width` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) width of clipping area
|
|
- `height` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) height of clipping area
|
|
- returns: [<Promise<Buffer>>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves to buffer with captured screenshot
|
|
|
|
#### page.saveScreenshot(filePath[, clipRect])
|
|
|
|
- `filePath` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The file path to save image to. The screenshot type will be inferred from file extension
|
|
- `clipRect` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Clip rect object which will be passed over to `page.screenshot` method.
|
|
|
|
#### page.printToPDF(filePath[, options])
|
|
|
|
- `filePath` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The file path to save image to. The screenshot type will be inferred from file extension
|
|
- `options` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Options object which might have the following properties:
|
|
- `scale` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)
|
|
- `displayHeaderFooter` [<boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
|
|
- `printBackground` [<boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
|
|
- `landscape` [<boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
|
|
- `pageRanges` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
|
|
- `format` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
|
|
- `width` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)
|
|
- `height` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)
|
|
- returns: [<Promise>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves when the PDF is saved.
|
|
|
|
#### page.plainText()
|
|
|
|
- returns: [<Promise<string>>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Returns page's inner text.
|
|
|
|
#### page.title()
|
|
|
|
- returns: [<Promise<string>>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Returns page's title.
|
|
|
|
#### page.close()
|
|
|
|
- returns: [<Promise>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Returns promise which resolves when page gets closed.
|