From 8e0db60c03ceaa65db163a8d6e22219b022616a9 Mon Sep 17 00:00:00 2001 From: Andrey Lushnikov Date: Wed, 21 Jun 2017 11:17:35 -0700 Subject: [PATCH] Update api.md This patch improves on api.md so that the raw md is human-readable and the rendering is still good. The next step would be linting markdown so that it's up-to-date and neat. References #14. --- docs/api.md | 140 ++++++++++++++++++++++++++++------------------------ 1 file changed, 75 insertions(+), 65 deletions(-) diff --git a/docs/api.md b/docs/api.md index ccb9a85d..eb966075 100644 --- a/docs/api.md +++ b/docs/api.md @@ -21,7 +21,7 @@ - [page.viewportSize()](#pagesize) - [page.evaluate(fun, args)](#pageevaluatefun-args) - [page.evaluateOnInitialized(fun, args)](#pageevaluateoninitializedfun-args) - - [page.screenshot([options])](#pagescreenshottype-cliprect) + - [page.screenshot(\[options\])](#pagescreenshottype-cliprect) - [page.printToPDF(filePath[, options])](#pageprinttopdffilepath-options) - [page.plainText()](#pageplaintext) - [page.title()](#pagetitle) @@ -35,25 +35,25 @@ not necessarily result in launching browser; the instance will be launched when #### 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/). +- `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](http://peter.sh/experiments/chromium-command-line-switches/). #### browser.newPage() -- returns: [<Promise<Page>>](http://todo) +- returns: <[Promise]<[Page]>> 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) +- returns: <[Promise]> #### browser.version() -- returns: [<Promise<string>>]((https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)) +- returns: <[Promise]<[string]>> #### browser.close() @@ -73,115 +73,125 @@ Pages could be closed by `page.close()` method. #### 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. +- `url` <[string]> Url of a script to be added +- returns: <[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. +- `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.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 +- `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.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 +- `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.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. +- returns: <[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. +- `userAgent` <[string]> Specific user agent to use in this page +- returns: <[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. +- returns: <[string]> Returns user agent override, if any. #### 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. +- returns: <[Promise]<[string]>> 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. +- `html` <[string]> HTML markup to assign to the page. +- returns: <[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: +- `url` <[string]> URL to navigate page to +- returns: <[Promise]<[boolean]>> 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.setViewportSize(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. +- `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.viewportSize() -- 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. +- returns: <[Object]> An object with two fields: + - `width` <[number]> Page's width in pixels. + - `height` <[number]> 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 +- `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>](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 +- `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.screenshot([options]) -- `options` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Options object which might have the following properties: - - `path` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The file path to save the image to. The screenshot type will be inferred from file extension. - - `type` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Specify screenshot type, could be either `jpeg` or `png`. - - `quality` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The quality of the image, between 0-100. Not applicable to `.jpg` images. - - `fullPage` [<boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) When true, takes a screenshot of the full scrollable page. - - `clip` [<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 +- `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 `.jpg` 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.printToPDF(filePath[, options]) -- `filePath` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The file path to save the 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. +- `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.plainText() -- returns: [<Promise<string>>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Returns page's inner text. +- returns: <[Promise]<[string]>> 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. +- returns: <[Promise]<[string]>> 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. +- returns: <[Promise]> Returns promise which resolves when page gets closed. + +[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array" +[boolean]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type "Boolean" +[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer" +[function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function "Function" +[number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number" +[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object" +[Page]: https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#class-page "Page" +[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise" +[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String"