From 549535e674e150aa6a54c2c58242dd74f2969ae4 Mon Sep 17 00:00:00 2001 From: Andrey Lushnikov Date: Tue, 13 Jun 2017 00:28:29 -0700 Subject: [PATCH] Add docs/api.md 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. --- docs/api.md | 209 ++++++++++++++++++++++++++++++++++++++++++++++++++++ lib/Page.js | 1 + 2 files changed, 210 insertions(+) create mode 100644 docs/api.md diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 00000000000..bfea91b971d --- /dev/null +++ b/docs/api.md @@ -0,0 +1,209 @@ +# 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. diff --git a/lib/Page.js b/lib/Page.js index 30ca2b2a610..2f8c9b3a8e4 100644 --- a/lib/Page.js +++ b/lib/Page.js @@ -404,6 +404,7 @@ class Page extends EventEmitter { /** * @param {string} filePath * @param {!Object=} options + * @return {!Promise} */ async printToPDF(filePath, options) { options = options || {};