github/puppeteer
0
0
Fork 0
mirror of https://github.com/puppeteer/puppeteer synced 2024-06-14 14:02:48 +00:00
Code Issues Packages Projects Releases Wiki Activity
57fa690724
puppeteer/docs/api.md

2705 lines
127 KiB
Markdown
Raw Normal View History

chore: bump version to v1.2.0-post (#2205)
2018-03-16 18:01:49 +00:00
##### Released APIs: [v1.2.0](https://github.com/GoogleChrome/puppeteer/blob/v1.2.0/docs/api.md) | [v1.1.1](https://github.com/GoogleChrome/puppeteer/blob/v1.1.1/docs/api.md) | [v1.1.0](https://github.com/GoogleChrome/puppeteer/blob/v1.1.0/docs/api.md) | [v1.0.0](https://github.com/GoogleChrome/puppeteer/blob/v1.0.0/docs/api.md) | [v0.13.0](https://github.com/GoogleChrome/puppeteer/blob/v0.13.0/docs/api.md) | [v0.12.0](https://github.com/GoogleChrome/puppeteer/blob/v0.12.0/docs/api.md) | [v0.11.0](https://github.com/GoogleChrome/puppeteer/blob/v0.11.0/docs/api.md) | [v0.10.2](https://github.com/GoogleChrome/puppeteer/blob/v0.10.2/docs/api.md) | [v0.10.1](https://github.com/GoogleChrome/puppeteer/blob/v0.10.1/docs/api.md) | [v0.10.0](https://github.com/GoogleChrome/puppeteer/blob/v0.10.0/docs/api.md) | [v0.9.0](https://github.com/GoogleChrome/puppeteer/blob/v0.9.0/docs/api.md)
# Puppeteer API v<!-- GEN:version -->1.2.0-post<!-- GEN:stop--> \*\*NOT RELEASED\*\*
> **NOTE** This version of API **is expected to be released** on **April 12, 2018**.
[doc] Add reference to released API
2017-08-23 20:44:44 +00:00
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.
2017-06-13 07:28:29 +00:00
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
##### Table of Contents
Implement documentation linter (#47) This patch implements documentation linter, which leaves under `test/doclint` folder. The documentation linter works like this: 1. Parse javascript source code with esprima and construct a "documentation" out of source code 2. Generate HTML out of `api.md` and traverse the HTML with puppeteer. 3. Make sure javascript aligns nicely with HTML The documentation linter adds the following commands: - `yarn doc` - to test that documentation covers all the relevant apis - `yarn generate-toc` - to update the table-of-contents for the `api.md`
2017-07-07 16:36:45 +00:00
<!-- toc -->
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
- [Overview](#overview)
- [Environment Variables](#environment-variables)
- [class: Puppeteer](#class-puppeteer)
* [puppeteer.connect(options)](#puppeteerconnectoptions)
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
* [puppeteer.createBrowserFetcher([options])](#puppeteercreatebrowserfetcheroptions)
feat(Launcher): allow the default arguments to be overridden (#1623) This patch: - adds `puppeteer.defaultArgs()` method to get default arguments that are used to launch chrome - adds `ignoreDefaultArgs` option to `puppeteer.launch` to avoid using default puppeteer arguments Fixes #872
2017-12-20 01:51:21 +00:00
* [puppeteer.defaultArgs()](#puppeteerdefaultargs)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [puppeteer.executablePath()](#puppeteerexecutablepath)
* [puppeteer.launch([options])](#puppeteerlaunchoptions)
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
- [class: BrowserFetcher](#class-browserfetcher)
* [browserFetcher.canDownload(revision)](#browserfetchercandownloadrevision)
* [browserFetcher.download(revision[, progressCallback])](#browserfetcherdownloadrevision-progresscallback)
* [browserFetcher.localRevisions()](#browserfetcherlocalrevisions)
* [browserFetcher.platform()](#browserfetcherplatform)
* [browserFetcher.remove(revision)](#browserfetcherremoverevision)
* [browserFetcher.revisionInfo(revision)](#browserfetcherrevisioninforevision)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
- [class: Browser](#class-browser)
feat(browser): add browser.disconnected event (#960) This patch adds a 'disconnected' event for the browser. The event is issued when the "browser" loses connection to the chrome process. References #952
2017-11-04 01:46:17 +00:00
* [event: 'disconnected'](#event-disconnected)
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
* [event: 'targetchanged'](#event-targetchanged)
* [event: 'targetcreated'](#event-targetcreated)
* [event: 'targetdestroyed'](#event-targetdestroyed)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [browser.close()](#browserclose)
feat(Browser): make browser.close() to always terminate remote browser This patch: - changes `browser.close` to terminate browser. - introduces new `browser.disconnect` to disconnect from a browser without closing it This patch: fixes #918, fixes #989 BREAKING CHANGE: `browser.close()` will always close a browser, even if it was initialized with `puppeteer.connect`. To disconnect from a remote browser, use `browser.disconnect()` instead.
2017-10-17 22:35:00 +00:00
* [browser.disconnect()](#browserdisconnect)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [browser.newPage()](#browsernewpage)
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
* [browser.pages()](#browserpages)
feat(Browser): introduce browser.process() variable (#1581) This patch adds a `browser.process()` getter to expose the child process with running browser. Fixes #1539.
2017-12-11 20:11:12 +00:00
* [browser.process()](#browserprocess)
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
* [browser.targets()](#browsertargets)
feat: introduce browser.userAgent() (#1716) The patch introduces browser.userAgent() method to retrieve default browser user agent. Fixes #1706.
2018-01-05 18:14:30 +00:00
* [browser.userAgent()](#browseruseragent)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [browser.version()](#browserversion)
* [browser.wsEndpoint()](#browserwsendpoint)
- [class: Page](#class-page)
feat(Page): page 'close' event (#2232) This patch adds 'page.close' event. References #952.
2018-03-28 20:11:51 +00:00
* [event: 'close'](#event-close)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [event: 'console'](#event-console)
* [event: 'dialog'](#event-dialog)
feat: add Page.Events.DOMContentLoaded (#1730) Fixes #1580
2018-01-17 07:22:44 +00:00
* [event: 'domcontentloaded'](#event-domcontentloaded)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [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)
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
* [page.$x(expression)](#pagexexpression)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.addScriptTag(options)](#pageaddscripttagoptions)
* [page.addStyleTag(options)](#pageaddstyletagoptions)
* [page.authenticate(credentials)](#pageauthenticatecredentials)
feat(Page): introduce Page bringToFront method (#1252) This patch introduces Page.bringToFront method to activate tabs. Fixes #1244
2017-11-07 21:17:36 +00:00
* [page.bringToFront()](#pagebringtofront)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.click(selector[, options])](#pageclickselector-options)
* [page.close()](#pageclose)
* [page.content()](#pagecontent)
* [page.cookies(...urls)](#pagecookiesurls)
feat: Implement JavaScript Coverage (#1673) This patch introduces a new `page.coverage` namespace with two methods: - `page.coverage.startJSCoverage` to initiate JavaScript coverage recording - `page.coverage.stopJSCoverage` to stop JavaScript coverage and get results
2018-01-03 03:53:53 +00:00
* [page.coverage](#pagecoverage)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [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.goBack(options)](#pagegobackoptions)
* [page.goForward(options)](#pagegoforwardoptions)
* [page.goto(url, options)](#pagegotourl-options)
* [page.hover(selector)](#pagehoverselector)
* [page.keyboard](#pagekeyboard)
* [page.mainFrame()](#pagemainframe)
feat(Page): rename Page.getMetrics into Page.metrics (#1240) BREAKING CHANGE: method page.getMetrics() got renamed into page.metrics().
2017-11-01 20:39:31 +00:00
* [page.metrics()](#pagemetrics)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [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)
feat(Page): introduce Page.setBypassCSP (#2324) This patch introduces `page.setBypassCSP` method that allows clients to ignore Content-Security-Policy for a given page. Fixes #1229.
2018-04-06 23:35:50 +00:00
* [page.setBypassCSP(enabled)](#pagesetbypasscspenabled)
feat(Page): add `setCacheEnabled(enabled)` to Page object (#1609) This change adds in the `Page.setCacheEnabled(enabled)` method to toggle ignoring cache for each request. Fixes #1556.
2018-02-08 05:58:48 +00:00
* [page.setCacheEnabled(enabled)](#pagesetcacheenabledenabled)
Revert "feat(Page): teach Page.setContent to wait for resources to load (#1152)" (#1312) This reverts commit 80ee46942908054dea3bc14e6505bc12718e0b2d. Lifecycle events are not ready yet to support the setContent scenario. The prerequisite for this is https://chromium-review.googlesource.com/c/chromium/src/+/747805 that might not land soon due to technical concerns.
2017-11-07 22:18:05 +00:00
* [page.setContent(html)](#pagesetcontenthtml)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.setCookie(...cookies)](#pagesetcookiecookies)
feat(Page): Add global navigation timeout setting (#1728) This patch introduces `page.setDefaultNavigationTimeout` method to override the default 30 seconds navigation timeout. Fixes #1514
2018-01-10 21:04:01 +00:00
* [page.setDefaultNavigationTimeout(timeout)](#pagesetdefaultnavigationtimeouttimeout)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.setExtraHTTPHeaders(headers)](#pagesetextrahttpheadersheaders)
* [page.setJavaScriptEnabled(enabled)](#pagesetjavascriptenabledenabled)
* [page.setOfflineMode(enabled)](#pagesetofflinemodeenabled)
feat(Chromium): Roll chromium to r511134 (#1153) This roll includes: - crrev.com/510651 that changes request interception methods in protocol - s/Page.setRequestInterceptionEnabled/Page.setRequestInterception BREAKING CHANGE Page.setRequestInterceptionEnabled is renamed into Page.setRequestInterception.
2017-10-24 21:45:03 +00:00
* [page.setRequestInterception(value)](#pagesetrequestinterceptionvalue)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.setUserAgent(userAgent)](#pagesetuseragentuseragent)
* [page.setViewport(viewport)](#pagesetviewportviewport)
* [page.tap(selector)](#pagetapselector)
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
* [page.target()](#pagetarget)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [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)
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
* [page.waitForXPath(xpath[, options])](#pagewaitforxpathxpath-options)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
- [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)
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
* [dialog.type()](#dialogtype)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
- [class: ConsoleMessage](#class-consolemessage)
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
* [consoleMessage.args()](#consolemessageargs)
* [consoleMessage.text()](#consolemessagetext)
* [consoleMessage.type()](#consolemessagetype)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
- [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)
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
* [frame.$x(expression)](#framexexpression)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [frame.addScriptTag(options)](#frameaddscripttagoptions)
* [frame.addStyleTag(options)](#frameaddstyletagoptions)
* [frame.childFrames()](#framechildframes)
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
* [frame.click(selector[, options])](#frameclickselector-options)
feat(Frame): implement frame.content and frame.setContent methods (#1447) This refactors the page.content and page.setContent methods to be defined on the Frame class. This allows access from the Page still but also on all frames. Fixes #754
2017-11-23 02:44:33 +00:00
* [frame.content()](#framecontent)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [frame.evaluate(pageFunction, ...args)](#frameevaluatepagefunction-args)
feat(Frame): add Frame.evaluateHandle (#1885) This patch adds Frame.evaluateHandle method. The method is a shortcut for frame.executionContext().evaluateHandle. Fixes #1051
2018-01-25 05:16:01 +00:00
* [frame.evaluateHandle(pageFunction, ...args)](#frameevaluatehandlepagefunction-args)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [frame.executionContext()](#frameexecutioncontext)
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
* [frame.focus(selector)](#framefocusselector)
* [frame.hover(selector)](#framehoverselector)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [frame.isDetached()](#frameisdetached)
* [frame.name()](#framename)
* [frame.parentFrame()](#frameparentframe)
feat(Frame): introduce Frame.select This patch adds `Frame.select` method that does the same functionality as former `Page.select`, but on a per-frame level. The `Page.select` method becomes a shortcut for the ÷main frame's select. Fixes #1139
2017-11-02 05:06:04 +00:00
* [frame.select(selector, ...values)](#frameselectselector-values)
feat(Frame): implement frame.content and frame.setContent methods (#1447) This refactors the page.content and page.setContent methods to be defined on the Frame class. This allows access from the Page still but also on all frames. Fixes #754
2017-11-23 02:44:33 +00:00
* [frame.setContent(html)](#framesetcontenthtml)
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
* [frame.tap(selector)](#frametapselector)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [frame.title()](#frametitle)
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
* [frame.type(selector, text[, options])](#frametypeselector-text-options)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [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)
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
* [frame.waitForXPath(xpath[, options])](#framewaitforxpathxpath-options)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
- [class: ExecutionContext](#class-executioncontext)
* [executionContext.evaluate(pageFunction, ...args)](#executioncontextevaluatepagefunction-args)
* [executionContext.evaluateHandle(pageFunction, ...args)](#executioncontextevaluatehandlepagefunction-args)
feat(ExecutionContext): introduce ExecutionContext.frame() (#1972) This patch introduces ExecutionContext.frame() that returns Frame associated with this Execution Context. This allows to associate console messages with the originating frame, if any.
2018-02-13 22:02:44 +00:00
* [executionContext.frame()](#executioncontextframe)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [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)
feat(ElementHandle): add ElementHandle.$ and ElementHandle.$$ (#1151) This patch adds `ElementHandle.$` and `ElementHandle.$$` methods to query nested elements. Fixes #508
2017-10-27 09:08:58 +00:00
* [elementHandle.$(selector)](#elementhandleselector)
* [elementHandle.$$(selector)](#elementhandleselector)
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
* [elementHandle.$x(expression)](#elementhandlexexpression)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [elementHandle.asElement()](#elementhandleaselement)
* [elementHandle.boundingBox()](#elementhandleboundingbox)
feat(ElementHandle): add ElementHandle.boxModel method (#2256) This patch introduces ElementHandle.boxModel to get element's box model. Fixes #1357
2018-03-29 20:52:28 +00:00
* [elementHandle.boxModel()](#elementhandleboxmodel)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [elementHandle.click([options])](#elementhandleclickoptions)
feat(ElementHandle): implement ElementHandle.contentFrame() (#2094) This patch adds ElementHandle.contentFrame() method that allows to get a reference to the Frame owned by the iframe. Fixes #433.
2018-02-24 05:22:53 +00:00
* [elementHandle.contentFrame()](#elementhandlecontentframe)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [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)
feat(Request): allow aborting intercepted requests with custom reasons (#1080) This patch adds optional parameter to the `request.abort()` method that specifies abort reason. References #1020.
2017-10-18 07:26:48 +00:00
* [request.abort([errorCode])](#requestaborterrorcode)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [request.continue([overrides])](#requestcontinueoverrides)
feat(Request): introduce Request.failure() method (#1065) Similarly to the `request.response()` method, this patch adds `request.failure()` method that returns error details for the failed requests. Fixes #901.
2017-10-18 00:48:04 +00:00
* [request.failure()](#requestfailure)
feat: Attribute network requests to frames (#1646) This patch introduces `request.frame()` method that returns the frame that initiated request. Fixes #1579
2018-01-10 02:47:21 +00:00
* [request.frame()](#requestframe)
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
* [request.headers()](#requestheaders)
* [request.method()](#requestmethod)
* [request.postData()](#requestpostdata)
feat(Network): implement request.redirectChain() api (#2194) The request.redirectChain() returns all the requests issued to fetch the resource. Fixes #1816.
2018-03-16 00:17:38 +00:00
* [request.redirectChain()](#requestredirectchain)
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
* [request.resourceType()](#requestresourcetype)
feat(interception): Implement request.mockResponse method (#1064) feat(interception): Implement request.respond method This patch implements a new Request.respond method. This allows users to fulfill the intercepted request with a hand-crafted response if they wish so. References #1020.
2017-10-20 23:55:15 +00:00
* [request.respond(response)](#requestrespondresponse)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [request.response()](#requestresponse)
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
* [request.url()](#requesturl)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
- [class: Response](#class-response)
* [response.buffer()](#responsebuffer)
feat(Response): add Response.fromCache / Response.fromServiceWorker (#1971) This patch: - introduces `test/assets/cached` folder and teaches server to cache all the assets from the folder - introduces `test/assets/serviceworkers` folder that stores all the service workers and makes them register with unique URL prefix - introduces `Response.fromCache()` and `Response.fromServiceWorker()` methods Fixes #1551.
2018-02-05 22:59:07 +00:00
* [response.fromCache()](#responsefromcache)
* [response.fromServiceWorker()](#responsefromserviceworker)
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
* [response.headers()](#responseheaders)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [response.json()](#responsejson)
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
* [response.ok()](#responseok)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [response.request()](#responserequest)
feat(Network): introduce response.securityDetails() method (#1880) This patch: - introduces `SecurityDetails` class that exposes a set of fields that describe properties of secure connection - introduces method `response.securityDetails()` that returns an instance of `SecurityDetails` object.
2018-02-13 19:26:18 +00:00
* [response.securityDetails()](#responsesecuritydetails)
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
* [response.status()](#responsestatus)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [response.text()](#responsetext)
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
* [response.url()](#responseurl)
feat(Network): introduce response.securityDetails() method (#1880) This patch: - introduces `SecurityDetails` class that exposes a set of fields that describe properties of secure connection - introduces method `response.securityDetails()` that returns an instance of `SecurityDetails` object.
2018-02-13 19:26:18 +00:00
- [class: SecurityDetails](#class-securitydetails)
* [securityDetails.issuer()](#securitydetailsissuer)
* [securityDetails.protocol()](#securitydetailsprotocol)
* [securityDetails.subjectName()](#securitydetailssubjectname)
* [securityDetails.validFrom()](#securitydetailsvalidfrom)
* [securityDetails.validTo()](#securitydetailsvalidto)
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
- [class: Target](#class-target)
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
* [target.createCDPSession()](#targetcreatecdpsession)
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
* [target.page()](#targetpage)
* [target.type()](#targettype)
* [target.url()](#targeturl)
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
- [class: CDPSession](#class-cdpsession)
* [cdpSession.detach()](#cdpsessiondetach)
* [cdpSession.send(method[, params])](#cdpsessionsendmethod-params)
feat: Implement JavaScript Coverage (#1673) This patch introduces a new `page.coverage` namespace with two methods: - `page.coverage.startJSCoverage` to initiate JavaScript coverage recording - `page.coverage.stopJSCoverage` to stop JavaScript coverage and get results
2018-01-03 03:53:53 +00:00
- [class: Coverage](#class-coverage)
feat: implement CSS Coverage (#1714) This patch adds two new methods to the `page.coverage` namespace: - `page.coverage.startCSSCoverage()` - to initiate css coverage - `page.coverage.stopCSSCoverage()` - to stop css coverage The coverage format is consistent with the JavaScript coverage.
2018-01-04 02:21:40 +00:00
* [coverage.startCSSCoverage(options)](#coveragestartcsscoverageoptions)
feat: Implement JavaScript Coverage (#1673) This patch introduces a new `page.coverage` namespace with two methods: - `page.coverage.startJSCoverage` to initiate JavaScript coverage recording - `page.coverage.stopJSCoverage` to stop JavaScript coverage and get results
2018-01-03 03:53:53 +00:00
* [coverage.startJSCoverage(options)](#coveragestartjscoverageoptions)
feat: implement CSS Coverage (#1714) This patch adds two new methods to the `page.coverage` namespace: - `page.coverage.startCSSCoverage()` - to initiate css coverage - `page.coverage.stopCSSCoverage()` - to stop css coverage The coverage format is consistent with the JavaScript coverage.
2018-01-04 02:21:40 +00:00
* [coverage.stopCSSCoverage()](#coveragestopcsscoverage)
feat: Implement JavaScript Coverage (#1673) This patch introduces a new `page.coverage` namespace with two methods: - `page.coverage.startJSCoverage` to initiate JavaScript coverage recording - `page.coverage.stopJSCoverage` to stop JavaScript coverage and get results
2018-01-03 03:53:53 +00:00
* [coverage.stopJSCoverage()](#coveragestopjscoverage)
Implement documentation linter (#47) This patch implements documentation linter, which leaves under `test/doclint` folder. The documentation linter works like this: 1. Parse javascript source code with esprima and construct a "documentation" out of source code 2. Generate HTML out of `api.md` and traverse the HTML with puppeteer. 3. Make sure javascript aligns nicely with HTML The documentation linter adds the following commands: - `yarn doc` - to test that documentation covers all the relevant apis - `yarn generate-toc` - to update the table-of-contents for the `api.md`
2017-07-07 16:36:45 +00:00
<!-- tocstop -->
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.
2017-06-13 07:28:29 +00:00
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
### Overview
Get rid of page.emulate() / page.emulatedDevices() methods This patch: - gets rid of `page.emulate` and `page.emulatedDevices` methods. Instead, it is suggested to use `page.setViewport()` and `page.setUserAgent()` methods. - moves DeviceDescriptors to the top level of the puppeteer so that it is convenient to require them. - improves on documentation to describe the suggested emulation approach. References #88.
2017-07-21 01:14:43 +00:00
docs(README.md): Update docs to more clearly differentiate between Chromium and Chrome (#1574) This patch clarifies the documentation to more clearly note that Puppeteer works with both Chromium (by default) and Chrome. Fixes #1516
2017-12-15 03:09:48 +00:00
Puppeteer is a Node library which provides a high-level API to control Chromium or Chrome over the DevTools Protocol.
Get rid of page.emulate() / page.emulatedDevices() methods This patch: - gets rid of `page.emulate` and `page.emulatedDevices` methods. Instead, it is suggested to use `page.setViewport()` and `page.setUserAgent()` methods. - moves DeviceDescriptors to the top level of the puppeteer so that it is convenient to require them. - improves on documentation to describe the suggested emulation approach. References #88.
2017-07-21 01:14:43 +00:00
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
The Puppeteer API is hierarchical and mirrors the browser structure. On the following diagram, faded entities are not currently represented in Puppeteer.
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
![puppeteer overview](https://user-images.githubusercontent.com/746130/31592143-089f6f9a-b1db-11e7-9a20-16b7fc754fa1.png)
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- [`Puppeteer`](#class-puppeteer) communicates with the browser using [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/).
- [`Browser`](#class-browser) instance can own multiple pages.
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
- [`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.
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- [`Frame`](#class-frame) has at least one execution context - the default execution context - where the frame's JavaScript is executed. A Frame might have additional execution contexts that are associated with [extensions](https://developer.chrome.com/extensions).
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
(Diagram source: [link](https://docs.google.com/drawings/d/1Q_AM6KYs9kbyLZF-Lpp5mtpAWth73Cq8IKCsWYgi8MM/edit?usp=sharing))
Add environment variable to skip download (#606) This patch: - starts skipping chromium download if `PUPPETEER_SKIP_CHROMIUM_DOWNLOAD` env variable is set - adds description of support env variables to the `docs/api.md`. References #603
2017-08-31 04:40:15 +00:00
### Environment Variables
feat(install): support npm config for chromium revision (#2290) This patch: - adds `npm_config_puppeteer_chromium_revision` support - clarifies api documentation about variables from npm config
2018-03-30 17:49:48 +00:00
Puppeteer looks for certain [environment variables](https://en.wikipedia.org/wiki/Environment_variable) to aid its operations.
If puppeteer doesn't find them in environment, lowercased variant of these variables will be used from the [npm config](https://docs.npmjs.com/cli/config).
Add environment variable to skip download (#606) This patch: - starts skipping chromium download if `PUPPETEER_SKIP_CHROMIUM_DOWNLOAD` env variable is set - adds description of support env variables to the `docs/api.md`. References #603
2017-08-31 04:40:15 +00:00
- `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` - defines HTTP proxy settings that are used to download and run Chromium.
[docs] clarify env variables usage with npmrc
2017-09-26 02:15:18 +00:00
- `PUPPETEER_SKIP_CHROMIUM_DOWNLOAD` - do not download bundled Chromium during installation step.
feat(install): add environment variable to overwrite host part of url (#958) This patch adds PUPPETEER_DOWNLOAD_HOST env variable that allows to specify a download host. Useful for downloading from mirrors. Fixes #951
2017-10-22 01:22:13 +00:00
- `PUPPETEER_DOWNLOAD_HOST` - overwrite host part of URL that is used to download Chromium
feat(install): introduce PUPPETEER_CHROMIUM_REVISION (#2246) This patch introduces PUPPETEER_CHROMIUM_REVISION environment variable to specify chromium revision to be downloaded during install step.
2018-03-29 17:46:00 +00:00
- `PUPPETEER_CHROMIUM_REVISION` - specify a certain version of chrome you'd like puppeteer to use during the installation step.
[docs] clarify env variables usage with npmrc
2017-09-26 02:15:18 +00:00
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
### class: Puppeteer
Capitalize Chromium and Puppeteer (#263)
2017-08-15 07:14:12 +00:00
Puppeteer module provides a method to launch a Chromium instance.
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
The following is a typical example of using Puppeteer to drive automation:
Get rid of page.emulate() / page.emulatedDevices() methods This patch: - gets rid of `page.emulate` and `page.emulatedDevices` methods. Instead, it is suggested to use `page.setViewport()` and `page.setUserAgent()` methods. - moves DeviceDescriptors to the top level of the puppeteer so that it is convenient to require them. - improves on documentation to describe the suggested emulation approach. References #88.
2017-07-21 01:14:43 +00:00
```js
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
const puppeteer = require('puppeteer');
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
puppeteer.launch().then(async browser => {
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const page = await browser.newPage();
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
await page.goto('https://www.google.com');
Get rid of page.emulate() / page.emulatedDevices() methods This patch: - gets rid of `page.emulate` and `page.emulatedDevices` methods. Instead, it is suggested to use `page.setViewport()` and `page.setUserAgent()` methods. - moves DeviceDescriptors to the top level of the puppeteer so that it is convenient to require them. - improves on documentation to describe the suggested emulation approach. References #88.
2017-07-21 01:14:43 +00:00
// other actions...
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
Get rid of page.emulate() / page.emulatedDevices() methods This patch: - gets rid of `page.emulate` and `page.emulatedDevices` methods. Instead, it is suggested to use `page.setViewport()` and `page.setUserAgent()` methods. - moves DeviceDescriptors to the top level of the puppeteer so that it is convenient to require them. - improves on documentation to describe the suggested emulation approach. References #88.
2017-07-21 01:14:43 +00:00
});
```
Introduce Puppeteer.connect method (#264) This patch: - refactors Connection to use a single remote debugging URL instead of a pair of port and browserTargetId - introduces Puppeteer.connect() method to attach to already running browser instance. Fixes #238.
2017-08-15 21:29:42 +00:00
#### puppeteer.connect(options)
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `options` <[Object]>
Rename 'remoteDebuggingURL' into 'browserWSEndpoint' (#272)
2017-08-16 08:10:55 +00:00
- `browserWSEndpoint` <[string]> a [browser websocket endpoint](#browserwsendpoint) to connect to.
Introduce Puppeteer.connect method (#264) This patch: - refactors Connection to use a single remote debugging URL instead of a pair of port and browserTargetId - introduces Puppeteer.connect() method to attach to already running browser instance. Fixes #238.
2017-08-15 21:29:42 +00:00
- `ignoreHTTPSErrors` <[boolean]> Whether to ignore HTTPS errors during navigation. Defaults to `false`.
feat: add slowMo option to puppeteer.connect (#1864) This patch introduces a `slowMo` option to the `puppeteer.connect` method. The option is similar to the one in `puppeteer.launch` and is used to slow down the connection.
2018-01-23 00:45:46 +00:00
- `slowMo` <[number]> Slows down Puppeteer operations by the specified amount of milliseconds. Useful so that you can see what is going on.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- returns: <[Promise]<[Browser]>>
Introduce Puppeteer.connect method (#264) This patch: - refactors Connection to use a single remote debugging URL instead of a pair of port and browserTargetId - introduces Puppeteer.connect() method to attach to already running browser instance. Fixes #238.
2017-08-15 21:29:42 +00:00
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
This methods attaches Puppeteer to an existing Chromium instance.
Introduce Puppeteer.connect method (#264) This patch: - refactors Connection to use a single remote debugging URL instead of a pair of port and browserTargetId - introduces Puppeteer.connect() method to attach to already running browser instance. Fixes #238.
2017-08-15 21:29:42 +00:00
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
#### puppeteer.createBrowserFetcher([options])
- `options` <[Object]>
- `host` <[string]> A download host to be used. Defaults to `https://storage.googleapis.com`.
- `path` <[string]> A path for the downloads folder. Defaults to `<root>/.local-chromium`, where `<root>` is puppeteer's package root.
- `platform` <[string]> Possible values are: `mac`, `win32`, `win64`, `linux`. Defaults to the current platform.
- returns: <[BrowserFetcher]>
feat(Launcher): allow the default arguments to be overridden (#1623) This patch: - adds `puppeteer.defaultArgs()` method to get default arguments that are used to launch chrome - adds `ignoreDefaultArgs` option to `puppeteer.launch` to avoid using default puppeteer arguments Fixes #872
2017-12-20 01:51:21 +00:00
#### puppeteer.defaultArgs()
- returns: <[Array]<[string]>> The default flags that Chromium will be launched with.
[api] add Puppeteer.executablePath() method (#771) This patch adds Puppeteer.executablePath() method to query the path of bundled chromium. Fixes #745
2017-09-14 00:39:18 +00:00
#### puppeteer.executablePath()
- returns: <[string]> A path where Puppeteer expects to find bundled Chromium. Chromium might not exist there if the download was skipped with [`PUPPETEER_SKIP_CHROMIUM_DOWNLOAD`](#environment-variables).
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
#### puppeteer.launch([options])
- `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields:
- `ignoreHTTPSErrors` <[boolean]> Whether to ignore HTTPS errors during navigation. Defaults to `false`.
docs(README.md): Update docs to more clearly differentiate between Chromium and Chrome (#1574) This patch clarifies the documentation to more clearly note that Puppeteer works with both Chromium (by default) and Chrome. Fixes #1516
2017-12-15 03:09:48 +00:00
- `headless` <[boolean]> Whether to run browser in [headless mode](https://developers.google.com/web/updates/2017/04/headless-chrome). Defaults to `true` unless the `devtools` option is `true`.
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- `executablePath` <[string]> Path to a Chromium or Chrome executable to run instead of the bundled Chromium. If `executablePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
- `slowMo` <[number]> Slows down Puppeteer operations by the specified amount of milliseconds. Useful so that you can see what is going on.
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- `args` <[Array]<[string]>> Additional arguments to pass to the browser instance. The list of Chromium flags can be found [here](http://peter.sh/experiments/chromium-command-line-switches/).
feat(Launcher): allow the default arguments to be overridden (#1623) This patch: - adds `puppeteer.defaultArgs()` method to get default arguments that are used to launch chrome - adds `ignoreDefaultArgs` option to `puppeteer.launch` to avoid using default puppeteer arguments Fixes #872
2017-12-20 01:51:21 +00:00
- `ignoreDefaultArgs` <[boolean]> Do not use [`puppeteer.defaultArgs()`](#puppeteerdefaultargs). Dangerous option; use with care. Defaults to `false`.
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- `handleSIGINT` <[boolean]> Close the browser process on Ctrl-C. Defaults to `true`.
- `handleSIGTERM` <[boolean]> Close the browser process on SIGTERM. Defaults to `true`.
- `handleSIGHUP` <[boolean]> Close the browser process on SIGHUP. Defaults to `true`.
docs(README.md): Update docs to more clearly differentiate between Chromium and Chrome (#1574) This patch clarifies the documentation to more clearly note that Puppeteer works with both Chromium (by default) and Chrome. Fixes #1516
2017-12-15 03:09:48 +00:00
- `timeout` <[number]> Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- `dumpio` <[boolean]> Whether to pipe the browser process stdout and stderr into `process.stdout` and `process.stderr`. Defaults to `false`.
[api] Allow a custom userDataDir to be specified (#555) This patch adds a `userDataDir` option to the `puppeteer.launch()` method. Fixes #411.
2017-08-28 19:14:21 +00:00
- `userDataDir` <[string]> Path to a [User Data Directory](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md).
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- `env` <[Object]> Specify environment variables that will be visible to the browser. Defaults to `process.env`.
- `devtools` <[boolean]> Whether to auto-open a DevTools panel for each tab. If this option is `true`, the `headless` option will be set `false`.
feat(Launcher): introduce `pipe` option (#2288) This patch introduces a new `pipe` option to the launcher to connect over a pipe. In certain environments, exposing web socket for remote debugging is a security risk. Pipe connection eliminates this risk.
2018-04-03 22:05:27 +00:00
- `pipe` <[boolean]> Connects to the browser over a pipe instead of a WebSocket. Defaults to `false`.
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
- returns: <[Promise]<[Browser]>> Promise which resolves to browser instance.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
The method launches a browser instance with given arguments. The browser will be closed when the parent node.js process is closed.
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
chore: Spelling and Markdown Consistency (#1998) - Adding missing language tags to markdown code blocks. - Fixed various spelling mistakes my IDE complained to me about.
2018-02-09 03:59:46 +00:00
> **NOTE** Puppeteer can also be used to control the Chrome browser, but it works best with the version of Chromium it is bundled with. There is no guarantee it will work with any other version. Use `executablePath` option with extreme caution.
>
> If Google Chrome (rather than Chromium) is preferred, a [Chrome Canary](https://www.google.com/chrome/browser/canary.html) or [Dev Channel](https://www.chromium.org/getting-involved/dev-channel) build is suggested.
docs(README.md): Update docs to more clearly differentiate between Chromium and Chrome (#1574) This patch clarifies the documentation to more clearly note that Puppeteer works with both Chromium (by default) and Chrome. Fixes #1516
2017-12-15 03:09:48 +00:00
>
> In [puppeteer.launch([options])](#puppeteerlaunchoptions) above, any mention of Chromium also applies to Chrome.
>
chore: Spelling and Markdown Consistency (#1998) - Adding missing language tags to markdown code blocks. - Fixed various spelling mistakes my IDE complained to me about.
2018-02-09 03:59:46 +00:00
> See [`this article`](https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/) for a description of the differences between Chromium and Chrome. [`This article`](https://chromium.googlesource.com/chromium/src/+/lkcr/docs/chromium_browser_vs_google_chrome.md) describes some differences for Linux users.
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
### class: BrowserFetcher
BrowserFetcher can download and manage different versions of Chromium.
BrowserFetcher operates on revision strings that specify a precise version of Chromium, e.g. `"533271"`. Revision strings can be obtained from [omahaproxy.appspot.com](http://omahaproxy.appspot.com/).
Example on how to use BrowserFetcher to download a specific version of Chromium and run
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
Puppeteer against it:
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
```js
const browserFetcher = puppeteer.createBrowserFetcher();
const revisionInfo = await browserFetcher.download('533271');
const browser = await puppeteer.launch({executablePath: revisionInfo.executablePath})
```
> **NOTE** BrowserFetcher is not designed to work concurrently with other
> instances of BrowserFetcher that share the same downloads directory.
#### browserFetcher.canDownload(revision)
- `revision` <[string]> a revision to check availability.
- returns: <[Promise]<[boolean]>> returns `true` if the revision could be downloaded from the host.
The method initiates a HEAD request to check if the revision is available.
#### browserFetcher.download(revision[, progressCallback])
- `revision` <[string]> a revision to download.
- `progressCallback` <[function]([number], [number])> A function that will be called with two arguments:
- `downloadedBytes` <[number]> how many bytes have been downloaded
- `totalBytes` <[number]> how large is the total download.
- returns: <[Promise]<[Object]>> Resolves with revision information when the revision is downloaded and extracted
- `revision` <[string]> the revision the info was created from
- `folderPath` <[string]> path to the extracted revision folder
- `executablePath` <[string]> path to the revision executable
- `url` <[string]> URL this revision can be downloaded from
- `local` <[boolean]> whether the revision is locally available on disk
The method initiates a GET request to download the revision from the host.
#### browserFetcher.localRevisions()
- returns: <[Promise]<[Array]<[string]>>> A list of all revisions available locally on disk.
#### browserFetcher.platform()
- returns: <[string]> Returns one of `mac`, `linux`, `win32` or `win64`.
#### browserFetcher.remove(revision)
- `revision` <[string]> a revision to remove. The method will throw if the revision has not been downloaded.
- returns: <[Promise]> Resolves when the revision has been removed.
#### browserFetcher.revisionInfo(revision)
- `revision` <[string]> a revision to get info for.
- returns: <[Object]>
- `revision` <[string]> the revision the info was created from
- `folderPath` <[string]> path to the extracted revision folder
- `executablePath` <[string]> path to the revision executable
- `url` <[string]> URL this revision can be downloaded from
- `local` <[boolean]> whether the revision is locally available on disk
Add note about `executablePath` option to puppeteer.launch (#260)
2017-08-15 06:57:12 +00:00
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.
2017-06-13 07:28:29 +00:00
### class: Browser
docs(api.md): Note that Browser and Page extend from EventEmitter (#1541) Adds notes to the API documentation that Browser and Page classes are EventEmitters. Provides an example of using `.once` for Page. Fixes #1231
2017-12-06 07:53:27 +00:00
* extends: [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter)
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
A Browser is created when Puppeteer connects to a Chromium instance, either through [`puppeteer.launch`](#puppeteerlaunchoptions) or [`puppeteer.connect`](#puppeteerconnectoptions).
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.
2017-06-13 07:28:29 +00:00
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
An example of using a [Browser] to create a [Page]:
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
```js
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
const puppeteer = require('puppeteer');
puppeteer.launch().then(async browser => {
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const page = await browser.newPage();
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
await page.goto('https://example.com');
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
Docs: minor fixes (#167)
2017-07-30 01:08:35 +00:00
});
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
```
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.
2017-06-13 07:28:29 +00:00
feat(Browser): make browser.close() to always terminate remote browser This patch: - changes `browser.close` to terminate browser. - introduces new `browser.disconnect` to disconnect from a browser without closing it This patch: fixes #918, fixes #989 BREAKING CHANGE: `browser.close()` will always close a browser, even if it was initialized with `puppeteer.connect`. To disconnect from a remote browser, use `browser.disconnect()` instead.
2017-10-17 22:35:00 +00:00
An example of disconnecting from and reconnecting to a [Browser]:
```js
const puppeteer = require('puppeteer');
puppeteer.launch().then(async browser => {
// Store the endpoint to be able to reconnect to Chromium
const browserWSEndpoint = browser.wsEndpoint();
// Disconnect puppeteer from Chromium
browser.disconnect();
// Use the endpoint to reestablish a connection
const browser2 = await puppeteer.connect({browserWSEndpoint});
// Close Chromium
await browser2.close();
});
```
feat(browser): add browser.disconnected event (#960) This patch adds a 'disconnected' event for the browser. The event is issued when the "browser" loses connection to the chrome process. References #952
2017-11-04 01:46:17 +00:00
#### event: 'disconnected'
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
Emitted when Puppeteer gets disconnected from the Chromium instance. This might happen because of one of the following:
docs: update api.md This patch clarifies when the "disconnected" event is emitted and emphasizes the difference between Chromium and browser. References #1589.
2018-01-04 10:27:57 +00:00
- Chromium is closed or crashed
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- The [`browser.disconnect`](#browserdisconnect) method was called
feat(Browser): make browser.close() to always terminate remote browser This patch: - changes `browser.close` to terminate browser. - introduces new `browser.disconnect` to disconnect from a browser without closing it This patch: fixes #918, fixes #989 BREAKING CHANGE: `browser.close()` will always close a browser, even if it was initialized with `puppeteer.connect`. To disconnect from a remote browser, use `browser.disconnect()` instead.
2017-10-17 22:35:00 +00:00
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
#### event: 'targetchanged'
- <[Target]>
Emitted when the url of a target changes.
#### event: 'targetcreated'
- <[Target]>
Emitted when a target is created, for example when a new page is opened by [`window.open`](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) or [`browser.newPage`](#browsernewpage).
#### event: 'targetdestroyed'
- <[Target]>
Emitted when a target is destroyed, for example when a page is closed.
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
#### browser.close()
[api] Launcher: Close gracefully when a userDataDir is specified (#700) This patch: - makes `browser.close()` return a promise that resolves when browser gets closed - starts closing chrome gracefully if a custom `userDataDir` is supplied Fixes #527
2017-09-14 04:27:14 +00:00
- returns: <[Promise]>
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.
2017-06-13 07:28:29 +00:00
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
Closes Chromium and all of its pages (if any were opened). The [Browser] object itself is considered to be disposed and cannot be used anymore.
feat(Browser): make browser.close() to always terminate remote browser This patch: - changes `browser.close` to terminate browser. - introduces new `browser.disconnect` to disconnect from a browser without closing it This patch: fixes #918, fixes #989 BREAKING CHANGE: `browser.close()` will always close a browser, even if it was initialized with `puppeteer.connect`. To disconnect from a remote browser, use `browser.disconnect()` instead.
2017-10-17 22:35:00 +00:00
#### browser.disconnect()
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
Disconnects Puppeteer from the browser, but leaves the Chromium process running. After calling `disconnect`, the [Browser] object is considered disposed and cannot be used anymore.
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.
2017-06-13 07:28:29 +00:00
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
#### browser.newPage()
- returns: <[Promise]<[Page]>> Promise which resolves to a new [Page] object.
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.
2017-06-13 07:28:29 +00:00
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
#### browser.pages()
- returns: <[Promise]<[Array]<[Page]>>> Promise which resolves to an array of all open pages.
feat(Browser): introduce browser.process() variable (#1581) This patch adds a `browser.process()` getter to expose the child process with running browser. Fixes #1539.
2017-12-11 20:11:12 +00:00
#### browser.process()
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- returns: <?[ChildProcess]> Spawned browser process. Returns `null` if the browser instance was created with [`puppeteer.connect`](#puppeteerconnectoptions) method.
feat(Browser): introduce browser.process() variable (#1581) This patch adds a `browser.process()` getter to expose the child process with running browser. Fixes #1539.
2017-12-11 20:11:12 +00:00
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
#### browser.targets()
- returns: <[Array]<[Target]>> An array of all active targets.
feat: introduce browser.userAgent() (#1716) The patch introduces browser.userAgent() method to retrieve default browser user agent. Fixes #1706.
2018-01-05 18:14:30 +00:00
#### browser.userAgent()
- returns: <[Promise]<[string]>> Promise which resolves to the browser's original user agent.
> **NOTE** Pages can override browser user agent with [page.setUserAgent](#pagesetuseragentuseragent)
[doclint] introduce class members This patch unifies Documentation.Method with Documentation.Property, making it possible to verify sorting order across methods and properties. References #14.
2017-07-14 05:52:02 +00:00
#### browser.version()
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- returns: <[Promise]<[string]>> For headless Chromium, this is similar to `HeadlessChrome/61.0.3153.0`. For non-headless, this is similar to `Chrome/61.0.3153.0`.
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
> **NOTE** the format of browser.version() might change with future releases of Chromium.
[doclint] introduce class members This patch unifies Documentation.Method with Documentation.Property, making it possible to verify sorting order across methods and properties. References #14.
2017-07-14 05:52:02 +00:00
Rename 'remoteDebuggingURL' into 'browserWSEndpoint' (#272)
2017-08-16 08:10:55 +00:00
#### browser.wsEndpoint()
- returns: <[string]> Browser websocket url.
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
Browser websocket endpoint which can be used as an argument to
chore(doc): fix browser.wsEndpoint() return value format (#898)
2017-09-29 21:59:19 +00:00
[puppeteer.connect](#puppeteerconnectoptions). The format is `ws://${host}:${port}/devtools/browser/<id>`
Added info on how to find the browserWSEndpoint (#780)
2017-09-26 14:04:09 +00:00
You can find the `webSocketDebuggerUrl` from `http://${host}:${port}/json/version`. Learn more about the [devtools protocol](https://chromedevtools.github.io/devtools-protocol) and the [browser endpoint](https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target).
Rename 'remoteDebuggingURL' into 'browserWSEndpoint' (#272)
2017-08-16 08:10:55 +00:00
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.
2017-06-13 07:28:29 +00:00
### class: Page
docs(api.md): Note that Browser and Page extend from EventEmitter (#1541) Adds notes to the API documentation that Browser and Page classes are EventEmitters. Provides an example of using `.once` for Page. Fixes #1231
2017-12-06 07:53:27 +00:00
* extends: [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter)
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
Page provides methods to interact with a single tab in Chromium. One [Browser] instance might have multiple [Page] instances.
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.
2017-06-13 07:28:29 +00:00
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
This example creates a page, navigates it to a URL, and then saves a screenshot:
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
```js
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
const puppeteer = require('puppeteer');
puppeteer.launch().then(async browser => {
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const page = await browser.newPage();
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
await page.goto('https://example.com');
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
await page.screenshot({path: 'screenshot.png'});
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
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.
2017-06-13 07:28:29 +00:00
});
```
docs(README): Add's page.removeListener to Page class examples (#2122) This patch adds `page.removeListener` to Page class examples
2018-03-13 16:25:25 +00:00
The Page class emits various events (described below) which can be handled using any of Node's native [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter) methods, such as `on`, `once` or `removeListener`.
docs(api.md): Note that Browser and Page extend from EventEmitter (#1541) Adds notes to the API documentation that Browser and Page classes are EventEmitters. Provides an example of using `.once` for Page. Fixes #1231
2017-12-06 07:53:27 +00:00
This example logs a message for a single page `load` event:
```js
page.once('load', () => console.log('Page loaded!'));
```
docs(README): Add's page.removeListener to Page class examples (#2122) This patch adds `page.removeListener` to Page class examples
2018-03-13 16:25:25 +00:00
To unsubscribe from events use the `removeListener` method:
```js
function logRequest(interceptedRequest) {
console.log('A request was made:', interceptedRequest.url());
}
page.on('request', logRequest);
// Sometime later...
page.removeListener('request', logRequest);
```
feat(Page): page 'close' event (#2232) This patch adds 'page.close' event. References #952.
2018-03-28 20:11:51 +00:00
#### event: 'close'
Emitted when the page closes.
Rename Page's 'consolemessage' event into 'console' This patch: - renames 'consolemessage' event into 'console' - improves on 'console' event documentation References #39.
2017-07-18 03:38:11 +00:00
#### event: 'console'
feat(Console): Introduce ConsoleMessage type (#909) This patch introduces ConsoleMessage type and starts dispatching it for the 'console' event. BREAKING CHANGE: this breaks the api of the 'console' event. Fixes #744.
2017-09-29 18:27:22 +00:00
- <[ConsoleMessage]>
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`. Also emitted if the page throws an error or a warning.
Rename Page's 'consolemessage' event into 'console' This patch: - renames 'consolemessage' event into 'console' - improves on 'console' event documentation References #39.
2017-07-18 03:38:11 +00:00
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
The arguments passed into `console.log` appear as arguments on the event handler.
Rename Page's 'consolemessage' event into 'console' This patch: - renames 'consolemessage' event into 'console' - improves on 'console' event documentation References #39.
2017-07-18 03:38:11 +00:00
An example of handling `console` event:
```js
feat(Console): Introduce ConsoleMessage type (#909) This patch introduces ConsoleMessage type and starts dispatching it for the 'console' event. BREAKING CHANGE: this breaks the api of the 'console' event. Fixes #744.
2017-09-29 18:27:22 +00:00
page.on('console', msg => {
fix(Docs): fix Console example (#1961) Fixes #1874
2018-02-05 22:44:22 +00:00
for (let i = 0; i < msg.args().length; ++i)
console.log(`${i}: ${msg.args()[i]}`);
Rename Page's 'consolemessage' event into 'console' This patch: - renames 'consolemessage' event into 'console' - improves on 'console' event documentation References #39.
2017-07-18 03:38:11 +00:00
});
feat(Console): Introduce ConsoleMessage type (#909) This patch introduces ConsoleMessage type and starts dispatching it for the 'console' event. BREAKING CHANGE: this breaks the api of the 'console' event. Fixes #744.
2017-09-29 18:27:22 +00:00
page.evaluate(() => console.log('hello', 5, {foo: 'bar'}));
Rename Page's 'consolemessage' event into 'console' This patch: - renames 'consolemessage' event into 'console' - improves on 'console' event documentation References #39.
2017-07-18 03:38:11 +00:00
```
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
#### event: 'dialog'
- <[Dialog]>
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Puppeteer can respond to the dialog via [Dialog]'s [accept](#dialogacceptprompttext) or [dismiss](#dialogdismiss) methods.
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
feat: add Page.Events.DOMContentLoaded (#1730) Fixes #1580
2018-01-17 07:22:44 +00:00
#### event: 'domcontentloaded'
Emitted when the JavaScript [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event is dispatched.
Emit 'error' event when page crashes (#266) This patch starts emitting 'error' event when page crashes. 'error' events have special treatment in node, so page crashes become observable for users. Fixes #262.
2017-08-15 18:13:05 +00:00
#### event: 'error'
- <[Error]>
Emitted when the page crashes.
Introduce page.emulateMedia method (#383) Emulating `screen` media would force `page.pdf()` to print with `screen` media. Fixes #312
2017-08-18 23:49:02 +00:00
> **NOTE** `error` event has a special meaning in Node, see [error events](https://nodejs.org/api/events.html#events_error_events) for details.
Emit 'error' event when page crashes (#266) This patch starts emitting 'error' event when page crashes. 'error' events have special treatment in node, so page crashes become observable for users. Fixes #262.
2017-08-15 18:13:05 +00:00
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
#### event: 'frameattached'
- <[Frame]>
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
Emitted when a frame is attached.
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
#### event: 'framedetached'
- <[Frame]>
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
Emitted when a frame is detached.
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
#### event: 'framenavigated'
- <[Frame]>
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
Emitted when a frame is navigated to a new url.
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
#### event: 'load'
docs: fix typo in `event: 'load'` section (#325) fix `JavaScriot` to `JavaScript`
2017-08-17 06:27:19 +00:00
Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched.
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
feat(Page): Support Page.getMetrics and metrics event. (#939) Provides access to the current page performance metrics. Allows to push page metrics from the page JavaScript with console.timeStamp() Fixes #309
2017-10-10 21:50:38 +00:00
#### event: 'metrics'
- <[Object]>
- `title` <[string]> The title passed to `console.timeStamp`.
- `metrics` <[Object]> Object containing metrics as key/value pairs. The values
of metrics are of <[number]> type.
Emitted when the JavaScript code makes a call to `console.timeStamp`. For the list
feat(Page): rename Page.getMetrics into Page.metrics (#1240) BREAKING CHANGE: method page.getMetrics() got renamed into page.metrics().
2017-11-01 20:39:31 +00:00
of metrics see `page.metrics`.
feat(Page): Support Page.getMetrics and metrics event. (#939) Provides access to the current page performance metrics. Allows to push page metrics from the page JavaScript with console.timeStamp() Fixes #309
2017-10-10 21:50:38 +00:00
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
#### event: 'pageerror'
docs(api.md): `page.error` event dispatchers error
2018-02-05 22:45:35 +00:00
- <[Error]> The exception message
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
Emitted when an uncaught exception happens within the page.
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
#### event: 'request'
- <[Request]>
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
Emitted when a page issues a request. The [request] object is read-only.
feat(Chromium): Roll chromium to r511134 (#1153) This roll includes: - crrev.com/510651 that changes request interception methods in protocol - s/Page.setRequestInterceptionEnabled/Page.setRequestInterception BREAKING CHANGE Page.setRequestInterceptionEnabled is renamed into Page.setRequestInterception.
2017-10-24 21:45:03 +00:00
In order to intercept and mutate requests, see `page.setRequestInterception`.
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
#### event: 'requestfailed'
- <[Request]>
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
Emitted when a request fails, for example by timing out.
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
#### event: 'requestfinished'
- <[Request]>
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
Emitted when a request finishes successfully.
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
#### event: 'response'
- <[Response]>
Emitted when a [response] is received.
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.
2017-06-13 07:28:29 +00:00
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
#### page.$(selector)
Implement page.$eval (#638) This patch: - implements page.$eval and frame.$eval - drops elementHandle.attribute() method in favor of the page.$eval References #625
2017-08-31 22:38:01 +00:00
- `selector` <[string]> A [selector] to query page for
docs(api.md): fix return signatures that contains null (#1364)
2017-11-15 18:53:17 +00:00
- returns: <[Promise]<?[ElementHandle]>>
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
The method runs `document.querySelector` within the page. If no element matches the selector, the return value resolve to `null`.
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
Shortcut for [page.mainFrame().$(selector)](#frameselector).
Rename Page.setInPageCallback into Page.addBinding (#236) This seems to be a much better name which is actually used for a similar purposes in chromium/v8.
2017-08-11 04:44:49 +00:00
Implement page.$$ method (#463) This patch implements page.$$ which runs document.querySelectorAll in page and returns results as an array of ElementHandle instances. Fixes #384.
2017-08-23 05:56:55 +00:00
#### page.$$(selector)
Implement page.$eval (#638) This patch: - implements page.$eval and frame.$eval - drops elementHandle.attribute() method in favor of the page.$eval References #625
2017-08-31 22:38:01 +00:00
- `selector` <[string]> A [selector] to query page for
Implement page.$$ method (#463) This patch implements page.$$ which runs document.querySelectorAll in page and returns results as an array of ElementHandle instances. Fixes #384.
2017-08-23 05:56:55 +00:00
- returns: <[Promise]<[Array]<[ElementHandle]>>>
The method runs `document.querySelectorAll` within the page. If no elements match the selector, the return value resolve to `[]`.
Shortcut for [page.mainFrame().$$(selector)](#frameselector-1).
feat(Page): introduce Page.$$eval method (#1006) This patch adds a `Page.$$eval` method that runs `document.querySelectorAll` and passes resulting array to the page function. Fixes #625.
2017-10-11 06:23:14 +00:00
#### page.$$eval(selector, pageFunction[, ...args])
- `selector` <[string]> A [selector] to query frame for
- `pageFunction` <[function]> Function to be evaluated in browser context
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
feat(Page): introduce Page.$$eval method (#1006) This patch adds a `Page.$$eval` method that runs `document.querySelectorAll` and passes resulting array to the page function. Fixes #625.
2017-10-11 06:23:14 +00:00
- returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
This method runs `document.querySelectorAll` within the page and passes it as the first argument to `pageFunction`.
If `pageFunction` returns a [Promise], then `page.$$eval` would wait for the promise to resolve and return its value.
Examples:
```js
const divsCounts = await page.$$eval('div', divs => divs.length);
```
Implement page.$eval (#638) This patch: - implements page.$eval and frame.$eval - drops elementHandle.attribute() method in favor of the page.$eval References #625
2017-08-31 22:38:01 +00:00
#### page.$eval(selector, pageFunction[, ...args])
- `selector` <[string]> A [selector] to query page for
- `pageFunction` <[function]> Function to be evaluated in browser context
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
Implement page.$eval (#638) This patch: - implements page.$eval and frame.$eval - drops elementHandle.attribute() method in favor of the page.$eval References #625
2017-08-31 22:38:01 +00:00
- returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
This method runs `document.querySelector` within the page and passes it as the first argument to `pageFunction`. If there's no element matching `selector`, the method throws an error.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
If `pageFunction` returns a [Promise], then `page.$eval` would wait for the promise to resolve and return its value.
Implement page.$eval (#638) This patch: - implements page.$eval and frame.$eval - drops elementHandle.attribute() method in favor of the page.$eval References #625
2017-08-31 22:38:01 +00:00
Examples:
```js
const searchValue = await page.$eval('#search', el => el.value);
const preloadHref = await page.$eval('link[rel=preload]', el => el.href);
const html = await page.$eval('.main-container', e => e.outerHTML);
```
Shortcut for [page.mainFrame().$eval(selector, pageFunction)](#frameevalselector-pagefunction-args).
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
#### page.$x(expression)
- `expression` <[string]> Expression to [evaluate](https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate).
- returns: <[Promise]<[Array]<[ElementHandle]>>>
docs(api.md): fix typo on api docs (#1849)
2018-01-19 05:19:43 +00:00
The method evaluates the XPath expression.
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
docs(api.md): fix some links (#2253)
2018-03-28 20:18:59 +00:00
Shortcut for [page.mainFrame().$x(expression)](#framexexpression)
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
#### page.addScriptTag(options)
- `options` <[Object]>
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- `url` <[string]> URL of a script to be added.
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
- `path` <[string]> Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
- `content` <[string]> Raw JavaScript content to be injected into frame.
feat(FrameManager): add type=module to addScriptTag (#2090) This patch adds a new "type" option to the `addScriptTag` method that allows adding "module" tags to the page. Fixes #2078
2018-03-14 20:07:48 +00:00
- `type` <[string]> Script type. Use 'module' in order to load a Javascript ES6 module. See [script](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) for more details.
docs(api.md): fix return values of page.add*Tag() (#1269)
2017-11-03 16:32:17 +00:00
- returns: <[Promise]<[ElementHandle]>> which resolves to the added tag when the script's onload fires or when the script content was injected into frame.
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
Adds a `<script>` tag into the page with the desired url or content.
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
Shortcut for [page.mainFrame().addScriptTag(options)](#frameaddscripttagoptions).
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.
2017-06-13 07:28:29 +00:00
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
#### page.addStyleTag(options)
- `options` <[Object]>
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- `url` <[string]> URL of the `<link>` tag.
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
- `path` <[string]> Path to the CSS file to be injected into frame. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
- `content` <[string]> Raw CSS content to be injected into frame.
docs(api.md): fix return values of page.add*Tag() (#1269)
2017-11-03 16:32:17 +00:00
- returns: <[Promise]<[ElementHandle]>> which resolves to the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.
feat(Frame): Add `addStyleTag` API to frame - fixes #892 (#947) This patch adds `Page.addStyleTag` and `Frame.addStyleTag` methods to the API. Fixes #892.
2017-10-04 20:42:26 +00:00
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
Adds a `<link rel="stylesheet">` tag into the page with the desired url or a `<style type="text/css">` tag with the content.
feat(Frame): Add `addStyleTag` API to frame - fixes #892 (#947) This patch adds `Page.addStyleTag` and `Frame.addStyleTag` methods to the API. Fixes #892.
2017-10-04 20:42:26 +00:00
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
Shortcut for [page.mainFrame().addStyleTag(options)](#frameaddstyletagoptions).
feat(Frame): Add `addStyleTag` API to frame - fixes #892 (#947) This patch adds `Page.addStyleTag` and `Frame.addStyleTag` methods to the API. Fixes #892.
2017-10-04 20:42:26 +00:00
[api] Implement page.authenticate method (#729) This patch implements `page.authenticate` which should cover all cases of HTTP authentication. Fixes #426.
2017-09-11 23:32:13 +00:00
#### page.authenticate(credentials)
docs(api.md): fix return signatures that contains null (#1364)
2017-11-15 18:53:17 +00:00
- `credentials` <?[Object]>
[api] Implement page.authenticate method (#729) This patch implements `page.authenticate` which should cover all cases of HTTP authentication. Fixes #426.
2017-09-11 23:32:13 +00:00
- `username` <[string]>
- `password` <[string]>
- returns: <[Promise]>
Provide credentials for [http authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).
To disable authentication, pass `null`.
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
feat(Page): introduce Page bringToFront method (#1252) This patch introduces Page.bringToFront method to activate tabs. Fixes #1244
2017-11-07 21:17:36 +00:00
#### page.bringToFront()
- returns: <[Promise]>
Brings page to front (activates tab).
Mouse (#101) This patch: - adds Mouse class which holds mouse state and implements mouse primitives, such as moving, button down and button up. - implements high-level mouse api, such as `page.click` and `page.hover`. References #40, References #89
2017-07-22 03:29:31 +00:00
#### page.click(selector[, options])
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `selector` <[string]> A [selector] to search for element to click. If there are multiple elements satisfying the selector, the first will be clicked.
Mouse (#101) This patch: - adds Mouse class which holds mouse state and implements mouse primitives, such as moving, button down and button up. - implements high-level mouse api, such as `page.click` and `page.hover`. References #40, References #89
2017-07-22 03:29:31 +00:00
- `options` <[Object]>
- `button` <[string]> `left`, `right`, or `middle`, defaults to `left`.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `clickCount` <[number]> defaults to 1. See [UIEvent.detail].
Add delay option to input methods (#171) Add delay option to input methods for the keyboard and mouse. Closes #156
2017-08-01 01:18:15 +00:00
- `delay` <[number]> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully clicked. The Promise will be rejected if there is no element matching `selector`.
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
doc: fix descriptions of certain page methods (#424) This patch fixes descriptions of: - page.click() - page.focus() - page.hover() Fixes #397
2017-08-20 23:03:14 +00:00
This method fetches an element with `selector`, scrolls it into view if needed, and then uses [page.mouse](#pagemouse) to click in the center of the element.
If there's no element matching `selector`, the method throws an error.
Fill doc with stubs for missing documentation methods. This patch fills doc with stubs so that the command `npm run doc` does not complain.
2017-07-07 17:34:35 +00:00
docs(api.md): fix minor spelling errors (#2314)
2018-04-05 20:08:28 +00:00
Bear in mind that if `click()` triggers a navigation event and there's a separate `page.waitForNavigation()` promise to be resolved, you may end up with a race condition that yields unexpected results. The correct pattern for click and wait for navigation is the following:
docs(api.md): added page.click + waitForNavigation example (#1792) Fixes #1421.
2018-01-12 19:41:26 +00:00
```javascript
const [response] = await Promise.all([
docs(api): fix coverage example and typo (#1854)
2018-01-19 05:19:13 +00:00
page.waitForNavigation(waitOptions),
page.click(selector, clickOptions),
docs(api.md): added page.click + waitForNavigation example (#1792) Fixes #1421.
2018-01-12 19:41:26 +00:00
]);
```
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
Shortcut for [page.mainFrame().click(selector[, options])](#frameclickselector-options).
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
#### page.close()
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- returns: <[Promise]>
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.
2017-06-13 07:28:29 +00:00
Add Page.content() method. Fixes #406. (#419)
2017-08-21 16:02:30 +00:00
#### page.content()
- returns: <[Promise]<[String]>>
Gets the full HTML contents of the page, including the doctype.
Cookies (#314) Introduce cookies API. Fixes #53.
2017-08-24 19:21:46 +00:00
#### page.cookies(...urls)
- `...urls` <...[string]>
- returns: <[Promise]<[Array]<[Object]>>>
- `name` <[string]>
- `value` <[string]>
- `domain` <[string]>
- `path` <[string]>
- `expires` <[number]> Unix time in seconds.
- `httpOnly` <[boolean]>
- `secure` <[boolean]>
docs: add missing session cookie property to api.md (#1672) The session value is returned from the protocol, but not accepted as a cookie parameter. Fixes #980.
2017-12-28 02:58:57 +00:00
- `session` <[boolean]>
Cookies (#314) Introduce cookies API. Fixes #53.
2017-08-24 19:21:46 +00:00
- `sameSite` <[string]> `"Strict"` or `"Lax"`.
If no URLs are specified, this method returns cookies for the current page URL.
If URLs are specified, only cookies for those URLs are returned.
feat: Implement JavaScript Coverage (#1673) This patch introduces a new `page.coverage` namespace with two methods: - `page.coverage.startJSCoverage` to initiate JavaScript coverage recording - `page.coverage.stopJSCoverage` to stop JavaScript coverage and get results
2018-01-03 03:53:53 +00:00
#### page.coverage
- returns: <[Coverage]>
Cookies (#314) Introduce cookies API. Fixes #53.
2017-08-24 19:21:46 +00:00
#### page.deleteCookie(...cookies)
- `...cookies` <...[Object]>
- `name` <[string]> **required**
- `url` <[string]>
- `domain` <[string]>
- `path` <[string]>
- `secure` <[boolean]>
- returns: <[Promise]>
Introduce page.emulate convenience wrapper (#231) This patch: - introduces Page.emulate convenience wrapper - adds a screenshot-fullPage.js example
2017-08-11 01:42:30 +00:00
#### page.emulate(options)
- `options` <[Object]>
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `viewport` <[Object]>
- `width` <[number]> page width in pixels.
- `height` <[number]> page height in pixels.
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
- `deviceScaleFactor` <[number]> Specify device scale factor (can be thought of as dpr). Defaults to `1`.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `isMobile` <[boolean]> Whether the `meta viewport` tag is taken into account. Defaults to `false`.
- `hasTouch`<[boolean]> Specifies if viewport supports touch events. Defaults to `false`
- `isLandscape` <[boolean]> Specifies if viewport is in landscape mode. Defaults to `false`.
- `userAgent` <[string]>
- returns: <[Promise]>
Introduce page.emulate convenience wrapper (#231) This patch: - introduces Page.emulate convenience wrapper - adds a screenshot-fullPage.js example
2017-08-11 01:42:30 +00:00
Move emulation documentation under `page.emulate` method. (#253)
2017-08-13 07:47:01 +00:00
Emulates given device metrics and user agent. This method is a shortcut for calling two methods:
- [page.setUserAgent(userAgent)](#pagesetuseragentuseragent)
- [page.setViewport(viewport)](#pagesetviewportviewport)
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
To aid emulation, puppeteer provides a list of device descriptors which can be obtained via the `require('puppeteer/DeviceDescriptors')` command.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
Below is an example of emulating an iPhone 6 in puppeteer:
Move emulation documentation under `page.emulate` method. (#253)
2017-08-13 07:47:01 +00:00
```js
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
const puppeteer = require('puppeteer');
Move emulation documentation under `page.emulate` method. (#253)
2017-08-13 07:47:01 +00:00
const devices = require('puppeteer/DeviceDescriptors');
const iPhone = devices['iPhone 6'];
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
puppeteer.launch().then(async browser => {
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const page = await browser.newPage();
Move emulation documentation under `page.emulate` method. (#253)
2017-08-13 07:47:01 +00:00
await page.emulate(iPhone);
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
await page.goto('https://www.google.com');
Move emulation documentation under `page.emulate` method. (#253)
2017-08-13 07:47:01 +00:00
// other actions...
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
Move emulation documentation under `page.emulate` method. (#253)
2017-08-13 07:47:01 +00:00
});
```
List of all available devices is available in the source code: [DeviceDescriptors.js](https://github.com/GoogleChrome/puppeteer/blob/master/DeviceDescriptors.js).
Introduce page.emulate convenience wrapper (#231) This patch: - introduces Page.emulate convenience wrapper - adds a screenshot-fullPage.js example
2017-08-11 01:42:30 +00:00
Introduce page.emulateMedia method (#383) Emulating `screen` media would force `page.pdf()` to print with `screen` media. Fixes #312
2017-08-18 23:49:02 +00:00
#### page.emulateMedia(mediaType)
chore: Spelling and Markdown Consistency (#1998) - Adding missing language tags to markdown code blocks. - Fixed various spelling mistakes my IDE complained to me about.
2018-02-09 03:59:46 +00:00
- `mediaType` <?[string]> Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`. Passing `null` disables media emulation.
- returns: <[Promise]>
Introduce page.emulateMedia method (#383) Emulating `screen` media would force `page.pdf()` to print with `screen` media. Fixes #312
2017-08-18 23:49:02 +00:00
[doc] distinct naming for functions which are evaluated in page context This patch renames all the function parameters which are executed in page context into 'pageFunction'.
2017-07-14 20:51:22 +00:00
#### page.evaluate(pageFunction, ...args)
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `pageFunction` <[function]|[string]> Function to be evaluated in the page context
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
- returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
If the function passed to the `page.evaluate` returns a [Promise], then `page.evaluate` would wait for the promise to resolve and return its value.
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
If the function passed to the `page.evaluate` returns a non-[Serializable] value, then `page.evaluate` resolves to `undefined`.
fix: return undefined when Page.evaluate encounters circular JSON (#983)
2017-10-09 19:30:05 +00:00
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
Passing arguments to `pageFunction`:
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
```js
docs(API): add more explicit examples for page.evaluate (#1711)
2018-01-10 07:05:52 +00:00
const result = await page.evaluate(x => {
return Promise.resolve(8 * x);
}, 7);
[api] Teach page.evaluate to accept element handles as parameters (#725) This patch: - teaches `page.evaluate` to accept ElementHandles as parameters - removes `ElementHandle.evaluate` method since it's not needed any more References #382
2017-09-12 02:20:02 +00:00
console.log(result); // prints "56"
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
```
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
A string can also be passed in instead of a function:
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
```js
console.log(await page.evaluate('1 + 2')); // prints "3"
docs(API): add more explicit examples for page.evaluate (#1711)
2018-01-10 07:05:52 +00:00
const x = 10;
console.log(await page.evaluate(`1 + ${x}`)); // prints "11"
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
```
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.
2017-06-13 07:28:29 +00:00
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
[ElementHandle] instances can be passed as arguments to the `page.evaluate`:
[api] Teach page.evaluate to accept element handles as parameters (#725) This patch: - teaches `page.evaluate` to accept ElementHandles as parameters - removes `ElementHandle.evaluate` method since it's not needed any more References #382
2017-09-12 02:20:02 +00:00
```js
const bodyHandle = await page.$('body');
const html = await page.evaluate(body => body.innerHTML, bodyHandle);
await bodyHandle.dispose();
```
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
Shortcut for [page.mainFrame().evaluate(pageFunction, ...args)](#frameevaluatepagefunction-args).
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.
2017-06-13 07:28:29 +00:00
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
#### page.evaluateHandle(pageFunction, ...args)
- `pageFunction` <[function]|[string]> Function to be evaluated in the page context
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
- returns: <[Promise]<[JSHandle]>> Promise which resolves to the return value of `pageFunction` as in-page object (JSHandle)
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
The only difference between `page.evaluate` and `page.evaluateHandle` is that `page.evaluateHandle` returns in-page object (JSHandle).
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
If the function passed to the `page.evaluateHandle` returns a [Promise], then `page.evaluateHandle` would wait for the promise to resolve and return its value.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
A string can also be passed in instead of a function:
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
```js
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
const aHandle = await page.evaluateHandle('document'); // Handle for the 'document'
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
```
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
[JSHandle] instances can be passed as arguments to the `page.evaluateHandle`:
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
```js
const aHandle = await page.evaluateHandle(() => document.body);
const resultHandle = await page.evaluateHandle(body => body.innerHTML, aHandle);
console.log(await resultHandle.jsonValue());
await resultHandle.dispose();
```
chore(doc): fix nits after JSHandles PR (#976)
2017-10-07 15:31:55 +00:00
Shortcut for [page.mainFrame().executionContext().evaluateHandle(pageFunction, ...args)](#executioncontextevaluatehandlepagefunction-args).
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
Rename page.evaluateOnInitialized into page.evaluateOnNewDocument This patch renames page.evaluateOnInitialized into page.evaluateOnNewDocument to better align with the protocol and with what the method is actually doing. Fixes #119.
2017-07-25 07:00:25 +00:00
#### page.evaluateOnNewDocument(pageFunction, ...args)
page.evaluate takes a string in addition to function (#135) This patch improves on page.evaluate to accept a string. The string can have a trailing '//# sourceURL=' comment which would name the evaluation to make stacks beautiful. In order to make sourceURL comments possible, this patch: - removes wrapping of the client function into `Promise.resolve()` - stops passing `awaitPromise` parameter to `Runtime.evaluate` - starts to await promise via the `Runtime.awaitPromise` if the return type of the evaluation is promise closes #118
2017-07-27 19:23:41 +00:00
- `pageFunction` <[function]|[string]> Function to be evaluated in browser context
Add Serializable type into the docs (#318)
2017-08-18 03:24:11 +00:00
- `...args` <...[Serializable]> Arguments to pass to `pageFunction`
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- returns: <[Promise]>
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.
2017-06-13 07:28:29 +00:00
Rename page.evaluateOnInitialized into page.evaluateOnNewDocument This patch renames page.evaluateOnInitialized into page.evaluateOnNewDocument to better align with the protocol and with what the method is actually doing. Fixes #119.
2017-07-25 07:00:25 +00:00
Adds a function which would be invoked in one of the following scenarios:
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- whenever the page is navigated
- whenever the child frame is attached or navigated. In this case, the function is invoked in the context of the newly attached frame
Rename page.evaluateOnInitialized into page.evaluateOnNewDocument This patch renames page.evaluateOnInitialized into page.evaluateOnNewDocument to better align with the protocol and with what the method is actually doing. Fixes #119.
2017-07-25 07:00:25 +00:00
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
The function is invoked after the document was created but before any of its scripts were run. This is useful to amend the JavaScript environment, e.g. to seed `Math.random`.
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
doc(api.md): add evaluateOnNewDocument examples (#1202) Fixes #1201.
2017-11-17 18:34:20 +00:00
An example of overriding the navigator.languages property before the page loads:
```js
// preload.js
// overwrite the `languages` property to use a custom getter
Object.defineProperty(navigator, "languages", {
get: function() {
return ["en-US", "en", "bn"];
docs(api.md): Fix evaluateOnNewDocument sample syntax error (#2063)
2018-02-26 19:41:50 +00:00
}
doc(api.md): add evaluateOnNewDocument examples (#1202) Fixes #1201.
2017-11-17 18:34:20 +00:00
});
// In your puppeteer script, assuming the preload.js file is in same folder of our script
const preloadFile = fs.readFileSync('./preload.js', 'utf8');
await page.evaluateOnNewDocument(preloadFile);
```
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
#### page.exposeFunction(name, puppeteerFunction)
- `name` <[string]> Name of the function on the window object
- `puppeteerFunction` <[function]> Callback function which will be called in Puppeteer's context.
Add Serializable type into the docs (#318)
2017-08-18 03:24:11 +00:00
- returns: <[Promise]>
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
The method adds a function called `name` on the page's `window` object.
When called, the function executes `puppeteerFunction` in node.js and returns a [Promise] which resolves to the return value of `puppeteerFunction`.
If the `puppeteerFunction` returns a [Promise], it will be awaited.
> **NOTE** Functions installed via `page.exposeFunction` survive navigations.
An example of adding an `md5` function into the page:
```js
const puppeteer = require('puppeteer');
const crypto = require('crypto');
puppeteer.launch().then(async browser => {
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const page = await browser.newPage();
docs(api.md): fix exposeFunction example (#1900)
2018-01-25 22:50:42 +00:00
page.on('console', msg => console.log(msg.text()));
Make prettier JS snippets (#377) * Make prettier JS snippets * Conform to CS (about curly brace) * Apply feedback
2017-08-18 23:46:10 +00:00
await page.exposeFunction('md5', text =>
crypto.createHash('md5').update(text).digest('hex')
);
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
await page.evaluate(async () => {
// use window.md5 to compute hashes
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const myString = 'PUPPETEER';
const myHash = await window.md5(myString);
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
console.log(`md5 of ${myString} is ${myHash}`);
});
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
});
```
An example of adding a `window.readfile` function into the page:
```js
const puppeteer = require('puppeteer');
const fs = require('fs');
puppeteer.launch().then(async browser => {
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const page = await browser.newPage();
docs(api.md): fix exposeFunction example (#1900)
2018-01-25 22:50:42 +00:00
page.on('console', msg => console.log(msg.text()));
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
await page.exposeFunction('readfile', async filePath => {
return new Promise((resolve, reject) => {
fs.readFile(filePath, 'utf8', (err, text) => {
if (err)
reject(err);
else
resolve(text);
});
});
});
await page.evaluate(async () => {
// use window.readfile to read contents of a file
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const content = await window.readfile('/etc/hosts');
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
console.log(content);
});
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
});
```
[doclint] Fix bug in documentation linter This patch: - fixes a typo in documentation linter, which resulted in only certain method arguments being linted. - adds missing arguments to the documentation References #14.
2017-07-12 00:01:58 +00:00
#### page.focus(selector)
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `selector` <[string]> A [selector] of an element to focus. If there are multiple elements satisfying the selector, the first will be focused.
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully focused. The promise will be rejected if there is no element matching `selector`.
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
doc: fix descriptions of certain page methods (#424) This patch fixes descriptions of: - page.click() - page.focus() - page.hover() Fixes #397
2017-08-20 23:03:14 +00:00
This method fetches an element with `selector` and focuses it.
If there's no element matching `selector`, the method throws an error.
Fill doc with stubs for missing documentation methods. This patch fills doc with stubs so that the command `npm run doc` does not complain.
2017-07-07 17:34:35 +00:00
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
Shortcut for [page.mainFrame().focus(selector)](#framefocusselector).
Fill doc with stubs for missing documentation methods. This patch fills doc with stubs so that the command `npm run doc` does not complain.
2017-07-07 17:34:35 +00:00
#### page.frames()
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
- returns: <[Array]<[Frame]>> An array of all frames attached to the page.
Fill doc with stubs for missing documentation methods. This patch fills doc with stubs so that the command `npm run doc` does not complain.
2017-07-07 17:34:35 +00:00
Introduce page.goBack/page.goForward (#93) This patch introduces page.goBack/page.goForward methods to navigate the page history. References #89.
2017-07-19 02:11:37 +00:00
#### page.goBack(options)
Document all options objects wherever they are used (#139) This patch adds missing documentation for all the shortcut methods, such as `page.evaluate` or `page.waitForSelector`. closes #114
2017-07-26 04:01:05 +00:00
- `options` <[Object]> Navigation parameters which might have the following properties:
feat(Page): Add global navigation timeout setting (#1728) This patch introduces `page.setDefaultNavigationTimeout` method to override the default 30 seconds navigation timeout. Fixes #1514
2018-01-10 21:04:01 +00:00
- `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultNavigationTimeout(timeout)](#pagesetdefaultnavigationtimeouttimeout) method.
feat(Page): teach Page.setContent to wait for resources to load (#1152) This patch adds "options" parameter to the `page.setContent` method. The parameter is the same as a navigation parameter and allows to specify maximum timeout to wait for resources to be loaded, as well as to describe events that should be emitted before the setContent operation would be considered successful. Fixes #728.
2017-10-24 20:57:39 +00:00
- `waitUntil` <[string]|[Array]<[string]>> When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
Document all options objects wherever they are used (#139) This patch adds missing documentation for all the shortcut methods, such as `page.evaluate` or `page.waitForSelector`. closes #114
2017-07-26 04:01:05 +00:00
- `load` - consider navigation to be finished when the `load` event is fired.
feat(Page.goto): add a 'domcontentloaded' option to the Page.goto (#1145) This patch adds a new `domcontentloaded` option to a bunch of navigation methods: - Page.goto - Page.waitForNavigation - Page.goBack - Page.goForward - Page.reload Fixes #946.
2017-10-24 07:35:18 +00:00
- `domcontentloaded` - consider navigation to be finished when the `DOMContentLoaded` event is fired.
typo in api.md (#1216) more then -> more than
2017-10-31 18:30:29 +00:00
- `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.
- `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
docs(api.md): fix return signatures that contains null (#1364)
2017-11-15 18:53:17 +00:00
- returns: <[Promise]<?[Response]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. If
can not go back, resolves to `null`.
Introduce page.goBack/page.goForward (#93) This patch introduces page.goBack/page.goForward methods to navigate the page history. References #89.
2017-07-19 02:11:37 +00:00
Navigate to the previous page in history.
#### page.goForward(options)
Document all options objects wherever they are used (#139) This patch adds missing documentation for all the shortcut methods, such as `page.evaluate` or `page.waitForSelector`. closes #114
2017-07-26 04:01:05 +00:00
- `options` <[Object]> Navigation parameters which might have the following properties:
feat(Page): Add global navigation timeout setting (#1728) This patch introduces `page.setDefaultNavigationTimeout` method to override the default 30 seconds navigation timeout. Fixes #1514
2018-01-10 21:04:01 +00:00
- `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultNavigationTimeout(timeout)](#pagesetdefaultnavigationtimeouttimeout) method.
feat(Page): teach Page.setContent to wait for resources to load (#1152) This patch adds "options" parameter to the `page.setContent` method. The parameter is the same as a navigation parameter and allows to specify maximum timeout to wait for resources to be loaded, as well as to describe events that should be emitted before the setContent operation would be considered successful. Fixes #728.
2017-10-24 20:57:39 +00:00
- `waitUntil` <[string]|[Array]<[string]>> When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
Document all options objects wherever they are used (#139) This patch adds missing documentation for all the shortcut methods, such as `page.evaluate` or `page.waitForSelector`. closes #114
2017-07-26 04:01:05 +00:00
- `load` - consider navigation to be finished when the `load` event is fired.
feat(Page.goto): add a 'domcontentloaded' option to the Page.goto (#1145) This patch adds a new `domcontentloaded` option to a bunch of navigation methods: - Page.goto - Page.waitForNavigation - Page.goBack - Page.goForward - Page.reload Fixes #946.
2017-10-24 07:35:18 +00:00
- `domcontentloaded` - consider navigation to be finished when the `DOMContentLoaded` event is fired.
typo in api.md (#1216) more then -> more than
2017-10-31 18:30:29 +00:00
- `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.
- `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
docs(api.md): fix return signatures that contains null (#1364)
2017-11-15 18:53:17 +00:00
- returns: <[Promise]<?[Response]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. If
can not go back, resolves to `null`.
Introduce page.goBack/page.goForward (#93) This patch introduces page.goBack/page.goForward methods to navigate the page history. References #89.
2017-07-19 02:11:37 +00:00
Navigate to the next page in history.
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.
2017-06-13 07:28:29 +00:00
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
#### page.goto(url, options)
[doc] elaborate on `url` parameter in `page.goto`. (#504)
2017-08-23 22:34:57 +00:00
- `url` <[string]> URL to navigate page to. The url should include scheme, e.g. `https://`.
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
- `options` <[Object]> Navigation parameters which might have the following properties:
feat(Page): Add global navigation timeout setting (#1728) This patch introduces `page.setDefaultNavigationTimeout` method to override the default 30 seconds navigation timeout. Fixes #1514
2018-01-10 21:04:01 +00:00
- `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultNavigationTimeout(timeout)](#pagesetdefaultnavigationtimeouttimeout) method.
feat(Page): teach Page.setContent to wait for resources to load (#1152) This patch adds "options" parameter to the `page.setContent` method. The parameter is the same as a navigation parameter and allows to specify maximum timeout to wait for resources to be loaded, as well as to describe events that should be emitted before the setContent operation would be considered successful. Fixes #728.
2017-10-24 20:57:39 +00:00
- `waitUntil` <[string]|[Array]<[string]>> When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
- `load` - consider navigation to be finished when the `load` event is fired.
feat(Page.goto): add a 'domcontentloaded' option to the Page.goto (#1145) This patch adds a new `domcontentloaded` option to a bunch of navigation methods: - Page.goto - Page.waitForNavigation - Page.goBack - Page.goForward - Page.reload Fixes #946.
2017-10-24 07:35:18 +00:00
- `domcontentloaded` - consider navigation to be finished when the `DOMContentLoaded` event is fired.
typo in api.md (#1216) more then -> more than
2017-10-31 18:30:29 +00:00
- `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.
- `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
docs(api.md): fix return signatures that contains null (#1364)
2017-11-15 18:53:17 +00:00
- returns: <[Promise]<?[Response]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
The `page.goto` will throw an error if:
- there's an SSL error (e.g. in case of self-signed certificates).
- target URL is invalid.
- the `timeout` is exceeded during navigation.
- the main resource failed to load.
> **NOTE** `page.goto` either throw or return a main resource response. The only exception is navigation to `about:blank`, which would succeed and return `null`.
Document headless mode restriction for PDF (#836) Fixes: https://github.com/GoogleChrome/puppeteer/issues/830
2017-09-20 23:51:25 +00:00
> **NOTE** Headless mode doesn't support navigating to a PDF document. See the [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295).
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
Mouse (#101) This patch: - adds Mouse class which holds mouse state and implements mouse primitives, such as moving, button down and button up. - implements high-level mouse api, such as `page.click` and `page.hover`. References #40, References #89
2017-07-22 03:29:31 +00:00
#### page.hover(selector)
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `selector` <[string]> A [selector] to search for element to hover. If there are multiple elements satisfying the selector, the first will be hovered.
Mouse (#101) This patch: - adds Mouse class which holds mouse state and implements mouse primitives, such as moving, button down and button up. - implements high-level mouse api, such as `page.click` and `page.hover`. References #40, References #89
2017-07-22 03:29:31 +00:00
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully hovered. Promise gets rejected if there's no element matching `selector`.
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
doc: fix descriptions of certain page methods (#424) This patch fixes descriptions of: - page.click() - page.focus() - page.hover() Fixes #397
2017-08-20 23:03:14 +00:00
This method fetches an element with `selector`, scrolls it into view if needed, and then uses [page.mouse](#pagemouse) to hover over the center of the element.
If there's no element matching `selector`, the method throws an error.
Mouse (#101) This patch: - adds Mouse class which holds mouse state and implements mouse primitives, such as moving, button down and button up. - implements high-level mouse api, such as `page.click` and `page.hover`. References #40, References #89
2017-07-22 03:29:31 +00:00
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
Shortcut for [page.mainFrame().hover(selector)](#framehoverselector).
Intorduce Page.keyboard (#74) Introduce page.keyboard to provide low-level access to the keyboard.
2017-07-18 01:49:52 +00:00
#### page.keyboard
- returns: <[Keyboard]>
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
#### page.mainFrame()
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
- returns: <[Frame]> returns page's main frame.
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.
2017-06-13 07:28:29 +00:00
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
Page is guaranteed to have a main frame which persists during navigations.
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.
2017-06-13 07:28:29 +00:00
feat(Page): rename Page.getMetrics into Page.metrics (#1240) BREAKING CHANGE: method page.getMetrics() got renamed into page.metrics().
2017-11-01 20:39:31 +00:00
#### page.metrics()
- returns: <[Promise]<[Object]>> Object containing metrics as key/value pairs.
- `Timestamp` <[number]> The timestamp when the metrics sample was taken.
- `Documents` <[number]> Number of documents in the page.
- `Frames` <[number]> Number of frames in the page.
- `JSEventListeners` <[number]> Number of events in the page.
- `Nodes` <[number]> Number of DOM nodes in the page.
- `LayoutCount` <[number]> Total number of full or partial page layout.
- `RecalcStyleCount` <[number]> Total number of page style recalculations.
- `LayoutDuration` <[number]> Combined durations of all page layouts.
- `RecalcStyleDuration` <[number]> Combined duration of all page style recalculations.
- `ScriptDuration` <[number]> Combined duration of JavaScript execution.
- `TaskDuration` <[number]> Combined duration of all tasks performed by the browser.
- `JSHeapUsedSize` <[number]> Used JavaScript heap size.
- `JSHeapTotalSize` <[number]> Total JavaScript heap size.
> **NOTE** All timestamps are in monotonic time: monotonically increasing time in seconds since an arbitrary point in the past.
Mouse (#101) This patch: - adds Mouse class which holds mouse state and implements mouse primitives, such as moving, button down and button up. - implements high-level mouse api, such as `page.click` and `page.hover`. References #40, References #89
2017-07-22 03:29:31 +00:00
#### page.mouse
- returns: <[Mouse]>
Rename Page.printToPDF into page.pdf This patch: - renames Page.printToPDF into page.pdf - adds a 'path' option to the page.pdf options instead of a separate `filePath` parameter - improves on the documentation for the `page.pdf` References #39.
2017-07-17 09:06:52 +00:00
#### page.pdf(options)
- `options` <[Object]> Options object which might have the following properties:
Fix doc on pdf method. Minor addition to PDF path option docs. (#292)
2017-08-16 18:11:40 +00:00
- `path` <[string]> The file path to save the PDF to. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). If no path is provided, the PDF won't be saved to the disk.
Rename Page.printToPDF into page.pdf This patch: - renames Page.printToPDF into page.pdf - adds a 'path' option to the page.pdf options instead of a separate `filePath` parameter - improves on the documentation for the `page.pdf` References #39.
2017-07-17 09:06:52 +00:00
- `scale` <[number]> Scale of the webpage rendering. Defaults to `1`.
- `displayHeaderFooter` <[boolean]> Display header and footer. Defaults to `false`.
feat(pdf): add `headerTemplate` and `footerTemplate` to available PDF options (#1625) This patch allows specifying header and footer templates for PDF printing. Fixes #373.
2017-12-20 00:54:34 +00:00
- `headerTemplate` <[string]> HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them:
- `date` formatted print date
- `title` document title
- `url` document location
- `pageNumber` current page number
- `totalPages` total pages in the document
- `footerTemplate` <[string]> HTML template for the print footer. Should use the same format as the `headerTemplate`.
Rename Page.printToPDF into page.pdf This patch: - renames Page.printToPDF into page.pdf - adds a 'path' option to the page.pdf options instead of a separate `filePath` parameter - improves on the documentation for the `page.pdf` References #39.
2017-07-17 09:06:52 +00:00
- `printBackground` <[boolean]> Print background graphics. Defaults to `false`.
- `landscape` <[boolean]> Paper orientation. Defaults to `false`.
- `pageRanges` <[string]> Paper ranges to print, e.g., '1-5, 8, 11-13'. Defaults to the empty string, which means print all pages.
- `format` <[string]> Paper format. If set, takes priority over `width` or `height` options. Defaults to 'Letter'.
- `width` <[string]> Paper width, accepts values labeled with units.
- `height` <[string]> Paper height, accepts values labeled with units.
- `margin` <[Object]> Paper margins, defaults to none.
- `top` <[string]> Top margin, accepts values labeled with units.
- `right` <[string]> Right margin, accepts values labeled with units.
- `bottom` <[string]> Bottom margin, accepts values labeled with units.
- `left` <[string]> Left margin, accepts values labeled with units.
- returns: <[Promise]<[Buffer]>> Promise which resolves with PDF buffer.
readme: move up note about Page.pdf working on headless only (#577) Hard to find. From https://github.com/GoogleChrome/puppeteer/issues/576
2017-08-28 17:31:35 +00:00
> **NOTE** Generating a pdf is currently only supported in Chrome headless.
Introduce page.emulateMedia method (#383) Emulating `screen` media would force `page.pdf()` to print with `screen` media. Fixes #312
2017-08-18 23:49:02 +00:00
`page.pdf()` generates a pdf of the page with `print` css media. To generate a pdf with `screen` media, call [page.emulateMedia('screen')](#pageemulatemediamediatype) before calling `page.pdf()`:
```js
// Generates a PDF with 'screen' media type.
await page.emulateMedia('screen');
await page.pdf({path: 'page.pdf'});
```
Rename Page.printToPDF into page.pdf This patch: - renames Page.printToPDF into page.pdf - adds a 'path' option to the page.pdf options instead of a separate `filePath` parameter - improves on the documentation for the `page.pdf` References #39.
2017-07-17 09:06:52 +00:00
The `width`, `height`, and `margin` options accept values labeled with units. Unlabeled values are treated as pixels.
A few examples:
- `page.pdf({width: 100})` - prints with width set to 100 pixels
- `page.pdf({width: '100px'})` - prints with width set to 100 pixels
- `page.pdf({width: '10cm'})` - prints with width set to 10 centimeters.
All possible units are:
- `px` - pixel
- `in` - inch
- `cm` - centimeter
- `mm` - millimeter
The `format` options are:
- `Letter`: 8.5in x 11in
- `Legal`: 8.5in x 14in
- `Tabloid`: 11in x 17in
- `Ledger`: 17in x 11in
- `A0`: 33.1in x 46.8in
- `A1`: 23.4in x 33.1in
- `A2`: 16.5in x 23.4in
- `A3`: 11.7in x 16.5in
- `A4`: 8.27in x 11.7in
- `A5`: 5.83in x 8.27in
feat(Page.pdf): add 'A6' page format This patch adds 'A6' page format option to the Page.pdf method.
2017-10-11 20:18:14 +00:00
- `A6`: 4.13in x 5.83in
Rename Page.printToPDF into page.pdf This patch: - renames Page.printToPDF into page.pdf - adds a 'path' option to the page.pdf options instead of a separate `filePath` parameter - improves on the documentation for the `page.pdf` References #39.
2017-07-17 09:06:52 +00:00
feat(Page): introduce Page.queryObjects (#1005) This patch introduces `Page.queryObjects` and `ExecutionContext.queryObjects` methods to query JavaScript heap for objects with a certain prototype. Fixes #304.
2017-10-11 21:41:20 +00:00
#### page.queryObjects(prototypeHandle)
- `prototypeHandle` <[JSHandle]> A handle to the object prototype.
docs(api): `queryObjects` returns a Promise<JSHandle> (#1053)
2017-10-17 00:11:05 +00:00
- returns: <[Promise]<[JSHandle]>> Promise which resolves to a handle to an array of objects with this prototype.
feat(Page): introduce Page.queryObjects (#1005) This patch introduces `Page.queryObjects` and `ExecutionContext.queryObjects` methods to query JavaScript heap for objects with a certain prototype. Fixes #304.
2017-10-11 21:41:20 +00:00
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
The method iterates the JavaScript heap and finds all the objects with the given prototype.
feat(Page): introduce Page.queryObjects (#1005) This patch introduces `Page.queryObjects` and `ExecutionContext.queryObjects` methods to query JavaScript heap for objects with a certain prototype. Fixes #304.
2017-10-11 21:41:20 +00:00
```js
Roll chromium to 508268 (#1019) This gets us: - Plural metrics names https://crrev.com/507885 - TargetInfoChanged on URL changes https://crrev.com/508049 - Sending proper resource types for requests https://crrev.com/667504 Fixes #734
2017-10-12 08:17:06 +00:00
// Create a Map object
feat(Page): introduce Page.queryObjects (#1005) This patch introduces `Page.queryObjects` and `ExecutionContext.queryObjects` methods to query JavaScript heap for objects with a certain prototype. Fixes #304.
2017-10-11 21:41:20 +00:00
await page.evaluate(() => window.map = new Map());
// Get a handle to the Map object prototype
const mapPrototype = await page.evaluateHandle(() => Map.prototype);
// Query all map instances into an array
const mapInstances = await page.queryObjects(mapPrototype);
// Count amount of map objects in heap
const count = await page.evaluate(maps => maps.length, mapInstances);
await mapInstances.dispose();
await mapPrototype.dispose();
```
Shortcut for [page.mainFrame().executionContext().queryObjects(prototypeHandle)](#executioncontextqueryobjectsprototypehandle).
Introduce Page.waitForNavigation (#94) This patch introduces Page.waitForNavigation which allows to wait for render-initiated navigation. This patch also does a nice refactoring, replacing Navigator with NavigatorWatcher which is not a part of a page state. References #89
2017-07-19 01:54:24 +00:00
#### page.reload(options)
Document all options objects wherever they are used (#139) This patch adds missing documentation for all the shortcut methods, such as `page.evaluate` or `page.waitForSelector`. closes #114
2017-07-26 04:01:05 +00:00
- `options` <[Object]> Navigation parameters which might have the following properties:
feat(Page): Add global navigation timeout setting (#1728) This patch introduces `page.setDefaultNavigationTimeout` method to override the default 30 seconds navigation timeout. Fixes #1514
2018-01-10 21:04:01 +00:00
- `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultNavigationTimeout(timeout)](#pagesetdefaultnavigationtimeouttimeout) method.
feat(Page): teach Page.setContent to wait for resources to load (#1152) This patch adds "options" parameter to the `page.setContent` method. The parameter is the same as a navigation parameter and allows to specify maximum timeout to wait for resources to be loaded, as well as to describe events that should be emitted before the setContent operation would be considered successful. Fixes #728.
2017-10-24 20:57:39 +00:00
- `waitUntil` <[string]|[Array]<[string]>> When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
Document all options objects wherever they are used (#139) This patch adds missing documentation for all the shortcut methods, such as `page.evaluate` or `page.waitForSelector`. closes #114
2017-07-26 04:01:05 +00:00
- `load` - consider navigation to be finished when the `load` event is fired.
feat(Page.goto): add a 'domcontentloaded' option to the Page.goto (#1145) This patch adds a new `domcontentloaded` option to a bunch of navigation methods: - Page.goto - Page.waitForNavigation - Page.goBack - Page.goForward - Page.reload Fixes #946.
2017-10-24 07:35:18 +00:00
- `domcontentloaded` - consider navigation to be finished when the `DOMContentLoaded` event is fired.
typo in api.md (#1216) more then -> more than
2017-10-31 18:30:29 +00:00
- `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.
- `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
Add emulation for named devices. (#72) This patch introduces page emulation, making it possible to emulate different devices.
2017-07-18 01:13:04 +00:00
- returns: <[Promise]<[Response]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
Fix readme example
2017-06-19 22:01:14 +00:00
#### page.screenshot([options])
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.
2017-06-21 18:17:35 +00:00
- `options` <[Object]> Options object which might have the following properties:
chore: Spelling and Markdown Consistency (#1998) - Adding missing language tags to markdown code blocks. - Fixed various spelling mistakes my IDE complained to me about.
2018-02-09 03:59:46 +00:00
- `path` <[string]> The file path to save the image to. The screenshot type will be inferred from file extension. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). If no path is provided, the image won't be saved to the disk.
- `type` <[string]> Specify screenshot type, can be either `jpeg` or `png`. Defaults to 'png'.
- `quality` <[number]> The quality of the image, between 0-100. Not applicable to `png` images.
- `fullPage` <[boolean]> When true, takes a screenshot of the full scrollable page. Defaults to `false`.
- `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
- `omitBackground` <[boolean]> Hides default white background and allows capturing screenshots with transparency. Defaults to `false`.
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.
2017-06-21 18:17:35 +00:00
- returns: <[Promise]<[Buffer]>> Promise which resolves to buffer with captured screenshot
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.
2017-06-13 07:28:29 +00:00
[api] Introduce Page.select method (#779) This patch adds `Page.select` method to select values in a `select` tag.
2017-09-25 09:23:34 +00:00
#### page.select(selector, ...values)
- `selector` <[string]> A [selector] to query page for
- `...values` <...[string]> Values of options to select. If the `<select>` has the `multiple` attribute, all values are considered, otherwise only the first one is taken into account.
feat(Page.select): return selected options from Page.select (#1099) This patch teaches Page.select to return an array of actually selected options. If no option is selected, an empty array will be returned.
2017-11-01 04:47:52 +00:00
- returns: <[Promise]<[Array]<[string]>>> Returns an array of option values that have been successfully selected.
[api] Introduce Page.select method (#779) This patch adds `Page.select` method to select values in a `select` tag.
2017-09-25 09:23:34 +00:00
Triggers a `change` and `input` event once all the provided options have been selected.
feat(Frame): introduce Frame.select This patch adds `Frame.select` method that does the same functionality as former `Page.select`, but on a per-frame level. The `Page.select` method becomes a shortcut for the ÷main frame's select. Fixes #1139
2017-11-02 05:06:04 +00:00
If there's no `<select>` element matching `selector`, the method throws an error.
[api] Introduce Page.select method (#779) This patch adds `Page.select` method to select values in a `select` tag.
2017-09-25 09:23:34 +00:00
```js
page.select('select#colors', 'blue'); // single selection
page.select('select#colors', 'red', 'green', 'blue'); // multiple selections
```
docs(api.md): add missing parentheses after page.mainFrame (#1738)
2018-01-09 01:20:02 +00:00
Shortcut for [page.mainFrame().select()](#frameselectselector-values)
feat(Frame): introduce Frame.select This patch adds `Frame.select` method that does the same functionality as former `Page.select`, but on a per-frame level. The `Page.select` method becomes a shortcut for the ÷main frame's select. Fixes #1139
2017-11-02 05:06:04 +00:00
feat(Page): introduce Page.setBypassCSP (#2324) This patch introduces `page.setBypassCSP` method that allows clients to ignore Content-Security-Policy for a given page. Fixes #1229.
2018-04-06 23:35:50 +00:00
#### page.setBypassCSP(enabled)
- `enabled` <[boolean]> sets bypassing of page's Content-Security-Policy.
- returns: <[Promise]>
Toggles bypassing page's Content-Security-Policy.
> **NOTE** CSP bypassing happens at the moment of CSP initialization rather then evaluation. Usually this means
that `page.setBypassCSP` should be called before navigating to the domain.
feat(Page): add `setCacheEnabled(enabled)` to Page object (#1609) This change adds in the `Page.setCacheEnabled(enabled)` method to toggle ignoring cache for each request. Fixes #1556.
2018-02-08 05:58:48 +00:00
#### page.setCacheEnabled(enabled)
- `enabled` <[boolean]> sets the `enabled` state of the cache.
- returns: <[Promise]>
Toggles ignoring cache for each request based on the enabled state. By default, caching is enabled.
Revert "feat(Page): teach Page.setContent to wait for resources to load (#1152)" (#1312) This reverts commit 80ee46942908054dea3bc14e6505bc12718e0b2d. Lifecycle events are not ready yet to support the setContent scenario. The prerequisite for this is https://chromium-review.googlesource.com/c/chromium/src/+/747805 that might not land soon due to technical concerns.
2017-11-07 22:18:05 +00:00
#### page.setContent(html)
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
- `html` <[string]> HTML markup to assign to the page.
Revert "feat(Page): teach Page.setContent to wait for resources to load (#1152)" (#1312) This reverts commit 80ee46942908054dea3bc14e6505bc12718e0b2d. Lifecycle events are not ready yet to support the setContent scenario. The prerequisite for this is https://chromium-review.googlesource.com/c/chromium/src/+/747805 that might not land soon due to technical concerns.
2017-11-07 22:18:05 +00:00
- returns: <[Promise]>
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.
2017-06-13 07:28:29 +00:00
Cookies (#314) Introduce cookies API. Fixes #53.
2017-08-24 19:21:46 +00:00
#### page.setCookie(...cookies)
- `...cookies` <...[Object]>
- `name` <[string]> **required**
- `value` <[string]> **required**
- `url` <[string]>
- `domain` <[string]>
- `path` <[string]>
- `expires` <[number]> Unix time in seconds.
- `httpOnly` <[boolean]>
- `secure` <[boolean]>
- `sameSite` <[string]> `"Strict"` or `"Lax"`.
- returns: <[Promise]>
feat(Page): Add global navigation timeout setting (#1728) This patch introduces `page.setDefaultNavigationTimeout` method to override the default 30 seconds navigation timeout. Fixes #1514
2018-01-10 21:04:01 +00:00
#### page.setDefaultNavigationTimeout(timeout)
- `timeout` <[number]> Maximum navigation time in milliseconds
This setting will change the default maximum navigation time of 30 seconds for the following methods:
- [page.goto(url, options)](#pagegotourl-options)
- [page.goBack(options)](#pagegobackoptions)
- [page.goForward(options)](#pagegoforwardoptions)
- [page.reload(options)](#pagereloadoptions)
- [page.waitForNavigation(options)](#pagewaitfornavigationoptions)
Rename page.setHTTPHeaders into page.setExtraHTTPHeaders This patch: - renames page.setHTTPHeaders into page.setExtraHTTPHeaders - starts using Map instead of Object to align with other headers arguments Fixes #112.
2017-07-27 19:25:52 +00:00
#### page.setExtraHTTPHeaders(headers)
Assert that all extra HTTP header values are strings (#781) Since protocol ignores all HTTP headers that don't have string value, this patch starts validating header key-values before sending them over the protocol. Fixes #713.
2017-09-15 02:08:48 +00:00
- `headers` <[Object]> An object containing additional http headers to be sent with every request. All header values must be strings.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- returns: <[Promise]>
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
Rename page.setHTTPHeaders into page.setExtraHTTPHeaders This patch: - renames page.setHTTPHeaders into page.setExtraHTTPHeaders - starts using Map instead of Object to align with other headers arguments Fixes #112.
2017-07-27 19:25:52 +00:00
The extra HTTP headers will be sent with every request the page initiates.
> **NOTE** page.setExtraHTTPHeaders does not guarantee the order of headers in the outgoing requests.
Implement page.setJavaScriptEnabled method Fixes #462.
2017-08-23 21:08:56 +00:00
#### page.setJavaScriptEnabled(enabled)
fix a typo in the api.md (#505)
2017-08-23 21:29:47 +00:00
- `enabled` <[boolean]> Whether or not to enable JavaScript on the page.
Implement page.setJavaScriptEnabled method Fixes #462.
2017-08-23 21:08:56 +00:00
- returns: <[Promise]>
> **NOTE** changing this value won't affect scripts that have already been run. It will take full effect on the next [navigation](#pagegotourl-options).
Implement browser 'ignoreHTTPSErrors' option. (#177) This patch implements Browser 'ignoreHTTPSErrors' option. Fixes #84.
2017-08-01 22:17:57 +00:00
feat(Page): implement page.setOfflineMode (#1032) This patch implements page.setOfflineMode method. Fixes #63.
2017-10-13 21:41:39 +00:00
#### page.setOfflineMode(enabled)
- `enabled` <[boolean]> When `true`, enables offline mode for the page.
- returns: <[Promise]>
feat(Chromium): Roll chromium to r511134 (#1153) This roll includes: - crrev.com/510651 that changes request interception methods in protocol - s/Page.setRequestInterceptionEnabled/Page.setRequestInterception BREAKING CHANGE Page.setRequestInterceptionEnabled is renamed into Page.setRequestInterception.
2017-10-24 21:45:03 +00:00
#### page.setRequestInterception(value)
Introduce new interception API (#242) This patch introduces new interception API, via killing InterceptedRequest and giving the `abort` and `continue` methods to the Request object.
2017-08-12 00:24:31 +00:00
- `value` <[boolean]> Whether to enable request interception.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- returns: <[Promise]>
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
feat(interception): Implement request.mockResponse method (#1064) feat(interception): Implement request.respond method This patch implements a new Request.respond method. This allows users to fulfill the intercepted request with a hand-crafted response if they wish so. References #1020.
2017-10-20 23:55:15 +00:00
Activating request interception enables `request.abort`, `request.continue` and
`request.respond` methods.
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
feat(interception): Implement request.mockResponse method (#1064) feat(interception): Implement request.respond method This patch implements a new Request.respond method. This allows users to fulfill the intercepted request with a hand-crafted response if they wish so. References #1020.
2017-10-20 23:55:15 +00:00
An example of a naïve request interceptor that aborts all image requests:
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
```js
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
const puppeteer = require('puppeteer');
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
puppeteer.launch().then(async browser => {
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const page = await browser.newPage();
feat(Chromium): Roll chromium to r511134 (#1153) This roll includes: - crrev.com/510651 that changes request interception methods in protocol - s/Page.setRequestInterceptionEnabled/Page.setRequestInterception BREAKING CHANGE Page.setRequestInterceptionEnabled is renamed into Page.setRequestInterception.
2017-10-24 21:45:03 +00:00
await page.setRequestInterception(true);
update code example: setRequestInterceptionEnabled (#294)
2017-08-16 18:19:13 +00:00
page.on('request', interceptedRequest => {
docs(api.md): Fix sample code in API doc (#1821) Because `Request.url` is changed to `Request.url()`.
2018-01-19 05:39:50 +00:00
if (interceptedRequest.url().endsWith('.png') || interceptedRequest.url().endsWith('.jpg'))
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
interceptedRequest.abort();
else
interceptedRequest.continue();
});
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
await page.goto('https://example.com');
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
});
```
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
fix(interception): Disable newtork caching when intercepting (#1154) Request interception might not work properly if caching is enabled.
2017-10-24 22:14:25 +00:00
> **NOTE** Enabling request interception disables page caching.
Implement NetworkManager This patch implements NetworkManager, which encapsulates all the interaction with Network domain. The NetworkManager also uses partial implementation of Request and Response classes, defined in the Fetch API specification. References #26
2017-06-29 06:09:28 +00:00
#### page.setUserAgent(userAgent)
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
- `userAgent` <[string]> Specific user agent to use in this page
- returns: <[Promise]> Promise which resolves when the user agent is set.
Add emulation for named devices. (#72) This patch introduces page emulation, making it possible to emulate different devices.
2017-07-18 01:13:04 +00:00
#### page.setViewport(viewport)
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `viewport` <[Object]>
- `width` <[number]> page width in pixels.
- `height` <[number]> page height in pixels.
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
- `deviceScaleFactor` <[number]> Specify device scale factor (can be thought of as dpr). Defaults to `1`.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `isMobile` <[boolean]> Whether the `meta viewport` tag is taken into account. Defaults to `false`.
- `hasTouch`<[boolean]> Specifies if viewport supports touch events. Defaults to `false`
- `isLandscape` <[boolean]> Specifies if viewport is in landscape mode. Defaults to `false`.
- returns: <[Promise]>
Get rid of page.emulate() / page.emulatedDevices() methods This patch: - gets rid of `page.emulate` and `page.emulatedDevices` methods. Instead, it is suggested to use `page.setViewport()` and `page.setUserAgent()` methods. - moves DeviceDescriptors to the top level of the puppeteer so that it is convenient to require them. - improves on documentation to describe the suggested emulation approach. References #88.
2017-07-21 01:14:43 +00:00
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
> **NOTE** in certain cases, setting viewport will reload the page in order to set the `isMobile` or `hasTouch` properties.
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
In the case of multiple pages in a single browser, each page can have its own viewport size.
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.
2017-06-13 07:28:29 +00:00
[api] add touchScreen.tap (#639) This patch: - adds `page.touchscreen` namespace, similar to `page.mouse` and `page.keyboard`. - adds tapping to multiple layers: - `page.touchscreen.tap` - `page.tap` - convenience method which accepts selector - `elementHandle.tap` Fixes #568 and #569.
2017-09-02 02:03:51 +00:00
#### page.tap(selector)
- `selector` <[string]> A [selector] to search for element to tap. If there are multiple elements satisfying the selector, the first will be tapped.
- returns: <[Promise]>
This method fetches an element with `selector`, scrolls it into view if needed, and then uses [page.touchscreen](#pagetouchscreen) to tap in the center of the element.
If there's no element matching `selector`, the method throws an error.
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
Shortcut for [page.mainFrame().tap(selector)](#frametapselector).
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
#### page.target()
- returns: <[Target]> a target this page was created from.
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
#### page.title()
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.
2017-06-21 18:17:35 +00:00
- returns: <[Promise]<[string]>> Returns page's title.
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
Shortcut for [page.mainFrame().title()](#frametitle).
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.
2017-06-13 07:28:29 +00:00
[api] add touchScreen.tap (#639) This patch: - adds `page.touchscreen` namespace, similar to `page.mouse` and `page.keyboard`. - adds tapping to multiple layers: - `page.touchscreen.tap` - `page.tap` - convenience method which accepts selector - `elementHandle.tap` Fixes #568 and #569.
2017-09-02 02:03:51 +00:00
#### page.touchscreen
- returns: <[Touchscreen]>
Introduce page.tracing (#181) This patch introduces page.tracing, which allows to start and stop trace recording for a page. The trace could be then saved to file.
2017-08-02 17:45:11 +00:00
#### page.tracing
- returns: <[Tracing]>
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
#### page.type(selector, text[, options])
- `selector` <[string]> A [selector] of an element to type into. If there are multiple elements satisfying the selector, the first will be used.
[doclint] Fix bug in documentation linter This patch: - fixes a typo in documentation linter, which resulted in only certain method arguments being linted. - adds missing arguments to the documentation References #14.
2017-07-12 00:01:58 +00:00
- `text` <[string]> A text to type into a focused element.
Add delay option to input methods (#171) Add delay option to input methods for the keyboard and mouse. Closes #156
2017-08-01 01:18:15 +00:00
- `options` <[Object]>
- `delay` <[number]> Time to wait between key presses in milliseconds. Defaults to 0.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- returns: <[Promise]>
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.
2017-06-13 07:28:29 +00:00
Remove keyboard.type and keyboard.press (#98) This patch removes keyboard.type and keyboard.press methods. The motivation behind this is to keep only low-level API in the `keyboard` namespace.
2017-07-22 03:00:09 +00:00
Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
chore(doc): fix a link (#977)
2017-10-07 15:32:40 +00:00
To press a special key, like `Control` or `ArrowDown`, use [`keyboard.press`](#keyboardpresskey-options).
Remove keyboard.type and keyboard.press (#98) This patch removes keyboard.type and keyboard.press methods. The motivation behind this is to keep only low-level API in the `keyboard` namespace.
2017-07-22 03:00:09 +00:00
Add delay option to input methods (#171) Add delay option to input methods for the keyboard and mouse. Closes #156
2017-08-01 01:18:15 +00:00
```js
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
page.type('#mytextarea', 'Hello'); // Types instantly
page.type('#mytextarea', 'World', {delay: 100}); // Types slower, like a user
Add delay option to input methods (#171) Add delay option to input methods for the keyboard and mouse. Closes #156
2017-08-01 01:18:15 +00:00
```
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
Shortcut for [page.mainFrame().type(selector, text[, options])](#frametypeselector-text-options).
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
#### page.url()
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
- returns: <[string]>
Make page.url() return URL synchronously. page.url() is just a shortcut to page.mainFrame().url(). References #39.
2017-07-14 21:05:27 +00:00
This is a shortcut for [page.mainFrame().url()](#frameurl)
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
Add emulation for named devices. (#72) This patch introduces page emulation, making it possible to emulate different devices.
2017-07-18 01:13:04 +00:00
#### page.viewport()
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- returns: <[Object]>
- `width` <[number]> page width in pixels.
- `height` <[number]> page height in pixels.
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
- `deviceScaleFactor` <[number]> Specify device scale factor (can be though of as dpr). Defaults to `1`.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `isMobile` <[boolean]> Whether the `meta viewport` tag is taken into account. Defaults to `false`.
- `hasTouch`<[boolean]> Specifies if viewport supports touch events. Defaults to `false`
- `isLandscape` <[boolean]> Specifies if viewport is in landscape mode. Defaults to `false`.
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
page.waitFor should send ...args to page.waitForFunction (#775) This lets the user pass `...args` into `page.waitFor`. It also clarifies that the docs that `options` is not optional if `...args` are specified. Fixes #770
2017-09-15 21:28:15 +00:00
#### page.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])
Implement function as a part of a page.waitFor shortcut This patch adds a function as a possible argument to page.waitFor shortcut. Fixes #91.
2017-07-28 00:09:28 +00:00
- `selectorOrFunctionOrTimeout` <[string]|[number]|[function]> A [selector], predicate or timeout to wait for
Improve documentation for the `page.waitFor` method. Fixes #109.
2017-07-25 15:46:11 +00:00
- `options` <[Object]> Optional waiting parameters
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
- returns: <[Promise]<[JSHandle]>> Promise which resolves to a JSHandle of the success value
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
This method behaves differently with respect to the type of the first parameter:
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
- if `selectorOrFunctionOrTimeout` is a `string`, then the first argument is treated as a [selector] or [xpath], depending on whether or not it starts with '//', and the method is a shortcut for
[page.waitForSelector](#pagewaitforselectorselector-options) or [page.waitForXPath](#pagewaitforxpathxpath-options)
docs(api): fix typo 'Than' was used in a few places instead of 'then'.
2017-10-10 18:07:39 +00:00
- if `selectorOrFunctionOrTimeout` is a `function`, then the first argument is treated as a predicate to wait for and the method is a shortcut for [page.waitForFunction()](#pagewaitforfunctionpagefunction-options-args).
- if `selectorOrFunctionOrTimeout` is a `number`, then the first argument is treated as a timeout in milliseconds and the method returns a promise which resolves after the timeout
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
- otherwise, an exception is thrown
Added frame.waitFor(selector) (#59) This patch adds `frame.waitFor(selector)` method. Fixes #42.
2017-07-07 22:39:02 +00:00
page.waitFor should send ...args to page.waitForFunction (#775) This lets the user pass `...args` into `page.waitFor`. It also clarifies that the docs that `options` is not optional if `...args` are specified. Fixes #770
2017-09-15 21:28:15 +00:00
Shortcut for [page.mainFrame().waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#framewaitforselectororfunctionortimeout-options-args).
Implement waitFor which survives navigation (#99) This patch implements page.waitFor method which survives navigation. References #89.
2017-07-20 02:04:51 +00:00
page.waitFor should send ...args to page.waitForFunction (#775) This lets the user pass `...args` into `page.waitFor`. It also clarifies that the docs that `options` is not optional if `...args` are specified. Fixes #770
2017-09-15 21:28:15 +00:00
#### page.waitForFunction(pageFunction[, options[, ...args]])
Implement page.waitForFunction method The page.waitForFunction method allows to wait for a general predicate. The predicate will be continiously polled for in page, until it either returns true or the timeout happens. The polling parameter could be one of the following: - 'raf' - to poll on every animation frame - 'mutation' - to poll on every dom mutation - <number> - to poll every X milliseconds References #91
2017-07-27 22:17:43 +00:00
- `pageFunction` <[function]|[string]> Function to be evaluated in browser context
- `options` <[Object]> Optional waiting parameters
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
- `polling` <[string]|[number]> An interval at which the `pageFunction` is executed, defaults to `raf`. If `polling` is a number, then it is treated as an interval in milliseconds at which the function would be executed. If `polling` is a string, then it can be one of the following values:
Implement page.waitForFunction method The page.waitForFunction method allows to wait for a general predicate. The predicate will be continiously polled for in page, until it either returns true or the timeout happens. The polling parameter could be one of the following: - 'raf' - to poll on every animation frame - 'mutation' - to poll on every dom mutation - <number> - to poll every X milliseconds References #91
2017-07-27 22:17:43 +00:00
- `raf` - to constantly execute `pageFunction` in `requestAnimationFrame` callback. This is the tightest polling mode which is suitable to observe styling changes.
- `mutation` - to execute `pageFunction` on every DOM mutation.
feat(page): add an option to disable timeout for waitForFunction (#2252) This patch adds support for `timeout: 0` to disable timeout for the following functions: - `page.waitForFunction` - `page.waitForXPath` - `page.waitForSelector` and their `frame` counterparts. Fixes #2200
2018-03-28 23:34:37 +00:00
- `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
- returns: <[Promise]<[JSHandle]>> Promise which resolves when the `pageFunction` returns a truthy value. It resolves to a JSHandle of the truthy value.
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
The `waitForFunction` can be used to observe viewport size change:
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
```js
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
const puppeteer = require('puppeteer');
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
puppeteer.launch().then(async browser => {
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const page = await browser.newPage();
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
const watchDog = page.waitForFunction('window.innerWidth < 100');
docs(api.md): fix snippet to await page.setViewport() (#2113)
2018-03-01 21:06:22 +00:00
await page.setViewport({width: 50, height: 50});
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
await watchDog;
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
});
```
page.waitFor should send ...args to page.waitForFunction (#775) This lets the user pass `...args` into `page.waitFor`. It also clarifies that the docs that `options` is not optional if `...args` are specified. Fixes #770
2017-09-15 21:28:15 +00:00
Shortcut for [page.mainFrame().waitForFunction(pageFunction[, options[, ...args]])](#framewaitforfunctionpagefunction-options-args).
Implement page.waitForFunction method The page.waitForFunction method allows to wait for a general predicate. The predicate will be continiously polled for in page, until it either returns true or the timeout happens. The polling parameter could be one of the following: - 'raf' - to poll on every animation frame - 'mutation' - to poll on every dom mutation - <number> - to poll every X milliseconds References #91
2017-07-27 22:17:43 +00:00
Introduce Page.waitForNavigation (#94) This patch introduces Page.waitForNavigation which allows to wait for render-initiated navigation. This patch also does a nice refactoring, replacing Navigator with NavigatorWatcher which is not a part of a page state. References #89
2017-07-19 01:54:24 +00:00
#### page.waitForNavigation(options)
Document all options objects wherever they are used (#139) This patch adds missing documentation for all the shortcut methods, such as `page.evaluate` or `page.waitForSelector`. closes #114
2017-07-26 04:01:05 +00:00
- `options` <[Object]> Navigation parameters which might have the following properties:
feat(Page): Add global navigation timeout setting (#1728) This patch introduces `page.setDefaultNavigationTimeout` method to override the default 30 seconds navigation timeout. Fixes #1514
2018-01-10 21:04:01 +00:00
- `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultNavigationTimeout(timeout)](#pagesetdefaultnavigationtimeouttimeout) method.
feat(Page): teach Page.setContent to wait for resources to load (#1152) This patch adds "options" parameter to the `page.setContent` method. The parameter is the same as a navigation parameter and allows to specify maximum timeout to wait for resources to be loaded, as well as to describe events that should be emitted before the setContent operation would be considered successful. Fixes #728.
2017-10-24 20:57:39 +00:00
- `waitUntil` <[string]|[Array]<[string]>> When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
Document all options objects wherever they are used (#139) This patch adds missing documentation for all the shortcut methods, such as `page.evaluate` or `page.waitForSelector`. closes #114
2017-07-26 04:01:05 +00:00
- `load` - consider navigation to be finished when the `load` event is fired.
feat(Page.goto): add a 'domcontentloaded' option to the Page.goto (#1145) This patch adds a new `domcontentloaded` option to a bunch of navigation methods: - Page.goto - Page.waitForNavigation - Page.goBack - Page.goForward - Page.reload Fixes #946.
2017-10-24 07:35:18 +00:00
- `domcontentloaded` - consider navigation to be finished when the `DOMContentLoaded` event is fired.
typo in api.md (#1216) more then -> more than
2017-10-31 18:30:29 +00:00
- `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.
- `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
Introduce Page.waitForNavigation (#94) This patch introduces Page.waitForNavigation which allows to wait for render-initiated navigation. This patch also does a nice refactoring, replacing Navigator with NavigatorWatcher which is not a part of a page state. References #89
2017-07-19 01:54:24 +00:00
- returns: <[Promise]<[Response]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
Introduce polymorphic page.waitFor method This patch: - introduces page.waitForSelector to wait for the selector to appear - introduces polymorphic page.waitFor method, which accepts either string (and in this case is a shortcut for page.waitForSelector) or number (and in this case it's a promisified timeout). References #91.
2017-07-21 19:41:49 +00:00
#### page.waitForSelector(selector[, options])
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- `selector` <[string]> A [selector] of an element to wait for
Document all options objects wherever they are used (#139) This patch adds missing documentation for all the shortcut methods, such as `page.evaluate` or `page.waitForSelector`. closes #114
2017-07-26 04:01:05 +00:00
- `options` <[Object]> Optional waiting parameters
- `visible` <[boolean]> wait for element to be present in DOM and to be visible, i.e. to not have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
feat(page): waitForSelector hidden option (#967) This patch adds a 'hidden' option for the `page.waitForSelector` method.
2017-10-13 16:11:11 +00:00
- `hidden` <[boolean]> wait for element to not be found in the DOM or to be hidden, i.e. have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
feat(page): add an option to disable timeout for waitForFunction (#2252) This patch adds support for `timeout: 0` to disable timeout for the following functions: - `page.waitForFunction` - `page.waitForXPath` - `page.waitForSelector` and their `frame` counterparts. Fixes #2200
2018-03-28 23:34:37 +00:00
- `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- returns: <[Promise]<[ElementHandle]>> Promise which resolves when element specified by selector string is added to DOM.
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
Wait for the `selector` to appear in page. If at the moment of calling
the method the `selector` already exists, the method will return
immediately. If the selector doesn't appear after the `timeout` milliseconds of waiting, the function will throw.
This method works across navigations:
```js
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
const puppeteer = require('puppeteer');
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
puppeteer.launch().then(async browser => {
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const page = await browser.newPage();
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
let currentURL;
Make prettier JS snippets (#377) * Make prettier JS snippets * Conform to CS (about curly brace) * Apply feedback
2017-08-18 23:46:10 +00:00
page
.waitForSelector('img')
.then(() => console.log('First URL with image: ' + currentURL));
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com'])
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
await page.goto(currentURL);
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
});
```
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
Shortcut for [page.mainFrame().waitForSelector(selector[, options])](#framewaitforselectorselector-options).
Introduce polymorphic page.waitFor method This patch: - introduces page.waitForSelector to wait for the selector to appear - introduces polymorphic page.waitFor method, which accepts either string (and in this case is a shortcut for page.waitForSelector) or number (and in this case it's a promisified timeout). References #91.
2017-07-21 19:41:49 +00:00
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
#### page.waitForXPath(xpath[, options])
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- `xpath` <[string]> A [xpath] of an element to wait for
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
- `options` <[Object]> Optional waiting parameters
- `visible` <[boolean]> wait for element to be present in DOM and to be visible, i.e. to not have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
- `hidden` <[boolean]> wait for element to not be found in the DOM or to be hidden, i.e. have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
feat(page): add an option to disable timeout for waitForFunction (#2252) This patch adds support for `timeout: 0` to disable timeout for the following functions: - `page.waitForFunction` - `page.waitForXPath` - `page.waitForSelector` and their `frame` counterparts. Fixes #2200
2018-03-28 23:34:37 +00:00
- `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
- returns: <[Promise]<[ElementHandle]>> Promise which resolves when element specified by xpath string is added to DOM.
Wait for the `xpath` to appear in page. If at the moment of calling
the method the `xpath` already exists, the method will return
immediately. If the xpath doesn't appear after the `timeout` milliseconds of waiting, the function will throw.
This method works across navigations:
```js
const puppeteer = require('puppeteer');
puppeteer.launch().then(async browser => {
const page = await browser.newPage();
let currentURL;
page
.waitForXPath('//img')
.then(() => console.log('First URL with image: ' + currentURL));
for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com'])
await page.goto(currentURL);
await browser.close();
});
```
Shortcut for [page.mainFrame().waitForXPath(xpath[, options])](#framewaitforxpathxpath-options).
Intorduce Page.keyboard (#74) Introduce page.keyboard to provide low-level access to the keyboard.
2017-07-18 01:49:52 +00:00
### class: Keyboard
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
Keyboard provides an api for managing a virtual keyboard. The high level api is [`keyboard.type`](#keyboardtypetext-options), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page.
Intorduce Page.keyboard (#74) Introduce page.keyboard to provide low-level access to the keyboard.
2017-07-18 01:49:52 +00:00
Rename keyboard.hold and release to up and down (#95) References #89
2017-07-19 21:27:01 +00:00
For finer control, you can use [`keyboard.down`](#keyboarddownkey-options), [`keyboard.up`](#keyboardupkey), and [`keyboard.sendCharacter`](#keyboardsendcharacterchar) to manually fire events as if they were generated from a real keyboard.
Intorduce Page.keyboard (#74) Introduce page.keyboard to provide low-level access to the keyboard.
2017-07-18 01:49:52 +00:00
An example of holding down `Shift` in order to select and delete some text:
```js
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
await page.keyboard.type('Hello World!');
await page.keyboard.press('ArrowLeft');
Intorduce Page.keyboard (#74) Introduce page.keyboard to provide low-level access to the keyboard.
2017-07-18 01:49:52 +00:00
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
await page.keyboard.down('Shift');
Remove keyboard.type and keyboard.press (#98) This patch removes keyboard.type and keyboard.press methods. The motivation behind this is to keep only low-level API in the `keyboard` namespace.
2017-07-22 03:00:09 +00:00
for (let i = 0; i < ' World'.length; i++)
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
await page.keyboard.press('ArrowLeft');
await page.keyboard.up('Shift');
Intorduce Page.keyboard (#74) Introduce page.keyboard to provide low-level access to the keyboard.
2017-07-18 01:49:52 +00:00
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
await page.keyboard.press('Backspace');
Intorduce Page.keyboard (#74) Introduce page.keyboard to provide low-level access to the keyboard.
2017-07-18 01:49:52 +00:00
// Result text will end up saying 'Hello!'
```
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
An example of pressing `A`
```js
await page.keyboard.down('Shift');
await page.keyboard.press('KeyA');
await page.keyboard.up('Shift');
```
docs: document osx keyboard shortcuts not working (#1311) Fixes #776
2017-11-08 00:22:58 +00:00
> **NOTE** On MacOS, keyboard shortcuts like `⌘ A` -> Select All do not work. See [#1313](https://github.com/GoogleChrome/puppeteer/issues/1313)
Rename keyboard.hold and release to up and down (#95) References #89
2017-07-19 21:27:01 +00:00
#### keyboard.down(key[, options])
feat(keyboard): Accept codes (#1116) BREAKING CHANGE: This patch lets key names be code in addition to key. When specifying a code, the proper text is generated assuming a standard US keyboard layout. e.g Digit5 -> "5" or "%" depending on Shift. * location is now specified. #777 * Using unknown key names now throws an error. #723 * Typing newlines now correctly presses enter. #681
2017-10-23 19:43:45 +00:00
- `key` <[string]> Name of key to press, such as `ArrowLeft`. See [USKeyboardLayout] for a list of all key names.
Intorduce Page.keyboard (#74) Introduce page.keyboard to provide low-level access to the keyboard.
2017-07-18 01:49:52 +00:00
- `options` <[Object]>
- `text` <[string]> If specified, generates an input event with this text.
- returns: <[Promise]>
Dispatches a `keydown` event.
feat(keyboard): make keyboard.down generate input event by default (#1016) This patch starts generating input events for `keyboard.down`, addressing bullet 2 of #723. With this patch, there's no longer any difference between `keboard.press('a')` and `keyboard.press('a', {text: 'a'})`. BREAKING CHANGE: `keyboard.down('a')` starts generating input event (wasn't the case before). References #723
2017-10-13 22:22:55 +00:00
If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`/`input` event will also generated. The `text` option can be specified to force an input event to be generated.
Intorduce Page.keyboard (#74) Introduce page.keyboard to provide low-level access to the keyboard.
2017-07-18 01:49:52 +00:00
Rename keyboard.hold and release to up and down (#95) References #89
2017-07-19 21:27:01 +00:00
If `key` is a modifier key, `Shift`, `Meta`, `Control`, or `Alt`, subsequent key presses will be sent with that modifier active. To release the modifier key, use [`keyboard.up`](#keyboardupkey).
Intorduce Page.keyboard (#74) Introduce page.keyboard to provide low-level access to the keyboard.
2017-07-18 01:49:52 +00:00
Specify repeat property on repeated keypresses (#172) This patch implements 'autoRepeat' functionality for `keyboard.down`. With this patch, the subsequent calls to `keyboard.down` would generate an event with 'autoRepeat` flag set to true. Closes #157
2017-07-31 19:05:46 +00:00
After the key is pressed once, subsequent calls to [`keyboard.down`](#keyboarddownkey-options) will have [repeat](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/repeat) set to true. To release the key, use [`keyboard.up`](#keyboardupkey).
docs: use less confusing synonym This change was suggested in #1636.
2017-12-28 03:35:14 +00:00
> **NOTE** Modifier keys DO influence `keyboard.down`. Holding down `Shift` will type the text in upper case.
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
#### keyboard.press(key[, options])
feat(keyboard): Accept codes (#1116) BREAKING CHANGE: This patch lets key names be code in addition to key. When specifying a code, the proper text is generated assuming a standard US keyboard layout. e.g Digit5 -> "5" or "%" depending on Shift. * location is now specified. #777 * Using unknown key names now throws an error. #723 * Typing newlines now correctly presses enter. #681
2017-10-23 19:43:45 +00:00
- `key` <[string]> Name of key to press, such as `ArrowLeft`. See [USKeyboardLayout] for a list of all key names.
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
- `options` <[Object]>
- `text` <[string]> If specified, generates an input event with this text.
- `delay` <[number]> Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
- returns: <[Promise]>
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`/`input` event will also generated. The `text` option can be specified to force an input event to be generated.
> **NOTE** Modifier keys DO effect `elementHandle.press`. Holding down `Shift` will type the text in upper case.
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
Shortcut for [`keyboard.down`](#keyboarddownkey-options) and [`keyboard.up`](#keyboardupkey).
Intorduce Page.keyboard (#74) Introduce page.keyboard to provide low-level access to the keyboard.
2017-07-18 01:49:52 +00:00
#### keyboard.sendCharacter(char)
- `char` <[string]> Character to send into the page.
- returns: <[Promise]>
Dispatches a `keypress` and `input` event. This does not send a `keydown` or `keyup` event.
```js
page.keyboard.sendCharacter('嗨');
```
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
> **NOTE** Modifier keys DO NOT effect `keyboard.sendCharacter`. Holding down `Shift` will not type the text in upper case.
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
#### keyboard.type(text, options)
- `text` <[string]> A text to type into a focused element.
- `options` <[Object]>
- `delay` <[number]> Time to wait between key presses in milliseconds. Defaults to 0.
- returns: <[Promise]>
Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
To press a special key, like `Control` or `ArrowDown`, use [`keyboard.press`](#keyboardpresskey-options).
```js
page.keyboard.type('Hello'); // Types instantly
page.keyboard.type('World', {delay: 100}); // Types slower, like a user
```
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
> **NOTE** Modifier keys DO NOT effect `keyboard.type`. Holding down `Shift` will not type the text in upper case.
Rename keyboard.hold and release to up and down (#95) References #89
2017-07-19 21:27:01 +00:00
#### keyboard.up(key)
feat(keyboard): Accept codes (#1116) BREAKING CHANGE: This patch lets key names be code in addition to key. When specifying a code, the proper text is generated assuming a standard US keyboard layout. e.g Digit5 -> "5" or "%" depending on Shift. * location is now specified. #777 * Using unknown key names now throws an error. #723 * Typing newlines now correctly presses enter. #681
2017-10-23 19:43:45 +00:00
- `key` <[string]> Name of key to release, such as `ArrowLeft`. See [USKeyboardLayout] for a list of all key names.
Rename keyboard.hold and release to up and down (#95) References #89
2017-07-19 21:27:01 +00:00
- returns: <[Promise]>
Dispatches a `keyup` event.
Mouse (#101) This patch: - adds Mouse class which holds mouse state and implements mouse primitives, such as moving, button down and button up. - implements high-level mouse api, such as `page.click` and `page.hover`. References #40, References #89
2017-07-22 03:29:31 +00:00
### class: Mouse
Implement mouse.click(x,y) (#131) Closes #107
2017-07-25 23:05:23 +00:00
#### mouse.click(x, y, [options])
- `x` <[number]>
- `y` <[number]>
- `options` <[Object]>
- `button` <[string]> `left`, `right`, or `middle`, defaults to `left`.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `clickCount` <[number]> defaults to 1. See [UIEvent.detail].
Add delay option to input methods (#171) Add delay option to input methods for the keyboard and mouse. Closes #156
2017-08-01 01:18:15 +00:00
- `delay` <[number]> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
Implement mouse.click(x,y) (#131) Closes #107
2017-07-25 23:05:23 +00:00
- returns: <[Promise]>
doc: fix a link (#856)
2017-09-22 23:16:52 +00:00
Shortcut for [`mouse.move`](#mousemovex-y-options), [`mouse.down`](#mousedownoptions) and [`mouse.up`](#mouseupoptions).
Implement mouse.click(x,y) (#131) Closes #107
2017-07-25 23:05:23 +00:00
Mouse (#101) This patch: - adds Mouse class which holds mouse state and implements mouse primitives, such as moving, button down and button up. - implements high-level mouse api, such as `page.click` and `page.hover`. References #40, References #89
2017-07-22 03:29:31 +00:00
#### mouse.down([options])
- `options` <[Object]>
- `button` <[string]> `left`, `right`, or `middle`, defaults to `left`.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `clickCount` <[number]> defaults to 1. See [UIEvent.detail].
Mouse (#101) This patch: - adds Mouse class which holds mouse state and implements mouse primitives, such as moving, button down and button up. - implements high-level mouse api, such as `page.click` and `page.hover`. References #40, References #89
2017-07-22 03:29:31 +00:00
- returns: <[Promise]>
Dispatches a `mousedown` event.
[api] Add "step" option to mouse.move method (#601) This patch adds "step" option to the mouse.move method, that optionally tweens mouse movement over multiple steps. References #423.
2017-08-29 21:13:38 +00:00
#### mouse.move(x, y, [options])
Mouse (#101) This patch: - adds Mouse class which holds mouse state and implements mouse primitives, such as moving, button down and button up. - implements high-level mouse api, such as `page.click` and `page.hover`. References #40, References #89
2017-07-22 03:29:31 +00:00
- `x` <[number]>
- `y` <[number]>
[api] Add "step" option to mouse.move method (#601) This patch adds "step" option to the mouse.move method, that optionally tweens mouse movement over multiple steps. References #423.
2017-08-29 21:13:38 +00:00
- `options` <[Object]>
- `steps` <[number]> defaults to 1. Sends intermediate `mousemove` events.
Mouse (#101) This patch: - adds Mouse class which holds mouse state and implements mouse primitives, such as moving, button down and button up. - implements high-level mouse api, such as `page.click` and `page.hover`. References #40, References #89
2017-07-22 03:29:31 +00:00
- returns: <[Promise]>
Dispatches a `mousemove` event.
#### mouse.up([options])
- `options` <[Object]>
- `button` <[string]> `left`, `right`, or `middle`, defaults to `left`.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `clickCount` <[number]> defaults to 1. See [UIEvent.detail].
Mouse (#101) This patch: - adds Mouse class which holds mouse state and implements mouse primitives, such as moving, button down and button up. - implements high-level mouse api, such as `page.click` and `page.hover`. References #40, References #89
2017-07-22 03:29:31 +00:00
- returns: <[Promise]>
Dispatches a `mouseup` event.
[api] add touchScreen.tap (#639) This patch: - adds `page.touchscreen` namespace, similar to `page.mouse` and `page.keyboard`. - adds tapping to multiple layers: - `page.touchscreen.tap` - `page.tap` - convenience method which accepts selector - `elementHandle.tap` Fixes #568 and #569.
2017-09-02 02:03:51 +00:00
### class: Touchscreen
#### touchscreen.tap(x, y)
- `x` <[number]>
- `y` <[number]>
- returns: <[Promise]>
Dispatches a `touchstart` and `touchend` event.
Introduce page.tracing (#181) This patch introduces page.tracing, which allows to start and stop trace recording for a page. The trace could be then saved to file.
2017-08-02 17:45:11 +00:00
### class: Tracing
doc: fix some links in api.md (#400)
2017-08-20 21:32:53 +00:00
You can use [`tracing.start`](#tracingstartoptions) and [`tracing.stop`](#tracingstop) to create a trace file which can be opened in Chrome DevTools or [timeline viewer](https://chromedevtools.github.io/timeline-viewer/).
Introduce page.tracing (#181) This patch introduces page.tracing, which allows to start and stop trace recording for a page. The trace could be then saved to file.
2017-08-02 17:45:11 +00:00
```js
Move path option into tracing.start (#192) This consolidates all the tracing options in the tracing.start()
2017-08-02 22:41:05 +00:00
await page.tracing.start({path: 'trace.json'});
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
await page.goto('https://www.google.com');
Move path option into tracing.start (#192) This consolidates all the tracing options in the tracing.start()
2017-08-02 22:41:05 +00:00
await page.tracing.stop();
Introduce page.tracing (#181) This patch introduces page.tracing, which allows to start and stop trace recording for a page. The trace could be then saved to file.
2017-08-02 17:45:11 +00:00
```
Move path option into tracing.start (#192) This consolidates all the tracing options in the tracing.start()
2017-08-02 22:41:05 +00:00
#### tracing.start(options)
Introduce page.tracing (#181) This patch introduces page.tracing, which allows to start and stop trace recording for a page. The trace could be then saved to file.
2017-08-02 17:45:11 +00:00
- `options` <[Object]>
Move path option into tracing.start (#192) This consolidates all the tracing options in the tracing.start()
2017-08-02 22:41:05 +00:00
- `path` <[string]> A path to write the trace file to. **required**
Introduce page.tracing (#181) This patch introduces page.tracing, which allows to start and stop trace recording for a page. The trace could be then saved to file.
2017-08-02 17:45:11 +00:00
- `screenshots` <[boolean]> captures screenshots in the trace.
docs(api.md): Note that Browser and Page extend from EventEmitter (#1541) Adds notes to the API documentation that Browser and Page classes are EventEmitters. Provides an example of using `.once` for Page. Fixes #1231
2017-12-06 07:53:27 +00:00
- `categories` <[Array]<[string]>> specify custom categories to use instead of default.
Introduce page.tracing (#181) This patch introduces page.tracing, which allows to start and stop trace recording for a page. The trace could be then saved to file.
2017-08-02 17:45:11 +00:00
- returns: <[Promise]>
[doc] Remove mention of broken javascript dialogs from api.md (#210)
2017-08-04 08:12:18 +00:00
Only one trace can be active at a time per browser.
Move path option into tracing.start (#192) This consolidates all the tracing options in the tracing.start()
2017-08-02 22:41:05 +00:00
#### tracing.stop()
Introduce page.tracing (#181) This patch introduces page.tracing, which allows to start and stop trace recording for a page. The trace could be then saved to file.
2017-08-02 17:45:11 +00:00
- returns: <[Promise]>
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
### class: Dialog
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
[Dialog] objects are dispatched by page via the ['dialog'](#event-dialog) event.
[doc] add examples for Dialog and Frame classes
2017-07-17 18:02:13 +00:00
An example of using `Dialog` class:
```js
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
const puppeteer = require('puppeteer');
puppeteer.launch().then(async browser => {
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const page = await browser.newPage();
page.on('dialog', async dialog => {
[doc] add examples for Dialog and Frame classes
2017-07-17 18:02:13 +00:00
console.log(dialog.message());
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
await dialog.dismiss();
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
[doc] add examples for Dialog and Frame classes
2017-07-17 18:02:13 +00:00
});
page.evaluate(() => alert('1'));
});
```
[doclint] Fix bug in documentation linter This patch: - fixes a typo in documentation linter, which resulted in only certain method arguments being linted. - adds missing arguments to the documentation References #14.
2017-07-12 00:01:58 +00:00
#### dialog.accept([promptText])
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
- `promptText` <[string]> A text to enter in prompt. Does not cause any effects if the dialog's `type` is not prompt.
doc: fix typo (#431)
2017-08-21 02:54:05 +00:00
- returns: <[Promise]> Promise which resolves when the dialog has been accepted.
[doclint] Fix bug in documentation linter This patch: - fixes a typo in documentation linter, which resulted in only certain method arguments being linted. - adds missing arguments to the documentation References #14.
2017-07-12 00:01:58 +00:00
Plumb default prompt value to the dialog (#243) This patch: - plumbs default prompt value to the dialog - enables one more phantom test
2017-08-11 19:17:43 +00:00
#### dialog.defaultValue()
- returns: <[string]> If dialog is prompt, returns default prompt value. Otherwise, returns empty string.
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
#### dialog.dismiss()
doc: fix typo (#431)
2017-08-21 02:54:05 +00:00
- returns: <[Promise]> Promise which resolves when the dialog has been dismissed.
[doclint] add linting for class properties This patch: - adds linting for class properties - adds documentation for the missing class properties References #14.
2017-07-12 15:01:21 +00:00
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
#### dialog.message()
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
- returns: <[string]> A message displayed in the dialog.
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
#### dialog.type()
- returns: <[string]> Dialog's type, can be one of `alert`, `beforeunload`, `confirm` or `prompt`.
[doclint] add linting for class properties This patch: - adds linting for class properties - adds documentation for the missing class properties References #14.
2017-07-12 15:01:21 +00:00
feat(Console): Introduce ConsoleMessage type (#909) This patch introduces ConsoleMessage type and starts dispatching it for the 'console' event. BREAKING CHANGE: this breaks the api of the 'console' event. Fixes #744.
2017-09-29 18:27:22 +00:00
### class: ConsoleMessage
[ConsoleMessage] objects are dispatched by page via the ['console'](#event-console) event.
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
#### consoleMessage.args()
- returns: <[Array]<[JSHandle]>>
feat(Console): Introduce ConsoleMessage type (#909) This patch introduces ConsoleMessage type and starts dispatching it for the 'console' event. BREAKING CHANGE: this breaks the api of the 'console' event. Fixes #744.
2017-09-29 18:27:22 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
#### consoleMessage.text()
- returns: <[string]>
feat(Console): Introduce ConsoleMessage type (#909) This patch introduces ConsoleMessage type and starts dispatching it for the 'console' event. BREAKING CHANGE: this breaks the api of the 'console' event. Fixes #744.
2017-09-29 18:27:22 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
#### consoleMessage.type()
- returns: <[string]>
feat(Console): Introduce ConsoleMessage type (#909) This patch introduces ConsoleMessage type and starts dispatching it for the 'console' event. BREAKING CHANGE: this breaks the api of the 'console' event. Fixes #744.
2017-09-29 18:27:22 +00:00
One of the following values: `'log'`, `'debug'`, `'info'`, `'error'`, `'warning'`, `'dir'`, `'dirxml'`, `'table'`, `'trace'`, `'clear'`, `'startGroup'`, `'startGroupCollapsed'`, `'endGroup'`, `'assert'`, `'profile'`, `'profileEnd'`, `'count'`, `'timeEnd'`.
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
### class: Frame
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
At every point of time, page exposes its current frame tree via the [page.mainFrame()](#pagemainframe) and [frame.childFrames()](#framechildframes) methods.
[Frame] object's lifecycle is controlled by three events, dispatched on the page object:
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
- ['frameattached'](#event-frameattached) - fired when the frame gets attached to the page. A Frame can be attached to the page only once.
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
- ['framenavigated'](#event-framenavigated) - fired when the frame commits navigation to a different URL.
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
- ['framedetached'](#event-framedetached) - fired when the frame gets detached from the page. A Frame can be detached from the page only once.
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
[doc] add examples for Dialog and Frame classes
2017-07-17 18:02:13 +00:00
An example of dumping frame tree:
```js
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
const puppeteer = require('puppeteer');
[doc] add examples for Dialog and Frame classes
2017-07-17 18:02:13 +00:00
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
puppeteer.launch().then(async browser => {
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const page = await browser.newPage();
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
await page.goto('https://www.google.com/chrome/browser/canary.html');
[doc] add examples for Dialog and Frame classes
2017-07-17 18:02:13 +00:00
dumpFrameTree(page.mainFrame(), '');
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
[doc] add examples for Dialog and Frame classes
2017-07-17 18:02:13 +00:00
function dumpFrameTree(frame, indent) {
console.log(indent + frame.url());
for (let child of frame.childFrames())
dumpFrameTree(child, indent + ' ');
}
});
```
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
#### frame.$(selector)
- `selector` <[string]> Selector to query page for
docs(api.md): fix return signatures that contains null (#1364)
2017-11-15 18:53:17 +00:00
- returns: <[Promise]<?[ElementHandle]>> Promise which resolves to ElementHandle pointing to the frame element.
Implement page.$$ method (#463) This patch implements page.$$ which runs document.querySelectorAll in page and returns results as an array of ElementHandle instances. Fixes #384.
2017-08-23 05:56:55 +00:00
The method queries frame for the selector. If there's no such element within the frame, the method will resolve to `null`.
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
Implement page.$$ method (#463) This patch implements page.$$ which runs document.querySelectorAll in page and returns results as an array of ElementHandle instances. Fixes #384.
2017-08-23 05:56:55 +00:00
#### frame.$$(selector)
- `selector` <[string]> Selector to query page for
- returns: <[Promise]<[Array]<[ElementHandle]>>> Promise which resolves to ElementHandles pointing to the frame elements.
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
Implement page.$$ method (#463) This patch implements page.$$ which runs document.querySelectorAll in page and returns results as an array of ElementHandle instances. Fixes #384.
2017-08-23 05:56:55 +00:00
The method runs `document.querySelectorAll` within the frame. If no elements match the selector, the return value resolve to `[]`.
Introduce Page.$ and Page.$$ (#75) This patch introduces Page.$ and Page.$$ methods which are aliases for `document.querySelector` and `document.querySelectorAll`. Fixes #78.
2017-07-18 01:56:56 +00:00
feat(Page): introduce Page.$$eval method (#1006) This patch adds a `Page.$$eval` method that runs `document.querySelectorAll` and passes resulting array to the page function. Fixes #625.
2017-10-11 06:23:14 +00:00
#### frame.$$eval(selector, pageFunction[, ...args])
- `selector` <[string]> A [selector] to query frame for
- `pageFunction` <[function]> Function to be evaluated in browser context
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
feat(Page): introduce Page.$$eval method (#1006) This patch adds a `Page.$$eval` method that runs `document.querySelectorAll` and passes resulting array to the page function. Fixes #625.
2017-10-11 06:23:14 +00:00
- returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
This method runs `document.querySelectorAll` within the frame and passes it as the first argument to `pageFunction`.
If `pageFunction` returns a [Promise], then `frame.$$eval` would wait for the promise to resolve and return its value.
Examples:
```js
const divsCounts = await frame.$$eval('div', divs => divs.length);
```
Implement page.$eval (#638) This patch: - implements page.$eval and frame.$eval - drops elementHandle.attribute() method in favor of the page.$eval References #625
2017-08-31 22:38:01 +00:00
#### frame.$eval(selector, pageFunction[, ...args])
- `selector` <[string]> A [selector] to query frame for
- `pageFunction` <[function]> Function to be evaluated in browser context
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
Implement page.$eval (#638) This patch: - implements page.$eval and frame.$eval - drops elementHandle.attribute() method in favor of the page.$eval References #625
2017-08-31 22:38:01 +00:00
- returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
This method runs `document.querySelector` within the frame and passes it as the first argument to `pageFunction`. If there's no element matching `selector`, the method throws an error.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
If `pageFunction` returns a [Promise], then `frame.$eval` would wait for the promise to resolve and return its value.
Implement page.$eval (#638) This patch: - implements page.$eval and frame.$eval - drops elementHandle.attribute() method in favor of the page.$eval References #625
2017-08-31 22:38:01 +00:00
Examples:
```js
const searchValue = await frame.$eval('#search', el => el.value);
const preloadHref = await frame.$eval('link[rel=preload]', el => el.href);
const html = await frame.$eval('.main-container', e => e.outerHTML);
```
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
#### frame.$x(expression)
- `expression` <[string]> Expression to [evaluate](https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate).
- returns: <[Promise]<[Array]<[ElementHandle]>>>
docs(api.md): fix typo on api docs (#1849)
2018-01-19 05:19:43 +00:00
The method evaluates the XPath expression.
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
#### frame.addScriptTag(options)
- `options` <[Object]>
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- `url` <[string]> URL of a script to be added.
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
- `path` <[string]> Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
- `content` <[string]> Raw JavaScript content to be injected into frame.
feat(FrameManager): add type=module to addScriptTag (#2090) This patch adds a new "type" option to the `addScriptTag` method that allows adding "module" tags to the page. Fixes #2078
2018-03-14 20:07:48 +00:00
- `type` <[string]> Script type. Use 'module' in order to load a Javascript ES6 module. See [script](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) for more details.
feat(Frame): addStyleTag and addScriptTag now return ElementHandles. This patch teaches `page.addStyleTag` and `page.addScriptTag` to return ElementHandles to the added tags. Fixes #1179.
2017-11-03 07:05:38 +00:00
- returns: <[Promise]<[ElementHandle]>> which resolves to the added tag when the script's onload fires or when the script content was injected into frame.
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
Adds a `<script>` tag into the page with the desired url or content.
Move missing methods from page onto frame. (#125) Closes #113
2017-07-25 18:37:46 +00:00
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
#### frame.addStyleTag(options)
- `options` <[Object]>
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- `url` <[string]> URL of the `<link>` tag.
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
- `path` <[string]> Path to the CSS file to be injected into frame. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
- `content` <[string]> Raw CSS content to be injected into frame.
feat(Frame): addStyleTag and addScriptTag now return ElementHandles. This patch teaches `page.addStyleTag` and `page.addScriptTag` to return ElementHandles to the added tags. Fixes #1179.
2017-11-03 07:05:38 +00:00
- returns: <[Promise]<[ElementHandle]>> which resolves to the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.
feat(Frame): Add `addStyleTag` API to frame - fixes #892 (#947) This patch adds `Page.addStyleTag` and `Frame.addStyleTag` methods to the API. Fixes #892.
2017-10-04 20:42:26 +00:00
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
Adds a `<link rel="stylesheet">` tag into the page with the desired url or a `<style type="text/css">` tag with the content.
feat(Frame): Add `addStyleTag` API to frame - fixes #892 (#947) This patch adds `Page.addStyleTag` and `Frame.addStyleTag` methods to the API. Fixes #892.
2017-10-04 20:42:26 +00:00
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
#### frame.childFrames()
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
- returns: <[Array]<[Frame]>>
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
#### frame.click(selector[, options])
- `selector` <[string]> A [selector] to search for element to click. If there are multiple elements satisfying the selector, the first will be clicked.
- `options` <[Object]>
- `button` <[string]> `left`, `right`, or `middle`, defaults to `left`.
- `clickCount` <[number]> defaults to 1. See [UIEvent.detail].
- `delay` <[number]> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully clicked. The Promise will be rejected if there is no element matching `selector`.
This method fetches an element with `selector`, scrolls it into view if needed, and then uses [page.mouse](#pagemouse) to click in the center of the element.
If there's no element matching `selector`, the method throws an error.
docs(api.md): fix minor spelling errors (#2314)
2018-04-05 20:08:28 +00:00
Bear in mind that if `click()` triggers a navigation event and there's a separate `page.waitForNavigation()` promise to be resolved, you may end up with a race condition that yields unexpected results. The correct pattern for click and wait for navigation is the following:
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
```javascript
const [response] = await Promise.all([
page.waitForNavigation(waitOptions),
frame.click(selector, clickOptions),
]);
```
feat(Frame): implement frame.content and frame.setContent methods (#1447) This refactors the page.content and page.setContent methods to be defined on the Frame class. This allows access from the Page still but also on all frames. Fixes #754
2017-11-23 02:44:33 +00:00
#### frame.content()
- returns: <[Promise]<[String]>>
Gets the full HTML contents of the frame, including the doctype.
[doc] distinct naming for functions which are evaluated in page context This patch renames all the function parameters which are executed in page context into 'pageFunction'.
2017-07-14 20:51:22 +00:00
#### frame.evaluate(pageFunction, ...args)
page.evaluate takes a string in addition to function (#135) This patch improves on page.evaluate to accept a string. The string can have a trailing '//# sourceURL=' comment which would name the evaluation to make stacks beautiful. In order to make sourceURL comments possible, this patch: - removes wrapping of the client function into `Promise.resolve()` - stops passing `awaitPromise` parameter to `Runtime.evaluate` - starts to await promise via the `Runtime.awaitPromise` if the return type of the evaluation is promise closes #118
2017-07-27 19:23:41 +00:00
- `pageFunction` <[function]|[string]> Function to be evaluated in browser context
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
- returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
If the function passed to the `frame.evaluate` returns a [Promise], then `frame.evaluate` would wait for the promise to resolve and return its value.
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
If the function passed to the `frame.evaluate` returns a non-[Serializable] value, then `frame.evaluate` resolves to `undefined`.
fix: return undefined when Page.evaluate encounters circular JSON (#983)
2017-10-09 19:30:05 +00:00
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
```js
[api] Teach page.evaluate to accept element handles as parameters (#725) This patch: - teaches `page.evaluate` to accept ElementHandles as parameters - removes `ElementHandle.evaluate` method since it's not needed any more References #382
2017-09-12 02:20:02 +00:00
const result = await frame.evaluate(() => {
return Promise.resolve(8 * 7);
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
});
[api] Teach page.evaluate to accept element handles as parameters (#725) This patch: - teaches `page.evaluate` to accept ElementHandles as parameters - removes `ElementHandle.evaluate` method since it's not needed any more References #382
2017-09-12 02:20:02 +00:00
console.log(result); // prints "56"
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
```
Implement Frame.evaluate This patch implements Frame.evaluate method. References #4.
2017-06-27 19:40:46 +00:00
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
A string can also be passed in instead of a function.
```js
[api] Teach page.evaluate to accept element handles as parameters (#725) This patch: - teaches `page.evaluate` to accept ElementHandles as parameters - removes `ElementHandle.evaluate` method since it's not needed any more References #382
2017-09-12 02:20:02 +00:00
console.log(await frame.evaluate('1 + 2')); // prints "3"
```
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
[ElementHandle] instances can be passed as arguments to the `frame.evaluate`:
[api] Teach page.evaluate to accept element handles as parameters (#725) This patch: - teaches `page.evaluate` to accept ElementHandles as parameters - removes `ElementHandle.evaluate` method since it's not needed any more References #382
2017-09-12 02:20:02 +00:00
```js
const bodyHandle = await frame.$('body');
const html = await frame.evaluate(body => body.innerHTML, bodyHandle);
await bodyHandle.dispose();
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
```
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
feat(Frame): add Frame.evaluateHandle (#1885) This patch adds Frame.evaluateHandle method. The method is a shortcut for frame.executionContext().evaluateHandle. Fixes #1051
2018-01-25 05:16:01 +00:00
#### frame.evaluateHandle(pageFunction, ...args)
- `pageFunction` <[function]|[string]> Function to be evaluated in the page context
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
- returns: <[Promise]<[JSHandle]>> Promise which resolves to the return value of `pageFunction` as in-page object (JSHandle)
The only difference between `frame.evaluate` and `frame.evaluateHandle` is that `frame.evaluateHandle` returns in-page object (JSHandle).
feat(Frame): add Frame.evaluateHandle (#1885) This patch adds Frame.evaluateHandle method. The method is a shortcut for frame.executionContext().evaluateHandle. Fixes #1051
2018-01-25 05:16:01 +00:00
If the function, passed to the `frame.evaluateHandle`, returns a [Promise], then `frame.evaluateHandle` would wait for the promise to resolve and return its value.
```js
const aWindowHandle = await frame.evaluateHandle(() => Promise.resolve(window));
aWindowHandle; // Handle for the window object.
```
A string can also be passed in instead of a function.
```js
const aHandle = await frame.evaluateHandle('document'); // Handle for the 'document'.
```
[JSHandle] instances can be passed as arguments to the `frame.evaluateHandle`:
```js
const aHandle = await frame.evaluateHandle(() => document.body);
const resultHandle = await frame.evaluateHandle(body => body.innerHTML, aHandle);
console.log(await resultHandle.jsonValue());
await resultHandle.dispose();
```
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
#### frame.executionContext()
fix(Frame): postpone evaluations until execution context gets created (#1415) In Blink, frames don't necesserily have execution context all the time. DevTools Protocol precisely reports this situation, which results in Puppeteer's frame.executionContext() being null occasionally. However, from puppeteer point of view every frame will have at least a default executions context, sooner or later: - frame's execution context might be created naturally to run frame's javascript - if frame has no javascript, devtools protocol will issue execution context creation This patch builds up on this assumption and makes frame.executionContext() to be a promise. As a result, all the evaluations await for the execution context to be created first. Fixes #827, #1325 BREAKING CHANGE: this patch changes frame.executionContext() method to return a promise. To migrate onto a new behavior, await the context first before using it.
2017-11-19 00:27:52 +00:00
- returns: <[Promise]<[ExecutionContext]>> Execution context associated with this frame.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
#### frame.focus(selector)
- `selector` <[string]> A [selector] of an element to focus. If there are multiple elements satisfying the selector, the first will be focused.
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully focused. The promise will be rejected if there is no element matching `selector`.
This method fetches an element with `selector` and focuses it.
If there's no element matching `selector`, the method throws an error.
#### frame.hover(selector)
- `selector` <[string]> A [selector] to search for element to hover. If there are multiple elements satisfying the selector, the first will be hovered.
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully hovered. Promise gets rejected if there's no element matching `selector`.
This method fetches an element with `selector`, scrolls it into view if needed, and then uses [page.mouse](#pagemouse) to hover over the center of the element.
If there's no element matching `selector`, the method throws an error.
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
#### frame.isDetached()
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
- returns: <[boolean]>
doc: fix typo (#431)
2017-08-21 02:54:05 +00:00
Returns `true` if the frame has been detached, or `false` otherwise.
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
#### frame.name()
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
- returns: <[string]>
add tests for Frame class This patch: - improves documentation of frame.name() - adds a test for frame.name() - adds a test for frame.parent() References #50.
2017-07-27 18:36:03 +00:00
Returns frame's name attribute as specified in the tag.
If the name is empty, returns the id attribute instead.
Rename Page.setInPageCallback into Page.addBinding (#236) This seems to be a much better name which is actually used for a similar purposes in chromium/v8.
2017-08-11 04:44:49 +00:00
> **NOTE** This value is calculated once when the frame is created, and will not update if the attribute is changed later.
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
#### frame.parentFrame()
docs(api.md): fix return signatures that contains null (#1364)
2017-11-15 18:53:17 +00:00
- returns: <?[Frame]> Returns parent frame, if any. Detached frames and main frames return `null`.
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
feat(Frame): introduce Frame.select This patch adds `Frame.select` method that does the same functionality as former `Page.select`, but on a per-frame level. The `Page.select` method becomes a shortcut for the ÷main frame's select. Fixes #1139
2017-11-02 05:06:04 +00:00
#### frame.select(selector, ...values)
- `selector` <[string]> A [selector] to query frame for
- `...values` <...[string]> Values of options to select. If the `<select>` has the `multiple` attribute, all values are considered, otherwise only the first one is taken into account.
docs(api.md): fix return value of frame.select() (#1251)
2017-11-03 04:46:49 +00:00
- returns: <[Promise]<[Array]<[string]>>> Returns an array of option values that have been successfully selected.
feat(Frame): introduce Frame.select This patch adds `Frame.select` method that does the same functionality as former `Page.select`, but on a per-frame level. The `Page.select` method becomes a shortcut for the ÷main frame's select. Fixes #1139
2017-11-02 05:06:04 +00:00
Triggers a `change` and `input` event once all the provided options have been selected.
If there's no `<select>` element matching `selector`, the method throws an error.
```js
frame.select('select#colors', 'blue'); // single selection
frame.select('select#colors', 'red', 'green', 'blue'); // multiple selections
```
feat(Frame): implement frame.content and frame.setContent methods (#1447) This refactors the page.content and page.setContent methods to be defined on the Frame class. This allows access from the Page still but also on all frames. Fixes #754
2017-11-23 02:44:33 +00:00
#### frame.setContent(html)
- `html` <[string]> HTML markup to assign to the page.
- returns: <[Promise]>
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
#### frame.tap(selector)
- `selector` <[string]> A [selector] to search for element to tap. If there are multiple elements satisfying the selector, the first will be tapped.
- returns: <[Promise]>
This method fetches an element with `selector`, scrolls it into view if needed, and then uses [page.touchscreen](#pagetouchscreen) to tap in the center of the element.
If there's no element matching `selector`, the method throws an error.
Move missing methods from page onto frame. (#125) Closes #113
2017-07-25 18:37:46 +00:00
#### frame.title()
- returns: <[Promise]<[string]>> Returns page's title.
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
#### frame.type(selector, text[, options])
- `selector` <[string]> A [selector] of an element to type into. If there are multiple elements satisfying the selector, the first will be used.
- `text` <[string]> A text to type into a focused element.
- `options` <[Object]>
- `delay` <[number]> Time to wait between key presses in milliseconds. Defaults to 0.
- returns: <[Promise]>
Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
To press a special key, like `Control` or `ArrowDown`, use [`keyboard.press`](#keyboardpresskey-options).
```js
frame.type('#mytextarea', 'Hello'); // Types instantly
frame.type('#mytextarea', 'World', {delay: 100}); // Types slower, like a user
```
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
#### frame.url()
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
- returns: <[string]>
Returns frame's url.
Added frame.waitFor(selector) (#59) This patch adds `frame.waitFor(selector)` method. Fixes #42.
2017-07-07 22:39:02 +00:00
page.waitFor should send ...args to page.waitForFunction (#775) This lets the user pass `...args` into `page.waitFor`. It also clarifies that the docs that `options` is not optional if `...args` are specified. Fixes #770
2017-09-15 21:28:15 +00:00
#### frame.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])
Implement function as a part of a page.waitFor shortcut This patch adds a function as a possible argument to page.waitFor shortcut. Fixes #91.
2017-07-28 00:09:28 +00:00
- `selectorOrFunctionOrTimeout` <[string]|[number]|[function]> A [selector], predicate or timeout to wait for
Introduce polymorphic page.waitFor method This patch: - introduces page.waitForSelector to wait for the selector to appear - introduces polymorphic page.waitFor method, which accepts either string (and in this case is a shortcut for page.waitForSelector) or number (and in this case it's a promisified timeout). References #91.
2017-07-21 19:41:49 +00:00
- `options` <[Object]> Optional waiting parameters
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
- returns: <[Promise]<[JSHandle]>> Promise which resolves to a JSHandle of the success value
Implement function as a part of a page.waitFor shortcut This patch adds a function as a possible argument to page.waitFor shortcut. Fixes #91.
2017-07-28 00:09:28 +00:00
Improve documentation for the `page.waitFor` method. Fixes #109.
2017-07-25 15:46:11 +00:00
This method behaves differently with respect to the type of the first parameter:
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
- if `selectorOrFunctionOrTimeout` is a `string`, then the first argument is treated as a [selector] or [xpath], depending on whether or not it starts with '//', and the method is a shortcut for
docs(api.md): fix some links (#2253)
2018-03-28 20:18:59 +00:00
[frame.waitForSelector](#framewaitforselectorselector-options) or [frame.waitForXPath](#framewaitforxpathxpath-options)
docs(api): fix typo 'Than' was used in a few places instead of 'then'.
2017-10-10 18:07:39 +00:00
- if `selectorOrFunctionOrTimeout` is a `function`, then the first argument is treated as a predicate to wait for and the method is a shortcut for [frame.waitForFunction()](#framewaitforfunctionpagefunction-options-args).
- if `selectorOrFunctionOrTimeout` is a `number`, then the first argument is treated as a timeout in milliseconds and the method returns a promise which resolves after the timeout
Introduce polymorphic page.waitFor method This patch: - introduces page.waitForSelector to wait for the selector to appear - introduces polymorphic page.waitFor method, which accepts either string (and in this case is a shortcut for page.waitForSelector) or number (and in this case it's a promisified timeout). References #91.
2017-07-21 19:41:49 +00:00
- otherwise, an exception is thrown
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
page.waitFor should send ...args to page.waitForFunction (#775) This lets the user pass `...args` into `page.waitFor`. It also clarifies that the docs that `options` is not optional if `...args` are specified. Fixes #770
2017-09-15 21:28:15 +00:00
#### frame.waitForFunction(pageFunction[, options[, ...args]])
Implement page.waitForFunction method The page.waitForFunction method allows to wait for a general predicate. The predicate will be continiously polled for in page, until it either returns true or the timeout happens. The polling parameter could be one of the following: - 'raf' - to poll on every animation frame - 'mutation' - to poll on every dom mutation - <number> - to poll every X milliseconds References #91
2017-07-27 22:17:43 +00:00
- `pageFunction` <[function]|[string]> Function to be evaluated in browser context
- `options` <[Object]> Optional waiting parameters
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
- `polling` <[string]|[number]> An interval at which the `pageFunction` is executed, defaults to `raf`. If `polling` is a number, then it is treated as an interval in milliseconds at which the function would be executed. If `polling` is a string, then it can be one of the following values:
Implement page.waitForFunction method The page.waitForFunction method allows to wait for a general predicate. The predicate will be continiously polled for in page, until it either returns true or the timeout happens. The polling parameter could be one of the following: - 'raf' - to poll on every animation frame - 'mutation' - to poll on every dom mutation - <number> - to poll every X milliseconds References #91
2017-07-27 22:17:43 +00:00
- `raf` - to constantly execute `pageFunction` in `requestAnimationFrame` callback. This is the tightest polling mode which is suitable to observe styling changes.
- `mutation` - to execute `pageFunction` on every DOM mutation.
feat(page): add an option to disable timeout for waitForFunction (#2252) This patch adds support for `timeout: 0` to disable timeout for the following functions: - `page.waitForFunction` - `page.waitForXPath` - `page.waitForSelector` and their `frame` counterparts. Fixes #2200
2018-03-28 23:34:37 +00:00
- `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
- returns: <[Promise]<[JSHandle]>> Promise which resolves when the `pageFunction` returns a truthy value. It resolves to a JSHandle of the truthy value.
Implement page.waitForFunction method The page.waitForFunction method allows to wait for a general predicate. The predicate will be continiously polled for in page, until it either returns true or the timeout happens. The polling parameter could be one of the following: - 'raf' - to poll on every animation frame - 'mutation' - to poll on every dom mutation - <number> - to poll every X milliseconds References #91
2017-07-27 22:17:43 +00:00
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
The `waitForFunction` can be used to observe viewport size change:
Implement page.waitForFunction method The page.waitForFunction method allows to wait for a general predicate. The predicate will be continiously polled for in page, until it either returns true or the timeout happens. The polling parameter could be one of the following: - 'raf' - to poll on every animation frame - 'mutation' - to poll on every dom mutation - <number> - to poll every X milliseconds References #91
2017-07-27 22:17:43 +00:00
```js
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
const puppeteer = require('puppeteer');
Implement page.waitForFunction method The page.waitForFunction method allows to wait for a general predicate. The predicate will be continiously polled for in page, until it either returns true or the timeout happens. The polling parameter could be one of the following: - 'raf' - to poll on every animation frame - 'mutation' - to poll on every dom mutation - <number> - to poll every X milliseconds References #91
2017-07-27 22:17:43 +00:00
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
puppeteer.launch().then(async browser => {
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const page = await browser.newPage();
const watchDog = page.mainFrame().waitForFunction('window.innerWidth < 100');
Implement page.waitForFunction method The page.waitForFunction method allows to wait for a general predicate. The predicate will be continiously polled for in page, until it either returns true or the timeout happens. The polling parameter could be one of the following: - 'raf' - to poll on every animation frame - 'mutation' - to poll on every dom mutation - <number> - to poll every X milliseconds References #91
2017-07-27 22:17:43 +00:00
page.setViewport({width: 50, height: 50});
await watchDog;
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
Implement page.waitForFunction method The page.waitForFunction method allows to wait for a general predicate. The predicate will be continiously polled for in page, until it either returns true or the timeout happens. The polling parameter could be one of the following: - 'raf' - to poll on every animation frame - 'mutation' - to poll on every dom mutation - <number> - to poll every X milliseconds References #91
2017-07-27 22:17:43 +00:00
});
```
Introduce polymorphic page.waitFor method This patch: - introduces page.waitForSelector to wait for the selector to appear - introduces polymorphic page.waitFor method, which accepts either string (and in this case is a shortcut for page.waitForSelector) or number (and in this case it's a promisified timeout). References #91.
2017-07-21 19:41:49 +00:00
#### frame.waitForSelector(selector[, options])
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- `selector` <[string]> A [selector] of an element to wait for
Implement visible option for Page.waitFor method This patch adds a 'visible' option to the Page.waitFor method, making it possible to wait for the element to become actually visible. References #89, #91.
2017-07-21 07:58:38 +00:00
- `options` <[Object]> Optional waiting parameters
Implement timeout option for page.waitFor This patch implements timeout option for page.waitFor. The function will throw if the selector doesn't appear during timeout milliseconds of waittime. References #89, #91.
2017-07-21 18:46:57 +00:00
- `visible` <[boolean]> wait for element to be present in DOM and to be visible, i.e. to not have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
docs(api): add missing 'hidden' option on frame.waitForSelector
2017-10-15 05:57:56 +00:00
- `hidden` <[boolean]> wait for element to not be found in the DOM or to be hidden, i.e. have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
feat(page): add an option to disable timeout for waitForFunction (#2252) This patch adds support for `timeout: 0` to disable timeout for the following functions: - `page.waitForFunction` - `page.waitForXPath` - `page.waitForSelector` and their `frame` counterparts. Fixes #2200
2018-03-28 23:34:37 +00:00
- `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- returns: <[Promise]<[ElementHandle]>> Promise which resolves when element specified by selector string is added to DOM.
Added frame.waitFor(selector) (#59) This patch adds `frame.waitFor(selector)` method. Fixes #42.
2017-07-07 22:39:02 +00:00
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
Wait for the `selector` to appear in page. If at the moment of calling
the method the `selector` already exists, the method will return
Implement timeout option for page.waitFor This patch implements timeout option for page.waitFor. The function will throw if the selector doesn't appear during timeout milliseconds of waittime. References #89, #91.
2017-07-21 18:46:57 +00:00
immediately. If the selector doesn't appear after the `timeout` milliseconds of waiting, the function will throw.
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
Implement visible option for Page.waitFor method This patch adds a 'visible' option to the Page.waitFor method, making it possible to wait for the element to become actually visible. References #89, #91.
2017-07-21 07:58:38 +00:00
This method works across navigations:
```js
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
const puppeteer = require('puppeteer');
Implement visible option for Page.waitFor method This patch adds a 'visible' option to the Page.waitFor method, making it possible to wait for the element to become actually visible. References #89, #91.
2017-07-21 07:58:38 +00:00
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
puppeteer.launch().then(async browser => {
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const page = await browser.newPage();
Implement visible option for Page.waitFor method This patch adds a 'visible' option to the Page.waitFor method, making it possible to wait for the element to become actually visible. References #89, #91.
2017-07-21 07:58:38 +00:00
let currentURL;
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
page.mainFrame()
Make prettier JS snippets (#377) * Make prettier JS snippets * Conform to CS (about curly brace) * Apply feedback
2017-08-18 23:46:10 +00:00
.waitForSelector('img')
.then(() => console.log('First URL with image: ' + currentURL));
Implement visible option for Page.waitFor method This patch adds a 'visible' option to the Page.waitFor method, making it possible to wait for the element to become actually visible. References #89, #91.
2017-07-21 07:58:38 +00:00
for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com'])
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
await page.goto(currentURL);
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
Implement visible option for Page.waitFor method This patch adds a 'visible' option to the Page.waitFor method, making it possible to wait for the element to become actually visible. References #89, #91.
2017-07-21 07:58:38 +00:00
});
```
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
#### frame.waitForXPath(xpath[, options])
- `xpath` <[string]> A [xpath] of an element to wait for
- `options` <[Object]> Optional waiting parameters
- `visible` <[boolean]> wait for element to be present in DOM and to be visible, i.e. to not have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
- `hidden` <[boolean]> wait for element to not be found in the DOM or to be hidden, i.e. have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
feat(page): add an option to disable timeout for waitForFunction (#2252) This patch adds support for `timeout: 0` to disable timeout for the following functions: - `page.waitForFunction` - `page.waitForXPath` - `page.waitForSelector` and their `frame` counterparts. Fixes #2200
2018-03-28 23:34:37 +00:00
- `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
- returns: <[Promise]<[ElementHandle]>> Promise which resolves when element specified by xpath string is added to DOM.
Wait for the `xpath` to appear in page. If at the moment of calling
the method the `xpath` already exists, the method will return
immediately. If the xpath doesn't appear after the `timeout` milliseconds of waiting, the function will throw.
This method works across navigations:
```js
const puppeteer = require('puppeteer');
puppeteer.launch().then(async browser => {
const page = await browser.newPage();
let currentURL;
page.mainFrame()
.waitForXPath('//img')
.then(() => console.log('First URL with image: ' + currentURL));
for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com'])
await page.goto(currentURL);
await browser.close();
});
```
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
### class: ExecutionContext
The class represents a context for JavaScript execution. Examples of JavaScript contexts are:
- each [frame](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) has a separate execution context
- all kind of [workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) have their own contexts
#### executionContext.evaluate(pageFunction, ...args)
chore(doc): fix nits after JSHandles PR (#976)
2017-10-07 15:31:55 +00:00
- `pageFunction` <[function]|[string]> Function to be evaluated in `executionContext`
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
- returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
If the function passed to the `executionContext.evaluate` returns a [Promise], then `executionContext.evaluate` would wait for the promise to resolve and return its value.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
```js
docs(api.md): fix missing await in examples (#1801) `frame.executionContext()` returns a Promise, so running examples without `await` results in exceptions
2018-01-17 00:59:00 +00:00
const executionContext = await page.mainFrame().executionContext();
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
const result = await executionContext.evaluate(() => Promise.resolve(8 * 7));
console.log(result); // prints "56"
```
A string can also be passed in instead of a function.
```js
console.log(await executionContext.evaluate('1 + 2')); // prints "3"
```
chore(doc): fix nits after JSHandles PR (#976)
2017-10-07 15:31:55 +00:00
[JSHandle] instances can be passed as arguments to the `executionContext.evaluate`:
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
```js
const oneHandle = await executionContext.evaluateHandle(() => 1);
const twoHandle = await executionContext.evaluateHandle(() => 2);
const result = await executionContext.evaluate((a, b) => a + b, oneHandle, twoHandle);
await oneHandle.dispose();
await twoHandle.dispose();
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
console.log(result); // prints '3'.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
```
#### executionContext.evaluateHandle(pageFunction, ...args)
chore(doc): fix nits after JSHandles PR (#976)
2017-10-07 15:31:55 +00:00
- `pageFunction` <[function]|[string]> Function to be evaluated in the `executionContext`
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
- returns: <[Promise]<[JSHandle]>> Promise which resolves to the return value of `pageFunction` as in-page object (JSHandle)
The only difference between `executionContext.evaluate` and `executionContext.evaluateHandle` is that `executionContext.evaluateHandle` returns in-page object (JSHandle).
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
docs(api.md): fix typo (#2177)
2018-03-13 14:42:37 +00:00
If the function passed to the `executionContext.evaluateHandle` returns a [Promise], then `executionContext.evaluateHandle` would wait for the promise to resolve and return its value.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
```js
docs(api.md): fix missing await in examples (#1801) `frame.executionContext()` returns a Promise, so running examples without `await` results in exceptions
2018-01-17 00:59:00 +00:00
const context = await page.mainFrame().executionContext();
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
const aHandle = await context.evaluateHandle(() => Promise.resolve(self));
aHandle; // Handle for the global object.
```
A string can also be passed in instead of a function.
```js
const aHandle = await context.evaluateHandle('1 + 2'); // Handle for the '3' object.
```
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
[JSHandle] instances can be passed as arguments to the `executionContext.evaluateHandle`:
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
```js
const aHandle = await context.evaluateHandle(() => document.body);
const resultHandle = await context.evaluateHandle(body => body.innerHTML, aHandle);
console.log(await resultHandle.jsonValue()); // prints body's innerHTML
await aHandle.dispose();
await resultHandle.dispose();
```
feat(ExecutionContext): introduce ExecutionContext.frame() (#1972) This patch introduces ExecutionContext.frame() that returns Frame associated with this Execution Context. This allows to associate console messages with the originating frame, if any.
2018-02-13 22:02:44 +00:00
#### executionContext.frame()
- returns: <?[Frame]> Frame associated with this execution context.
> **NOTE** Not every execution context is associated with a frame. For example, workers and extensions have execution contexts that are not associated with frames.
feat(Page): introduce Page.queryObjects (#1005) This patch introduces `Page.queryObjects` and `ExecutionContext.queryObjects` methods to query JavaScript heap for objects with a certain prototype. Fixes #304.
2017-10-11 21:41:20 +00:00
#### executionContext.queryObjects(prototypeHandle)
- `prototypeHandle` <[JSHandle]> A handle to the object prototype.
- returns: <[JSHandle]> A handle to an array of objects with this prototype
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
The method iterates the JavaScript heap and finds all the objects with the given prototype.
feat(Page): introduce Page.queryObjects (#1005) This patch introduces `Page.queryObjects` and `ExecutionContext.queryObjects` methods to query JavaScript heap for objects with a certain prototype. Fixes #304.
2017-10-11 21:41:20 +00:00
```js
Roll chromium to 508268 (#1019) This gets us: - Plural metrics names https://crrev.com/507885 - TargetInfoChanged on URL changes https://crrev.com/508049 - Sending proper resource types for requests https://crrev.com/667504 Fixes #734
2017-10-12 08:17:06 +00:00
// Create a Map object
feat(Page): introduce Page.queryObjects (#1005) This patch introduces `Page.queryObjects` and `ExecutionContext.queryObjects` methods to query JavaScript heap for objects with a certain prototype. Fixes #304.
2017-10-11 21:41:20 +00:00
await page.evaluate(() => window.map = new Map());
// Get a handle to the Map object prototype
const mapPrototype = await page.evaluateHandle(() => Map.prototype);
// Query all map instances into an array
const mapInstances = await page.queryObjects(mapPrototype);
// Count amount of map objects in heap
const count = await page.evaluate(maps => maps.length, mapInstances);
await mapInstances.dispose();
await mapPrototype.dispose();
```
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
### class: JSHandle
docs(api): javascript -> JavaScript (#1338)
2017-11-10 21:35:22 +00:00
JSHandle represents an in-page JavaScript object. JSHandles can be created with the [page.evaluateHandle](#pageevaluatehandlepagefunction-args) method.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
```js
chore(doc): fix nits after JSHandles PR (#976)
2017-10-07 15:31:55 +00:00
const windowHandle = await page.evaluateHandle(() => window);
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
// ...
```
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
JSHandle prevents the referenced JavaScript object being garbage collected unless the handle is [disposed](#jshandledispose). JSHandles are auto-disposed when their origin frame gets navigated or the parent context gets destroyed.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
chore(doc): fix nits after JSHandles PR (#976)
2017-10-07 15:31:55 +00:00
JSHandle instances can be used as arguments in [`page.$eval()`](#pageevalselector-pagefunction-args), [`page.evaluate()`](#pageevaluatepagefunction-args) and [`page.evaluateHandle`](#pageevaluatehandlepagefunction-args) methods.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
#### jsHandle.asElement()
docs(api.md): fix return signatures that contains null (#1364)
2017-11-15 18:53:17 +00:00
- returns: <?[ElementHandle]>
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
Returns either `null` or the object handle itself, if the object handle is an instance of [ElementHandle].
#### jsHandle.dispose()
- returns: <[Promise]> Promise which resolves when the object handle is successfully disposed.
The `jsHandle.dispose` method stops referencing the element handle.
#### jsHandle.executionContext()
- returns: [ExecutionContext]
Returns execution context the handle belongs to.
#### jsHandle.getProperties()
- returns: <[Promise]<[Map]<[string], [JSHandle]>>>
The method returns a map with property names as keys and JSHandle instances for the property values.
```js
chore(doc): fix nits after JSHandles PR (#976)
2017-10-07 15:31:55 +00:00
const handle = await page.evaluateHandle(() => ({window, document}));
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
const properties = await handle.getProperties();
const windowHandle = properties.get('window');
const documentHandle = properties.get('document');
await handle.dispose();
```
#### jsHandle.getProperty(propertyName)
- `propertyName` <[string]> property to get
- returns: <[Promise]<[JSHandle]>>
Fetches a single property from the referenced object.
#### jsHandle.jsonValue()
- returns: <[Promise]<[Object]>>
fix(page.evaluate): jsonValue should ignore toJSON property (#1098) Currently, JSHandle.jsonValue() is implemented as in-page JSON.stringify call and consequent JSON.parse in node. This approach proved to be unfortunate for automation purposes: if page author overrode the Object.prototype.toJSON method, then it's harder for puppeteer to interact with the page. This patch switches JSHandle.jsonValue to use protocol serialization that ignores toJSON property. THis also changes the `page.evaluate` behavior since it is based on JSHandle.jsonValue(). Fixes #1003. BREAKING CHANGE: `page.evaluate` no longer calls toJSON when generating return value. For the old behavior, do JSON.parse/JSON.stringify manually: ```js const json = JSON.parse(await page.evaluate(() => JSON.stringify(obj))); ```
2017-10-20 17:45:49 +00:00
Returns a JSON representation of the object. If the object has a
[`toJSON`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#toJSON()_behavior)
function, it **will not be called**.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
> **NOTE** The method will return an empty JSON object if the referenced object is not stringifiable. It will throw an error if the object has circular references.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
### class: ElementHandle
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
> **NOTE** Class [ElementHandle] extends [JSHandle].
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
ElementHandle represents an in-page DOM element. ElementHandles can be created with the [page.$](#pageselector) method.
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
```js
const puppeteer = require('puppeteer');
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
puppeteer.launch().then(async browser => {
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const page = await browser.newPage();
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
await page.goto('https://google.com');
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const inputElement = await page.$('input[type=submit]');
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
await inputElement.click();
Make prettier JS snippets (#377) * Make prettier JS snippets * Conform to CS (about curly brace) * Apply feedback
2017-08-18 23:46:10 +00:00
// ...
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
});
```
Rename ElementHandle.release into ElementHandle.dispose (#284) The ElementHandle.release feels related to ElementHandle.click. The dispose is a more clear name.
2017-08-16 07:49:20 +00:00
ElementHandle prevents DOM element from garbage collection unless the handle is [disposed](#elementhandledispose). ElementHandles are auto-disposed when their origin frame gets navigated.
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
chore(doc): add a note about using ElementHandle instances (#925)
2017-10-01 22:47:40 +00:00
ElementHandle instances can be used as arguments in [`page.$eval()`](#pageevalselector-pagefunction-args) and [`page.evaluate()`](#pageevaluatepagefunction-args) methods.
feat(ElementHandle): add ElementHandle.$ and ElementHandle.$$ (#1151) This patch adds `ElementHandle.$` and `ElementHandle.$$` methods to query nested elements. Fixes #508
2017-10-27 09:08:58 +00:00
#### elementHandle.$(selector)
- `selector` <[string]> A [selector] to query element for
docs(api.md): fix return signatures that contains null (#1364)
2017-11-15 18:53:17 +00:00
- returns: <[Promise]<?[ElementHandle]>>
feat(ElementHandle): add ElementHandle.$ and ElementHandle.$$ (#1151) This patch adds `ElementHandle.$` and `ElementHandle.$$` methods to query nested elements. Fixes #508
2017-10-27 09:08:58 +00:00
The method runs `element.querySelector` within the page. If no element matches the selector, the return value resolve to `null`.
#### elementHandle.$$(selector)
- `selector` <[string]> A [selector] to query element for
- returns: <[Promise]<[Array]<[ElementHandle]>>>
The method runs `element.querySelectorAll` within the page. If no elements match the selector, the return value resolve to `[]`.
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
#### elementHandle.$x(expression)
- `expression` <[string]> Expression to [evaluate](https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate).
- returns: <[Promise]<?[ElementHandle]>> Promise which resolves to ElementHandle pointing to the frame element.
docs(api.md): fix typo on api docs (#1849)
2018-01-19 05:19:43 +00:00
The method evaluates the XPath expression relative to the elementHandle. If there's no such element, the method will resolve to `null`.
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
#### elementHandle.asElement()
feat(ElementHandle): add ElementHandle.$ and ElementHandle.$$ (#1151) This patch adds `ElementHandle.$` and `ElementHandle.$$` methods to query nested elements. Fixes #508
2017-10-27 09:08:58 +00:00
- returns: <[elementhandle]>
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
feat(ElementHandle): add EH.boundingBox and EH.screenshot This patch: - adds `ElementHandle.boundingBox()` method to get bounding box of element relative to the page - adds `ElementHandle.screenshot()` method to capture a screenshot of an element
2017-10-10 06:14:09 +00:00
#### elementHandle.boundingBox()
doc(api.md): ElementHandle.boundingBox() returns a promise (#1437)
2017-11-21 07:13:44 +00:00
- returns: <[Promise]<?[Object]>>
chore: Spelling and Markdown Consistency (#1998) - Adding missing language tags to markdown code blocks. - Fixed various spelling mistakes my IDE complained to me about.
2018-02-09 03:59:46 +00:00
- x <[number]> the x coordinate of the element in pixels.
- y <[number]> the y coordinate of the element in pixels.
- width <[number]> the width of the element in pixels.
- height <[number]> the height of the element in pixels.
feat(ElementHandle): add EH.boundingBox and EH.screenshot This patch: - adds `ElementHandle.boundingBox()` method to get bounding box of element relative to the page - adds `ElementHandle.screenshot()` method to capture a screenshot of an element
2017-10-10 06:14:09 +00:00
fix(Page.click): throw a meaningful message for invisible elements (#1309) This patch starts throwing a meaningful error message when trying to click the hidden node. References #1294
2017-11-07 21:54:40 +00:00
This method returns the bounding box of the element (relative to the main frame), or `null` if the element is not visible.
feat(ElementHandle): add EH.boundingBox and EH.screenshot This patch: - adds `ElementHandle.boundingBox()` method to get bounding box of element relative to the page - adds `ElementHandle.screenshot()` method to capture a screenshot of an element
2017-10-10 06:14:09 +00:00
feat(ElementHandle): add ElementHandle.boxModel method (#2256) This patch introduces ElementHandle.boxModel to get element's box model. Fixes #1357
2018-03-29 20:52:28 +00:00
#### elementHandle.boxModel()
- returns: <[Promise]<?[Object]>>
- content <[Array]<[Object]>> Content box, represented as an array of {x, y} points.
- padding <[Array]<[Object]>> Padding box, represented as an array of {x, y} points.
- border <[Array]<[Object]>> Border box, represented as an array of {x, y} points.
- margin <[Array]<[Object]>> Margin box, represented as an array of {x, y} points.
- width <[number]> Element's width.
- height <[number]> Element's height.
test(ElementHandle.boxModel): remake test to make it more readable (#2287) This patch: - re-makes test for EH.boxModel to make it more readable - slightly changes wording in the `docs/api.md`. References #1357.
2018-03-30 00:25:52 +00:00
This method returns boxes of the element, or `null` if the element is not visible. Boxes are represented as an array of points; each Point is an object `{x, y}`. Box points are sorted clock-wise.
feat(ElementHandle): add ElementHandle.boxModel method (#2256) This patch introduces ElementHandle.boxModel to get element's box model. Fixes #1357
2018-03-29 20:52:28 +00:00
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
#### elementHandle.click([options])
- `options` <[Object]>
- `button` <[string]> `left`, `right`, or `middle`, defaults to `left`.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `clickCount` <[number]> defaults to 1. See [UIEvent.detail].
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
- `delay` <[number]> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
- returns: <[Promise]> Promise which resolves when the element is successfully clicked. Promise gets rejected if the element is detached from DOM.
This method scrolls element into view if needed, and then uses [page.mouse](#pagemouse) to click in the center of the element.
If the element is detached from DOM, the method throws an error.
feat(ElementHandle): implement ElementHandle.contentFrame() (#2094) This patch adds ElementHandle.contentFrame() method that allows to get a reference to the Frame owned by the iframe. Fixes #433.
2018-02-24 05:22:53 +00:00
#### elementHandle.contentFrame()
- returns: <[Promise]<?[Frame]>> Resolves to the content frame for element handles referencing iframe nodes, or null otherwise
Rename ElementHandle.release into ElementHandle.dispose (#284) The ElementHandle.release feels related to ElementHandle.click. The dispose is a more clear name.
2017-08-16 07:49:20 +00:00
#### elementHandle.dispose()
- returns: <[Promise]> Promise which resolves when the element handle is successfully disposed.
The `elementHandle.dispose` method stops referencing the element handle.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
#### elementHandle.executionContext()
- returns: [ExecutionContext]
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
#### elementHandle.focus()
- returns: <[Promise]>
Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
#### elementHandle.getProperties()
- returns: <[Promise]<[Map]<[string], [JSHandle]>>>
The method returns a map with property names as keys and JSHandle instances for the property values.
```js
const listHandle = await page.evaluateHandle(() => document.body.children);
chore(doc): fix nits after JSHandles PR (#976)
2017-10-07 15:31:55 +00:00
const properties = await listHandle.getProperties();
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
const children = [];
for (const property of properties.values()) {
const element = property.asElement();
if (element)
children.push(element);
}
children; // holds elementHandles to all children of document.body
```
#### elementHandle.getProperty(propertyName)
- `propertyName` <[string]> property to get
- returns: <[Promise]<[JSHandle]>>
Fetches a single property from the objectHandle.
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
#### elementHandle.hover()
- returns: <[Promise]> Promise which resolves when the element is successfully hovered.
This method scrolls element into view if needed, and then uses [page.mouse](#pagemouse) to hover over the center of the element.
If the element is detached from DOM, the method throws an error.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
#### elementHandle.jsonValue()
- returns: <[Promise]<[Object]>>
Returns a JSON representation of the object. The JSON is generated by running [`JSON.stringify`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) on the object in page and consequent [`JSON.parse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) in puppeteer.
> **NOTE** The method will throw if the referenced object is not stringifiable.
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
#### elementHandle.press(key[, options])
feat(keyboard): Accept codes (#1116) BREAKING CHANGE: This patch lets key names be code in addition to key. When specifying a code, the proper text is generated assuming a standard US keyboard layout. e.g Digit5 -> "5" or "%" depending on Shift. * location is now specified. #777 * Using unknown key names now throws an error. #723 * Typing newlines now correctly presses enter. #681
2017-10-23 19:43:45 +00:00
- `key` <[string]> Name of key to press, such as `ArrowLeft`. See [USKeyboardLayout] for a list of all key names.
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
- `options` <[Object]>
- `text` <[string]> If specified, generates an input event with this text.
- `delay` <[number]> Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
- returns: <[Promise]>
Focuses the element, and then uses [`keyboard.down`](#keyboarddownkey-options) and [`keyboard.up`](#keyboardupkey).
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`/`input` event will also be generated. The `text` option can be specified to force an input event to be generated.
> **NOTE** Modifier keys DO effect `elementHandle.press`. Holding down `Shift` will type the text in upper case.
feat(ElementHandle): add EH.boundingBox and EH.screenshot This patch: - adds `ElementHandle.boundingBox()` method to get bounding box of element relative to the page - adds `ElementHandle.screenshot()` method to capture a screenshot of an element
2017-10-10 06:14:09 +00:00
#### elementHandle.screenshot([options])
- `options` <[Object]> Same options as in [page.screenshot](#pagescreenshotoptions).
- returns: <[Promise]<[Buffer]>> Promise which resolves to buffer with captured screenshot.
This method scrolls element into view if needed, and then uses [page.screenshot](#pagescreenshotoptions) to take a screenshot of the element.
If the element is detached from DOM, the method throws an error.
[api] add touchScreen.tap (#639) This patch: - adds `page.touchscreen` namespace, similar to `page.mouse` and `page.keyboard`. - adds tapping to multiple layers: - `page.touchscreen.tap` - `page.tap` - convenience method which accepts selector - `elementHandle.tap` Fixes #568 and #569.
2017-09-02 02:03:51 +00:00
#### elementHandle.tap()
- returns: <[Promise]> Promise which resolves when the element is successfully tapped. Promise gets rejected if the element is detached from DOM.
This method scrolls element into view if needed, and then uses [touchscreen.tap](#touchscreentapx-y) to tap in the center of the element.
If the element is detached from DOM, the method throws an error.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
#### elementHandle.toString()
- returns: <[string]>
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
#### elementHandle.type(text[, options])
- `text` <[string]> A text to type into a focused element.
- `options` <[Object]>
- `delay` <[number]> Time to wait between key presses in milliseconds. Defaults to 0.
- returns: <[Promise]>
Focuses the element, and then sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
To press a special key, like `Control` or `ArrowDown`, use [`elementHandle.press`](#elementhandlepresskey-options).
```js
elementHandle.type('Hello'); // Types instantly
elementHandle.type('World', {delay: 100}); // Types slower, like a user
```
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
An example of typing into a text field and then submitting the form:
```js
const elementHandle = await page.$('input');
await elementHandle.type('some text');
await elementHandle.press('Enter');
```
Move uploadFiles onto ElementHandle (#348) This patch: - removes the `page.uploadFile` method - adds `elementHandle.uploadFile` method. Motivation: `elementHandle.uploadFile` is rarely used, so it doesn't worth it to keep it on page.
2017-08-17 21:53:37 +00:00
#### elementHandle.uploadFile(...filePaths)
- `...filePaths` <...[string]> Sets the value of the file input these paths. If some of the `filePaths` are relative paths, then they are resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
- returns: <[Promise]>
This method expects `elementHandle` to point to an [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
### class: Request
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
Whenever the page sends a request, the following events are emitted by puppeteer's page:
- ['request'](#event-request) emitted when the request is issued by the page.
- ['response'](#event-response) emitted when/if the response is received for the request.
- ['requestfinished'](#event-requestfinished) emitted when the response body is downloaded and the request is complete.
If request fails at some point, then instead of 'requestfinished' event (and possibly instead of 'response' event), the ['requestfailed'](#event-requestfailed) event is emitted.
If request gets a 'redirect' response, the request is successfully finished with the 'requestfinished' event, and a new request is issued to a redirected url.
feat(Request): allow aborting intercepted requests with custom reasons (#1080) This patch adds optional parameter to the `request.abort()` method that specifies abort reason. References #1020.
2017-10-18 07:26:48 +00:00
#### request.abort([errorCode])
- `errorCode` <[string]> Optional error code. Defaults to `failed`, could be
one of the following:
- `aborted` - An operation was aborted (due to user action)
- `accessdenied` - Permission to access a resource, other than the network, was denied
- `addressunreachable` - The IP address is unreachable. This usually means
that there is no route to the specified host or network.
- `connectionaborted` - A connection timed out as a result of not receiving an ACK for data sent.
- `connectionclosed` - A connection was closed (corresponding to a TCP FIN).
- `connectionfailed` - A connection attempt failed.
- `connectionrefused` - A connection attempt was refused.
- `connectionreset` - A connection was reset (corresponding to a TCP RST).
- `internetdisconnected` - The Internet connection has been lost.
- `namenotresolved` - The host name could not be resolved.
- `timedout` - An operation timed out.
- `failed` - A generic failure occurred.
Do not leave dangling promises when sending messages over protocol (#742) It's very bad to have 'unhandled promise rejection' that can't be handled in user code. These errors will exit node process in a near future. This patch avoids 'unhandled promise rejection' while sending protocol messages. This patch: - introduces `puppeteer:error` debug scope and starts using it for all swalloed errors. - makes sure that every `client.send` method is either awaited or its errors are handled. - starts return promises from Request.continue() and Request.abort(). - starts swallow errors from Request.contine() and Request.abort(). The last is the most important part of the patch. Since `Request.continue()` might try to continue canceled request, we should disregard the error. Fixes #627.
2017-09-11 23:21:51 +00:00
- returns: <[Promise]>
Introduce new interception API (#242) This patch introduces new interception API, via killing InterceptedRequest and giving the `abort` and `continue` methods to the Request object.
2017-08-12 00:24:31 +00:00
feat(Chromium): Roll chromium to r511134 (#1153) This roll includes: - crrev.com/510651 that changes request interception methods in protocol - s/Page.setRequestInterceptionEnabled/Page.setRequestInterception BREAKING CHANGE Page.setRequestInterceptionEnabled is renamed into Page.setRequestInterception.
2017-10-24 21:45:03 +00:00
Aborts request. To use this, request interception should be enabled with `page.setRequestInterception`.
Introduce new interception API (#242) This patch introduces new interception API, via killing InterceptedRequest and giving the `abort` and `continue` methods to the Request object.
2017-08-12 00:24:31 +00:00
Exception is immediately thrown if the request interception is not enabled.
#### request.continue([overrides])
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
- `overrides` <[Object]> Optional request overwrites, which can be one of the following:
Introduce new interception API (#242) This patch introduces new interception API, via killing InterceptedRequest and giving the `abort` and `continue` methods to the Request object.
2017-08-12 00:24:31 +00:00
- `url` <[string]> If set, the request url will be changed
- `method` <[string]> If set changes the request method (e.g. `GET` or `POST`)
- `postData` <[string]> If set changes the post data of request
[api] use object instead of map for headers (#567) This patch: - switches to objects instead of maps for headers (in Request, Response and page.setExtraHTTPHeaders) - converts all header names to lower case Fixes #547, fixes #509
2017-08-28 19:09:24 +00:00
- `headers` <[Object]> If set changes the request HTTP headers
Do not leave dangling promises when sending messages over protocol (#742) It's very bad to have 'unhandled promise rejection' that can't be handled in user code. These errors will exit node process in a near future. This patch avoids 'unhandled promise rejection' while sending protocol messages. This patch: - introduces `puppeteer:error` debug scope and starts using it for all swalloed errors. - makes sure that every `client.send` method is either awaited or its errors are handled. - starts return promises from Request.continue() and Request.abort(). - starts swallow errors from Request.contine() and Request.abort(). The last is the most important part of the patch. Since `Request.continue()` might try to continue canceled request, we should disregard the error. Fixes #627.
2017-09-11 23:21:51 +00:00
- returns: <[Promise]>
Introduce new interception API (#242) This patch introduces new interception API, via killing InterceptedRequest and giving the `abort` and `continue` methods to the Request object.
2017-08-12 00:24:31 +00:00
feat(Chromium): Roll chromium to r511134 (#1153) This roll includes: - crrev.com/510651 that changes request interception methods in protocol - s/Page.setRequestInterceptionEnabled/Page.setRequestInterception BREAKING CHANGE Page.setRequestInterceptionEnabled is renamed into Page.setRequestInterception.
2017-10-24 21:45:03 +00:00
Continues request with optional request overrides. To use this, request interception should be enabled with `page.setRequestInterception`.
Introduce new interception API (#242) This patch introduces new interception API, via killing InterceptedRequest and giving the `abort` and `continue` methods to the Request object.
2017-08-12 00:24:31 +00:00
Exception is immediately thrown if the request interception is not enabled.
feat(Request): introduce Request.failure() method (#1065) Similarly to the `request.response()` method, this patch adds `request.failure()` method that returns error details for the failed requests. Fixes #901.
2017-10-18 00:48:04 +00:00
#### request.failure()
docs(api.md): fix return signatures that contains null (#1364)
2017-11-15 18:53:17 +00:00
- returns: <?[Object]> Object describing request failure, if any
feat(Request): introduce Request.failure() method (#1065) Similarly to the `request.response()` method, this patch adds `request.failure()` method that returns error details for the failed requests. Fixes #901.
2017-10-18 00:48:04 +00:00
- `errorText` <[string]> Human-readable error message, e.g. `'net::ERR_FAILED'`.
docs(api.md): fix return signatures that contains null (#1364)
2017-11-15 18:53:17 +00:00
The method returns `null` unless this request was failed, as reported by
feat(Request): introduce Request.failure() method (#1065) Similarly to the `request.response()` method, this patch adds `request.failure()` method that returns error details for the failed requests. Fixes #901.
2017-10-18 00:48:04 +00:00
`requestfailed` event.
Example of logging all failed requests:
```js
page.on('requestfailed', request => {
docs(api.md): fix sample code in API doc, `request.url` -> `request.url()` (#1889)
2018-01-25 05:09:37 +00:00
console.log(request.url() + ' ' + request.failure().errorText);
feat(Request): introduce Request.failure() method (#1065) Similarly to the `request.response()` method, this patch adds `request.failure()` method that returns error details for the failed requests. Fixes #901.
2017-10-18 00:48:04 +00:00
});
```
feat: Attribute network requests to frames (#1646) This patch introduces `request.frame()` method that returns the frame that initiated request. Fixes #1579
2018-01-10 02:47:21 +00:00
#### request.frame()
- returns: <?[Frame]> A matching [Frame] object, or `null` if navigating to error pages.
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
#### request.headers()
- returns: <[Object]> An object with HTTP headers associated with the request. All header names are lower-case.
[doclint] add linting for class properties This patch: - adds linting for class properties - adds documentation for the missing class properties References #14.
2017-07-12 15:01:21 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
#### request.method()
- returns: <[string]> Request's method (GET, POST, etc.)
Get rid of Body class The Body class was inlined in the Request and Response classes. This patch: - removes the Body class - adds Request.postData public property - adds Response.buffer(), Response.text() and Response.json() methods Fixes #106.
2017-07-28 06:11:24 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
#### request.postData()
- returns: <[string]> Request's post body, if any.
[doclint] introduce class members This patch unifies Documentation.Method with Documentation.Property, making it possible to verify sorting order across methods and properties. References #14.
2017-07-14 05:52:02 +00:00
feat(Network): implement request.redirectChain() api (#2194) The request.redirectChain() returns all the requests issued to fetch the resource. Fixes #1816.
2018-03-16 00:17:38 +00:00
#### request.redirectChain()
- returns: <[Array]<[Request]>>
A `redirectChain` is a chain of requests initiated to fetch a resource.
- If there are no redirects and the request was successful, the chain will be empty.
- If a server responds with at least a single redirect, then the chain will
contain all the requests that were redirected.
`redirectChain` is shared between all the requests of the same chain.
For example, if the website `http://example.com` has a single redirect to
`https://example.com`, then the chain will contain one request:
```js
const response = await page.goto('http://example.com');
const chain = response.request().redirectChain();
console.log(chain.length); // 1
console.log(chain[0].url()); // 'http://example.com'
```
If the website `https://google.com` has no redirects, then the chain will be empty:
```js
const response = await page.goto('https://google.com');
const chain = response.request().redirectChain();
console.log(chain.length); // 0
```
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
#### request.resourceType()
- returns: <[string]>
Implement Request.resourceType getter (#590) This patch plumbs `resourceType` parameter of RequestWillBeSent and requestIntercepted methods.
2017-08-29 23:27:59 +00:00
Contains the request's resource type as it was perceived by the rendering engine.
fix(Request): convert resourceType to all small-caps (#990) This patch moves resourceType to be all small-caps. This aligns with our convention that all string constants should be smallcaps. BREAKING CHANGE: this patch changes the constants of the request.resourceType to be all small-caps.
2017-10-10 17:53:37 +00:00
ResourceType will be one of the following: `document`, `stylesheet`, `image`, `media`, `font`, `script`, `texttrack`, `xhr`, `fetch`, `eventsource`, `websocket`, `manifest`, `other`.
Implement Request.resourceType getter (#590) This patch plumbs `resourceType` parameter of RequestWillBeSent and requestIntercepted methods.
2017-08-29 23:27:59 +00:00
feat(interception): Implement request.mockResponse method (#1064) feat(interception): Implement request.respond method This patch implements a new Request.respond method. This allows users to fulfill the intercepted request with a hand-crafted response if they wish so. References #1020.
2017-10-20 23:55:15 +00:00
#### request.respond(response)
- `response` <[Object]> Response that will fulfill this request
- `status` <[number]> Response status code, defaults to `200`.
- `headers` <[Object]> Optional response headers
- `contentType` <[string]> If set, equals to setting `Content-Type` response header
- `body` <[Buffer]|[string]> Optional response body
- returns: <[Promise]>
Fulfills request with given response. To use this, request interception should
feat(Chromium): Roll chromium to r511134 (#1153) This roll includes: - crrev.com/510651 that changes request interception methods in protocol - s/Page.setRequestInterceptionEnabled/Page.setRequestInterception BREAKING CHANGE Page.setRequestInterceptionEnabled is renamed into Page.setRequestInterception.
2017-10-24 21:45:03 +00:00
be enabled with `page.setRequestInterception`. Exception is thrown if
feat(interception): Implement request.mockResponse method (#1064) feat(interception): Implement request.respond method This patch implements a new Request.respond method. This allows users to fulfill the intercepted request with a hand-crafted response if they wish so. References #1020.
2017-10-20 23:55:15 +00:00
request interception is not enabled.
An example of fulfilling all requests with 404 responses:
```js
feat(Chromium): Roll chromium to r511134 (#1153) This roll includes: - crrev.com/510651 that changes request interception methods in protocol - s/Page.setRequestInterceptionEnabled/Page.setRequestInterception BREAKING CHANGE Page.setRequestInterceptionEnabled is renamed into Page.setRequestInterception.
2017-10-24 21:45:03 +00:00
await page.setRequestInterception(true);
feat(interception): Implement request.mockResponse method (#1064) feat(interception): Implement request.respond method This patch implements a new Request.respond method. This allows users to fulfill the intercepted request with a hand-crafted response if they wish so. References #1020.
2017-10-20 23:55:15 +00:00
page.on('request', request => {
request.respond({
status: 404,
contentType: 'text/plain',
body: 'Not Found!'
});
});
```
fix: support PlzNavigate in puppeteer. (#1239) This patch migrates puppeteer to support PlzNavigate chromium project. As a consequence of this patch, we no longer wait for both requestWillBeSent and requestIntercepted events to happen. This should resolve a ton of request interception bugs that "hanged" the loading. Fixes #877.
2017-11-01 21:04:10 +00:00
> **NOTE** Mocking responses for dataURL requests is not supported.
> Calling `request.respond` for a dataURL request is a noop.
feat(interception): Implement request.mockResponse method (#1064) feat(interception): Implement request.respond method This patch implements a new Request.respond method. This allows users to fulfill the intercepted request with a hand-crafted response if they wish so. References #1020.
2017-10-20 23:55:15 +00:00
[doclint] introduce class members This patch unifies Documentation.Method with Documentation.Property, making it possible to verify sorting order across methods and properties. References #14.
2017-07-14 05:52:02 +00:00
#### request.response()
docs(api.md): fix return signatures that contains null (#1364)
2017-11-15 18:53:17 +00:00
- returns: <?[Response]> A matching [Response] object, or `null` if the response has not been received yet.
[doclint] introduce class members This patch unifies Documentation.Method with Documentation.Property, making it possible to verify sorting order across methods and properties. References #14.
2017-07-14 05:52:02 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
#### request.url()
- returns: <[string]> URL of the request.
Fill doc with stubs for missing documentation methods. This patch fills doc with stubs so that the command `npm run doc` does not complain.
2017-07-07 17:34:35 +00:00
### class: Response
[doclint] add linting for class properties This patch: - adds linting for class properties - adds documentation for the missing class properties References #14.
2017-07-12 15:01:21 +00:00
doc: remove mentions of removed Boxy mixin (#425) Fixes #399.
2017-08-20 23:03:30 +00:00
[Response] class represents responses which are received by page.
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
Get rid of Body class The Body class was inlined in the Request and Response classes. This patch: - removes the Body class - adds Request.postData public property - adds Response.buffer(), Response.text() and Response.json() methods Fixes #106.
2017-07-28 06:11:24 +00:00
#### response.buffer()
- returns: <Promise<[Buffer]>> Promise which resolves to a buffer with response body.
feat(Response): add Response.fromCache / Response.fromServiceWorker (#1971) This patch: - introduces `test/assets/cached` folder and teaches server to cache all the assets from the folder - introduces `test/assets/serviceworkers` folder that stores all the service workers and makes them register with unique URL prefix - introduces `Response.fromCache()` and `Response.fromServiceWorker()` methods Fixes #1551.
2018-02-05 22:59:07 +00:00
#### response.fromCache()
- returns: <[boolean]>
True if the response was served from either the browser's disk cache or memory cache.
#### response.fromServiceWorker()
- returns: <[boolean]>
True if the response was served by a service worker.
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
#### response.headers()
- returns: <[Object]> An object with HTTP headers associated with the response. All header names are lower-case.
[doclint] add linting for class properties This patch: - adds linting for class properties - adds documentation for the missing class properties References #14.
2017-07-12 15:01:21 +00:00
Get rid of Body class The Body class was inlined in the Request and Response classes. This patch: - removes the Body class - adds Request.postData public property - adds Response.buffer(), Response.text() and Response.json() methods Fixes #106.
2017-07-28 06:11:24 +00:00
#### response.json()
- returns: <Promise<[Object]>> Promise which resolves to a JSON representation of response body.
This method will throw if the response body is not parsable via `JSON.parse`.
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
#### response.ok()
- returns: <[boolean]>
[doclint] add linting for class properties This patch: - adds linting for class properties - adds documentation for the missing class properties References #14.
2017-07-12 15:01:21 +00:00
Contains a boolean stating whether the response was successful (status in the range 200-299) or not.
[doclint] introduce class members This patch unifies Documentation.Method with Documentation.Property, making it possible to verify sorting order across methods and properties. References #14.
2017-07-14 05:52:02 +00:00
#### response.request()
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
- returns: <[Request]> A matching [Request] object.
feat(Network): introduce response.securityDetails() method (#1880) This patch: - introduces `SecurityDetails` class that exposes a set of fields that describe properties of secure connection - introduces method `response.securityDetails()` that returns an instance of `SecurityDetails` object.
2018-02-13 19:26:18 +00:00
#### response.securityDetails()
fix(Network): fulfill security details for response redirects (#2025) This patch: - starts fulfilling security details for redirect responses - changes `response.securityDetails()` to return null if the response is served over non-secure connection
2018-02-15 00:08:20 +00:00
- returns: <?[SecurityDetails]> Security details if the response was received over the secure connection, or `null` otherwise.
feat(Network): introduce response.securityDetails() method (#1880) This patch: - introduces `SecurityDetails` class that exposes a set of fields that describe properties of secure connection - introduces method `response.securityDetails()` that returns an instance of `SecurityDetails` object.
2018-02-13 19:26:18 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
#### response.status()
- returns: <[number]>
[doclint] add linting for class properties This patch: - adds linting for class properties - adds documentation for the missing class properties References #14.
2017-07-12 15:01:21 +00:00
Contains the status code of the response (e.g., 200 for a success).
Get rid of Body class The Body class was inlined in the Request and Response classes. This patch: - removes the Body class - adds Request.postData public property - adds Response.buffer(), Response.text() and Response.json() methods Fixes #106.
2017-07-28 06:11:24 +00:00
#### response.text()
doc: Fix return type in response.text()
2017-08-20 21:32:14 +00:00
- returns: <[Promise]<[string]>> Promise which resolves to a text representation of response body.
[doclint] introduce class members This patch unifies Documentation.Method with Documentation.Property, making it possible to verify sorting order across methods and properties. References #14.
2017-07-14 05:52:02 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
#### response.url()
- returns: <[string]>
[doclint] add linting for class properties This patch: - adds linting for class properties - adds documentation for the missing class properties References #14.
2017-07-12 15:01:21 +00:00
Contains the URL of the response.
feat(Network): introduce response.securityDetails() method (#1880) This patch: - introduces `SecurityDetails` class that exposes a set of fields that describe properties of secure connection - introduces method `response.securityDetails()` that returns an instance of `SecurityDetails` object.
2018-02-13 19:26:18 +00:00
### class: SecurityDetails
[SecurityDetails] class represents responses which are received by page.
#### securityDetails.issuer()
- returns: <[string]> A string with the name of issuer of the certificate.
#### securityDetails.protocol()
- returns: <[string]> String with the security protocol, eg. "TLS 1.2".
#### securityDetails.subjectName()
- returns: <[string]> Name of the subject to which the certificate was issued to.
#### securityDetails.validFrom()
fix(Network): fulfill security details for response redirects (#2025) This patch: - starts fulfilling security details for redirect responses - changes `response.securityDetails()` to return null if the response is served over non-secure connection
2018-02-15 00:08:20 +00:00
- returns: <[number]> [UnixTime] stating the start of validity of the certificate.
feat(Network): introduce response.securityDetails() method (#1880) This patch: - introduces `SecurityDetails` class that exposes a set of fields that describe properties of secure connection - introduces method `response.securityDetails()` that returns an instance of `SecurityDetails` object.
2018-02-13 19:26:18 +00:00
#### securityDetails.validTo()
fix(Network): fulfill security details for response redirects (#2025) This patch: - starts fulfilling security details for redirect responses - changes `response.securityDetails()` to return null if the response is served over non-secure connection
2018-02-15 00:08:20 +00:00
- returns: <[number]> [UnixTime] stating the end of validity of the certificate.
feat(Network): introduce response.securityDetails() method (#1880) This patch: - introduces `SecurityDetails` class that exposes a set of fields that describe properties of secure connection - introduces method `response.securityDetails()` that returns an instance of `SecurityDetails` object.
2018-02-13 19:26:18 +00:00
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
### class: Target
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
#### target.createCDPSession()
- returns: <[Promise]<[CDPSession]>>
Creates a Chrome Devtools Protocol session attached to the target.
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
#### target.page()
docs(api.md): fix return signatures that contains null (#1364)
2017-11-15 18:53:17 +00:00
- returns: <[Promise]<?[Page]>>
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
If the target is not of type `"page"`, returns `null`.
#### target.type()
- returns: <[string]>
feat(Targets): expose browser target (#2036) This patch exposes "browser" target to the list of targets.
2018-02-15 21:24:24 +00:00
Identifies what kind of target this is. Can be `"page"`, `"service_worker"`, `"browser"` or `"other"`.
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
#### target.url()
- returns: <[string]>
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
### class: CDPSession
* extends: [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter)
The `CDPSession` instances are used to talk raw Chrome Devtools Protocol:
- protocol methods can be called with `session.send` method.
- protocol events can be subscribed to with `session.on` method.
Documentation on DevTools Protocol can be found here: [DevTools Protocol Viewer](https://chromedevtools.github.io/devtools-protocol/).
```js
const client = await page.target().createCDPSession();
await client.send('Animation.enable');
await client.on('Animation.animationCreated', () => console.log('Animation created!'));
const response = await client.send('Animation.getPlaybackRate');
console.log('playback rate is ' + response.playbackRate);
await client.send('Animation.setPlaybackRate', {
playbackRate: response.playbackRate / 2
});
```
#### cdpSession.detach()
- returns: <[Promise]>
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
Detaches the cdpSession from the target. Once detached, the cdpSession object won't emit any events and can't be used
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
to send messages.
#### cdpSession.send(method[, params])
- `method` <[string]> protocol method name
- `params` <[Object]> Optional method parameters
- returns: <[Promise]<[Object]>>
feat: Implement JavaScript Coverage (#1673) This patch introduces a new `page.coverage` namespace with two methods: - `page.coverage.startJSCoverage` to initiate JavaScript coverage recording - `page.coverage.stopJSCoverage` to stop JavaScript coverage and get results
2018-01-03 03:53:53 +00:00
### class: Coverage
feat: implement CSS Coverage (#1714) This patch adds two new methods to the `page.coverage` namespace: - `page.coverage.startCSSCoverage()` - to initiate css coverage - `page.coverage.stopCSSCoverage()` - to stop css coverage The coverage format is consistent with the JavaScript coverage.
2018-01-04 02:21:40 +00:00
Coverage gathers information about parts of JavaScript and CSS that were used by the page.
An example of using JavaScript and CSS coverage to get percentage of initially
executed code:
```js
// Enable both JavaScript and CSS coverage
await Promise.all([
docs(api): fix coverage example and typo (#1854)
2018-01-19 05:19:13 +00:00
page.coverage.startJSCoverage(),
page.coverage.startCSSCoverage()
feat: implement CSS Coverage (#1714) This patch adds two new methods to the `page.coverage` namespace: - `page.coverage.startCSSCoverage()` - to initiate css coverage - `page.coverage.stopCSSCoverage()` - to stop css coverage The coverage format is consistent with the JavaScript coverage.
2018-01-04 02:21:40 +00:00
]);
// Navigate to page
await page.goto('https://example.com');
// Disable both JavaScript and CSS coverage
const [jsCoverage, cssCoverage] = await Promise.all([
docs(api): fix coverage example and typo (#1854)
2018-01-19 05:19:13 +00:00
page.coverage.stopJSCoverage(),
page.coverage.stopCSSCoverage(),
feat: implement CSS Coverage (#1714) This patch adds two new methods to the `page.coverage` namespace: - `page.coverage.startCSSCoverage()` - to initiate css coverage - `page.coverage.stopCSSCoverage()` - to stop css coverage The coverage format is consistent with the JavaScript coverage.
2018-01-04 02:21:40 +00:00
]);
let totalBytes = 0;
let usedBytes = 0;
docs(api): fix coverage example and typo (#1854)
2018-01-19 05:19:13 +00:00
const coverage = [...jsCoverage, ...cssCoverage];
feat: implement CSS Coverage (#1714) This patch adds two new methods to the `page.coverage` namespace: - `page.coverage.startCSSCoverage()` - to initiate css coverage - `page.coverage.stopCSSCoverage()` - to stop css coverage The coverage format is consistent with the JavaScript coverage.
2018-01-04 02:21:40 +00:00
for (const entry of coverage) {
totalBytes += entry.text.length;
for (const range of entry.ranges)
usedBytes += range.end - range.start - 1;
}
console.log(`Bytes used: ${usedBytes / totalBytes * 100}%`);
```
docs: add documentation referencing puppeteer-to-istanbul (#2135) Fixes #1768.
2018-03-07 05:49:01 +00:00
_To output coverage in a form consumable by [Istanbul](https://github.com/istanbuljs),
see [puppeteer-to-istanbul](https://github.com/istanbuljs/puppeteer-to-istanbul)._
feat: implement CSS Coverage (#1714) This patch adds two new methods to the `page.coverage` namespace: - `page.coverage.startCSSCoverage()` - to initiate css coverage - `page.coverage.stopCSSCoverage()` - to stop css coverage The coverage format is consistent with the JavaScript coverage.
2018-01-04 02:21:40 +00:00
#### coverage.startCSSCoverage(options)
- `options` <[Object]> Set of configurable options for coverage
- `resetOnNavigation` <[boolean]> Whether to reset coverage on every navigation. Defaults to `true`.
- returns: <[Promise]> Promise that resolves when coverage is started
feat: Implement JavaScript Coverage (#1673) This patch introduces a new `page.coverage` namespace with two methods: - `page.coverage.startJSCoverage` to initiate JavaScript coverage recording - `page.coverage.stopJSCoverage` to stop JavaScript coverage and get results
2018-01-03 03:53:53 +00:00
#### coverage.startJSCoverage(options)
- `options` <[Object]> Set of configurable options for coverage
- `resetOnNavigation` <[boolean]> Whether to reset coverage on every navigation. Defaults to `true`.
- returns: <[Promise]> Promise that resolves when coverage is started
feat: implement CSS Coverage (#1714) This patch adds two new methods to the `page.coverage` namespace: - `page.coverage.startCSSCoverage()` - to initiate css coverage - `page.coverage.stopCSSCoverage()` - to stop css coverage The coverage format is consistent with the JavaScript coverage.
2018-01-04 02:21:40 +00:00
#### coverage.stopCSSCoverage()
- returns: <[Promise]<[Array]<[Object]>>> Promise that resolves to the array of coverage reports for all stylesheets
- `url` <[string]> StyleSheet URL
- `text` <[string]> StyleSheet content
- `ranges` <[Array]<[Object]>> StyleSheet ranges that were used. Ranges are sorted and non-overlapping.
- `start` <[number]> A start offset in text, inclusive
- `end` <[number]> An end offset in text, exclusive
> **NOTE** CSS Coverage doesn't include dynamically injected style tags without sourceURLs.
feat: Implement JavaScript Coverage (#1673) This patch introduces a new `page.coverage` namespace with two methods: - `page.coverage.startJSCoverage` to initiate JavaScript coverage recording - `page.coverage.stopJSCoverage` to stop JavaScript coverage and get results
2018-01-03 03:53:53 +00:00
#### coverage.stopJSCoverage()
- returns: <[Promise]<[Array]<[Object]>>> Promise that resolves to the array of coverage reports for all non-anonymous scripts
- `url` <[string]> Script URL
- `text` <[string]> Script content
- `ranges` <[Array]<[Object]>> Script ranges that were executed. Ranges are sorted and non-overlapping.
- `start` <[number]> A start offset in text, inclusive
- `end` <[number]> An end offset in text, exclusive
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
> **NOTE** JavaScript Coverage doesn't include anonymous scripts. However, scripts with sourceURLs are
feat: Implement JavaScript Coverage (#1673) This patch introduces a new `page.coverage` namespace with two methods: - `page.coverage.startJSCoverage` to initiate JavaScript coverage recording - `page.coverage.stopJSCoverage` to stop JavaScript coverage and get results
2018-01-03 03:53:53 +00:00
reported.
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.
2017-06-21 18:17:35 +00:00
[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"
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
[Page]: #class-page "Page"
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.
2017-06-21 18:17:35 +00:00
[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"
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
[stream.Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "stream.Readable"
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
[CDPSession]: #class-cdpsession "CDPSession"
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
[BrowserFetcher]: #class-browserfetcher "BrowserFetcher"
Emit 'error' event when page crashes (#266) This patch starts emitting 'error' event when page crashes. 'error' events have special treatment in node, so page crashes become observable for users. Fixes #262.
2017-08-15 18:13:05 +00:00
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
[Frame]: #class-frame "Frame"
feat(Console): Introduce ConsoleMessage type (#909) This patch introduces ConsoleMessage type and starts dispatching it for the 'console' event. BREAKING CHANGE: this breaks the api of the 'console' event. Fixes #744.
2017-09-29 18:27:22 +00:00
[ConsoleMessage]: #class-consolemessage "ConsoleMessage"
feat(Browser): introduce browser.process() variable (#1581) This patch adds a `browser.process()` getter to expose the child process with running browser. Fixes #1539.
2017-12-11 20:11:12 +00:00
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
feat: Implement JavaScript Coverage (#1673) This patch introduces a new `page.coverage` namespace with two methods: - `page.coverage.startJSCoverage` to initiate JavaScript coverage recording - `page.coverage.stopJSCoverage` to stop JavaScript coverage and get results
2018-01-03 03:53:53 +00:00
[Coverage]: #class-coverage "Coverage"
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
[iterator]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols "Iterator"
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
[Response]: #class-response "Response"
[Request]: #class-request "Request"
[Browser]: #class-browser "Browser"
[Body]: #class-body "Body"
Introduce Page.$ and Page.$$ (#75) This patch introduces Page.$ and Page.$$ methods which are aliases for `document.querySelector` and `document.querySelectorAll`. Fixes #78.
2017-07-18 01:56:56 +00:00
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
[Keyboard]: #class-keyboard "Keyboard"
[Dialog]: #class-dialog "Dialog"
chore(doc): fix implicit link to JSHandle
2017-10-07 07:34:54 +00:00
[JSHandle]: #class-jshandle "JSHandle"
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
[ExecutionContext]: #class-executioncontext "ExecutionContext"
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
[Mouse]: #class-mouse "Mouse"
Drop Headers class in favor of a Map object This patch removes Header class and substitutes it with a simple Map object. The map is chosen over the vanilla object since it has explicit order of headers which we'd like to preserve. References #106.
2017-07-27 16:35:44 +00:00
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
Remove redundant methods from Body class This patch: - removes Body.arrayBuffer. This method is redundant since there's already a Body.buffer() method - removes Body.bodyUsed getter. References #106
2017-07-27 21:42:31 +00:00
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
[Tracing]: #class-tracing "Tracing"
docs: fix link to ElementHandle (#345)
2017-08-17 16:26:10 +00:00
[ElementHandle]: #class-elementhandle "ElementHandle"
Rename 'remoteDebuggingURL' into 'browserWSEndpoint' (#272)
2017-08-16 08:10:55 +00:00
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
Make prettier JS snippets (#377) * Make prettier JS snippets * Conform to CS (about curly brace) * Apply feedback
2017-08-18 23:46:10 +00:00
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
[api] add touchScreen.tap (#639) This patch: - adds `page.touchscreen` namespace, similar to `page.mouse` and `page.keyboard`. - adds tapping to multiple layers: - `page.touchscreen.tap` - `page.tap` - convenience method which accepts selector - `elementHandle.tap` Fixes #568 and #569.
2017-09-02 02:03:51 +00:00
[Touchscreen]: #class-touchscreen "Touchscreen"
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
[Target]: #class-target "Target"
feat(Page.goto): add a 'domcontentloaded' option to the Page.goto (#1145) This patch adds a new `domcontentloaded` option to a bunch of navigation methods: - Page.goto - Page.waitForNavigation - Page.goBack - Page.goForward - Page.reload Fixes #946.
2017-10-24 07:35:18 +00:00
[USKeyboardLayout]: ../lib/USKeyboardLayout.js "USKeyboardLayout"
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
fix(Network): fulfill security details for response redirects (#2025) This patch: - starts fulfilling security details for redirect responses - changes `response.securityDetails()` to return null if the response is served over non-secure connection
2018-02-15 00:08:20 +00:00
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
docs(api.md): fix nits in securityDetails description (#2023)
2018-02-15 00:37:40 +00:00
[SecurityDetails]: #class-securitydetails "SecurityDetails"
Reference in New Issue Copy Permalink