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
8d2a427eee
puppeteer/docs/api.md

1422 lines
65 KiB
Markdown
Raw Normal View History

Bump version to 0.11.0-alpha
2017-09-08 20:37:47 +00:00
##### Released API: [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)
[doc] Add reference to released API
2017-08-23 20:44:44 +00:00
Bump version to 0.11.0-alpha
2017-09-08 20:37:47 +00:00
# Puppeteer API v<!-- GEN:version -->0.11.0-alpha<!-- GEN:stop-->
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 -->
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
- [Puppeteer](#puppeteer)
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](#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
* [class: Puppeteer](#class-puppeteer)
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)](#puppeteerconnectoptions)
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])](#puppeteerlaunchoptions)
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
* [class: Browser](#class-browser)
+ [browser.close()](#browserclose)
+ [browser.newPage()](#browsernewpage)
+ [browser.version()](#browserversion)
Rename 'remoteDebuggingURL' into 'browserWSEndpoint' (#272)
2017-08-16 08:10:55 +00:00
+ [browser.wsEndpoint()](#browserwsendpoint)
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
* [class: Page](#class-page)
+ [event: 'console'](#event-console)
+ [event: 'dialog'](#event-dialog)
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'](#event-error)
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
+ [event: 'frameattached'](#event-frameattached)
+ [event: 'framedetached'](#event-framedetached)
+ [event: 'framenavigated'](#event-framenavigated)
+ [event: 'load'](#event-load)
+ [event: 'pageerror'](#event-pageerror)
+ [event: 'request'](#event-request)
+ [event: 'requestfailed'](#event-requestfailed)
+ [event: 'requestfinished'](#event-requestfinished)
+ [event: 'response'](#event-response)
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)](#pageselector)
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)](#pageselector)
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])](#pageevalselector-pagefunction-args)
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
+ [page.addScriptTag(url)](#pageaddscripttagurl)
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])](#pageclickselector-options)
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
+ [page.close()](#pageclose)
Add Page.content() method. Fixes #406. (#419)
2017-08-21 16:02:30 +00:00
+ [page.content()](#pagecontent)
Cookies (#314) Introduce cookies API. Fixes #53.
2017-08-24 19:21:46 +00:00
+ [page.cookies(...urls)](#pagecookiesurls)
+ [page.deleteCookie(...cookies)](#pagedeletecookiecookies)
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)](#pageemulateoptions)
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)](#pageemulatemediamediatype)
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
+ [page.evaluate(pageFunction, ...args)](#pageevaluatepagefunction-args)
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)](#pageevaluateonnewdocumentpagefunction-args)
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
+ [page.exposeFunction(name, puppeteerFunction)](#pageexposefunctionname-puppeteerfunction)
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
+ [page.focus(selector)](#pagefocusselector)
+ [page.frames()](#pageframes)
+ [page.goBack(options)](#pagegobackoptions)
+ [page.goForward(options)](#pagegoforwardoptions)
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
+ [page.goto(url, options)](#pagegotourl-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
+ [page.hover(selector)](#pagehoverselector)
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
+ [page.injectFile(filePath)](#pageinjectfilefilepath)
+ [page.keyboard](#pagekeyboard)
+ [page.mainFrame()](#pagemainframe)
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](#pagemouse)
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
+ [page.pdf(options)](#pagepdfoptions)
+ [page.plainText()](#pageplaintext)
+ [page.press(key[, options])](#pagepresskey-options)
+ [page.reload(options)](#pagereloadoptions)
+ [page.screenshot([options])](#pagescreenshotoptions)
+ [page.setContent(html)](#pagesetcontenthtml)
Cookies (#314) Introduce cookies API. Fixes #53.
2017-08-24 19:21:46 +00:00
+ [page.setCookie(...cookies)](#pagesetcookiecookies)
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)](#pagesetextrahttpheadersheaders)
Implement page.setJavaScriptEnabled method Fixes #462.
2017-08-23 21:08:56 +00:00
+ [page.setJavaScriptEnabled(enabled)](#pagesetjavascriptenabledenabled)
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
+ [page.setRequestInterceptionEnabled(value)](#pagesetrequestinterceptionenabledvalue)
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
+ [page.setUserAgent(userAgent)](#pagesetuseragentuseragent)
+ [page.setViewport(viewport)](#pagesetviewportviewport)
[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)](#pagetapselector)
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
+ [page.title()](#pagetitle)
[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](#pagetouchscreen)
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](#pagetracing)
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
+ [page.type(text, options)](#pagetypetext-options)
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
+ [page.url()](#pageurl)
+ [page.viewport()](#pageviewport)
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
+ [page.waitFor(selectorOrFunctionOrTimeout[, options])](#pagewaitforselectororfunctionortimeout-options)
[doc] Clarify that `path` is resolved against current working directory Fixes #150.
2017-07-28 06:34:32 +00:00
+ [page.waitForFunction(pageFunction[, options, ...args])](#pagewaitforfunctionpagefunction-options-args)
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
+ [page.waitForNavigation(options)](#pagewaitfornavigationoptions)
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])](#pagewaitforselectorselector-options)
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
* [class: Keyboard](#class-keyboard)
+ [keyboard.down(key[, options])](#keyboarddownkey-options)
+ [keyboard.sendCharacter(char)](#keyboardsendcharacterchar)
+ [keyboard.up(key)](#keyboardupkey)
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](#class-mouse)
Implement mouse.click(x,y) (#131) Closes #107
2017-07-25 23:05:23 +00:00
+ [mouse.click(x, y, [options])](#mouseclickx-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
+ [mouse.down([options])](#mousedownoptions)
[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])](#mousemovex-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
+ [mouse.up([options])](#mouseupoptions)
[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](#class-touchscreen)
+ [touchscreen.tap(x, y)](#touchscreentapx-y)
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](#class-tracing)
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)](#tracingstartoptions)
+ [tracing.stop()](#tracingstop)
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
* [class: Dialog](#class-dialog)
+ [dialog.accept([promptText])](#dialogacceptprompttext)
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()](#dialogdefaultvalue)
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
+ [dialog.dismiss()](#dialogdismiss)
+ [dialog.message()](#dialogmessage)
+ [dialog.type](#dialogtype)
* [class: Frame](#class-frame)
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)](#frameselector)
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)](#frameselector)
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])](#frameevalselector-pagefunction-args)
Move missing methods from page onto frame. (#125) Closes #113
2017-07-25 18:37:46 +00:00
+ [frame.addScriptTag(url)](#frameaddscripttagurl)
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
+ [frame.childFrames()](#framechildframes)
+ [frame.evaluate(pageFunction, ...args)](#frameevaluatepagefunction-args)
Move missing methods from page onto frame. (#125) Closes #113
2017-07-25 18:37:46 +00:00
+ [frame.injectFile(filePath)](#frameinjectfilefilepath)
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
+ [frame.isDetached()](#frameisdetached)
+ [frame.name()](#framename)
+ [frame.parentFrame()](#frameparentframe)
Move missing methods from page onto frame. (#125) Closes #113
2017-07-25 18:37:46 +00:00
+ [frame.title()](#frametitle)
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
+ [frame.url()](#frameurl)
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
+ [frame.waitFor(selectorOrFunctionOrTimeout[, options])](#framewaitforselectororfunctionortimeout-options)
[doc] Clarify that `path` is resolved against current working directory Fixes #150.
2017-07-28 06:34:32 +00:00
+ [frame.waitForFunction(pageFunction[, options, ...args])](#framewaitforfunctionpagefunction-options-args)
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])](#framewaitforselectorselector-options)
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](#class-elementhandle)
+ [elementHandle.click([options])](#elementhandleclickoptions)
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()](#elementhandledispose)
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.evaluate(pageFunction, ...args)](#elementhandleevaluatepagefunction-args)
+ [elementHandle.hover()](#elementhandlehover)
[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()](#elementhandletap)
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)](#elementhandleuploadfilefilepaths)
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
* [class: Request](#class-request)
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
+ [request.abort()](#requestabort)
+ [request.continue([overrides])](#requestcontinueoverrides)
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
+ [request.headers](#requestheaders)
+ [request.method](#requestmethod)
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
+ [request.postData](#requestpostdata)
Implement Request.resourceType getter (#590) This patch plumbs `resourceType` parameter of RequestWillBeSent and requestIntercepted methods.
2017-08-29 23:27:59 +00:00
+ [request.resourceType](#requestresourcetype)
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
+ [request.response()](#requestresponse)
+ [request.url](#requesturl)
* [class: Response](#class-response)
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()](#responsebuffer)
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
+ [response.headers](#responseheaders)
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()](#responsejson)
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
+ [response.ok](#responseok)
+ [response.request()](#responserequest)
+ [response.status](#responsestatus)
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()](#responsetext)
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
+ [response.url](#responseurl)
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
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
## Puppeteer
Puppeteer is a Node library which provides a high-level API to control Chromium over the DevTools Protocol.
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
Puppeteer looks for certain environment variables to aid its operations:
- `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` - defines HTTP proxy settings that are used to download and run Chromium.
- `PUPPETEER_SKIP_CHROMIUM_DOWNLOAD` - do not download bundled Chromium during installation step.
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.
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
The following is a typical example of using a 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...
browser.close();
});
```
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`.
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
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`.
Capitalize Chromium and Puppeteer (#263)
2017-08-15 07:14:12 +00:00
- `headless` <[boolean]> Whether to run Chromium in [headless mode](https://developers.google.com/web/updates/2017/04/headless-chrome). Defaults to `true`.
- `executablePath` <[string]> Path to a Chromium executable to run instead of 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.
Capitalize Chromium and Puppeteer (#263)
2017-08-15 07:14:12 +00:00
- `args` <[Array]<[string]>> Additional arguments to pass to the Chromium instance. List of Chromium flags can be found [here](http://peter.sh/experiments/chromium-command-line-switches/).
Launcher: add timeout to chrome launching (#434) This patch: - adds a 'timeout' launcher option that constrains the time for chromium to launch. - adds a 'handleSIGINT' launcher option that is `true` by default and that closes chrome instance Fixes #363.
2017-08-21 22:43:36 +00:00
- `handleSIGINT` <[boolean]> Close chrome process on Ctrl-C. Defaults to `true`.
- `timeout` <[number]> Maximum time in milliseconds to wait for the Chrome instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
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
- `dumpio` <[boolean]> Whether to pipe 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).
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
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** Puppeteer 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.
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
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');
[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.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
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
#### 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
[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
Closes browser with all the pages (if any were opened). The browser object itself is considered to be disposed and could not 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
[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.
Browser websocket endpoint which could be used as an argument to
doc: fix some links in api.md (#400)
2017-08-20 21:32:53 +00:00
[puppeteer.connect](#puppeteerconnectoptions).
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
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'});
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
});
```
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'
[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
- <[string]>
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
page.on('console', (...args) => {
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
for (let i = 0; i < args.length; ++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
console.log(`${i}: ${args[i]}`);
});
page.evaluate(() => console.log(5, 'hello', {foo: 'bar'}));
```
[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
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
#### event: 'pageerror'
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- <[string]> 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.
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
In order to intercept and mutate requests, see `page.setRequestInterceptionEnabled`.
[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
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +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).
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
- `...args` <...[Serializable]> Arguments to pass to `pageFunction`
- 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.
If `pageFunction` returns a [Promise], then `page.$eval` would wait for the promise to resolve and return it's value.
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).
[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.addScriptTag(url)
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `url` <[string]> Url of the `<script>` tag
- returns: <[Promise]> which resolves when the script's onload fires.
[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
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
Adds a `<script>` tag into the page with the desired url. Alternatively, a local JavaScript file could be injected via [`page.injectFile`](#pageinjectfilefilepath) method.
[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().addScriptTag(url)](#frameaddscripttagurl).
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
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
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]>
- `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.
#### 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.
corrected minor typos (#322)
2017-08-17 04:57:23 +00:00
- `deviceScaleFactor` <[number]> Specify device scale factor (could 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)
To aid emulation, puppeteer provides a list of device descriptors which could 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...
browser.close();
});
```
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)
[docs] a mistake in allowed values of `page.evaluateMedia` (#580)
2017-08-28 17:37:38 +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.
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
- returns: <[Promise]>
[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
Add Serializable type into the docs (#318)
2017-08-18 03:24:11 +00:00
- `...args` <...[Serializable]> Arguments to pass to `pageFunction`
- returns: <[Promise]<[Serializable]>> 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
If the function, passed to the `page.evaluate`, returns a [Promise], then `page.evaluate` would wait for the promise to resolve and return it's value.
```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 result = await page.evaluate(() => {
return Promise.resolve(8 * 7);
});
console.log(result); // prints "56"
browser.close();
});
```
A string can also be passed in instead of a function.
```js
console.log(await page.evaluate('1 + 2')); // prints "3"
```
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
[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
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
doc: remove a link to a deleted example (#392) Refs: https://github.com/GoogleChrome/puppeteer/pull/221
2017-08-19 16:28:58 +00:00
The function is invoked after the document was created but before any of its scripts were run. This is useful to amend 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
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();
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
page.on('console', console.log);
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}`);
});
browser.close();
});
```
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();
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
page.on('console', console.log);
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);
});
browser.close();
});
```
[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
#### 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:
- `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `waitUntil` <[string]> When to consider a navigation finished, defaults to `load`. Could 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.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `networkidle` - consider navigation to be finished when the network activity stays "idle" for at least `networkIdleTimeout` ms.
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
- `networkIdleInflight` <[number]> Maximum amount of inflight requests which are considered "idle". Takes effect only with `waitUntil: 'networkidle'` parameter.
- `networkIdleTimeout` <[number]> A timeout to wait before completing navigation. Takes effect only with `waitUntil: 'networkidle'` parameter.
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
- 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.
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:
- `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds.
- `waitUntil` <[string]> When to consider navigation succeeded, defaults to `load`. Could be either:
- `load` - consider navigation to be finished when the `load` event is fired.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `networkidle` - consider navigation to be finished when the network activity stays "idle" for at least `networkIdleTimeout` ms.
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
- `networkIdleInflight` <[number]> Maximum amount of inflight requests which are considered "idle". Takes effect only with `waitUntil: 'networkidle'` parameter.
- `networkIdleTimeout` <[number]> A timeout to wait before completing navigation. Takes effect only with `waitUntil: 'networkidle'` parameter.
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
- 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.
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:
- `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds.
- `waitUntil` <[string]> When to consider navigation succeeded, defaults to `load`. Could be either:
- `load` - consider navigation to be finished when the `load` event is fired.
Docs: add default networkIdleTimeout value (#234)
2017-08-10 21:49:34 +00:00
- `networkidle` - consider navigation to be finished when the network activity stays "idle" for at least `networkIdleTimeout` ms.
[doc] Clarify networkIdleInflight default in docs. (#630)
2017-08-31 06:08:46 +00:00
- `networkIdleInflight` <[number]> Maximum amount of inflight requests which are considered "idle". Takes effect only with `waitUntil: 'networkidle'` parameter. Defaults to 2.
Docs: add default networkIdleTimeout value (#234)
2017-08-10 21:49:34 +00:00
- `networkIdleTimeout` <[number]> A timeout to wait before completing navigation. Takes effect only with `waitUntil: 'networkidle'` parameter. Defaults to 1000 ms.
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +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.
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`.
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
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
#### page.injectFile(filePath)
[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
- `filePath` <[string]> Path to the JavaScript file to be injected into frame. If `filePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
- returns: <[Promise]> Promise which resolves when file gets successfully evaluated in frame.
Shortcut for [page.mainFrame().injectFile(filePath)](#frameinjectfilefilepath).
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
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
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`.
- `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
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
#### page.plainText()
- returns: <[Promise]<[string]>> Returns page's inner text.
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
Inroduce page.press (#96) This patch: - introduces page.press() method - adds more input tests References #89
2017-07-19 21:43:07 +00:00
#### page.press(key[, options])
- `key` <[string]> Name of key to press, such as `ArrowLeft`. See [KeyboardEvent.key](https://www.w3.org/TR/uievents-key/)
- `options` <[Object]>
- `text` <[string]> If specified, generates an input event with this text.
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 `keydown` and `keyup` in milliseconds. Defaults to 0.
Inroduce page.press (#96) This patch: - introduces page.press() method - adds more input tests References #89
2017-07-19 21:43:07 +00:00
- returns: <[Promise]>
docs: fix broken links in API (#144) This patch fixes links in api.md.
2017-07-26 22:06:23 +00:00
Shortcut for [`keyboard.down`](#keyboarddownkey-options) and [`keyboard.up`](#keyboardupkey).
Inroduce page.press (#96) This patch: - introduces page.press() method - adds more input tests References #89
2017-07-19 21:43:07 +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.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:
- `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds.
- `waitUntil` <[string]> When to consider navigation succeeded, defaults to `load`. Could be either:
- `load` - consider navigation to be finished when the `load` event is fired.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `networkidle` - consider navigation to be finished when the network activity stays "idle" for at least `networkIdleTimeout` ms.
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
- `networkIdleInflight` <[number]> Maximum amount of inflight requests which are considered "idle". Takes effect only with `waitUntil: 'networkidle'` parameter.
- `networkIdleTimeout` <[number]> A timeout to wait before completing navigation. Takes effect only with `waitUntil: 'networkidle'` parameter.
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:
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 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.
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
- `type` <[string]> Specify screenshot type, could 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`.
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
- `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
Allow capturing transparent screenshots (#354) This patch adds `omitBackground` option to the `page.screenshot` method. Fixes #344
2017-08-18 04:11:39 +00:00
- `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
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
#### page.setContent(html)
- `html` <[string]> HTML markup to assign to the page.
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
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]>
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)
[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]> An object containing additional http headers to be sent with every request.
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
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
#### page.setRequestInterceptionEnabled(value)
- `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
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
Activating request interception enables `request.abort` and `request.continue`.
[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
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
An example of a naïve request interceptor which 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();
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
await page.setRequestInterceptionEnabled(true);
update code example: setRequestInterceptionEnabled (#294)
2017-08-16 18:19:13 +00:00
page.on('request', interceptedRequest => {
[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
if (interceptedRequest.url.endsWith('.png') || interceptedRequest.url.endsWith('.jpg'))
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');
[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.close();
});
```
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
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.
corrected minor typos (#322)
2017-08-17 04:57:23 +00:00
- `deviceScaleFactor` <[number]> Specify device scale factor (could 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.
[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]>
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
#### page.type(text, options)
[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.
To press a special key, use [`page.press`](#pagepresskey-options).
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
page.type('Hello'); // Types instantly
page.type('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
#### 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.
- `deviceScaleFactor` <[number]> Specify device scale factor (could be though of as dpr). Defaults to `1`.
- `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
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
#### page.waitFor(selectorOrFunctionOrTimeout[, options])
- `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
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
- returns: <[Promise]>
[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:
doc: fix some links in api.md (#400)
2017-08-20 21:32:53 +00:00
- if `selectorOrFunctionOrTimeout` is a `string`, than the first argument is treated as a [selector] to wait for and the method is a shortcut for [page.waitForSelector](#pagewaitforselectorselector-options)
- if `selectorOrFunctionOrTimeout` is a `function`, than the first argument is treated as a predicate to wait for and the method is a shortcut for [page.waitForFunction()](#pagewaitforfunctionpagefunction-options-args).
[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
- if `selectorOrFunctionOrTimeout` is a `number`, than the first argument is treated as a timeout in milliseconds and the method returns a promise which resolves after the timeout
- 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
[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().waitFor(selectorOrFunctionOrTimeout[, options])](#framewaitforselectororfunctionortimeout-options).
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
[doc] Clarify that `path` is resolved against current working directory Fixes #150.
2017-07-28 06:34:32 +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
- `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 could be one of the following values:
- `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.
- `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds).
Add Serializable type into the docs (#318)
2017-08-18 03:24:11 +00:00
- `...args` <...[Serializable]> Arguments to pass to `pageFunction`
doc: fix copy-paste artefacts (#394)
2017-08-19 17:04:02 +00:00
- returns: <[Promise]> Promise which resolves when the `pageFunction` returns a 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
The `waitForFunction` could be used to observe viewport size change:
```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');
page.setViewport({width: 50, height: 50});
await watchDog;
browser.close();
});
```
[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().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:
- `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds.
- `waitUntil` <[string]> When to consider navigation succeeded, defaults to `load`. Could be either:
- `load` - consider navigation to be finished when the `load` event is fired.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `networkidle` - consider navigation to be finished when the network activity stays "idle" for at least `networkIdleTimeout` ms.
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
- `networkIdleInflight` <[number]> Maximum amount of inflight requests which are considered "idle". Takes effect only with `waitUntil: 'networkidle'` parameter.
- `networkIdleTimeout` <[number]> A timeout to wait before completing navigation. Takes effect only with `waitUntil: 'networkidle'` parameter.
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])
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +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`.
- `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds).
[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: <[Promise]> 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] 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
browser.close();
});
```
[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
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
doc: fix some links in api.md (#400)
2017-08-20 21:32:53 +00:00
Keyboard provides an api for managing a virtual keyboard. The high level api is [`page.type`](#pagetypetext-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
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
page.type('Hello World!');
page.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
Rename keyboard.hold and release to up and down (#95) References #89
2017-07-19 21:27:01 +00:00
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++)
page.press('ArrowLeft');
Rename keyboard.hold and release to up and down (#95) References #89
2017-07-19 21:27:01 +00:00
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
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
page.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!'
```
Rename keyboard.hold and release to up and down (#95) References #89
2017-07-19 21:27:01 +00:00
#### keyboard.down(key[, options])
Intorduce Page.keyboard (#74) Introduce page.keyboard to provide low-level access to the keyboard.
2017-07-18 01:49:52 +00:00
- `key` <[string]> Name of key to press, such as `ArrowLeft`. See [KeyboardEvent.key](https://www.w3.org/TR/uievents-key/)
- `options` <[Object]>
- `text` <[string]> If specified, generates an input event with this text.
- returns: <[Promise]>
Dispatches a `keydown` event.
This will not send input events unless `text` is specified.
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).
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('嗨');
```
Rename keyboard.hold and release to up and down (#95) References #89
2017-07-19 21:27:01 +00:00
#### keyboard.up(key)
- `key` <[string]> Name of key to release, such as `ArrowLeft`. See [KeyboardEvent.key](https://www.w3.org/TR/uievents-key/)
- 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 some links in api.md (#400)
2017-08-20 21:32:53 +00:00
Shortcut for [`mouse.move`](#mousemovex-y), [`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.
- 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 examples for Dialog and Frame classes
2017-07-17 18:02:13 +00:00
browser.close();
});
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
[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
#### dialog.type
- <[string]>
Dialog's type, could be one of the `alert`, `beforeunload`, `confirm` and `prompt`.
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:
- ['frameattached'](#event-frameattached) - fired when the frame gets attached to the page. Frame could be attached to the page only once.
- ['framenavigated'](#event-framenavigated) - fired when the frame commits navigation to a different URL.
- ['framedetached'](#event-framedetached) - fired when the frame gets detached from the page. Frame could be detached from the page only once.
[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(), '');
browser.close();
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
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]<[ElementHandle]>> Promise which resolves to ElementHandle pointing to the frame element.
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
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
- `...args` <...[Serializable]> Arguments to pass to `pageFunction`
- 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.
If `pageFunction` returns a [Promise], then `frame.$eval` would wait for the promise to resolve and return it's value.
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);
```
Move missing methods from page onto frame. (#125) Closes #113
2017-07-25 18:37:46 +00:00
#### frame.addScriptTag(url)
- `url` <[string]> Url of a script to be added
- returns: <[Promise]> Promise which resolves as the script gets added and loads.
[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: minor fixes (#167)
2017-07-30 01:08:35 +00:00
Adds a `<script>` tag to the frame with the desired url. Alternatively, JavaScript could be injected to the frame via [`frame.injectFile`](#frameinjectfilefilepath) method.
Move missing methods from page onto frame. (#125) Closes #113
2017-07-25 18:37:46 +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]>>
[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
Add Serializable type into the docs (#318)
2017-08-18 03:24:11 +00:00
- `...args` <...[Serializable]> Arguments to pass to `pageFunction`
- returns: <[Promise]<[Serializable]>> Promise which resolves to function return 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
[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
If the function, passed to the `page.evaluate`, returns a [Promise], then `page.evaluate` would wait for the promise to resolve and return it's value.
```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();
const result = await page.mainFrame().evaluate(() => {
[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
return Promise.resolve(8 * 7);
});
console.log(result); // prints "56"
browser.close();
});
```
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
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
console.log(await page.mainFrame().evaluate('1 + 2')); // prints "3"
[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
Move missing methods from page onto frame. (#125) Closes #113
2017-07-25 18:37:46 +00:00
#### frame.injectFile(filePath)
Docs: minor fixes (#167)
2017-07-30 01:08:35 +00:00
- `filePath` <[string]> Path to the JavaScript file to be injected into frame. If `filePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
Move missing methods from page onto frame. (#125) Closes #113
2017-07-25 18:37:46 +00:00
- returns: <[Promise]> Promise which resolves when file gets successfully evaluated in frame.
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()
[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 parent frame, if any. Detached frames and main frames return `null`.
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.
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
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
#### frame.waitFor(selectorOrFunctionOrTimeout[, options])
- `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
- returns: <[Promise]>
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:
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
- if `selectorOrFunctionOrTimeout` is a `string`, than the first argument is treated as a [selector] to wait for and the method is a shortcut for [frame.waitForSelector](#framewaitforselectorselector-options)
- if `selectorOrFunctionOrTimeout` is a `function`, than 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`, than 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
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
[doc] Clarify that `path` is resolved against current working directory Fixes #150.
2017-07-28 06:34:32 +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
- `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 could be one of the following values:
- `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.
- `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds).
Add Serializable type into the docs (#318)
2017-08-18 03:24:11 +00:00
- `...args` <...[Serializable]> Arguments to pass to `pageFunction`
doc: fix copy-paste artefacts (#394)
2017-08-19 17:04:02 +00:00
- returns: <[Promise]> Promise which resolves when the `pageFunction` returns a 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
The `waitForFunction` could be used to observe viewport size change:
```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;
browser.close();
});
```
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])
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +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`.
- `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds).
Added frame.waitFor(selector) (#59) This patch adds `frame.waitFor(selector)` method. Fixes #42.
2017-07-07 22:39:02 +00:00
- returns: <[Promise]> Promise which resolves when element specified by selector string is added to DOM.
[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);
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
browser.close();
});
```
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
ElementHandle represents an in-page DOM element. ElementHandles could be created with the [page.$](#pageselector) method.
```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
#### 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.
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.
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.evaluate(pageFunction, ...args)
- `pageFunction` <[function]> 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`
- returns: <[Promise]<[Serializable]>> Promise which resolves to function return value
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
If the function, passed to the `elementHandle.evaluate`, returns a [Promise], then `elementHandle.evaluate` would wait for the promise to resolve and return it's value.
doc: change ambiguous phrase in api.md (#410)
2017-08-20 23:44:52 +00:00
The element will be passed as the first argument to `pageFunction`, followed by any `args`.
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.
[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.
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.
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
#### request.abort()
Aborts request. To use this, request interception should be enabled with `page.setRequestInterceptionEnabled`.
Exception is immediately thrown if the request interception is not enabled.
#### request.continue([overrides])
- `overrides` <[Object]> Optional request overwrites, which could be one of the following:
- `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
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
Continues request with optional request overrides. To use this, request interception should be enabled with `page.setRequestInterceptionEnabled`.
Exception is immediately thrown if the request interception is not enabled.
[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
#### request.headers
[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
- <[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
#### request.method
- <[string]>
Contains the 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
#### request.postData
- <[string]>
Contains the 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
Implement Request.resourceType getter (#590) This patch plumbs `resourceType` parameter of RequestWillBeSent and requestIntercepted methods.
2017-08-29 23:27:59 +00:00
#### request.resourceType
- <[string]>
Contains the request's resource type as it was perceived by the rendering engine.
ResourceType will be one of the following: `Document`, `Stylesheet`, `Image`, `Media`, `Font`, `Script`, `TextTrack`, `XHR`, `Fetch`, `EventSource`, `WebSocket`, `Manifest`, `Other`.
[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()
[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: <[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
[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
#### request.url
- <[string]>
Contains the 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.
[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
#### response.headers
[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
- <[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`.
[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
#### response.ok
- <[boolean]>
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.
[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
#### response.status
- <[number]>
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
[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
#### response.url
- <[string]>
Contains the URL of the response.
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"
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"
[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"
[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"
Reference in New Issue Copy Permalink