From e7eb7b3ccbf5ef47419c99dc236e62a4272a7dee Mon Sep 17 00:00:00 2001 From: Andrey Lushnikov Date: Mon, 16 Oct 2017 11:07:06 -0700 Subject: [PATCH] docs(api): add hierarchical diagram (#1040) --- docs/api.md | 348 +++++++++++++++++++++++++++------------------------- 1 file changed, 180 insertions(+), 168 deletions(-) diff --git a/docs/api.md b/docs/api.md index 2f81dbbb11c..16207782871 100644 --- a/docs/api.md +++ b/docs/api.md @@ -6,180 +6,192 @@ -- [Puppeteer](#puppeteer) - * [Environment Variables](#environment-variables) - * [class: Puppeteer](#class-puppeteer) - + [puppeteer.connect(options)](#puppeteerconnectoptions) - + [puppeteer.executablePath()](#puppeteerexecutablepath) - + [puppeteer.launch([options])](#puppeteerlaunchoptions) - * [class: Browser](#class-browser) - + [browser.close()](#browserclose) - + [browser.newPage()](#browsernewpage) - + [browser.version()](#browserversion) - + [browser.wsEndpoint()](#browserwsendpoint) - * [class: Page](#class-page) - + [event: 'console'](#event-console) - + [event: 'dialog'](#event-dialog) - + [event: 'error'](#event-error) - + [event: 'frameattached'](#event-frameattached) - + [event: 'framedetached'](#event-framedetached) - + [event: 'framenavigated'](#event-framenavigated) - + [event: 'load'](#event-load) - + [event: 'metrics'](#event-metrics) - + [event: 'pageerror'](#event-pageerror) - + [event: 'request'](#event-request) - + [event: 'requestfailed'](#event-requestfailed) - + [event: 'requestfinished'](#event-requestfinished) - + [event: 'response'](#event-response) - + [page.$(selector)](#pageselector) - + [page.$$(selector)](#pageselector) - + [page.$$eval(selector, pageFunction[, ...args])](#pageevalselector-pagefunction-args) - + [page.$eval(selector, pageFunction[, ...args])](#pageevalselector-pagefunction-args) - + [page.addScriptTag(options)](#pageaddscripttagoptions) - + [page.addStyleTag(options)](#pageaddstyletagoptions) - + [page.authenticate(credentials)](#pageauthenticatecredentials) - + [page.click(selector[, options])](#pageclickselector-options) - + [page.close()](#pageclose) - + [page.content()](#pagecontent) - + [page.cookies(...urls)](#pagecookiesurls) - + [page.deleteCookie(...cookies)](#pagedeletecookiecookies) - + [page.emulate(options)](#pageemulateoptions) - + [page.emulateMedia(mediaType)](#pageemulatemediamediatype) - + [page.evaluate(pageFunction, ...args)](#pageevaluatepagefunction-args) - + [page.evaluateHandle(pageFunction, ...args)](#pageevaluatehandlepagefunction-args) - + [page.evaluateOnNewDocument(pageFunction, ...args)](#pageevaluateonnewdocumentpagefunction-args) - + [page.exposeFunction(name, puppeteerFunction)](#pageexposefunctionname-puppeteerfunction) - + [page.focus(selector)](#pagefocusselector) - + [page.frames()](#pageframes) - + [page.getMetrics()](#pagegetmetrics) - + [page.goBack(options)](#pagegobackoptions) - + [page.goForward(options)](#pagegoforwardoptions) - + [page.goto(url, options)](#pagegotourl-options) - + [page.hover(selector)](#pagehoverselector) - + [page.keyboard](#pagekeyboard) - + [page.mainFrame()](#pagemainframe) - + [page.mouse](#pagemouse) - + [page.pdf(options)](#pagepdfoptions) - + [page.queryObjects(prototypeHandle)](#pagequeryobjectsprototypehandle) - + [page.reload(options)](#pagereloadoptions) - + [page.screenshot([options])](#pagescreenshotoptions) - + [page.select(selector, ...values)](#pageselectselector-values) - + [page.setContent(html)](#pagesetcontenthtml) - + [page.setCookie(...cookies)](#pagesetcookiecookies) - + [page.setExtraHTTPHeaders(headers)](#pagesetextrahttpheadersheaders) - + [page.setJavaScriptEnabled(enabled)](#pagesetjavascriptenabledenabled) - + [page.setOfflineMode(enabled)](#pagesetofflinemodeenabled) - + [page.setRequestInterceptionEnabled(value)](#pagesetrequestinterceptionenabledvalue) - + [page.setUserAgent(userAgent)](#pagesetuseragentuseragent) - + [page.setViewport(viewport)](#pagesetviewportviewport) - + [page.tap(selector)](#pagetapselector) - + [page.title()](#pagetitle) - + [page.touchscreen](#pagetouchscreen) - + [page.tracing](#pagetracing) - + [page.type(selector, text[, options])](#pagetypeselector-text-options) - + [page.url()](#pageurl) - + [page.viewport()](#pageviewport) - + [page.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#pagewaitforselectororfunctionortimeout-options-args) - + [page.waitForFunction(pageFunction[, options[, ...args]])](#pagewaitforfunctionpagefunction-options-args) - + [page.waitForNavigation(options)](#pagewaitfornavigationoptions) - + [page.waitForSelector(selector[, options])](#pagewaitforselectorselector-options) - * [class: Keyboard](#class-keyboard) - + [keyboard.down(key[, options])](#keyboarddownkey-options) - + [keyboard.press(key[, options])](#keyboardpresskey-options) - + [keyboard.sendCharacter(char)](#keyboardsendcharacterchar) - + [keyboard.type(text, options)](#keyboardtypetext-options) - + [keyboard.up(key)](#keyboardupkey) - * [class: Mouse](#class-mouse) - + [mouse.click(x, y, [options])](#mouseclickx-y-options) - + [mouse.down([options])](#mousedownoptions) - + [mouse.move(x, y, [options])](#mousemovex-y-options) - + [mouse.up([options])](#mouseupoptions) - * [class: Touchscreen](#class-touchscreen) - + [touchscreen.tap(x, y)](#touchscreentapx-y) - * [class: Tracing](#class-tracing) - + [tracing.start(options)](#tracingstartoptions) - + [tracing.stop()](#tracingstop) - * [class: Dialog](#class-dialog) - + [dialog.accept([promptText])](#dialogacceptprompttext) - + [dialog.defaultValue()](#dialogdefaultvalue) - + [dialog.dismiss()](#dialogdismiss) - + [dialog.message()](#dialogmessage) - + [dialog.type](#dialogtype) - * [class: ConsoleMessage](#class-consolemessage) - + [consoleMessage.args](#consolemessageargs) - + [consoleMessage.text](#consolemessagetext) - + [consoleMessage.type](#consolemessagetype) - * [class: Frame](#class-frame) - + [frame.$(selector)](#frameselector) - + [frame.$$(selector)](#frameselector) - + [frame.$$eval(selector, pageFunction[, ...args])](#frameevalselector-pagefunction-args) - + [frame.$eval(selector, pageFunction[, ...args])](#frameevalselector-pagefunction-args) - + [frame.addScriptTag(options)](#frameaddscripttagoptions) - + [frame.addStyleTag(options)](#frameaddstyletagoptions) - + [frame.childFrames()](#framechildframes) - + [frame.evaluate(pageFunction, ...args)](#frameevaluatepagefunction-args) - + [frame.executionContext()](#frameexecutioncontext) - + [frame.isDetached()](#frameisdetached) - + [frame.name()](#framename) - + [frame.parentFrame()](#frameparentframe) - + [frame.title()](#frametitle) - + [frame.url()](#frameurl) - + [frame.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#framewaitforselectororfunctionortimeout-options-args) - + [frame.waitForFunction(pageFunction[, options[, ...args]])](#framewaitforfunctionpagefunction-options-args) - + [frame.waitForSelector(selector[, options])](#framewaitforselectorselector-options) - * [class: ExecutionContext](#class-executioncontext) - + [executionContext.evaluate(pageFunction, ...args)](#executioncontextevaluatepagefunction-args) - + [executionContext.evaluateHandle(pageFunction, ...args)](#executioncontextevaluatehandlepagefunction-args) - + [executionContext.queryObjects(prototypeHandle)](#executioncontextqueryobjectsprototypehandle) - * [class: JSHandle](#class-jshandle) - + [jsHandle.asElement()](#jshandleaselement) - + [jsHandle.dispose()](#jshandledispose) - + [jsHandle.executionContext()](#jshandleexecutioncontext) - + [jsHandle.getProperties()](#jshandlegetproperties) - + [jsHandle.getProperty(propertyName)](#jshandlegetpropertypropertyname) - + [jsHandle.jsonValue()](#jshandlejsonvalue) - * [class: ElementHandle](#class-elementhandle) - + [elementHandle.asElement()](#elementhandleaselement) - + [elementHandle.boundingBox()](#elementhandleboundingbox) - + [elementHandle.click([options])](#elementhandleclickoptions) - + [elementHandle.dispose()](#elementhandledispose) - + [elementHandle.executionContext()](#elementhandleexecutioncontext) - + [elementHandle.focus()](#elementhandlefocus) - + [elementHandle.getProperties()](#elementhandlegetproperties) - + [elementHandle.getProperty(propertyName)](#elementhandlegetpropertypropertyname) - + [elementHandle.hover()](#elementhandlehover) - + [elementHandle.jsonValue()](#elementhandlejsonvalue) - + [elementHandle.press(key[, options])](#elementhandlepresskey-options) - + [elementHandle.screenshot([options])](#elementhandlescreenshotoptions) - + [elementHandle.tap()](#elementhandletap) - + [elementHandle.toString()](#elementhandletostring) - + [elementHandle.type(text[, options])](#elementhandletypetext-options) - + [elementHandle.uploadFile(...filePaths)](#elementhandleuploadfilefilepaths) - * [class: Request](#class-request) - + [request.abort()](#requestabort) - + [request.continue([overrides])](#requestcontinueoverrides) - + [request.headers](#requestheaders) - + [request.method](#requestmethod) - + [request.postData](#requestpostdata) - + [request.resourceType](#requestresourcetype) - + [request.response()](#requestresponse) - + [request.url](#requesturl) - * [class: Response](#class-response) - + [response.buffer()](#responsebuffer) - + [response.headers](#responseheaders) - + [response.json()](#responsejson) - + [response.ok](#responseok) - + [response.request()](#responserequest) - + [response.status](#responsestatus) - + [response.text()](#responsetext) - + [response.url](#responseurl) +- [Overview](#overview) +- [Environment Variables](#environment-variables) +- [class: Puppeteer](#class-puppeteer) + * [puppeteer.connect(options)](#puppeteerconnectoptions) + * [puppeteer.executablePath()](#puppeteerexecutablepath) + * [puppeteer.launch([options])](#puppeteerlaunchoptions) +- [class: Browser](#class-browser) + * [browser.close()](#browserclose) + * [browser.newPage()](#browsernewpage) + * [browser.version()](#browserversion) + * [browser.wsEndpoint()](#browserwsendpoint) +- [class: Page](#class-page) + * [event: 'console'](#event-console) + * [event: 'dialog'](#event-dialog) + * [event: 'error'](#event-error) + * [event: 'frameattached'](#event-frameattached) + * [event: 'framedetached'](#event-framedetached) + * [event: 'framenavigated'](#event-framenavigated) + * [event: 'load'](#event-load) + * [event: 'metrics'](#event-metrics) + * [event: 'pageerror'](#event-pageerror) + * [event: 'request'](#event-request) + * [event: 'requestfailed'](#event-requestfailed) + * [event: 'requestfinished'](#event-requestfinished) + * [event: 'response'](#event-response) + * [page.$(selector)](#pageselector) + * [page.$$(selector)](#pageselector) + * [page.$$eval(selector, pageFunction[, ...args])](#pageevalselector-pagefunction-args) + * [page.$eval(selector, pageFunction[, ...args])](#pageevalselector-pagefunction-args) + * [page.addScriptTag(options)](#pageaddscripttagoptions) + * [page.addStyleTag(options)](#pageaddstyletagoptions) + * [page.authenticate(credentials)](#pageauthenticatecredentials) + * [page.click(selector[, options])](#pageclickselector-options) + * [page.close()](#pageclose) + * [page.content()](#pagecontent) + * [page.cookies(...urls)](#pagecookiesurls) + * [page.deleteCookie(...cookies)](#pagedeletecookiecookies) + * [page.emulate(options)](#pageemulateoptions) + * [page.emulateMedia(mediaType)](#pageemulatemediamediatype) + * [page.evaluate(pageFunction, ...args)](#pageevaluatepagefunction-args) + * [page.evaluateHandle(pageFunction, ...args)](#pageevaluatehandlepagefunction-args) + * [page.evaluateOnNewDocument(pageFunction, ...args)](#pageevaluateonnewdocumentpagefunction-args) + * [page.exposeFunction(name, puppeteerFunction)](#pageexposefunctionname-puppeteerfunction) + * [page.focus(selector)](#pagefocusselector) + * [page.frames()](#pageframes) + * [page.getMetrics()](#pagegetmetrics) + * [page.goBack(options)](#pagegobackoptions) + * [page.goForward(options)](#pagegoforwardoptions) + * [page.goto(url, options)](#pagegotourl-options) + * [page.hover(selector)](#pagehoverselector) + * [page.keyboard](#pagekeyboard) + * [page.mainFrame()](#pagemainframe) + * [page.mouse](#pagemouse) + * [page.pdf(options)](#pagepdfoptions) + * [page.queryObjects(prototypeHandle)](#pagequeryobjectsprototypehandle) + * [page.reload(options)](#pagereloadoptions) + * [page.screenshot([options])](#pagescreenshotoptions) + * [page.select(selector, ...values)](#pageselectselector-values) + * [page.setContent(html)](#pagesetcontenthtml) + * [page.setCookie(...cookies)](#pagesetcookiecookies) + * [page.setExtraHTTPHeaders(headers)](#pagesetextrahttpheadersheaders) + * [page.setJavaScriptEnabled(enabled)](#pagesetjavascriptenabledenabled) + * [page.setOfflineMode(enabled)](#pagesetofflinemodeenabled) + * [page.setRequestInterceptionEnabled(value)](#pagesetrequestinterceptionenabledvalue) + * [page.setUserAgent(userAgent)](#pagesetuseragentuseragent) + * [page.setViewport(viewport)](#pagesetviewportviewport) + * [page.tap(selector)](#pagetapselector) + * [page.title()](#pagetitle) + * [page.touchscreen](#pagetouchscreen) + * [page.tracing](#pagetracing) + * [page.type(selector, text[, options])](#pagetypeselector-text-options) + * [page.url()](#pageurl) + * [page.viewport()](#pageviewport) + * [page.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#pagewaitforselectororfunctionortimeout-options-args) + * [page.waitForFunction(pageFunction[, options[, ...args]])](#pagewaitforfunctionpagefunction-options-args) + * [page.waitForNavigation(options)](#pagewaitfornavigationoptions) + * [page.waitForSelector(selector[, options])](#pagewaitforselectorselector-options) +- [class: Keyboard](#class-keyboard) + * [keyboard.down(key[, options])](#keyboarddownkey-options) + * [keyboard.press(key[, options])](#keyboardpresskey-options) + * [keyboard.sendCharacter(char)](#keyboardsendcharacterchar) + * [keyboard.type(text, options)](#keyboardtypetext-options) + * [keyboard.up(key)](#keyboardupkey) +- [class: Mouse](#class-mouse) + * [mouse.click(x, y, [options])](#mouseclickx-y-options) + * [mouse.down([options])](#mousedownoptions) + * [mouse.move(x, y, [options])](#mousemovex-y-options) + * [mouse.up([options])](#mouseupoptions) +- [class: Touchscreen](#class-touchscreen) + * [touchscreen.tap(x, y)](#touchscreentapx-y) +- [class: Tracing](#class-tracing) + * [tracing.start(options)](#tracingstartoptions) + * [tracing.stop()](#tracingstop) +- [class: Dialog](#class-dialog) + * [dialog.accept([promptText])](#dialogacceptprompttext) + * [dialog.defaultValue()](#dialogdefaultvalue) + * [dialog.dismiss()](#dialogdismiss) + * [dialog.message()](#dialogmessage) + * [dialog.type](#dialogtype) +- [class: ConsoleMessage](#class-consolemessage) + * [consoleMessage.args](#consolemessageargs) + * [consoleMessage.text](#consolemessagetext) + * [consoleMessage.type](#consolemessagetype) +- [class: Frame](#class-frame) + * [frame.$(selector)](#frameselector) + * [frame.$$(selector)](#frameselector) + * [frame.$$eval(selector, pageFunction[, ...args])](#frameevalselector-pagefunction-args) + * [frame.$eval(selector, pageFunction[, ...args])](#frameevalselector-pagefunction-args) + * [frame.addScriptTag(options)](#frameaddscripttagoptions) + * [frame.addStyleTag(options)](#frameaddstyletagoptions) + * [frame.childFrames()](#framechildframes) + * [frame.evaluate(pageFunction, ...args)](#frameevaluatepagefunction-args) + * [frame.executionContext()](#frameexecutioncontext) + * [frame.isDetached()](#frameisdetached) + * [frame.name()](#framename) + * [frame.parentFrame()](#frameparentframe) + * [frame.title()](#frametitle) + * [frame.url()](#frameurl) + * [frame.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#framewaitforselectororfunctionortimeout-options-args) + * [frame.waitForFunction(pageFunction[, options[, ...args]])](#framewaitforfunctionpagefunction-options-args) + * [frame.waitForSelector(selector[, options])](#framewaitforselectorselector-options) +- [class: ExecutionContext](#class-executioncontext) + * [executionContext.evaluate(pageFunction, ...args)](#executioncontextevaluatepagefunction-args) + * [executionContext.evaluateHandle(pageFunction, ...args)](#executioncontextevaluatehandlepagefunction-args) + * [executionContext.queryObjects(prototypeHandle)](#executioncontextqueryobjectsprototypehandle) +- [class: JSHandle](#class-jshandle) + * [jsHandle.asElement()](#jshandleaselement) + * [jsHandle.dispose()](#jshandledispose) + * [jsHandle.executionContext()](#jshandleexecutioncontext) + * [jsHandle.getProperties()](#jshandlegetproperties) + * [jsHandle.getProperty(propertyName)](#jshandlegetpropertypropertyname) + * [jsHandle.jsonValue()](#jshandlejsonvalue) +- [class: ElementHandle](#class-elementhandle) + * [elementHandle.asElement()](#elementhandleaselement) + * [elementHandle.boundingBox()](#elementhandleboundingbox) + * [elementHandle.click([options])](#elementhandleclickoptions) + * [elementHandle.dispose()](#elementhandledispose) + * [elementHandle.executionContext()](#elementhandleexecutioncontext) + * [elementHandle.focus()](#elementhandlefocus) + * [elementHandle.getProperties()](#elementhandlegetproperties) + * [elementHandle.getProperty(propertyName)](#elementhandlegetpropertypropertyname) + * [elementHandle.hover()](#elementhandlehover) + * [elementHandle.jsonValue()](#elementhandlejsonvalue) + * [elementHandle.press(key[, options])](#elementhandlepresskey-options) + * [elementHandle.screenshot([options])](#elementhandlescreenshotoptions) + * [elementHandle.tap()](#elementhandletap) + * [elementHandle.toString()](#elementhandletostring) + * [elementHandle.type(text[, options])](#elementhandletypetext-options) + * [elementHandle.uploadFile(...filePaths)](#elementhandleuploadfilefilepaths) +- [class: Request](#class-request) + * [request.abort()](#requestabort) + * [request.continue([overrides])](#requestcontinueoverrides) + * [request.headers](#requestheaders) + * [request.method](#requestmethod) + * [request.postData](#requestpostdata) + * [request.resourceType](#requestresourcetype) + * [request.response()](#requestresponse) + * [request.url](#requesturl) +- [class: Response](#class-response) + * [response.buffer()](#responsebuffer) + * [response.headers](#responseheaders) + * [response.json()](#responsejson) + * [response.ok](#responseok) + * [response.request()](#responserequest) + * [response.status](#responsestatus) + * [response.text()](#responsetext) + * [response.url](#responseurl) -## Puppeteer +### Overview 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 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).