docs(api): add hierarchical diagram (#1040)

This commit is contained in:
Andrey Lushnikov 2017-10-16 11:07:06 -07:00 committed by GitHub
parent e3eec24894
commit e7eb7b3ccb

View File

@ -6,180 +6,192 @@
<!-- toc --> <!-- toc -->
- [Puppeteer](#puppeteer) - [Overview](#overview)
* [Environment Variables](#environment-variables) - [Environment Variables](#environment-variables)
* [class: Puppeteer](#class-puppeteer) - [class: Puppeteer](#class-puppeteer)
+ [puppeteer.connect(options)](#puppeteerconnectoptions) * [puppeteer.connect(options)](#puppeteerconnectoptions)
+ [puppeteer.executablePath()](#puppeteerexecutablepath) * [puppeteer.executablePath()](#puppeteerexecutablepath)
+ [puppeteer.launch([options])](#puppeteerlaunchoptions) * [puppeteer.launch([options])](#puppeteerlaunchoptions)
* [class: Browser](#class-browser) - [class: Browser](#class-browser)
+ [browser.close()](#browserclose) * [browser.close()](#browserclose)
+ [browser.newPage()](#browsernewpage) * [browser.newPage()](#browsernewpage)
+ [browser.version()](#browserversion) * [browser.version()](#browserversion)
+ [browser.wsEndpoint()](#browserwsendpoint) * [browser.wsEndpoint()](#browserwsendpoint)
* [class: Page](#class-page) - [class: Page](#class-page)
+ [event: 'console'](#event-console) * [event: 'console'](#event-console)
+ [event: 'dialog'](#event-dialog) * [event: 'dialog'](#event-dialog)
+ [event: 'error'](#event-error) * [event: 'error'](#event-error)
+ [event: 'frameattached'](#event-frameattached) * [event: 'frameattached'](#event-frameattached)
+ [event: 'framedetached'](#event-framedetached) * [event: 'framedetached'](#event-framedetached)
+ [event: 'framenavigated'](#event-framenavigated) * [event: 'framenavigated'](#event-framenavigated)
+ [event: 'load'](#event-load) * [event: 'load'](#event-load)
+ [event: 'metrics'](#event-metrics) * [event: 'metrics'](#event-metrics)
+ [event: 'pageerror'](#event-pageerror) * [event: 'pageerror'](#event-pageerror)
+ [event: 'request'](#event-request) * [event: 'request'](#event-request)
+ [event: 'requestfailed'](#event-requestfailed) * [event: 'requestfailed'](#event-requestfailed)
+ [event: 'requestfinished'](#event-requestfinished) * [event: 'requestfinished'](#event-requestfinished)
+ [event: 'response'](#event-response) * [event: 'response'](#event-response)
+ [page.$(selector)](#pageselector) * [page.$(selector)](#pageselector)
+ [page.$$(selector)](#pageselector) * [page.$$(selector)](#pageselector)
+ [page.$$eval(selector, pageFunction[, ...args])](#pageevalselector-pagefunction-args) * [page.$$eval(selector, pageFunction[, ...args])](#pageevalselector-pagefunction-args)
+ [page.$eval(selector, pageFunction[, ...args])](#pageevalselector-pagefunction-args) * [page.$eval(selector, pageFunction[, ...args])](#pageevalselector-pagefunction-args)
+ [page.addScriptTag(options)](#pageaddscripttagoptions) * [page.addScriptTag(options)](#pageaddscripttagoptions)
+ [page.addStyleTag(options)](#pageaddstyletagoptions) * [page.addStyleTag(options)](#pageaddstyletagoptions)
+ [page.authenticate(credentials)](#pageauthenticatecredentials) * [page.authenticate(credentials)](#pageauthenticatecredentials)
+ [page.click(selector[, options])](#pageclickselector-options) * [page.click(selector[, options])](#pageclickselector-options)
+ [page.close()](#pageclose) * [page.close()](#pageclose)
+ [page.content()](#pagecontent) * [page.content()](#pagecontent)
+ [page.cookies(...urls)](#pagecookiesurls) * [page.cookies(...urls)](#pagecookiesurls)
+ [page.deleteCookie(...cookies)](#pagedeletecookiecookies) * [page.deleteCookie(...cookies)](#pagedeletecookiecookies)
+ [page.emulate(options)](#pageemulateoptions) * [page.emulate(options)](#pageemulateoptions)
+ [page.emulateMedia(mediaType)](#pageemulatemediamediatype) * [page.emulateMedia(mediaType)](#pageemulatemediamediatype)
+ [page.evaluate(pageFunction, ...args)](#pageevaluatepagefunction-args) * [page.evaluate(pageFunction, ...args)](#pageevaluatepagefunction-args)
+ [page.evaluateHandle(pageFunction, ...args)](#pageevaluatehandlepagefunction-args) * [page.evaluateHandle(pageFunction, ...args)](#pageevaluatehandlepagefunction-args)
+ [page.evaluateOnNewDocument(pageFunction, ...args)](#pageevaluateonnewdocumentpagefunction-args) * [page.evaluateOnNewDocument(pageFunction, ...args)](#pageevaluateonnewdocumentpagefunction-args)
+ [page.exposeFunction(name, puppeteerFunction)](#pageexposefunctionname-puppeteerfunction) * [page.exposeFunction(name, puppeteerFunction)](#pageexposefunctionname-puppeteerfunction)
+ [page.focus(selector)](#pagefocusselector) * [page.focus(selector)](#pagefocusselector)
+ [page.frames()](#pageframes) * [page.frames()](#pageframes)
+ [page.getMetrics()](#pagegetmetrics) * [page.getMetrics()](#pagegetmetrics)
+ [page.goBack(options)](#pagegobackoptions) * [page.goBack(options)](#pagegobackoptions)
+ [page.goForward(options)](#pagegoforwardoptions) * [page.goForward(options)](#pagegoforwardoptions)
+ [page.goto(url, options)](#pagegotourl-options) * [page.goto(url, options)](#pagegotourl-options)
+ [page.hover(selector)](#pagehoverselector) * [page.hover(selector)](#pagehoverselector)
+ [page.keyboard](#pagekeyboard) * [page.keyboard](#pagekeyboard)
+ [page.mainFrame()](#pagemainframe) * [page.mainFrame()](#pagemainframe)
+ [page.mouse](#pagemouse) * [page.mouse](#pagemouse)
+ [page.pdf(options)](#pagepdfoptions) * [page.pdf(options)](#pagepdfoptions)
+ [page.queryObjects(prototypeHandle)](#pagequeryobjectsprototypehandle) * [page.queryObjects(prototypeHandle)](#pagequeryobjectsprototypehandle)
+ [page.reload(options)](#pagereloadoptions) * [page.reload(options)](#pagereloadoptions)
+ [page.screenshot([options])](#pagescreenshotoptions) * [page.screenshot([options])](#pagescreenshotoptions)
+ [page.select(selector, ...values)](#pageselectselector-values) * [page.select(selector, ...values)](#pageselectselector-values)
+ [page.setContent(html)](#pagesetcontenthtml) * [page.setContent(html)](#pagesetcontenthtml)
+ [page.setCookie(...cookies)](#pagesetcookiecookies) * [page.setCookie(...cookies)](#pagesetcookiecookies)
+ [page.setExtraHTTPHeaders(headers)](#pagesetextrahttpheadersheaders) * [page.setExtraHTTPHeaders(headers)](#pagesetextrahttpheadersheaders)
+ [page.setJavaScriptEnabled(enabled)](#pagesetjavascriptenabledenabled) * [page.setJavaScriptEnabled(enabled)](#pagesetjavascriptenabledenabled)
+ [page.setOfflineMode(enabled)](#pagesetofflinemodeenabled) * [page.setOfflineMode(enabled)](#pagesetofflinemodeenabled)
+ [page.setRequestInterceptionEnabled(value)](#pagesetrequestinterceptionenabledvalue) * [page.setRequestInterceptionEnabled(value)](#pagesetrequestinterceptionenabledvalue)
+ [page.setUserAgent(userAgent)](#pagesetuseragentuseragent) * [page.setUserAgent(userAgent)](#pagesetuseragentuseragent)
+ [page.setViewport(viewport)](#pagesetviewportviewport) * [page.setViewport(viewport)](#pagesetviewportviewport)
+ [page.tap(selector)](#pagetapselector) * [page.tap(selector)](#pagetapselector)
+ [page.title()](#pagetitle) * [page.title()](#pagetitle)
+ [page.touchscreen](#pagetouchscreen) * [page.touchscreen](#pagetouchscreen)
+ [page.tracing](#pagetracing) * [page.tracing](#pagetracing)
+ [page.type(selector, text[, options])](#pagetypeselector-text-options) * [page.type(selector, text[, options])](#pagetypeselector-text-options)
+ [page.url()](#pageurl) * [page.url()](#pageurl)
+ [page.viewport()](#pageviewport) * [page.viewport()](#pageviewport)
+ [page.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#pagewaitforselectororfunctionortimeout-options-args) * [page.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#pagewaitforselectororfunctionortimeout-options-args)
+ [page.waitForFunction(pageFunction[, options[, ...args]])](#pagewaitforfunctionpagefunction-options-args) * [page.waitForFunction(pageFunction[, options[, ...args]])](#pagewaitforfunctionpagefunction-options-args)
+ [page.waitForNavigation(options)](#pagewaitfornavigationoptions) * [page.waitForNavigation(options)](#pagewaitfornavigationoptions)
+ [page.waitForSelector(selector[, options])](#pagewaitforselectorselector-options) * [page.waitForSelector(selector[, options])](#pagewaitforselectorselector-options)
* [class: Keyboard](#class-keyboard) - [class: Keyboard](#class-keyboard)
+ [keyboard.down(key[, options])](#keyboarddownkey-options) * [keyboard.down(key[, options])](#keyboarddownkey-options)
+ [keyboard.press(key[, options])](#keyboardpresskey-options) * [keyboard.press(key[, options])](#keyboardpresskey-options)
+ [keyboard.sendCharacter(char)](#keyboardsendcharacterchar) * [keyboard.sendCharacter(char)](#keyboardsendcharacterchar)
+ [keyboard.type(text, options)](#keyboardtypetext-options) * [keyboard.type(text, options)](#keyboardtypetext-options)
+ [keyboard.up(key)](#keyboardupkey) * [keyboard.up(key)](#keyboardupkey)
* [class: Mouse](#class-mouse) - [class: Mouse](#class-mouse)
+ [mouse.click(x, y, [options])](#mouseclickx-y-options) * [mouse.click(x, y, [options])](#mouseclickx-y-options)
+ [mouse.down([options])](#mousedownoptions) * [mouse.down([options])](#mousedownoptions)
+ [mouse.move(x, y, [options])](#mousemovex-y-options) * [mouse.move(x, y, [options])](#mousemovex-y-options)
+ [mouse.up([options])](#mouseupoptions) * [mouse.up([options])](#mouseupoptions)
* [class: Touchscreen](#class-touchscreen) - [class: Touchscreen](#class-touchscreen)
+ [touchscreen.tap(x, y)](#touchscreentapx-y) * [touchscreen.tap(x, y)](#touchscreentapx-y)
* [class: Tracing](#class-tracing) - [class: Tracing](#class-tracing)
+ [tracing.start(options)](#tracingstartoptions) * [tracing.start(options)](#tracingstartoptions)
+ [tracing.stop()](#tracingstop) * [tracing.stop()](#tracingstop)
* [class: Dialog](#class-dialog) - [class: Dialog](#class-dialog)
+ [dialog.accept([promptText])](#dialogacceptprompttext) * [dialog.accept([promptText])](#dialogacceptprompttext)
+ [dialog.defaultValue()](#dialogdefaultvalue) * [dialog.defaultValue()](#dialogdefaultvalue)
+ [dialog.dismiss()](#dialogdismiss) * [dialog.dismiss()](#dialogdismiss)
+ [dialog.message()](#dialogmessage) * [dialog.message()](#dialogmessage)
+ [dialog.type](#dialogtype) * [dialog.type](#dialogtype)
* [class: ConsoleMessage](#class-consolemessage) - [class: ConsoleMessage](#class-consolemessage)
+ [consoleMessage.args](#consolemessageargs) * [consoleMessage.args](#consolemessageargs)
+ [consoleMessage.text](#consolemessagetext) * [consoleMessage.text](#consolemessagetext)
+ [consoleMessage.type](#consolemessagetype) * [consoleMessage.type](#consolemessagetype)
* [class: Frame](#class-frame) - [class: Frame](#class-frame)
+ [frame.$(selector)](#frameselector) * [frame.$(selector)](#frameselector)
+ [frame.$$(selector)](#frameselector) * [frame.$$(selector)](#frameselector)
+ [frame.$$eval(selector, pageFunction[, ...args])](#frameevalselector-pagefunction-args) * [frame.$$eval(selector, pageFunction[, ...args])](#frameevalselector-pagefunction-args)
+ [frame.$eval(selector, pageFunction[, ...args])](#frameevalselector-pagefunction-args) * [frame.$eval(selector, pageFunction[, ...args])](#frameevalselector-pagefunction-args)
+ [frame.addScriptTag(options)](#frameaddscripttagoptions) * [frame.addScriptTag(options)](#frameaddscripttagoptions)
+ [frame.addStyleTag(options)](#frameaddstyletagoptions) * [frame.addStyleTag(options)](#frameaddstyletagoptions)
+ [frame.childFrames()](#framechildframes) * [frame.childFrames()](#framechildframes)
+ [frame.evaluate(pageFunction, ...args)](#frameevaluatepagefunction-args) * [frame.evaluate(pageFunction, ...args)](#frameevaluatepagefunction-args)
+ [frame.executionContext()](#frameexecutioncontext) * [frame.executionContext()](#frameexecutioncontext)
+ [frame.isDetached()](#frameisdetached) * [frame.isDetached()](#frameisdetached)
+ [frame.name()](#framename) * [frame.name()](#framename)
+ [frame.parentFrame()](#frameparentframe) * [frame.parentFrame()](#frameparentframe)
+ [frame.title()](#frametitle) * [frame.title()](#frametitle)
+ [frame.url()](#frameurl) * [frame.url()](#frameurl)
+ [frame.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#framewaitforselectororfunctionortimeout-options-args) * [frame.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#framewaitforselectororfunctionortimeout-options-args)
+ [frame.waitForFunction(pageFunction[, options[, ...args]])](#framewaitforfunctionpagefunction-options-args) * [frame.waitForFunction(pageFunction[, options[, ...args]])](#framewaitforfunctionpagefunction-options-args)
+ [frame.waitForSelector(selector[, options])](#framewaitforselectorselector-options) * [frame.waitForSelector(selector[, options])](#framewaitforselectorselector-options)
* [class: ExecutionContext](#class-executioncontext) - [class: ExecutionContext](#class-executioncontext)
+ [executionContext.evaluate(pageFunction, ...args)](#executioncontextevaluatepagefunction-args) * [executionContext.evaluate(pageFunction, ...args)](#executioncontextevaluatepagefunction-args)
+ [executionContext.evaluateHandle(pageFunction, ...args)](#executioncontextevaluatehandlepagefunction-args) * [executionContext.evaluateHandle(pageFunction, ...args)](#executioncontextevaluatehandlepagefunction-args)
+ [executionContext.queryObjects(prototypeHandle)](#executioncontextqueryobjectsprototypehandle) * [executionContext.queryObjects(prototypeHandle)](#executioncontextqueryobjectsprototypehandle)
* [class: JSHandle](#class-jshandle) - [class: JSHandle](#class-jshandle)
+ [jsHandle.asElement()](#jshandleaselement) * [jsHandle.asElement()](#jshandleaselement)
+ [jsHandle.dispose()](#jshandledispose) * [jsHandle.dispose()](#jshandledispose)
+ [jsHandle.executionContext()](#jshandleexecutioncontext) * [jsHandle.executionContext()](#jshandleexecutioncontext)
+ [jsHandle.getProperties()](#jshandlegetproperties) * [jsHandle.getProperties()](#jshandlegetproperties)
+ [jsHandle.getProperty(propertyName)](#jshandlegetpropertypropertyname) * [jsHandle.getProperty(propertyName)](#jshandlegetpropertypropertyname)
+ [jsHandle.jsonValue()](#jshandlejsonvalue) * [jsHandle.jsonValue()](#jshandlejsonvalue)
* [class: ElementHandle](#class-elementhandle) - [class: ElementHandle](#class-elementhandle)
+ [elementHandle.asElement()](#elementhandleaselement) * [elementHandle.asElement()](#elementhandleaselement)
+ [elementHandle.boundingBox()](#elementhandleboundingbox) * [elementHandle.boundingBox()](#elementhandleboundingbox)
+ [elementHandle.click([options])](#elementhandleclickoptions) * [elementHandle.click([options])](#elementhandleclickoptions)
+ [elementHandle.dispose()](#elementhandledispose) * [elementHandle.dispose()](#elementhandledispose)
+ [elementHandle.executionContext()](#elementhandleexecutioncontext) * [elementHandle.executionContext()](#elementhandleexecutioncontext)
+ [elementHandle.focus()](#elementhandlefocus) * [elementHandle.focus()](#elementhandlefocus)
+ [elementHandle.getProperties()](#elementhandlegetproperties) * [elementHandle.getProperties()](#elementhandlegetproperties)
+ [elementHandle.getProperty(propertyName)](#elementhandlegetpropertypropertyname) * [elementHandle.getProperty(propertyName)](#elementhandlegetpropertypropertyname)
+ [elementHandle.hover()](#elementhandlehover) * [elementHandle.hover()](#elementhandlehover)
+ [elementHandle.jsonValue()](#elementhandlejsonvalue) * [elementHandle.jsonValue()](#elementhandlejsonvalue)
+ [elementHandle.press(key[, options])](#elementhandlepresskey-options) * [elementHandle.press(key[, options])](#elementhandlepresskey-options)
+ [elementHandle.screenshot([options])](#elementhandlescreenshotoptions) * [elementHandle.screenshot([options])](#elementhandlescreenshotoptions)
+ [elementHandle.tap()](#elementhandletap) * [elementHandle.tap()](#elementhandletap)
+ [elementHandle.toString()](#elementhandletostring) * [elementHandle.toString()](#elementhandletostring)
+ [elementHandle.type(text[, options])](#elementhandletypetext-options) * [elementHandle.type(text[, options])](#elementhandletypetext-options)
+ [elementHandle.uploadFile(...filePaths)](#elementhandleuploadfilefilepaths) * [elementHandle.uploadFile(...filePaths)](#elementhandleuploadfilefilepaths)
* [class: Request](#class-request) - [class: Request](#class-request)
+ [request.abort()](#requestabort) * [request.abort()](#requestabort)
+ [request.continue([overrides])](#requestcontinueoverrides) * [request.continue([overrides])](#requestcontinueoverrides)
+ [request.headers](#requestheaders) * [request.headers](#requestheaders)
+ [request.method](#requestmethod) * [request.method](#requestmethod)
+ [request.postData](#requestpostdata) * [request.postData](#requestpostdata)
+ [request.resourceType](#requestresourcetype) * [request.resourceType](#requestresourcetype)
+ [request.response()](#requestresponse) * [request.response()](#requestresponse)
+ [request.url](#requesturl) * [request.url](#requesturl)
* [class: Response](#class-response) - [class: Response](#class-response)
+ [response.buffer()](#responsebuffer) * [response.buffer()](#responsebuffer)
+ [response.headers](#responseheaders) * [response.headers](#responseheaders)
+ [response.json()](#responsejson) * [response.json()](#responsejson)
+ [response.ok](#responseok) * [response.ok](#responseok)
+ [response.request()](#responserequest) * [response.request()](#responserequest)
+ [response.status](#responsestatus) * [response.status](#responsestatus)
+ [response.text()](#responsetext) * [response.text()](#responsetext)
+ [response.url](#responseurl) * [response.url](#responseurl)
<!-- tocstop --> <!-- tocstop -->
## Puppeteer ### Overview
Puppeteer is a Node library which provides a high-level API to control Chromium over the DevTools Protocol. Puppeteer is a Node library which provides a high-level API to control Chromium over the DevTools Protocol.
Puppeteer API is hierarchical and mirrors browser objects. On the following diagram, faded entities are not currently represented in Puppeteer.
![puppeteer overview](https://user-images.githubusercontent.com/746130/31592143-089f6f9a-b1db-11e7-9a20-16b7fc754fa1.png)
- [`Puppeteer`](#class-puppeteer) communicates with browser using [devtools protocol](https://chromedevtools.github.io/devtools-protocol/).
- [`Browser`](#class-browser) instance owns multiple pages.
- [`Page`](#class-page) has at least one frame: main frame. There might be other frames created by [iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) or [frame](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/frame) tags.
- [`Frame`](#class-frame) has at least one execution context - default execution context - where frame's javascript is executed. Frame might have additional execution contexts associated with [extensions](https://developer.chrome.com/extensions).
(Diagram source: [link](https://docs.google.com/drawings/d/1Q_AM6KYs9kbyLZF-Lpp5mtpAWth73Cq8IKCsWYgi8MM/edit?usp=sharing))
### Environment Variables ### Environment Variables
Puppeteer looks for certain [environment variables](https://en.wikipedia.org/wiki/Environment_variable) to aid its operations. These variables can either be set in the environment or in the [npm config](https://docs.npmjs.com/cli/config). Puppeteer looks for certain [environment variables](https://en.wikipedia.org/wiki/Environment_variable) to aid its operations. These variables can either be set in the environment or in the [npm config](https://docs.npmjs.com/cli/config).