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
9a8bac7138
puppeteer/docs/api.md

5645 lines
256 KiB
Markdown
Raw Normal View History

chore: unfreeze version on docs (#8575) Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>
2022-06-24 16:49:31 +00:00
# Puppeteer API <!-- GEN:version -->Tip-Of-Tree<!-- GEN:stop-->
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore: mark version v1.20.0 (#4928)
2019-09-12 22:21:21 +00:00
<!-- GEN:empty-if-release --><!-- GEN:stop -->
chore: bump version to v1.15.0-post (#4347)
2019-04-26 07:44:58 +00:00
docs(api.md): add links to CDP guide and pptr.dev (#4159)
2019-03-13 20:17:10 +00:00
- Interactive Documentation: https://pptr.dev
docs(api.md): re-factor api.md heading (#3185) - drop the "all previous releases" part, only have last 5 releases per chromium versions - link to Chinese translation of the documentation
2018-09-04 15:54:02 +00:00
- API Translations: [中文|Chinese](https://zhaoqize.github.io/puppeteer-api-zh_CN/#/)
chore: update references to branch names (#6022)
2020-06-15 15:34:16 +00:00
- Troubleshooting: [troubleshooting.md](https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
<!-- prettier-ignore-start -->
chore: automate Chromium => Puppeteer version listing (#6558) Issue: #6482
2020-10-29 21:24:35 +00:00
<!-- GEN:versions-per-release -->
- Releases per Chromium version:
chore(main): release 15.1.0 (#8573) * chore(main): release 15.1.0 * chore: freeze version on docs Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>
2022-06-24 16:42:31 +00:00
* Chromium 104.0.5109.0 - [Puppeteer v15.1.0](https://github.com/puppeteer/puppeteer/blob/v15.1.0/docs/api.md)
chore(main): release 14.2.0 (#8457) * chore(main): release 14.2.0 * chore: freeze version on docs Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>
2022-06-01 20:11:58 +00:00
* Chromium 103.0.5059.0 - [Puppeteer v14.2.0](https://github.com/puppeteer/puppeteer/blob/v14.2.0/docs/api.md)
chore(release): mark v14.0.0 (#8326)
2022-05-09 13:13:07 +00:00
* Chromium 102.0.5002.0 - [Puppeteer v14.0.0](https://github.com/puppeteer/puppeteer/blob/v14.0.0/docs/api.md)
chore(release): mark v13.6.0 (#8249) Co-authored-by: Ergün Erdoğmuş <ergunsh@chromium.org>
2022-04-20 08:07:34 +00:00
* Chromium 101.0.4950.0 - [Puppeteer v13.6.0](https://github.com/puppeteer/puppeteer/blob/v13.6.0/docs/api.md)
chore(release): mark v13.5.0 (#8110)
2022-03-07 12:58:56 +00:00
* Chromium 100.0.4889.0 - [Puppeteer v13.5.0](https://github.com/puppeteer/puppeteer/blob/v13.5.0/docs/api.md)
chore(release): mark v13.2.0 (#7970)
2022-02-07 14:35:33 +00:00
* Chromium 99.0.4844.16 - [Puppeteer v13.2.0](https://github.com/puppeteer/puppeteer/blob/v13.2.0/docs/api.md)
chore(release): mark v13.1.0 (#7908)
2022-01-17 14:40:56 +00:00
* Chromium 98.0.4758.0 - [Puppeteer v13.1.0](https://github.com/puppeteer/puppeteer/blob/v13.1.0/docs/api.md)
chore(release): mark v12.0.0 (#7800)
2021-11-26 08:58:29 +00:00
* Chromium 97.0.4692.0 - [Puppeteer v12.0.0](https://github.com/puppeteer/puppeteer/blob/v12.0.0/docs/api.md)
chore(release): mark v10.2.0 (#7467)
2021-08-04 12:45:31 +00:00
* Chromium 93.0.4577.0 - [Puppeteer v10.2.0](https://github.com/puppeteer/puppeteer/blob/v10.2.0/docs/api.md)
chore(release): mark v10.0.0 (#7299)
2021-05-31 12:34:04 +00:00
* Chromium 92.0.4512.0 - [Puppeteer v10.0.0](https://github.com/puppeteer/puppeteer/blob/v10.0.0/docs/api.md)
chore(release): mark v9.0.0 (#7111)
2021-04-21 11:18:09 +00:00
* Chromium 91.0.4469.0 - [Puppeteer v9.0.0](https://github.com/puppeteer/puppeteer/blob/v9.0.0/docs/api.md)
chore: add latest chromium version (#6952)
2021-03-04 06:50:08 +00:00
* Chromium 90.0.4427.0 - [Puppeteer v8.0.0](https://github.com/puppeteer/puppeteer/blob/v8.0.0/docs/api.md)
chore(release): mark v7.0.0 (#6804)
2021-02-03 15:33:32 +00:00
* Chromium 90.0.4403.0 - [Puppeteer v7.0.0](https://github.com/puppeteer/puppeteer/blob/v7.0.0/docs/api.md)
chore: fix version number (#6803)
2021-02-02 12:32:13 +00:00
* Chromium 89.0.4389.0 - [Puppeteer v6.0.0](https://github.com/puppeteer/puppeteer/blob/v6.0.0/docs/api.md)
docs: correct link for v5.0.0 (#6778)
2021-01-25 06:33:45 +00:00
* Chromium 88.0.4298.0 - [Puppeteer v5.5.0](https://github.com/puppeteer/puppeteer/blob/v5.5.0/docs/api.md)
chore: mark version v5.4.0 (#6542)
2020-10-23 14:28:38 +00:00
* Chromium 87.0.4272.0 - [Puppeteer v5.4.0](https://github.com/puppeteer/puppeteer/blob/v5.4.0/docs/api.md)
chore: mark version v5.3.0 (#6412)
2020-09-11 08:43:09 +00:00
* Chromium 86.0.4240.0 - [Puppeteer v5.3.0](https://github.com/puppeteer/puppeteer/blob/v5.3.0/docs/api.md)
chore: mark v5.2.1 (#6254)
2020-07-21 12:53:02 +00:00
* Chromium 85.0.4182.0 - [Puppeteer v5.2.1](https://github.com/puppeteer/puppeteer/blob/v5.2.1/docs/api.md)
chore: mark version v5.1.0 (#6206) Co-authored-by: Changhao Han <changhaohan@chromium.org>
2020-07-13 08:25:14 +00:00
* Chromium 84.0.4147.0 - [Puppeteer v5.1.0](https://github.com/puppeteer/puppeteer/blob/v5.1.0/docs/api.md)
chore: mark version v3.1.0 (#5883) * chore: mark version v3.1.0 Co-authored-by: Alex Rudenko <alexrudenko@chromium.org>
2020-05-18 11:47:03 +00:00
* Chromium 83.0.4103.0 - [Puppeteer v3.1.0](https://github.com/puppeteer/puppeteer/blob/v3.1.0/docs/api.md)
chore: mark version v3.0.0 (#5642) Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2020-04-16 08:43:12 +00:00
* Chromium 81.0.4044.0 - [Puppeteer v3.0.0](https://github.com/puppeteer/puppeteer/blob/v3.0.0/docs/api.md)
chore: mark version v2.1.0 (#5347) This changes the Chromium revision to r722234 (Chrome 80.0.3987.0), since that's the most recent version in the Chromium 80 range for which a download exists for all supported platforms.
2020-01-27 14:27:00 +00:00
* Chromium 80.0.3987.0 - [Puppeteer v2.1.0](https://github.com/puppeteer/puppeteer/blob/v2.1.0/docs/api.md)
chore: update URLs (#5185)
2019-11-26 12:12:25 +00:00
* Chromium 79.0.3942.0 - [Puppeteer v2.0.0](https://github.com/puppeteer/puppeteer/blob/v2.0.0/docs/api.md)
* Chromium 78.0.3882.0 - [Puppeteer v1.20.0](https://github.com/puppeteer/puppeteer/blob/v1.20.0/docs/api.md)
* Chromium 77.0.3803.0 - [Puppeteer v1.19.0](https://github.com/puppeteer/puppeteer/blob/v1.19.0/docs/api.md)
* Chromium 76.0.3803.0 - [Puppeteer v1.17.0](https://github.com/puppeteer/puppeteer/blob/v1.17.0/docs/api.md)
* Chromium 75.0.3765.0 - [Puppeteer v1.15.0](https://github.com/puppeteer/puppeteer/blob/v1.15.0/docs/api.md)
* Chromium 74.0.3723.0 - [Puppeteer v1.13.0](https://github.com/puppeteer/puppeteer/blob/v1.13.0/docs/api.md)
* Chromium 73.0.3679.0 - [Puppeteer v1.12.2](https://github.com/puppeteer/puppeteer/blob/v1.12.2/docs/api.md)
* [All releases](https://github.com/puppeteer/puppeteer/releases)
chore: automate Chromium => Puppeteer version listing (#6558) Issue: #6482
2020-10-29 21:24:35 +00:00
<!-- 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
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
<!-- prettier-ignore-end -->
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
##### Table of Contents
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
<!-- prettier-ignore-start -->
docs(api.md): fix table-of-contents (#2636) This patch drops the markdown-toc module and instead rolls out our own simple markdown table-of-contents generator. As a side effect, it fixes links to `page.$` and `page.$$`.
2018-05-31 21:21:43 +00:00
<!-- GEN:toc -->
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
- [Overview](#overview)
docs(api.md): expand on puppeteer-core vs puppeteer (#3189)
2018-09-04 16:32:57 +00:00
- [puppeteer vs puppeteer-core](#puppeteer-vs-puppeteer-core)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
- [Environment Variables](#environment-variables)
docs(api.md): expand on testing Chrome Extensions (#2893) Fixes #2823
2018-07-19 02:33:51 +00:00
- [Working with Chrome Extensions](#working-with-chrome-extensions)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
- [class: Puppeteer](#class-puppeteer)
chore: mark version v5.4.0 (#6542)
2020-10-23 14:28:38 +00:00
* [puppeteer.clearCustomQueryHandlers()](#puppeteerclearcustomqueryhandlers)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [puppeteer.connect(options)](#puppeteerconnectoptions)
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
* [puppeteer.createBrowserFetcher([options])](#puppeteercreatebrowserfetcheroptions)
chore: mark version v5.4.0 (#6542)
2020-10-23 14:28:38 +00:00
* [puppeteer.customQueryHandlerNames()](#puppeteercustomqueryhandlernames)
feat(launcher): allow options to be passed into puppeteer.defaultArgs (#2950)
2018-08-07 20:22:04 +00:00
* [puppeteer.defaultArgs([options])](#puppeteerdefaultargsoptions)
feat(puppeteer): introduce `puppeteer.errors` and `puppeteer.devices` (#4312) These getters are introduced as a more convenient substitute for a `require('puppeteer/Errors')` and `require('puppeteer/DeviceDescriptors')`. This way we can make cross-browser story nicer - a single require of `puppeteer` or `puppeteer-firefox` fully defines Puppeteer environment.
2019-04-19 22:33:06 +00:00
* [puppeteer.devices](#puppeteerdevices)
* [puppeteer.errors](#puppeteererrors)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [puppeteer.executablePath()](#puppeteerexecutablepath)
* [puppeteer.launch([options])](#puppeteerlaunchoptions)
feat: add page.emulateNetworkConditions (#6759)
2021-01-21 09:00:57 +00:00
* [puppeteer.networkConditions](#puppeteernetworkconditions)
feat(launcher): add option to run Puppeteer with different browsers (#5137) * feat: Set which browser to launch via PUPPETEER_PRODUCT This change introduces a PUPPETEER_PRODUCT environment variable as a first step toward using Puppeteer with many different browsers. Setting PUPPETEER_PRODUCT=firefox, for example, enables Firefox-specific Launcher settings. The state is also exposed as `puppeteer.product` in the API to support adding other product-specific behaviour as needed. The bulk of the change is a refactoring in Launcher to decouple generic browser start-up from product-specific configuration. Respecting the puppeteer-core restriction for PUPPETEER_ environment variables, lazily instantiate the Launcher based on a `product` Puppeteer.launch option, if available. * test: Distinguish Juggler unit tests from Firefox The funit script is renamed to fjunit (j for Juggler, which is used only by the experimental puppeteer-firefox package. In contrast, the funit script now refers to running Puppeteer unit tests against the main puppeteer package with Firefox. To do so with Firefox Nightly, run: `BINARY=path/to/firefox npm run funit` A number of changes in this patch make it easier to run Puppeteer unit tests in Mozilla's CI.
2019-11-26 09:23:19 +00:00
* [puppeteer.product](#puppeteerproduct)
chore: mark version v5.4.0 (#6542)
2020-10-23 14:28:38 +00:00
* [puppeteer.registerCustomQueryHandler(name, queryHandler)](#puppeteerregistercustomqueryhandlername-queryhandler)
* [puppeteer.unregisterCustomQueryHandler(name)](#puppeteerunregistercustomqueryhandlername)
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
- [class: BrowserFetcher](#class-browserfetcher)
* [browserFetcher.canDownload(revision)](#browserfetchercandownloadrevision)
* [browserFetcher.download(revision[, progressCallback])](#browserfetcherdownloadrevision-progresscallback)
(feat) Add option to fetch Firefox Nightly (#5467) * (feat) Add option to fetch Firefox Nightly Add Firefox support to BrowserFetcher and the install script. By default, the latest Firefox Nightly is downloaded directly from archive.mozilla.org (dmg, tar.bz2 and zip) This also required changes that impact `puppeteer.launch()` and `puppeteer.executablePath()` Fixes #5151 * Update docs/api.md Co-Authored-By: Mathias Bynens <mathias@qiwi.be> * Clean up revision promise * Improve error handling in revision check * Remove matchAll * Use explicit octal mode * Update .gitignore Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2020-03-10 20:59:03 +00:00
* [browserFetcher.host()](#browserfetcherhost)
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
* [browserFetcher.localRevisions()](#browserfetcherlocalrevisions)
* [browserFetcher.platform()](#browserfetcherplatform)
(feat) Add option to fetch Firefox Nightly (#5467) * (feat) Add option to fetch Firefox Nightly Add Firefox support to BrowserFetcher and the install script. By default, the latest Firefox Nightly is downloaded directly from archive.mozilla.org (dmg, tar.bz2 and zip) This also required changes that impact `puppeteer.launch()` and `puppeteer.executablePath()` Fixes #5151 * Update docs/api.md Co-Authored-By: Mathias Bynens <mathias@qiwi.be> * Clean up revision promise * Improve error handling in revision check * Remove matchAll * Use explicit octal mode * Update .gitignore Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2020-03-10 20:59:03 +00:00
* [browserFetcher.product()](#browserfetcherproduct)
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
* [browserFetcher.remove(revision)](#browserfetcherremoverevision)
* [browserFetcher.revisionInfo(revision)](#browserfetcherrevisioninforevision)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
- [class: Browser](#class-browser)
feat(browser): add browser.disconnected event (#960) This patch adds a 'disconnected' event for the browser. The event is issued when the "browser" loses connection to the chrome process. References #952
2017-11-04 01:46:17 +00:00
* [event: 'disconnected'](#event-disconnected)
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
* [event: 'targetchanged'](#event-targetchanged)
* [event: 'targetcreated'](#event-targetcreated)
* [event: 'targetdestroyed'](#event-targetdestroyed)
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
* [browser.browserContexts()](#browserbrowsercontexts)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [browser.close()](#browserclose)
feat: add proxy and bypass list parameters to createIncognitoBrowserContext (#7516) Example: (async () => { const browser = await puppeteer.launch(); const context = await browser.createIncognitoBrowserContext('myproxy.com:3128'); const page = await context.newPage() await page.authenticate({username: 'foo', password: 'bar' }); await page.goto('https://google.com'); await browser.close(); })(); Issue: #678
2021-09-18 09:56:05 +00:00
* [browser.createIncognitoBrowserContext([options])](#browsercreateincognitobrowsercontextoptions)
feat(browsercontext): implement BrowserContext.overridePermissions (#3159) Introduce an API to manage permissions per browser context: - BrowserContext.overridePermissions(origin, permissions) - BrowserContext.clearPermissionOverrides() Fixes #846.
2018-08-30 22:36:09 +00:00
* [browser.defaultBrowserContext()](#browserdefaultbrowsercontext)
feat(Browser): make browser.close() to always terminate remote browser This patch: - changes `browser.close` to terminate browser. - introduces new `browser.disconnect` to disconnect from a browser without closing it This patch: fixes #918, fixes #989 BREAKING CHANGE: `browser.close()` will always close a browser, even if it was initialized with `puppeteer.connect`. To disconnect from a remote browser, use `browser.disconnect()` instead.
2017-10-17 22:35:00 +00:00
* [browser.disconnect()](#browserdisconnect)
feat(browser): Add browser.isConnected() (#4403) Add `browser.isConnected()` to the public api to be able to tell when the browser is connected fixes https://github.com/smooth-code/jest-puppeteer/pull/237#issuecomment-490260041
2019-05-09 23:24:52 +00:00
* [browser.isConnected()](#browserisconnected)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [browser.newPage()](#browsernewpage)
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
* [browser.pages()](#browserpages)
feat(Browser): introduce browser.process() variable (#1581) This patch adds a `browser.process()` getter to expose the child process with running browser. Fixes #1539.
2017-12-11 20:11:12 +00:00
* [browser.process()](#browserprocess)
feat(launcher): add experimental "transport" option to pptr.connect (#3265) This patch: - adds experimental "transport" option to pptr.connect - uses "transport" option to make sure Puppeteer-Web works with Target.exposeDevToolsProtocol Drive-by: add `browser.target()` to access browser target.
2018-09-20 18:55:23 +00:00
* [browser.target()](#browsertarget)
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
* [browser.targets()](#browsertargets)
feat: introduce browser.userAgent() (#1716) The patch introduces browser.userAgent() method to retrieve default browser user agent. Fixes #1706.
2018-01-05 18:14:30 +00:00
* [browser.userAgent()](#browseruseragent)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [browser.version()](#browserversion)
feat: browser.waitForTarget (#3356) This adds `browser.waitForTarget` and `browserContext.waitForTarget`. It also fixes a flaky test that was incorrectly expecting targets to appear instantly.
2018-10-09 21:16:53 +00:00
* [browser.waitForTarget(predicate[, options])](#browserwaitfortargetpredicate-options)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [browser.wsEndpoint()](#browserwsendpoint)
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
- [class: BrowserContext](#class-browsercontext)
* [event: 'targetchanged'](#event-targetchanged-1)
* [event: 'targetcreated'](#event-targetcreated-1)
* [event: 'targetdestroyed'](#event-targetdestroyed-1)
* [browserContext.browser()](#browsercontextbrowser)
feat(browsercontext): implement BrowserContext.overridePermissions (#3159) Introduce an API to manage permissions per browser context: - BrowserContext.overridePermissions(origin, permissions) - BrowserContext.clearPermissionOverrides() Fixes #846.
2018-08-30 22:36:09 +00:00
* [browserContext.clearPermissionOverrides()](#browsercontextclearpermissionoverrides)
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
* [browserContext.close()](#browsercontextclose)
* [browserContext.isIncognito()](#browsercontextisincognito)
* [browserContext.newPage()](#browsercontextnewpage)
feat(browsercontext): implement BrowserContext.overridePermissions (#3159) Introduce an API to manage permissions per browser context: - BrowserContext.overridePermissions(origin, permissions) - BrowserContext.clearPermissionOverrides() Fixes #846.
2018-08-30 22:36:09 +00:00
* [browserContext.overridePermissions(origin, permissions)](#browsercontextoverridepermissionsorigin-permissions)
feat(browsercontext): add BrowserContext.pages() method (#3003)
2018-07-31 20:24:29 +00:00
* [browserContext.pages()](#browsercontextpages)
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
* [browserContext.targets()](#browsercontexttargets)
feat: browser.waitForTarget (#3356) This adds `browser.waitForTarget` and `browserContext.waitForTarget`. It also fixes a flaky test that was incorrectly expecting targets to appear instantly.
2018-10-09 21:16:53 +00:00
* [browserContext.waitForTarget(predicate[, options])](#browsercontextwaitfortargetpredicate-options)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
- [class: Page](#class-page)
feat(Page): page 'close' event (#2232) This patch adds 'page.close' event. References #952.
2018-03-28 20:11:51 +00:00
* [event: 'close'](#event-close)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [event: 'console'](#event-console)
* [event: 'dialog'](#event-dialog)
feat: add Page.Events.DOMContentLoaded (#1730) Fixes #1580
2018-01-17 07:22:44 +00:00
* [event: 'domcontentloaded'](#event-domcontentloaded)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [event: 'error'](#event-error)
* [event: 'frameattached'](#event-frameattached)
* [event: 'framedetached'](#event-framedetached)
* [event: 'framenavigated'](#event-framenavigated)
* [event: 'load'](#event-load)
* [event: 'metrics'](#event-metrics)
* [event: 'pageerror'](#event-pageerror)
feat(page): introduce "Popup" event (#3661) This patch adds a new "popup" event for page. "Popup" event is fired whenever page opens another page with given opener.
2018-12-13 01:09:42 +00:00
* [event: 'popup'](#event-popup)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [event: 'request'](#event-request)
* [event: 'requestfailed'](#event-requestfailed)
* [event: 'requestfinished'](#event-requestfinished)
* [event: 'response'](#event-response)
feat(Page): introduce workers (#2560) This adds `page.workers()`, and two events `workercreated` and `workerdestroyed`. It also forwards logs from a worker into the page `console` event. Only dedicated workers are supported for now, ServiceWorkers will probably work differently because they aren't necessarily associated with a single page. Fixes #2350.
2018-05-21 21:31:11 +00:00
* [event: 'workercreated'](#event-workercreated)
* [event: 'workerdestroyed'](#event-workerdestroyed)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.$(selector)](#pageselector)
docs(api.md): fix table-of-contents (#2636) This patch drops the markdown-toc module and instead rolls out our own simple markdown table-of-contents generator. As a side effect, it fixes links to `page.$` and `page.$$`.
2018-05-31 21:21:43 +00:00
* [page.$$(selector)](#pageselector-1)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.$$eval(selector, pageFunction[, ...args])](#pageevalselector-pagefunction-args)
docs(api.md): fix table-of-contents (#2636) This patch drops the markdown-toc module and instead rolls out our own simple markdown table-of-contents generator. As a side effect, it fixes links to `page.$` and `page.$$`.
2018-05-31 21:21:43 +00:00
* [page.$eval(selector, pageFunction[, ...args])](#pageevalselector-pagefunction-args-1)
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
* [page.$x(expression)](#pagexexpression)
feat(accessibility): snapshot the accessibility tree (#3470) This adds `page.accessibility.snapshot()`. It serializes and returns the accessibility tree for the page. By default, uninteresting nodes are filtered out of the snapshot. fixes #2033
2018-11-02 01:54:51 +00:00
* [page.accessibility](#pageaccessibility)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.addScriptTag(options)](#pageaddscripttagoptions)
* [page.addStyleTag(options)](#pageaddstyletagoptions)
* [page.authenticate(credentials)](#pageauthenticatecredentials)
feat(Page): introduce Page bringToFront method (#1252) This patch introduces Page.bringToFront method to activate tabs. Fixes #1244
2017-11-07 21:17:36 +00:00
* [page.bringToFront()](#pagebringtofront)
Add `Page.browser()` method (#2387) Call page.browser() to get the browser instance associated with a page. Fixes #2275
2018-04-17 17:37:17 +00:00
* [page.browser()](#pagebrowser)
feat: introduce page.browserContext() (#3655)
2018-12-12 23:08:31 +00:00
* [page.browserContext()](#pagebrowsercontext)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.click(selector[, options])](#pageclickselector-options)
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
* [page.close([options])](#pagecloseoptions)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.content()](#pagecontent)
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
* [page.cookies([...urls])](#pagecookiesurls)
feat: Implement JavaScript Coverage (#1673) This patch introduces a new `page.coverage` namespace with two methods: - `page.coverage.startJSCoverage` to initiate JavaScript coverage recording - `page.coverage.stopJSCoverage` to stop JavaScript coverage and get results
2018-01-03 03:53:53 +00:00
* [page.coverage](#pagecoverage)
feat: add a streaming version for page.pdf Co-authored-by: Jan Scheffler <janscheffler@chromium.org>
2021-06-23 12:51:38 +00:00
* [page.createPDFStream([options])](#pagecreatepdfstreamoptions)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.deleteCookie(...cookies)](#pagedeletecookiecookies)
* [page.emulate(options)](#pageemulateoptions)
feat: add page.emulateCPUThrottling (#7343)
2021-06-22 11:43:11 +00:00
* [page.emulateCPUThrottling(factor)](#pageemulatecputhrottlingfactor)
feat(page): emulate idle state (#6410) * https://bugs.chromium.org/p/chromium/issues/detail?id=1090802 * added `page.emulateIdleState(...)` allowing emulate or remove emulation of the idle state; * added test `emulate idle` -> `remove emulation` -> `emulate idle` -> `remove emulation`; * added launch argument `--enable-blink-features=IdleDetection` to turn IdleDetection on.
2020-09-14 09:31:23 +00:00
* [page.emulateIdleState(overrides)](#pageemulateidlestateoverrides)
feat(api): add page.emulateMedia{Type,Features} (#5012)
2019-10-23 11:55:00 +00:00
* [page.emulateMediaFeatures(features)](#pageemulatemediafeaturesfeatures)
* [page.emulateMediaType(type)](#pageemulatemediatypetype)
feat: add page.emulateNetworkConditions (#6759)
2021-01-21 09:00:57 +00:00
* [page.emulateNetworkConditions(networkConditions)](#pageemulatenetworkconditionsnetworkconditions)
feat(api): add page.emulateTimezone(timezoneId) (#4949) This enables dynamically changing the timezone of the page.
2019-10-23 13:49:39 +00:00
* [page.emulateTimezone(timezoneId)](#pageemulatetimezonetimezoneid)
feat(api): add page.emulateVisionDeficiency(type) (#5901) Design doc: https://goo.gle/devtools-cvd
2020-05-26 15:14:20 +00:00
* [page.emulateVisionDeficiency(type)](#pageemulatevisiondeficiencytype)
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
* [page.evaluate(pageFunction[, ...args])](#pageevaluatepagefunction-args)
* [page.evaluateHandle(pageFunction[, ...args])](#pageevaluatehandlepagefunction-args)
* [page.evaluateOnNewDocument(pageFunction[, ...args])](#pageevaluateonnewdocumentpagefunction-args)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.exposeFunction(name, puppeteerFunction)](#pageexposefunctionname-puppeteerfunction)
* [page.focus(selector)](#pagefocusselector)
* [page.frames()](#pageframes)
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
* [page.goBack([options])](#pagegobackoptions)
* [page.goForward([options])](#pagegoforwardoptions)
* [page.goto(url[, options])](#pagegotourl-options)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.hover(selector)](#pagehoverselector)
feat(page): add page.isClosed method (#2588) Fixes #2501.
2018-05-25 23:53:57 +00:00
* [page.isClosed()](#pageisclosed)
feat(api): make `page.isDragInterceptionEnabled` a method (#7419) Having it be a getter is surprising and inconsistent, since the other `page.is*` APIs are just methods. Issue: #7150
2021-07-13 09:37:39 +00:00
* [page.isDragInterceptionEnabled()](#pageisdraginterceptionenabled)
feat(api): add Page.isJavaScriptEnabled + mark properties as private (#5993) Just one was used externally and I wrapped that up in a method. I think it's a useful method to provide (I can imagine wanting to know if JS is enabled on a page) so I think there's no harm here (I'd rather that then have JSHandle reach into a private variable).
2020-06-10 15:15:02 +00:00
* [page.isJavaScriptEnabled()](#pageisjavascriptenabled)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.keyboard](#pagekeyboard)
* [page.mainFrame()](#pagemainframe)
feat(Page): rename Page.getMetrics into Page.metrics (#1240) BREAKING CHANGE: method page.getMetrics() got renamed into page.metrics().
2017-11-01 20:39:31 +00:00
* [page.metrics()](#pagemetrics)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.mouse](#pagemouse)
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
* [page.pdf([options])](#pagepdfoptions)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.queryObjects(prototypeHandle)](#pagequeryobjectsprototypehandle)
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
* [page.reload([options])](#pagereloadoptions)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.screenshot([options])](#pagescreenshotoptions)
* [page.select(selector, ...values)](#pageselectselector-values)
feat(Page): introduce Page.setBypassCSP (#2324) This patch introduces `page.setBypassCSP` method that allows clients to ignore Content-Security-Policy for a given page. Fixes #1229.
2018-04-06 23:35:50 +00:00
* [page.setBypassCSP(enabled)](#pagesetbypasscspenabled)
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
* [page.setCacheEnabled([enabled])](#pagesetcacheenabledenabled)
feat(page): support waitUntil option for `page.setContent` (#3557) This patch teaches `page.setContent` to await resources in the new document. **NOTE**: This patch changes behavior: currently, `page.setContent` awaits the `"domcontentloaded"` event; with this patch, we can now await other lifecycle events, and switched default to the `"load"` event. The change is justified since current behavior made `page.setContent` unusable for its main designated usecases, pushing our client to use [dataURL workaround](https://github.com/GoogleChrome/puppeteer/issues/728#issuecomment-334301491). Fixes #728
2018-11-20 23:32:46 +00:00
* [page.setContent(html[, options])](#pagesetcontenthtml-options)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.setCookie(...cookies)](#pagesetcookiecookies)
feat(Page): Add global navigation timeout setting (#1728) This patch introduces `page.setDefaultNavigationTimeout` method to override the default 30 seconds navigation timeout. Fixes #1514
2018-01-10 21:04:01 +00:00
* [page.setDefaultNavigationTimeout(timeout)](#pagesetdefaultnavigationtimeouttimeout)
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
* [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout)
feat: add drag-and-drop support (#7150) This commit adds drag-and-drop support, leveraging new additions to the CDP Input domain (Input.setInterceptDrags, Input.dispatchDragEvent, and Input.dragIntercepted).
2021-06-04 10:25:36 +00:00
* [page.setDragInterception(enabled)](#pagesetdraginterceptionenabled)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.setExtraHTTPHeaders(headers)](#pagesetextrahttpheadersheaders)
feat(page): Introduce page.setGeolocation method (#3160) Fixes #1077
2018-08-31 17:04:12 +00:00
* [page.setGeolocation(options)](#pagesetgeolocationoptions)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.setJavaScriptEnabled(enabled)](#pagesetjavascriptenabledenabled)
* [page.setOfflineMode(enabled)](#pagesetofflinemodeenabled)
feat(requestinterception): remove cacheSafe flag (#7217)
2021-05-20 12:09:56 +00:00
* [page.setRequestInterception(value)](#pagesetrequestinterceptionvalue)
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
- [Multiple Intercept Handlers and Asynchronous Resolutions](#multiple-intercept-handlers-and-asynchronous-resolutions)
- [Cooperative Intercept Mode](#cooperative-intercept-mode)
- [Cooperative Request Continuation](#cooperative-request-continuation)
- [Upgrading to Cooperative Intercept Mode for package maintainers](#upgrading-to-cooperative-intercept-mode-for-package-maintainers)
feat: add support for useragentdata (#7378) Adds userAgentData to setUserAgent that supports specifying user agent data for the new navigator.userAgentData and Client Hints headers.
2021-06-29 16:29:55 +00:00
* [page.setUserAgent(userAgent[, userAgentMetadata])](#pagesetuseragentuseragent-useragentmetadata)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.setViewport(viewport)](#pagesetviewportviewport)
* [page.tap(selector)](#pagetapselector)
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
* [page.target()](#pagetarget)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.title()](#pagetitle)
* [page.touchscreen](#pagetouchscreen)
* [page.tracing](#pagetracing)
* [page.type(selector, text[, options])](#pagetypeselector-text-options)
* [page.url()](#pageurl)
* [page.viewport()](#pageviewport)
* [page.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#pagewaitforselectororfunctionortimeout-options-args)
feat(page): introduce file chooser interception (#4653) This patch introduces a page.waitForFileChooser() method that adds a watchdog to wait for file chooser dialogs. This lets Puppeteer users to capture file chooser requests and fulfill/cancel them if necessary. Fixes #2946
2019-07-23 04:30:49 +00:00
* [page.waitForFileChooser([options])](#pagewaitforfilechooseroptions)
feat(oop iframes)!: integrate OOP iframes with the frame manager (#7556) This pull request to adds better support for OOP iframes (see #2548) The current problem with OOP iframes is that they are moved to a different target. Because of this, the previous versions of Puppeteer pretty much ignored them. This change extends the FrameManager to already take OOP iframes into account and hides the fact that those frames are actually in different targets. Further work needs to be done to also make the NetworkManager aware of these and to make sure that settings like emulations etc. are also properly passed down to the new targets.
2021-10-28 09:25:49 +00:00
* [page.waitForFrame(urlOrPredicate[, options])](#pagewaitforframeurlorpredicate-options)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.waitForFunction(pageFunction[, options[, ...args]])](#pagewaitforfunctionpagefunction-options-args)
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
* [page.waitForNavigation([options])](#pagewaitfornavigationoptions)
feat(api): implement `Page.waitForNetworkIdle()` (#5140) which will wait for there to be no network requests in progress during the `idleTime` before resolving.
2021-09-11 20:28:12 +00:00
* [page.waitForNetworkIdle([options])](#pagewaitfornetworkidleoptions)
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
* [page.waitForRequest(urlOrPredicate[, options])](#pagewaitforrequesturlorpredicate-options)
* [page.waitForResponse(urlOrPredicate[, options])](#pagewaitforresponseurlorpredicate-options)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [page.waitForSelector(selector[, options])](#pagewaitforselectorselector-options)
feat: page.waitForTimeout (#6268)
2020-07-28 08:37:49 +00:00
* [page.waitForTimeout(milliseconds)](#pagewaitfortimeoutmilliseconds)
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
* [page.waitForXPath(xpath[, options])](#pagewaitforxpathxpath-options)
feat(Page): introduce workers (#2560) This adds `page.workers()`, and two events `workercreated` and `workerdestroyed`. It also forwards logs from a worker into the page `console` event. Only dedicated workers are supported for now, ServiceWorkers will probably work differently because they aren't necessarily associated with a single page. Fixes #2350.
2018-05-21 21:31:11 +00:00
* [page.workers()](#pageworkers)
docs(new): migrate Page.ts to TSDoc (part 0 / 2) (#6104) * docs(new): migrate Page.ts to TSDoc (part 0 / 2) Co-authored-by: Changhao Han <changhaohan@chromium.org>
2020-06-26 07:24:56 +00:00
* [GeolocationOptions](#geolocationoptions)
* [WaitTimeoutOptions](#waittimeoutoptions)
chore: rename Worker to WebWorker (#5941) To avoid TS name conflicts.
2020-05-29 11:57:54 +00:00
- [class: WebWorker](#class-webworker)
* [webWorker.evaluate(pageFunction[, ...args])](#webworkerevaluatepagefunction-args)
* [webWorker.evaluateHandle(pageFunction[, ...args])](#webworkerevaluatehandlepagefunction-args)
* [webWorker.executionContext()](#webworkerexecutioncontext)
* [webWorker.url()](#webworkerurl)
feat(accessibility): snapshot the accessibility tree (#3470) This adds `page.accessibility.snapshot()`. It serializes and returns the accessibility tree for the page. By default, uninteresting nodes are filtered out of the snapshot. fixes #2033
2018-11-02 01:54:51 +00:00
- [class: Accessibility](#class-accessibility)
* [accessibility.snapshot([options])](#accessibilitysnapshotoptions)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
- [class: Keyboard](#class-keyboard)
* [keyboard.down(key[, options])](#keyboarddownkey-options)
* [keyboard.press(key[, options])](#keyboardpresskey-options)
* [keyboard.sendCharacter(char)](#keyboardsendcharacterchar)
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
* [keyboard.type(text[, options])](#keyboardtypetext-options)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [keyboard.up(key)](#keyboardupkey)
- [class: Mouse](#class-mouse)
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
* [mouse.click(x, y[, options])](#mouseclickx-y-options)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [mouse.down([options])](#mousedownoptions)
feat: add drag-and-drop support (#7150) This commit adds drag-and-drop support, leveraging new additions to the CDP Input domain (Input.setInterceptDrags, Input.dispatchDragEvent, and Input.dragIntercepted).
2021-06-04 10:25:36 +00:00
* [mouse.drag(start, target)](#mousedragstart-target)
* [mouse.dragAndDrop(start, target[, options])](#mousedraganddropstart-target-options)
* [mouse.dragEnter(target, data)](#mousedragentertarget-data)
* [mouse.dragOver(target, data)](#mousedragovertarget-data)
* [mouse.drop(target, data)](#mousedroptarget-data)
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
* [mouse.move(x, y[, options])](#mousemovex-y-options)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [mouse.up([options])](#mouseupoptions)
feat: add Mouse#wheel (#6141)
2020-07-06 07:27:17 +00:00
* [mouse.wheel([options])](#mousewheeloptions)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
- [class: Touchscreen](#class-touchscreen)
* [touchscreen.tap(x, y)](#touchscreentapx-y)
- [class: Tracing](#class-tracing)
fix(tracing): start without options (#4388)
2019-05-10 00:15:33 +00:00
* [tracing.start([options])](#tracingstartoptions)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [tracing.stop()](#tracingstop)
feat(page): introduce file chooser interception (#4653) This patch introduces a page.waitForFileChooser() method that adds a watchdog to wait for file chooser dialogs. This lets Puppeteer users to capture file chooser requests and fulfill/cancel them if necessary. Fixes #2946
2019-07-23 04:30:49 +00:00
- [class: FileChooser](#class-filechooser)
* [fileChooser.accept(filePaths)](#filechooseracceptfilepaths)
* [fileChooser.cancel()](#filechoosercancel)
* [fileChooser.isMultiple()](#filechooserismultiple)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
- [class: Dialog](#class-dialog)
* [dialog.accept([promptText])](#dialogacceptprompttext)
* [dialog.defaultValue()](#dialogdefaultvalue)
* [dialog.dismiss()](#dialogdismiss)
* [dialog.message()](#dialogmessage)
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
* [dialog.type()](#dialogtype)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
- [class: ConsoleMessage](#class-consolemessage)
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
* [consoleMessage.args()](#consolemessageargs)
feat(page): introduce consoleMessage.location() (#3365) This patch adds a new consoleMessage.location() method that returns console message origins. Fixes #3029
2019-01-11 00:51:13 +00:00
* [consoleMessage.location()](#consolemessagelocation)
feat(console): expose stack trace for console messages (#6445)
2020-09-25 13:27:13 +00:00
* [consoleMessage.stackTrace()](#consolemessagestacktrace)
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
* [consoleMessage.text()](#consolemessagetext)
* [consoleMessage.type()](#consolemessagetype)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
- [class: Frame](#class-frame)
* [frame.$(selector)](#frameselector)
docs(api.md): fix table-of-contents (#2636) This patch drops the markdown-toc module and instead rolls out our own simple markdown table-of-contents generator. As a side effect, it fixes links to `page.$` and `page.$$`.
2018-05-31 21:21:43 +00:00
* [frame.$$(selector)](#frameselector-1)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [frame.$$eval(selector, pageFunction[, ...args])](#frameevalselector-pagefunction-args)
docs(api.md): fix table-of-contents (#2636) This patch drops the markdown-toc module and instead rolls out our own simple markdown table-of-contents generator. As a side effect, it fixes links to `page.$` and `page.$$`.
2018-05-31 21:21:43 +00:00
* [frame.$eval(selector, pageFunction[, ...args])](#frameevalselector-pagefunction-args-1)
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
* [frame.$x(expression)](#framexexpression)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [frame.addScriptTag(options)](#frameaddscripttagoptions)
* [frame.addStyleTag(options)](#frameaddstyletagoptions)
* [frame.childFrames()](#framechildframes)
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
* [frame.click(selector[, options])](#frameclickselector-options)
feat(Frame): implement frame.content and frame.setContent methods (#1447) This refactors the page.content and page.setContent methods to be defined on the Frame class. This allows access from the Page still but also on all frames. Fixes #754
2017-11-23 02:44:33 +00:00
* [frame.content()](#framecontent)
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
* [frame.evaluate(pageFunction[, ...args])](#frameevaluatepagefunction-args)
* [frame.evaluateHandle(pageFunction[, ...args])](#frameevaluatehandlepagefunction-args)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [frame.executionContext()](#frameexecutioncontext)
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
* [frame.focus(selector)](#framefocusselector)
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
* [frame.goto(url[, options])](#framegotourl-options)
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
* [frame.hover(selector)](#framehoverselector)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [frame.isDetached()](#frameisdetached)
feat(oop iframes)!: integrate OOP iframes with the frame manager (#7556) This pull request to adds better support for OOP iframes (see #2548) The current problem with OOP iframes is that they are moved to a different target. Because of this, the previous versions of Puppeteer pretty much ignored them. This change extends the FrameManager to already take OOP iframes into account and hides the fact that those frames are actually in different targets. Further work needs to be done to also make the NetworkManager aware of these and to make sure that settings like emulations etc. are also properly passed down to the new targets.
2021-10-28 09:25:49 +00:00
* [frame.isOOPFrame()](#frameisoopframe)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [frame.name()](#framename)
* [frame.parentFrame()](#frameparentframe)
feat(Frame): introduce Frame.select This patch adds `Frame.select` method that does the same functionality as former `Page.select`, but on a per-frame level. The `Page.select` method becomes a shortcut for the ÷main frame's select. Fixes #1139
2017-11-02 05:06:04 +00:00
* [frame.select(selector, ...values)](#frameselectselector-values)
feat(page): support waitUntil option for `page.setContent` (#3557) This patch teaches `page.setContent` to await resources in the new document. **NOTE**: This patch changes behavior: currently, `page.setContent` awaits the `"domcontentloaded"` event; with this patch, we can now await other lifecycle events, and switched default to the `"load"` event. The change is justified since current behavior made `page.setContent` unusable for its main designated usecases, pushing our client to use [dataURL workaround](https://github.com/GoogleChrome/puppeteer/issues/728#issuecomment-334301491). Fixes #728
2018-11-20 23:32:46 +00:00
* [frame.setContent(html[, options])](#framesetcontenthtml-options)
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
* [frame.tap(selector)](#frametapselector)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [frame.title()](#frametitle)
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
* [frame.type(selector, text[, options])](#frametypeselector-text-options)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [frame.url()](#frameurl)
* [frame.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#framewaitforselectororfunctionortimeout-options-args)
* [frame.waitForFunction(pageFunction[, options[, ...args]])](#framewaitforfunctionpagefunction-options-args)
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
* [frame.waitForNavigation([options])](#framewaitfornavigationoptions)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [frame.waitForSelector(selector[, options])](#framewaitforselectorselector-options)
feat: page.waitForTimeout (#6268)
2020-07-28 08:37:49 +00:00
* [frame.waitForTimeout(milliseconds)](#framewaitfortimeoutmilliseconds)
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
* [frame.waitForXPath(xpath[, options])](#framewaitforxpathxpath-options)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
- [class: ExecutionContext](#class-executioncontext)
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
* [executionContext.evaluate(pageFunction[, ...args])](#executioncontextevaluatepagefunction-args)
* [executionContext.evaluateHandle(pageFunction[, ...args])](#executioncontextevaluatehandlepagefunction-args)
feat(ExecutionContext): introduce ExecutionContext.frame() (#1972) This patch introduces ExecutionContext.frame() that returns Frame associated with this Execution Context. This allows to associate console messages with the originating frame, if any.
2018-02-13 22:02:44 +00:00
* [executionContext.frame()](#executioncontextframe)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [executionContext.queryObjects(prototypeHandle)](#executioncontextqueryobjectsprototypehandle)
- [class: JSHandle](#class-jshandle)
* [jsHandle.asElement()](#jshandleaselement)
* [jsHandle.dispose()](#jshandledispose)
feat(api): add element.select and element.evaluate for consistency (#4892)
2019-09-04 22:19:34 +00:00
* [jsHandle.evaluate(pageFunction[, ...args])](#jshandleevaluatepagefunction-args)
* [jsHandle.evaluateHandle(pageFunction[, ...args])](#jshandleevaluatehandlepagefunction-args)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [jsHandle.executionContext()](#jshandleexecutioncontext)
* [jsHandle.getProperties()](#jshandlegetproperties)
* [jsHandle.getProperty(propertyName)](#jshandlegetpropertypropertyname)
* [jsHandle.jsonValue()](#jshandlejsonvalue)
- [class: ElementHandle](#class-elementhandle)
feat(ElementHandle): add ElementHandle.$ and ElementHandle.$$ (#1151) This patch adds `ElementHandle.$` and `ElementHandle.$$` methods to query nested elements. Fixes #508
2017-10-27 09:08:58 +00:00
* [elementHandle.$(selector)](#elementhandleselector)
docs(api.md): fix table-of-contents (#2636) This patch drops the markdown-toc module and instead rolls out our own simple markdown table-of-contents generator. As a side effect, it fixes links to `page.$` and `page.$$`.
2018-05-31 21:21:43 +00:00
* [elementHandle.$$(selector)](#elementhandleselector-1)
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
* [elementHandle.$$eval(selector, pageFunction[, ...args])](#elementhandleevalselector-pagefunction-args)
* [elementHandle.$eval(selector, pageFunction[, ...args])](#elementhandleevalselector-pagefunction-args-1)
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
* [elementHandle.$x(expression)](#elementhandlexexpression)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [elementHandle.asElement()](#elementhandleaselement)
* [elementHandle.boundingBox()](#elementhandleboundingbox)
feat(ElementHandle): add ElementHandle.boxModel method (#2256) This patch introduces ElementHandle.boxModel to get element's box model. Fixes #1357
2018-03-29 20:52:28 +00:00
* [elementHandle.boxModel()](#elementhandleboxmodel)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [elementHandle.click([options])](#elementhandleclickoptions)
feat: add ability to specify offsets for JSHandle.click (#7573) Until now, the click would be always sent to the middle point of the target element. With this change, one can define offsets relative to the border box of the elements and click different areas of an element.
2021-09-20 09:01:32 +00:00
* [elementHandle.clickablePoint([offset])](#elementhandleclickablepointoffset)
feat(ElementHandle): implement ElementHandle.contentFrame() (#2094) This patch adds ElementHandle.contentFrame() method that allows to get a reference to the Frame owned by the iframe. Fixes #433.
2018-02-24 05:22:53 +00:00
* [elementHandle.contentFrame()](#elementhandlecontentframe)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [elementHandle.dispose()](#elementhandledispose)
feat: add drag-and-drop support (#7150) This commit adds drag-and-drop support, leveraging new additions to the CDP Input domain (Input.setInterceptDrags, Input.dispatchDragEvent, and Input.dragIntercepted).
2021-06-04 10:25:36 +00:00
* [elementHandle.drag(target)](#elementhandledragtarget)
* [elementHandle.dragAndDrop(target[, options])](#elementhandledraganddroptarget-options)
* [elementHandle.dragEnter([data])](#elementhandledragenterdata)
* [elementHandle.dragOver([data])](#elementhandledragoverdata)
* [elementHandle.drop([data])](#elementhandledropdata)
feat(api): add element.select and element.evaluate for consistency (#4892)
2019-09-04 22:19:34 +00:00
* [elementHandle.evaluate(pageFunction[, ...args])](#elementhandleevaluatepagefunction-args)
* [elementHandle.evaluateHandle(pageFunction[, ...args])](#elementhandleevaluatehandlepagefunction-args)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [elementHandle.executionContext()](#elementhandleexecutioncontext)
* [elementHandle.focus()](#elementhandlefocus)
* [elementHandle.getProperties()](#elementhandlegetproperties)
* [elementHandle.getProperty(propertyName)](#elementhandlegetpropertypropertyname)
* [elementHandle.hover()](#elementhandlehover)
feat: add threshold to Page.isIntersectingViewport (#6497)
2021-09-15 20:56:50 +00:00
* [elementHandle.isIntersectingViewport([options])](#elementhandleisintersectingviewportoptions)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [elementHandle.jsonValue()](#elementhandlejsonvalue)
* [elementHandle.press(key[, options])](#elementhandlepresskey-options)
* [elementHandle.screenshot([options])](#elementhandlescreenshotoptions)
feat(api): add element.select and element.evaluate for consistency (#4892)
2019-09-04 22:19:34 +00:00
* [elementHandle.select(...values)](#elementhandleselectvalues)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
* [elementHandle.tap()](#elementhandletap)
* [elementHandle.toString()](#elementhandletostring)
* [elementHandle.type(text[, options])](#elementhandletypetext-options)
* [elementHandle.uploadFile(...filePaths)](#elementhandleuploadfilefilepaths)
feat: implement Element.waitForSelector (#7825) Co-authored-by: Johan Bay <jobay@google.com> Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-12-09 11:51:14 +00:00
* [elementHandle.waitForSelector(selector[, options])](#elementhandlewaitforselectorselector-options)
feat: add waitForXPath to ElementHandle (#8329)
2022-05-10 10:45:20 +00:00
* [elementHandle.waitForXPath(xpath[, options])](#elementhandlewaitforxpathxpath-options)
chore: rename Request class to HTTPRequest (#5934) It conflicts with an inbuilt TypeScript `Request` type so can cause confusion when in TS land. Note: `Response.ts` and `Worker.ts` also suffer from this; PRs to rename them are incoming.
2020-05-29 08:38:40 +00:00
- [class: HTTPRequest](#class-httprequest)
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
* [httpRequest.abort([errorCode], [priority])](#httprequestaborterrorcode-priority)
* [httpRequest.abortErrorReason()](#httprequestaborterrorreason)
* [httpRequest.continue([overrides], [priority])](#httprequestcontinueoverrides-priority)
* [httpRequest.continueRequestOverrides()](#httprequestcontinuerequestoverrides)
* [httpRequest.enqueueInterceptAction(pendingHandler)](#httprequestenqueueinterceptactionpendinghandler)
chore: rename Request class to HTTPRequest (#5934) It conflicts with an inbuilt TypeScript `Request` type so can cause confusion when in TS land. Note: `Response.ts` and `Worker.ts` also suffer from this; PRs to rename them are incoming.
2020-05-29 08:38:40 +00:00
* [httpRequest.failure()](#httprequestfailure)
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
* [httpRequest.finalizeInterceptions()](#httprequestfinalizeinterceptions)
chore: rename Request class to HTTPRequest (#5934) It conflicts with an inbuilt TypeScript `Request` type so can cause confusion when in TS land. Note: `Response.ts` and `Worker.ts` also suffer from this; PRs to rename them are incoming.
2020-05-29 08:38:40 +00:00
* [httpRequest.frame()](#httprequestframe)
* [httpRequest.headers()](#httprequestheaders)
feat: add initiator to HTTPRequest (#7614) Co-Authored-By: atersolis <atersolis@atersolis.net>
2021-09-29 15:14:21 +00:00
* [httpRequest.initiator()](#httprequestinitiator)
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
* [httpRequest.interceptResolutionState()](#httprequestinterceptresolutionstate)
* [httpRequest.isInterceptResolutionHandled()](#httprequestisinterceptresolutionhandled)
chore: rename Request class to HTTPRequest (#5934) It conflicts with an inbuilt TypeScript `Request` type so can cause confusion when in TS land. Note: `Response.ts` and `Worker.ts` also suffer from this; PRs to rename them are incoming.
2020-05-29 08:38:40 +00:00
* [httpRequest.isNavigationRequest()](#httprequestisnavigationrequest)
* [httpRequest.method()](#httprequestmethod)
* [httpRequest.postData()](#httprequestpostdata)
* [httpRequest.redirectChain()](#httprequestredirectchain)
* [httpRequest.resourceType()](#httprequestresourcetype)
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
* [httpRequest.respond(response, [priority])](#httprequestrespondresponse-priority)
chore: rename Request class to HTTPRequest (#5934) It conflicts with an inbuilt TypeScript `Request` type so can cause confusion when in TS land. Note: `Response.ts` and `Worker.ts` also suffer from this; PRs to rename them are incoming.
2020-05-29 08:38:40 +00:00
* [httpRequest.response()](#httprequestresponse)
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
* [httpRequest.responseForRequest()](#httprequestresponseforrequest)
chore: rename Request class to HTTPRequest (#5934) It conflicts with an inbuilt TypeScript `Request` type so can cause confusion when in TS land. Note: `Response.ts` and `Worker.ts` also suffer from this; PRs to rename them are incoming.
2020-05-29 08:38:40 +00:00
* [httpRequest.url()](#httprequesturl)
chore: rename `Response` to `HTTPResponse` (#5940) To avoid any conflicts with the TS `Response` type.
2020-05-29 10:49:30 +00:00
- [class: HTTPResponse](#class-httpresponse)
* [httpResponse.buffer()](#httpresponsebuffer)
* [httpResponse.frame()](#httpresponseframe)
* [httpResponse.fromCache()](#httpresponsefromcache)
* [httpResponse.fromServiceWorker()](#httpresponsefromserviceworker)
* [httpResponse.headers()](#httpresponseheaders)
* [httpResponse.json()](#httpresponsejson)
* [httpResponse.ok()](#httpresponseok)
* [httpResponse.remoteAddress()](#httpresponseremoteaddress)
* [httpResponse.request()](#httpresponserequest)
* [httpResponse.securityDetails()](#httpresponsesecuritydetails)
* [httpResponse.status()](#httpresponsestatus)
* [httpResponse.statusText()](#httpresponsestatustext)
* [httpResponse.text()](#httpresponsetext)
feat(HTTPResponse): expose timing information (#8025)
2022-02-15 10:16:49 +00:00
* [httpResponse.timing()](#httpresponsetiming)
chore: rename `Response` to `HTTPResponse` (#5940) To avoid any conflicts with the TS `Response` type.
2020-05-29 10:49:30 +00:00
* [httpResponse.url()](#httpresponseurl)
feat(Network): introduce response.securityDetails() method (#1880) This patch: - introduces `SecurityDetails` class that exposes a set of fields that describe properties of secure connection - introduces method `response.securityDetails()` that returns an instance of `SecurityDetails` object.
2018-02-13 19:26:18 +00:00
- [class: SecurityDetails](#class-securitydetails)
* [securityDetails.issuer()](#securitydetailsissuer)
* [securityDetails.protocol()](#securitydetailsprotocol)
feat: add securityDetails.subjectAlternativeNames() #5628 (#5881) Co-authored-by: Michal TOMA <michaltoma2205@gmail.com> Co-authored-by: Alex Rudenko <alexrudenko@chromium.org> Fixes #5625. Closes #5628.
2020-05-18 10:58:46 +00:00
* [securityDetails.subjectAlternativeNames()](#securitydetailssubjectalternativenames)
feat(Network): introduce response.securityDetails() method (#1880) This patch: - introduces `SecurityDetails` class that exposes a set of fields that describe properties of secure connection - introduces method `response.securityDetails()` that returns an instance of `SecurityDetails` object.
2018-02-13 19:26:18 +00:00
* [securityDetails.subjectName()](#securitydetailssubjectname)
* [securityDetails.validFrom()](#securitydetailsvalidfrom)
* [securityDetails.validTo()](#securitydetailsvalidto)
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
- [class: Target](#class-target)
Add `Page.browser()` method (#2387) Call page.browser() to get the browser instance associated with a page. Fixes #2275
2018-04-17 17:37:17 +00:00
* [target.browser()](#targetbrowser)
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
* [target.browserContext()](#targetbrowsercontext)
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
* [target.createCDPSession()](#targetcreatecdpsession)
feat(targets): add target.opener() (#2641) This adds a `.opener` property to a target so that its origin can be tracked. For now returns `null` when there's no `openerId`. Fixes #1830
2018-06-01 00:06:29 +00:00
* [target.opener()](#targetopener)
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
* [target.page()](#targetpage)
* [target.type()](#targettype)
* [target.url()](#targeturl)
feat(workers): create workers from service workers and shared workers (#4397) This allows users to easily evaluate javascript inside service workers and shared workers by creating a Worker object for them.
2019-05-10 00:29:18 +00:00
* [target.worker()](#targetworker)
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
- [class: CDPSession](#class-cdpsession)
feat: expose other sessions from connection (#6863)
2021-05-07 08:31:39 +00:00
* [cdpSession.connection()](#cdpsessionconnection)
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
* [cdpSession.detach()](#cdpsessiondetach)
feat(oop iframes)!: integrate OOP iframes with the frame manager (#7556) This pull request to adds better support for OOP iframes (see #2548) The current problem with OOP iframes is that they are moved to a different target. Because of this, the previous versions of Puppeteer pretty much ignored them. This change extends the FrameManager to already take OOP iframes into account and hides the fact that those frames are actually in different targets. Further work needs to be done to also make the NetworkManager aware of these and to make sure that settings like emulations etc. are also properly passed down to the new targets.
2021-10-28 09:25:49 +00:00
* [cdpSession.id()](#cdpsessionid)
chore: use devtools-protocol package (#6172) * chore: Use devtools-protocol package Rather than maintain our own protocol we can instead use the devtools-protocol package and pin it to the version of Chromium that Puppeteer is shipping with. The only changes are naming changes between the bespoke protocol that Puppeteer created and the devtools-protocol one.
2020-07-10 10:51:52 +00:00
* [cdpSession.send(method[, ...paramArgs])](#cdpsessionsendmethod-paramargs)
feat: Implement JavaScript Coverage (#1673) This patch introduces a new `page.coverage` namespace with two methods: - `page.coverage.startJSCoverage` to initiate JavaScript coverage recording - `page.coverage.stopJSCoverage` to stop JavaScript coverage and get results
2018-01-03 03:53:53 +00:00
- [class: Coverage](#class-coverage)
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
* [coverage.startCSSCoverage([options])](#coveragestartcsscoverageoptions)
* [coverage.startJSCoverage([options])](#coveragestartjscoverageoptions)
feat: implement CSS Coverage (#1714) This patch adds two new methods to the `page.coverage` namespace: - `page.coverage.startCSSCoverage()` - to initiate css coverage - `page.coverage.stopCSSCoverage()` - to stop css coverage The coverage format is consistent with the JavaScript coverage.
2018-01-04 02:21:40 +00:00
* [coverage.stopCSSCoverage()](#coveragestopcsscoverage)
feat: Implement JavaScript Coverage (#1673) This patch introduces a new `page.coverage` namespace with two methods: - `page.coverage.startJSCoverage` to initiate JavaScript coverage recording - `page.coverage.stopJSCoverage` to stop JavaScript coverage and get results
2018-01-03 03:53:53 +00:00
* [coverage.stopJSCoverage()](#coveragestopjscoverage)
feat: introduce puppeteer/Errors (#3056) This patch adds a new require, `puppeteer/Errors`, that holds all the Puppeteer-specific error classes. Currently, the only custom error class we use is `TimeoutError`. We'll expand in future with `CrashError` and some others. Fixes #1694.
2018-08-09 23:51:12 +00:00
- [class: TimeoutError](#class-timeouterror)
chore: migrate away from Node's EventEmitter (#5979)
2020-06-15 10:52:19 +00:00
- [class: EventEmitter](#class-eventemitter)
* [eventEmitter.addListener(event, handler)](#eventemitteraddlistenerevent-handler)
* [eventEmitter.emit(event, [eventData])](#eventemitteremitevent-eventdata)
* [eventEmitter.listenerCount(event)](#eventemitterlistenercountevent)
* [eventEmitter.off(event, handler)](#eventemitteroffevent-handler)
* [eventEmitter.on(event, handler)](#eventemitteronevent-handler)
* [eventEmitter.once(event, handler)](#eventemitteronceevent-handler)
* [eventEmitter.removeAllListeners([event])](#eventemitterremovealllistenersevent)
* [eventEmitter.removeListener(event, handler)](#eventemitterremovelistenerevent-handler)
chore: mark version v5.4.0 (#6542)
2020-10-23 14:28:38 +00:00
- [interface: CustomQueryHandler](#interface-customqueryhandler)
docs(api.md): add documentation on custom handlers (#8074)
2022-02-28 09:43:59 +00:00
- [interface: Selector](#interface-selector)
docs(api.md): fix table-of-contents (#2636) This patch drops the markdown-toc module and instead rolls out our own simple markdown table-of-contents generator. As a side effect, it fixes links to `page.$` and `page.$$`.
2018-05-31 21:21:43 +00:00
<!-- 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
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
<!-- prettier-ignore-end -->
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
### Overview
Get rid of page.emulate() / page.emulatedDevices() methods This patch: - gets rid of `page.emulate` and `page.emulatedDevices` methods. Instead, it is suggested to use `page.setViewport()` and `page.setUserAgent()` methods. - moves DeviceDescriptors to the top level of the puppeteer so that it is convenient to require them. - improves on documentation to describe the suggested emulation approach. References #88.
2017-07-21 01:14:43 +00:00
docs(README.md): Update docs to more clearly differentiate between Chromium and Chrome (#1574) This patch clarifies the documentation to more clearly note that Puppeteer works with both Chromium (by default) and Chrome. Fixes #1516
2017-12-15 03:09:48 +00:00
Puppeteer is a Node library which provides a high-level API to control Chromium or Chrome over the DevTools Protocol.
Get rid of page.emulate() / page.emulatedDevices() methods This patch: - gets rid of `page.emulate` and `page.emulatedDevices` methods. Instead, it is suggested to use `page.setViewport()` and `page.setUserAgent()` methods. - moves DeviceDescriptors to the top level of the puppeteer so that it is convenient to require them. - improves on documentation to describe the suggested emulation approach. References #88.
2017-07-21 01:14:43 +00:00
docs(api.md): update puppeteer overview (#2584) Puppeteer tip-of-tree includes both workers and browser contexts.
2018-05-25 23:47:15 +00:00
The Puppeteer API is hierarchical and mirrors the browser structure.
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
docs(api.md): update puppeteer overview (#2584) Puppeteer tip-of-tree includes both workers and browser contexts.
2018-05-25 23:47:15 +00:00
> **NOTE** On the following diagram, faded entities are not currently represented in Puppeteer.
docs(api): fix overview diagram for pptr.dev (#6128) We need to serve the image from user-images.githubusercontent.com for it to work properly on pptr.dev. This broke when merging #5947. Fixes #6127.
2020-06-30 14:56:26 +00:00
![puppeteer overview](https://user-images.githubusercontent.com/81942/86137523-ab2ba080-baed-11ea-9d4b-30eda784585a.png)
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- [`Puppeteer`](#class-puppeteer) communicates with the browser using [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/).
docs(api.md): update puppeteer overview (#2584) Puppeteer tip-of-tree includes both workers and browser contexts.
2018-05-25 23:47:15 +00:00
- [`Browser`](#class-browser) instance can own multiple browser contexts.
- [`BrowserContext`](#class-browsercontext) instance defines a browsing session and can own multiple pages.
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
- [`Page`](#class-page) has at least one frame: main frame. There might be other frames created by [iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) or [frame](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/frame) tags.
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- [`Frame`](#class-frame) has at least one execution context - the default execution context - where the frame's JavaScript is executed. A Frame might have additional execution contexts that are associated with [extensions](https://developer.chrome.com/extensions).
docs: heading ID references in docs/api.md (#7974) - `Worker` -> `WebWorker`, `#class-worker` -> `#class-webworker` - `#pagesetuseragentuseragent-useragentdata` -> `#pagesetuseragentuseragent-useragentmetadata` - `####WaitTimeoutOptions` -> `#waittimeoutoptions` - `#cooperative-intercept-mode-and-legacy-intercept-mode` -> `#cooperative-intercept-mode` Co-authored-by: jrandolf <86539915+jrandolf@users.noreply.github.com>
2022-02-11 13:43:52 +00:00
- [`WebWorker`](#class-webworker) has a single execution context and facilitates interacting with [WebWorkers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API).
docs(api): add hierarchical diagram (#1040)
2017-10-16 18:07:06 +00:00
(Diagram source: [link](https://docs.google.com/drawings/d/1Q_AM6KYs9kbyLZF-Lpp5mtpAWth73Cq8IKCsWYgi8MM/edit?usp=sharing))
docs(api.md): expand on puppeteer-core vs puppeteer (#3189)
2018-09-04 16:32:57 +00:00
### puppeteer vs puppeteer-core
Every release since v1.7.0 we publish two packages:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api.md): expand on puppeteer-core vs puppeteer (#3189)
2018-09-04 16:32:57 +00:00
- [puppeteer](https://www.npmjs.com/package/puppeteer)
- [puppeteer-core](https://www.npmjs.com/package/puppeteer-core)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
`puppeteer` is a _product_ for browser automation. When installed, it downloads a version of
docs(api.md): expand on puppeteer-core vs puppeteer (#3189)
2018-09-04 16:32:57 +00:00
Chromium, which it then drives using `puppeteer-core`. Being an end-user product, `puppeteer` supports a bunch of convenient `PUPPETEER_*` env variables to tweak its behavior.
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
`puppeteer-core` is a _library_ to help drive anything that supports DevTools protocol. `puppeteer-core` doesn't download Chromium when installed. Being a library, `puppeteer-core` is fully driven
docs(api.md): expand on puppeteer-core vs puppeteer (#3189)
2018-09-04 16:32:57 +00:00
through its programmatic interface and disregards all the `PUPPETEER_*` env variables.
To sum up, the only differences between `puppeteer-core` and `puppeteer` are:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api.md): expand on puppeteer-core vs puppeteer (#3189)
2018-09-04 16:32:57 +00:00
- `puppeteer-core` doesn't automatically download Chromium when installed.
- `puppeteer-core` ignores all `PUPPETEER_*` env variables.
In most cases, you'll be fine using the `puppeteer` package.
However, you should use `puppeteer-core` if:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api.md): fix typo (#3848)
2019-01-27 05:37:02 +00:00
- you're building another end-user product or library atop of DevTools protocol. For example, one might build a PDF generator using `puppeteer-core` and write a custom `install.js` script that downloads [`headless_shell`](https://chromium.googlesource.com/chromium/src/+/lkgr/headless/README.md) instead of Chromium to save disk space.
docs(api.md): expand on puppeteer-core vs puppeteer (#3189)
2018-09-04 16:32:57 +00:00
- you're bundling Puppeteer to use in Chrome Extension / browser with the DevTools protocol where downloading an additional Chromium binary is unnecessary.
feat: make it possible to run `install.js` script with `puppeteer-core` (#5325) Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2020-01-28 12:08:13 +00:00
- you're building a set of tools where `puppeteer-core` is one of the ingredients and you want to postpone `install.js` script execution until Chromium is about to be used.
docs(api.md): expand on puppeteer-core vs puppeteer (#3189)
2018-09-04 16:32:57 +00:00
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
When using `puppeteer-core`, remember to change the _include_ line:
docs(api.md): add an include statement for puppeteer-core (#3213) Fix #3204
2018-09-07 09:46:59 +00:00
```js
const puppeteer = require('puppeteer-core');
```
feat: add channel parameter for puppeteer.launch (#7389) This change adds a new `channel` parameter to `puppeteer.launch`. When specified, Puppeteer will search for the locally installed release channel of Google Chrome and use it to launch. Available values are `chrome`, `chrome-beta`, `chrome-canary`, `chrome-dev`. This parameter is mutually exclusive with `executablePath`.
2021-07-09 12:43:42 +00:00
You will then need to call [`puppeteer.connect([options])`](#puppeteerconnectoptions) or [`puppeteer.launch([options])`](#puppeteerlaunchoptions) with an explicit `executablePath` or `channel` option.
docs(api.md): expand on puppeteer-core vs puppeteer (#3189)
2018-09-04 16:32:57 +00:00
Add environment variable to skip download (#606) This patch: - starts skipping chromium download if `PUPPETEER_SKIP_CHROMIUM_DOWNLOAD` env variable is set - adds description of support env variables to the `docs/api.md`. References #603
2017-08-31 04:40:15 +00:00
### Environment Variables
feat(install): support npm config for chromium revision (#2290) This patch: - adds `npm_config_puppeteer_chromium_revision` support - clarifies api documentation about variables from npm config
2018-03-30 17:49:48 +00:00
Puppeteer looks for certain [environment variables](https://en.wikipedia.org/wiki/Environment_variable) to aid its operations.
feat(puppeteer): support convenience env variables (#3190) We had (and still have) a ton of pull requests to support PUPPETEER_EXECUTABLE_PATH and PUPPETEER_CHROMIUM_REVISION in puppeteer launcher. We were hesitant before since env variables are not scoped and thus don't make a good interface for a library. Now, since we determined `puppeteer-core` as a library and `puppeteer` as our end-user product, it's safe to satisfy our user needs. This patch: - teaches PUPPETEER_EXECUTABLE_PATH and PUPPETEER_CHROMIUM_REVISION env variables to control how Puppeteer launches browser - makes sure these variables play no role in `puppeteer-core` package.
2018-09-05 21:59:14 +00:00
If Puppeteer doesn't find them in the environment during the installation step, a lowercased variant of these variables will be used from the [npm config](https://docs.npmjs.com/cli/config).
Add environment variable to skip download (#606) This patch: - starts skipping chromium download if `PUPPETEER_SKIP_CHROMIUM_DOWNLOAD` env variable is set - adds description of support env variables to the `docs/api.md`. References #603
2017-08-31 04:40:15 +00:00
fix(install): respect environment proxy config when downloading Firef… (#6577) Issues: #6573
2021-09-15 19:41:03 +00:00
- `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` - defines HTTP proxy settings that are used to download and run the browser.
[docs] clarify env variables usage with npmrc
2017-09-26 02:15:18 +00:00
- `PUPPETEER_SKIP_CHROMIUM_DOWNLOAD` - do not download bundled Chromium during installation step.
feat: allow to customize tmpdir (#7243)
2021-09-23 07:26:00 +00:00
- `PUPPETEER_TMP_DIR` - defines the directory to be used by Puppeteer for creating temporary files. Defaults to [`os.tmpdir()`](https://nodejs.org/api/os.html#os_os_tmpdir).
docs(api.md): better documentation for PUPPETEER_DOWNLOAD_HOST (#3669) Fix #3635.
2018-12-17 21:31:32 +00:00
- `PUPPETEER_DOWNLOAD_HOST` - overwrite URL prefix that is used to download Chromium. Note: this includes protocol and might even include path prefix. Defaults to `https://storage.googleapis.com`.
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
- `PUPPETEER_DOWNLOAD_PATH` - overwrite the path for the downloads folder. Defaults to `<root>/.local-chromium`, where `<root>` is Puppeteer's package root.
chore: update URLs (#5185)
2019-11-26 12:12:25 +00:00
- `PUPPETEER_CHROMIUM_REVISION` - specify a certain version of Chromium you'd like Puppeteer to use. See [puppeteer.launch([options])](#puppeteerlaunchoptions) on how executable path is inferred. **BEWARE**: Puppeteer is only [guaranteed to work](https://github.com/puppeteer/puppeteer/#q-why-doesnt-puppeteer-vxxx-work-with-chromium-vyyy) with the bundled Chromium, use at your own risk.
- `PUPPETEER_EXECUTABLE_PATH` - specify an executable path to be used in `puppeteer.launch`. See [puppeteer.launch([options])](#puppeteerlaunchoptions) on how the executable path is inferred. **BEWARE**: Puppeteer is only [guaranteed to work](https://github.com/puppeteer/puppeteer/#q-why-doesnt-puppeteer-vxxx-work-with-chromium-vyyy) with the bundled Chromium, use at your own risk.
(feat) Add option to fetch Firefox Nightly (#5467) * (feat) Add option to fetch Firefox Nightly Add Firefox support to BrowserFetcher and the install script. By default, the latest Firefox Nightly is downloaded directly from archive.mozilla.org (dmg, tar.bz2 and zip) This also required changes that impact `puppeteer.launch()` and `puppeteer.executablePath()` Fixes #5151 * Update docs/api.md Co-Authored-By: Mathias Bynens <mathias@qiwi.be> * Clean up revision promise * Improve error handling in revision check * Remove matchAll * Use explicit octal mode * Update .gitignore Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2020-03-10 20:59:03 +00:00
- `PUPPETEER_PRODUCT` - specify which browser you'd like Puppeteer to use. Must be one of `chrome` or `firefox`. This can also be used during installation to fetch the recommended browser binary. Setting `product` programmatically in [puppeteer.launch([options])](#puppeteerlaunchoptions) supersedes this environment variable. The product is exposed in [`puppeteer.product`](#puppeteerproduct)
feat: add support for Apple Silicon chromium builds (#7546) Google has published Chromium builds for Apple Silicon so we can fetch it now Related to #6622
2022-05-05 07:33:19 +00:00
- `PUPPETEER_EXPERIMENTAL_CHROMIUM_MAC_ARM` — specify Puppeteer download Chromium for Apple M1. On Apple M1 devices Puppeteer by default downloads the version for Intel's processor which runs via Rosetta. It works without any problems, however, with this option, you should get more efficient resource usage (CPU and RAM) that could lead to a faster execution time. **BEWARE**: it's an experimental option that makes sense only if you have an Apple M1 device, use at your own risk.
[docs] clarify env variables usage with npmrc
2017-09-26 02:15:18 +00:00
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
> **NOTE** `PUPPETEER_*` env variables are not accounted for in the [`puppeteer-core`](https://www.npmjs.com/package/puppeteer-core) package.
feat: introduce puppeteer/Errors (#3056) This patch adds a new require, `puppeteer/Errors`, that holds all the Puppeteer-specific error classes. Currently, the only custom error class we use is `TimeoutError`. We'll expand in future with `CrashError` and some others. Fixes #1694.
2018-08-09 23:51:12 +00:00
docs(api.md): expand on testing Chrome Extensions (#2893) Fixes #2823
2018-07-19 02:33:51 +00:00
### Working with Chrome Extensions
Puppeteer can be used for testing Chrome Extensions.
docs: improve the Working with Chrome Extensions section (#8321) - Added a note to mention the experimental Chrome headless mode can also be used. - Improved the example code to wait for the background page to be ready. The previous example sometimes didn't work, since the background page would take a split-second to load. - Added a note to mention how to find the background ServiceWorker for Chrome MV3 extensions.
2022-05-10 06:21:57 +00:00
> **NOTE** Extensions in Chrome / Chromium currently only work in non-headless mode and experimental Chrome headless mode.
docs(api.md): expand on testing Chrome Extensions (#2893) Fixes #2823
2018-07-19 02:33:51 +00:00
docs(api.md): some grammar/wording (#3057)
2018-08-10 00:49:06 +00:00
The following is code for getting a handle to the [background page](https://developer.chrome.com/extensions/background_pages) of an extension whose source is located in `./my-extension`:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api.md): expand on testing Chrome Extensions (#2893) Fixes #2823
2018-07-19 02:33:51 +00:00
```js
const puppeteer = require('puppeteer');
(async () => {
const pathToExtension = require('path').join(__dirname, 'my-extension');
docs(api.md): Fix missing `await` in extension example (#3447) The extensions example did not `await puppeteer.launch(...)` throwing errors right after awaiting `browser.targets()`.
2018-10-27 01:38:00 +00:00
const browser = await puppeteer.launch({
docs: improve the Working with Chrome Extensions section (#8321) - Added a note to mention the experimental Chrome headless mode can also be used. - Improved the example code to wait for the background page to be ready. The previous example sometimes didn't work, since the background page would take a split-second to load. - Added a note to mention how to find the background ServiceWorker for Chrome MV3 extensions.
2022-05-10 06:21:57 +00:00
headless: 'chrome',
docs(api.md): expand on testing Chrome Extensions (#2893) Fixes #2823
2018-07-19 02:33:51 +00:00
args: [
`--disable-extensions-except=${pathToExtension}`,
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
`--load-extension=${pathToExtension}`,
],
docs(api.md): expand on testing Chrome Extensions (#2893) Fixes #2823
2018-07-19 02:33:51 +00:00
});
docs: improve the Working with Chrome Extensions section (#8321) - Added a note to mention the experimental Chrome headless mode can also be used. - Improved the example code to wait for the background page to be ready. The previous example sometimes didn't work, since the background page would take a split-second to load. - Added a note to mention how to find the background ServiceWorker for Chrome MV3 extensions.
2022-05-10 06:21:57 +00:00
const backgroundPageTarget = await browser.waitForTarget(
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
target => target.type() === 'background_page'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
);
docs(api.md): expand on testing Chrome Extensions (#2893) Fixes #2823
2018-07-19 02:33:51 +00:00
const backgroundPage = await backgroundPageTarget.page();
// Test the background page as you would any other page.
await browser.close();
})();
```
docs: improve the Working with Chrome Extensions section (#8321) - Added a note to mention the experimental Chrome headless mode can also be used. - Improved the example code to wait for the background page to be ready. The previous example sometimes didn't work, since the background page would take a split-second to load. - Added a note to mention how to find the background ServiceWorker for Chrome MV3 extensions.
2022-05-10 06:21:57 +00:00
> **NOTE** Chrome Manifest V3 extensions have a background ServiceWorker of type 'service_worker', instead of a page of type 'background_page'.
docs(api.md): expand on testing Chrome Extensions (#2893) Fixes #2823
2018-07-19 02:33:51 +00:00
> **NOTE** It is not yet possible to test extension popups or content scripts.
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
### class: Puppeteer
Capitalize Chromium and Puppeteer (#263)
2017-08-15 07:14:12 +00:00
Puppeteer module provides a method to launch a Chromium instance.
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
The following is a typical example of using Puppeteer to drive automation:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
```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
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
(async () => {
const browser = await puppeteer.launch();
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const page = await browser.newPage();
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
await page.goto('https://www.google.com');
Get rid of page.emulate() / page.emulatedDevices() methods This patch: - gets rid of `page.emulate` and `page.emulatedDevices` methods. Instead, it is suggested to use `page.setViewport()` and `page.setUserAgent()` methods. - moves DeviceDescriptors to the top level of the puppeteer so that it is convenient to require them. - improves on documentation to describe the suggested emulation approach. References #88.
2017-07-21 01:14:43 +00:00
// other actions...
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +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
```
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore: mark version v5.4.0 (#6542)
2020-10-23 14:28:38 +00:00
#### puppeteer.clearCustomQueryHandlers()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore: mark version v5.4.0 (#6542)
2020-10-23 14:28:38 +00:00
Clears all registered handlers.
Get rid of page.emulate() / page.emulatedDevices() methods This patch: - gets rid of `page.emulate` and `page.emulatedDevices` methods. Instead, it is suggested to use `page.setViewport()` and `page.setUserAgent()` methods. - moves DeviceDescriptors to the top level of the puppeteer so that it is convenient to require them. - improves on documentation to describe the suggested emulation approach. References #88.
2017-07-21 01:14:43 +00:00
Introduce Puppeteer.connect method (#264) This patch: - refactors Connection to use a single remote debugging URL instead of a pair of port and browserTargetId - introduces Puppeteer.connect() method to attach to already running browser instance. Fixes #238.
2017-08-15 21:29:42 +00:00
#### puppeteer.connect(options)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `options` <[Object]>
feat(launcher): add browserUrl option to puppeteer.connect (#3558) The `browserURL` option allows to connect to a browser that exposed it's remote debugging protocol on a known port. Fixes #3537
2019-01-14 21:23:34 +00:00
- `browserWSEndpoint` <?[string]> a [browser websocket endpoint](#browserwsendpoint) to connect to.
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
- `browserURL` <?[string]> a browser URL to connect to, in format `http://${host}:${port}`. Use interchangeably with `browserWSEndpoint` to let Puppeteer fetch it from [metadata endpoint](https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target).
Introduce Puppeteer.connect method (#264) This patch: - refactors Connection to use a single remote debugging URL instead of a pair of port and browserTargetId - introduces Puppeteer.connect() method to attach to already running browser instance. Fixes #238.
2017-08-15 21:29:42 +00:00
- `ignoreHTTPSErrors` <[boolean]> Whether to ignore HTTPS errors during navigation. Defaults to `false`.
feat: add option to specify the default viewport (#3005) Fixes #1183.
2018-08-01 23:23:03 +00:00
- `defaultViewport` <?[Object]> Sets a consistent viewport for each page. Defaults to an 800x600 viewport. `null` disables the default viewport.
- `width` <[number]> page width in pixels.
- `height` <[number]> page height in pixels.
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
- `deviceScaleFactor` <[number]> Specify device scale factor (can be thought of as DPR). Defaults to `1`.
feat: add option to specify the default viewport (#3005) Fixes #1183.
2018-08-01 23:23:03 +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`.
feat: add slowMo option to puppeteer.connect (#1864) This patch introduces a `slowMo` option to the `puppeteer.connect` method. The option is similar to the one in `puppeteer.launch` and is used to slow down the connection.
2018-01-23 00:45:46 +00:00
- `slowMo` <[number]> Slows down Puppeteer operations by the specified amount of milliseconds. Useful so that you can see what is going on.
fix(types): fix parameters where they disagree with the api (#3525)
2018-11-12 20:59:21 +00:00
- `transport` <[ConnectionTransport]> **Experimental** Specify a custom transport object for Puppeteer to use.
fix: update preferred revision after Launcher is created (#5640) Fixes an edge case where Puppeteer looked for a Chromium revision when launching Firefox. Allow appropriate Launcher to be instantiated when calling `Puppeteer.connect`. Add an example of running Firefox.
2020-04-14 16:42:48 +00:00
- `product` <[string]> Possible values are: `chrome`, `firefox`. Defaults to `chrome`.
fix: make targetFilter synchronous (#7203)
2021-05-05 07:50:50 +00:00
- `targetFilter` <?[function]\([Protocol.Target.TargetInfo]\):[boolean]> Use this function to decide if Puppeteer should connect to the given target. If a `targetFilter` is provided, Puppeteer only connects to targets for which `targetFilter` returns `true`. By default, Puppeteer connects to all available targets.
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
docs: connect works with any supported browser (#5572)
2020-04-02 08:35:47 +00:00
This methods attaches Puppeteer to an existing browser instance.
Introduce Puppeteer.connect method (#264) This patch: - refactors Connection to use a single remote debugging URL instead of a pair of port and browserTargetId - introduces Puppeteer.connect() method to attach to already running browser instance. Fixes #238.
2017-08-15 21:29:42 +00:00
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
#### puppeteer.createBrowserFetcher([options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
- `options` <[Object]>
(feat) Add option to fetch Firefox Nightly (#5467) * (feat) Add option to fetch Firefox Nightly Add Firefox support to BrowserFetcher and the install script. By default, the latest Firefox Nightly is downloaded directly from archive.mozilla.org (dmg, tar.bz2 and zip) This also required changes that impact `puppeteer.launch()` and `puppeteer.executablePath()` Fixes #5151 * Update docs/api.md Co-Authored-By: Mathias Bynens <mathias@qiwi.be> * Clean up revision promise * Improve error handling in revision check * Remove matchAll * Use explicit octal mode * Update .gitignore Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2020-03-10 20:59:03 +00:00
- `host` <[string]> A download host to be used. Defaults to `https://storage.googleapis.com`. If the `product` is `firefox`, this defaults to `https://archive.mozilla.org/pub/firefox/nightly/latest-mozilla-central`.
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
- `path` <[string]> A path for the downloads folder. Defaults to `<root>/.local-chromium`, where `<root>` is Puppeteer's package root. If the `product` is `firefox`, this defaults to `<root>/.local-firefox`.
chore: migrate src/Launcher to TypeScript (#5775)
2020-04-30 12:45:58 +00:00
- `platform` <"linux"|"mac"|"win32"|"win64"> [string] for the current platform. Possible values are: `mac`, `win32`, `win64`, `linux`. Defaults to the current platform.
chore: migrate src/BrowserFetcher to TypeScript (#5727) * chore: migrate src/BrowserFetcher to TypeScript
2020-04-24 07:57:53 +00:00
- `product` <"chrome"|"firefox"> [string] for the product to run. Possible values are: `chrome`, `firefox`. Defaults to `chrome`.
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
- returns: <[BrowserFetcher]>
chore: mark version v5.4.0 (#6542)
2020-10-23 14:28:38 +00:00
#### puppeteer.customQueryHandlerNames()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api): fix some typos (#6672)
2020-12-22 12:34:44 +00:00
- returns: <[Array]<string>> A list with the names of all registered custom query handlers.
chore: mark version v5.4.0 (#6542)
2020-10-23 14:28:38 +00:00
feat(launcher): allow options to be passed into puppeteer.defaultArgs (#2950)
2018-08-07 20:22:04 +00:00
#### puppeteer.defaultArgs([options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields:
feat: support chrome headless mode (#8260) * feat: support chrome headless mode Co-authored-by: Ergün Erdoğmuş <erdogmusergun@gmail.com>
2022-04-25 11:11:23 +00:00
- `headless` <[boolean]|"chrome"> Whether to run browser in [headless mode](https://developers.google.com/web/updates/2017/04/headless-chrome). Defaults to `true` unless the `devtools` option is `true`. "chrome" is a new experimental headless mode (use at your own risk).
feat(launcher): allow options to be passed into puppeteer.defaultArgs (#2950)
2018-08-07 20:22:04 +00:00
- `args` <[Array]<[string]>> Additional arguments to pass to the browser instance. The list of Chromium flags can be found [here](http://peter.sh/experiments/chromium-command-line-switches/).
chore: remove references to upstream `master` branches (#7412) Chromium had its branch renamed to `main`, and for other projects we can just point to the `HEAD`.
2021-09-14 15:02:39 +00:00
- `userDataDir` <[string]> Path to a [User Data Directory](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/docs/user_data_dir.md).
feat(launcher): allow options to be passed into puppeteer.defaultArgs (#2950)
2018-08-07 20:22:04 +00:00
- `devtools` <[boolean]> Whether to auto-open a DevTools panel for each tab. If this option is `true`, the `headless` option will be set `false`.
feat: add custom debugging port option (#4993)
2021-09-29 14:05:18 +00:00
- `debuggingPort` <[number]> Specify custom debugging port. Pass `0` to discover a random port. Defaults to `0`.
feat(launcher): ignoreDefaultArgs to accept array of options (#3049) If `ignoreDefaultArgs` is given an array of options, than these options will be excluded from the default command-line flags.
2018-08-09 02:10:10 +00:00
- returns: <[Array]<[string]>>
feat(Launcher): allow the default arguments to be overridden (#1623) This patch: - adds `puppeteer.defaultArgs()` method to get default arguments that are used to launch chrome - adds `ignoreDefaultArgs` option to `puppeteer.launch` to avoid using default puppeteer arguments Fixes #872
2017-12-20 01:51:21 +00:00
feat(launcher): ignoreDefaultArgs to accept array of options (#3049) If `ignoreDefaultArgs` is given an array of options, than these options will be excluded from the default command-line flags.
2018-08-09 02:10:10 +00:00
The default flags that Chromium will be launched with.
feat(launcher): allow options to be passed into puppeteer.defaultArgs (#2950)
2018-08-07 20:22:04 +00:00
feat(puppeteer): introduce `puppeteer.errors` and `puppeteer.devices` (#4312) These getters are introduced as a more convenient substitute for a `require('puppeteer/Errors')` and `require('puppeteer/DeviceDescriptors')`. This way we can make cross-browser story nicer - a single require of `puppeteer` or `puppeteer-firefox` fully defines Puppeteer environment.
2019-04-19 22:33:06 +00:00
#### puppeteer.devices
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(puppeteer): introduce `puppeteer.errors` and `puppeteer.devices` (#4312) These getters are introduced as a more convenient substitute for a `require('puppeteer/Errors')` and `require('puppeteer/DeviceDescriptors')`. This way we can make cross-browser story nicer - a single require of `puppeteer` or `puppeteer-firefox` fully defines Puppeteer environment.
2019-04-19 22:33:06 +00:00
- returns: <[Object]>
Returns a list of devices to be used with [`page.emulate(options)`](#pageemulateoptions). Actual list of
docs: fix link text Closes #6245.
2020-07-20 05:25:09 +00:00
devices can be found in [`src/common/DeviceDescriptors.ts`](https://github.com/puppeteer/puppeteer/blob/main/src/common/DeviceDescriptors.ts).
feat(puppeteer): introduce `puppeteer.errors` and `puppeteer.devices` (#4312) These getters are introduced as a more convenient substitute for a `require('puppeteer/Errors')` and `require('puppeteer/DeviceDescriptors')`. This way we can make cross-browser story nicer - a single require of `puppeteer` or `puppeteer-firefox` fully defines Puppeteer environment.
2019-04-19 22:33:06 +00:00
```js
const puppeteer = require('puppeteer');
const iPhone = puppeteer.devices['iPhone 6'];
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
(async () => {
const browser = await puppeteer.launch();
feat(puppeteer): introduce `puppeteer.errors` and `puppeteer.devices` (#4312) These getters are introduced as a more convenient substitute for a `require('puppeteer/Errors')` and `require('puppeteer/DeviceDescriptors')`. This way we can make cross-browser story nicer - a single require of `puppeteer` or `puppeteer-firefox` fully defines Puppeteer environment.
2019-04-19 22:33:06 +00:00
const page = await browser.newPage();
await page.emulate(iPhone);
await page.goto('https://www.google.com');
// other actions...
await browser.close();
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
})();
feat(puppeteer): introduce `puppeteer.errors` and `puppeteer.devices` (#4312) These getters are introduced as a more convenient substitute for a `require('puppeteer/Errors')` and `require('puppeteer/DeviceDescriptors')`. This way we can make cross-browser story nicer - a single require of `puppeteer` or `puppeteer-firefox` fully defines Puppeteer environment.
2019-04-19 22:33:06 +00:00
```
#### puppeteer.errors
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(puppeteer): introduce `puppeteer.errors` and `puppeteer.devices` (#4312) These getters are introduced as a more convenient substitute for a `require('puppeteer/Errors')` and `require('puppeteer/DeviceDescriptors')`. This way we can make cross-browser story nicer - a single require of `puppeteer` or `puppeteer-firefox` fully defines Puppeteer environment.
2019-04-19 22:33:06 +00:00
- returns: <[Object]>
- `TimeoutError` <[function]> A class of [TimeoutError].
docs(api.md): fix typo (#4761)
2019-07-29 21:14:31 +00:00
Puppeteer methods might throw errors if they are unable to fulfill a request. For example, [page.waitForSelector(selector[, options])](#pagewaitforselectorselector-options)
feat(puppeteer): introduce `puppeteer.errors` and `puppeteer.devices` (#4312) These getters are introduced as a more convenient substitute for a `require('puppeteer/Errors')` and `require('puppeteer/DeviceDescriptors')`. This way we can make cross-browser story nicer - a single require of `puppeteer` or `puppeteer-firefox` fully defines Puppeteer environment.
2019-04-19 22:33:06 +00:00
might fail if the selector doesn't match any nodes during the given timeframe.
For certain types of errors Puppeteer uses specific error classes.
These classes are available via [`puppeteer.errors`](#puppeteererrors)
An example of handling a timeout error:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(puppeteer): introduce `puppeteer.errors` and `puppeteer.devices` (#4312) These getters are introduced as a more convenient substitute for a `require('puppeteer/Errors')` and `require('puppeteer/DeviceDescriptors')`. This way we can make cross-browser story nicer - a single require of `puppeteer` or `puppeteer-firefox` fully defines Puppeteer environment.
2019-04-19 22:33:06 +00:00
```js
try {
await page.waitForSelector('.foo');
} catch (e) {
if (e instanceof puppeteer.errors.TimeoutError) {
// Do something if this is a timeout.
}
}
```
> **NOTE** The old way (Puppeteer versions <= v1.14.0) errors can be obtained with `require('puppeteer/Errors')`.
[api] add Puppeteer.executablePath() method (#771) This patch adds Puppeteer.executablePath() method to query the path of bundled chromium. Fixes #745
2017-09-14 00:39:18 +00:00
#### puppeteer.executablePath()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api): fix typo in environment variable name (#6918) `PUPPETEER_SKIP_DOWNLOAD ~ PUPPETEER_SKIP_CHROMIUM_DOWNLOAD`.
2021-02-23 12:36:30 +00:00
- returns: <[string]> A path where Puppeteer expects to find the bundled browser. The browser binary might not be there if the download was skipped with [`PUPPETEER_SKIP_CHROMIUM_DOWNLOAD`](#environment-variables).
[api] add Puppeteer.executablePath() method (#771) This patch adds Puppeteer.executablePath() method to query the path of bundled chromium. Fixes #745
2017-09-14 00:39:18 +00:00
docs(api.md): add note regarding puppeteer.executablePath() (#4092) References #4091
2019-03-14 18:32:44 +00:00
> **NOTE** `puppeteer.executablePath()` is affected by the `PUPPETEER_EXECUTABLE_PATH` and `PUPPETEER_CHROMIUM_REVISION` env variables. See [Environment Variables](#environment-variables) for details.
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])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields:
feat(launcher): add option to run Puppeteer with different browsers (#5137) * feat: Set which browser to launch via PUPPETEER_PRODUCT This change introduces a PUPPETEER_PRODUCT environment variable as a first step toward using Puppeteer with many different browsers. Setting PUPPETEER_PRODUCT=firefox, for example, enables Firefox-specific Launcher settings. The state is also exposed as `puppeteer.product` in the API to support adding other product-specific behaviour as needed. The bulk of the change is a refactoring in Launcher to decouple generic browser start-up from product-specific configuration. Respecting the puppeteer-core restriction for PUPPETEER_ environment variables, lazily instantiate the Launcher based on a `product` Puppeteer.launch option, if available. * test: Distinguish Juggler unit tests from Firefox The funit script is renamed to fjunit (j for Juggler, which is used only by the experimental puppeteer-firefox package. In contrast, the funit script now refers to running Puppeteer unit tests against the main puppeteer package with Firefox. To do so with Firefox Nightly, run: `BINARY=path/to/firefox npm run funit` A number of changes in this patch make it easier to run Puppeteer unit tests in Mozilla's CI.
2019-11-26 09:23:19 +00:00
- `product` <[string]> Which browser to launch. At this time, this is either `chrome` or `firefox`. See also `PUPPETEER_PRODUCT`.
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
- `ignoreHTTPSErrors` <[boolean]> Whether to ignore HTTPS errors during navigation. Defaults to `false`.
feat: support chrome headless mode (#8260) * feat: support chrome headless mode Co-authored-by: Ergün Erdoğmuş <erdogmusergun@gmail.com>
2022-04-25 11:11:23 +00:00
- `headless` <[boolean]|"chrome"> Whether to run browser in [headless mode](https://developers.google.com/web/updates/2017/04/headless-chrome). Defaults to `true` unless the `devtools` option is `true`. "chrome" is a new experimental headless mode (use at your own risk).
feat: add channel parameter for puppeteer.launch (#7389) This change adds a new `channel` parameter to `puppeteer.launch`. When specified, Puppeteer will search for the locally installed release channel of Google Chrome and use it to launch. Available values are `chrome`, `chrome-beta`, `chrome-canary`, `chrome-dev`. This parameter is mutually exclusive with `executablePath`.
2021-07-09 12:43:42 +00:00
- `channel` <[string]> When specified, Puppeteer will search for the locally installed release channel of Google Chrome and use it to launch. Available values are `chrome`, `chrome-beta`, `chrome-canary`, `chrome-dev`. When channel is specified, `executablePath` cannot be specified.
docs(api) Fix url (#5367) A little slash had been missing since https://github.com/puppeteer/puppeteer/commit/eddb23b52175a3dad8cec4a5e9b3c13e58f6f144
2020-02-06 21:54:48 +00:00
- `executablePath` <[string]> Path to a browser executable to run instead of the bundled Chromium. If `executablePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). **BEWARE**: Puppeteer is only [guaranteed to work](https://github.com/puppeteer/puppeteer/#q-why-doesnt-puppeteer-vxxx-work-with-chromium-vyyy) with the bundled Chromium, use at your own risk.
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.
feat: add option to specify the default viewport (#3005) Fixes #1183.
2018-08-01 23:23:03 +00:00
- `defaultViewport` <?[Object]> Sets a consistent viewport for each page. Defaults to an 800x600 viewport. `null` disables the default viewport.
- `width` <[number]> page width in pixels.
- `height` <[number]> page height in pixels.
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
- `deviceScaleFactor` <[number]> Specify device scale factor (can be thought of as DPR). Defaults to `1`.
feat: add option to specify the default viewport (#3005) Fixes #1183.
2018-08-01 23:23:03 +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`.
docs: update firefox flags link (#7779) The original link <https://developer.mozilla.org/en-US/docs/Mozilla/Command_Line_Options> returns 'Page not found', I searched and guess the new available link should be <https://wiki.mozilla.org/Firefox/CommandLineOptions>
2022-02-15 12:29:11 +00:00
- `args` <[Array]<[string]>> Additional arguments to pass to the browser instance. The list of Chromium flags can be found [here](http://peter.sh/experiments/chromium-command-line-switches/), and here is the list of [Firefox flags](https://wiki.mozilla.org/Firefox/CommandLineOptions).
docs(api.md): fix defaultArgs link (#5126) Closes #5094.
2019-11-04 22:43:04 +00:00
- `ignoreDefaultArgs` <[boolean]|[Array]<[string]>> If `true`, then do not use [`puppeteer.defaultArgs()`](#puppeteerdefaultargsoptions). If an array is given, then filter out the given default arguments. Dangerous option; use with care. Defaults to `false`.
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- `handleSIGINT` <[boolean]> Close the browser process on Ctrl-C. Defaults to `true`.
- `handleSIGTERM` <[boolean]> Close the browser process on SIGTERM. Defaults to `true`.
- `handleSIGHUP` <[boolean]> Close the browser process on SIGHUP. Defaults to `true`.
docs(README.md): Update docs to more clearly differentiate between Chromium and Chrome (#1574) This patch clarifies the documentation to more clearly note that Puppeteer works with both Chromium (by default) and Chrome. Fixes #1516
2017-12-15 03:09:48 +00:00
- `timeout` <[number]> Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- `dumpio` <[boolean]> Whether to pipe the browser process stdout and stderr into `process.stdout` and `process.stderr`. Defaults to `false`.
chore: remove references to upstream `master` branches (#7412) Chromium had its branch renamed to `main`, and for other projects we can just point to the `HEAD`.
2021-09-14 15:02:39 +00:00
- `userDataDir` <[string]> Path to a [User Data Directory](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/docs/user_data_dir.md).
feat: add custom debugging port option (#4993)
2021-09-29 14:05:18 +00:00
- `debuggingPort` <[number]> Specify custom debugging port. Pass `0` to discover a random port. Defaults to `0`.
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- `env` <[Object]> Specify environment variables that will be visible to the browser. Defaults to `process.env`.
- `devtools` <[boolean]> Whether to auto-open a DevTools panel for each tab. If this option is `true`, the `headless` option will be set `false`.
feat(Launcher): introduce `pipe` option (#2288) This patch introduces a new `pipe` option to the launcher to connect over a pipe. In certain environments, exposing web socket for remote debugging is a security risk. Pipe connection eliminates this risk.
2018-04-03 22:05:27 +00:00
- `pipe` <[boolean]> Connects to the browser over a pipe instead of a WebSocket. Defaults to `false`.
fix: update firefox prefs documentation link (#7539)
2021-09-10 18:59:43 +00:00
- `extraPrefsFirefox` <[Object]> Additional [preferences](https://searchfox.org/mozilla-release/source/modules/libpref/init/all.js) that can be passed to Firefox (see `PUPPETEER_PRODUCT`)
fix: make targetFilter synchronous (#7203)
2021-05-05 07:50:50 +00:00
- `targetFilter` <?[function]\([Protocol.Target.TargetInfo]\):[boolean]> Use this function to decide if Puppeteer should connect to the given target. If a `targetFilter` is provided, Puppeteer only connects to targets for which `targetFilter` returns `true`. By default, Puppeteer connects to all available targets.
feat(launcher): add new launcher option `waitForInitialPage` (#7105) The existing behavior is expected to be unchanged as the value defaults to true. Adding such option would allow user to skip the initial wait. Issue: #3630
2021-05-06 20:30:04 +00:00
- `waitForInitialPage` <[boolean]> Whether to wait for the initial page to be ready. Defaults to `true`.
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.
feat(puppeteer): support convenience env variables (#3190) We had (and still have) a ton of pull requests to support PUPPETEER_EXECUTABLE_PATH and PUPPETEER_CHROMIUM_REVISION in puppeteer launcher. We were hesitant before since env variables are not scoped and thus don't make a good interface for a library. Now, since we determined `puppeteer-core` as a library and `puppeteer` as our end-user product, it's safe to satisfy our user needs. This patch: - teaches PUPPETEER_EXECUTABLE_PATH and PUPPETEER_CHROMIUM_REVISION env variables to control how Puppeteer launches browser - makes sure these variables play no role in `puppeteer-core` package.
2018-09-05 21:59:14 +00:00
You can use `ignoreDefaultArgs` to filter out `--mute-audio` from default arguments:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(launcher): ignoreDefaultArgs to accept array of options (#3049) If `ignoreDefaultArgs` is given an array of options, than these options will be excluded from the default command-line flags.
2018-08-09 02:10:10 +00:00
```js
const browser = await puppeteer.launch({
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
ignoreDefaultArgs: ['--mute-audio'],
feat(launcher): ignoreDefaultArgs to accept array of options (#3049) If `ignoreDefaultArgs` is given an array of options, than these options will be excluded from the default command-line flags.
2018-08-09 02:10:10 +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
feat: add channel parameter for puppeteer.launch (#7389) This change adds a new `channel` parameter to `puppeteer.launch`. When specified, Puppeteer will search for the locally installed release channel of Google Chrome and use it to launch. Available values are `chrome`, `chrome-beta`, `chrome-canary`, `chrome-dev`. This parameter is mutually exclusive with `executablePath`.
2021-07-09 12:43:42 +00:00
> **NOTE** Puppeteer can also be used to control the Chrome browser, but it works best with the version of Chromium it is bundled with. There is no guarantee it will work with any other version. Use `executablePath` or `channel` option with extreme caution.
chore: Spelling and Markdown Consistency (#1998) - Adding missing language tags to markdown code blocks. - Fixed various spelling mistakes my IDE complained to me about.
2018-02-09 03:59:46 +00:00
>
> If Google Chrome (rather than Chromium) is preferred, a [Chrome Canary](https://www.google.com/chrome/browser/canary.html) or [Dev Channel](https://www.chromium.org/getting-involved/dev-channel) build is suggested.
docs(README.md): Update docs to more clearly differentiate between Chromium and Chrome (#1574) This patch clarifies the documentation to more clearly note that Puppeteer works with both Chromium (by default) and Chrome. Fixes #1516
2017-12-15 03:09:48 +00:00
>
> In [puppeteer.launch([options])](#puppeteerlaunchoptions) above, any mention of Chromium also applies to Chrome.
>
docs(api.md): Working link to Linux differences (#4232) A link on line 525 is pointing to a undefined branch (`lkcr`) in `chromium.googlesource.com/chromium/src/`. Change it to point to `lkgr` instead, since it's the closest defined branch in name.
2019-04-03 02:15:20 +00:00
> See [`this article`](https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/) for a description of the differences between Chromium and Chrome. [`This article`](https://chromium.googlesource.com/chromium/src/+/lkgr/docs/chromium_browser_vs_google_chrome.md) describes some differences for Linux users.
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
feat: add page.emulateNetworkConditions (#6759)
2021-01-21 09:00:57 +00:00
#### puppeteer.networkConditions
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: add page.emulateNetworkConditions (#6759)
2021-01-21 09:00:57 +00:00
- returns: <[Object]>
Returns a list of network conditions to be used with [`page.emulateNetworkConditions(networkConditions)`](#pageemulatenetworkconditionsnetworkconditions). Actual list of
conditions can be found in [`src/common/NetworkConditions.ts`](https://github.com/puppeteer/puppeteer/blob/main/src/common/NetworkConditions.ts).
```js
const puppeteer = require('puppeteer');
const slow3G = puppeteer.networkConditions['Slow 3G'];
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.emulateNetworkConditions(slow3G);
await page.goto('https://www.google.com');
// other actions...
await browser.close();
})();
```
feat(launcher): add option to run Puppeteer with different browsers (#5137) * feat: Set which browser to launch via PUPPETEER_PRODUCT This change introduces a PUPPETEER_PRODUCT environment variable as a first step toward using Puppeteer with many different browsers. Setting PUPPETEER_PRODUCT=firefox, for example, enables Firefox-specific Launcher settings. The state is also exposed as `puppeteer.product` in the API to support adding other product-specific behaviour as needed. The bulk of the change is a refactoring in Launcher to decouple generic browser start-up from product-specific configuration. Respecting the puppeteer-core restriction for PUPPETEER_ environment variables, lazily instantiate the Launcher based on a `product` Puppeteer.launch option, if available. * test: Distinguish Juggler unit tests from Firefox The funit script is renamed to fjunit (j for Juggler, which is used only by the experimental puppeteer-firefox package. In contrast, the funit script now refers to running Puppeteer unit tests against the main puppeteer package with Firefox. To do so with Firefox Nightly, run: `BINARY=path/to/firefox npm run funit` A number of changes in this patch make it easier to run Puppeteer unit tests in Mozilla's CI.
2019-11-26 09:23:19 +00:00
#### puppeteer.product
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
(feat) Add option to fetch Firefox Nightly (#5467) * (feat) Add option to fetch Firefox Nightly Add Firefox support to BrowserFetcher and the install script. By default, the latest Firefox Nightly is downloaded directly from archive.mozilla.org (dmg, tar.bz2 and zip) This also required changes that impact `puppeteer.launch()` and `puppeteer.executablePath()` Fixes #5151 * Update docs/api.md Co-Authored-By: Mathias Bynens <mathias@qiwi.be> * Clean up revision promise * Improve error handling in revision check * Remove matchAll * Use explicit octal mode * Update .gitignore Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2020-03-10 20:59:03 +00:00
- returns: <[string]> returns the name of the browser that is under automation (`"chrome"` or `"firefox"`)
feat(launcher): add option to run Puppeteer with different browsers (#5137) * feat: Set which browser to launch via PUPPETEER_PRODUCT This change introduces a PUPPETEER_PRODUCT environment variable as a first step toward using Puppeteer with many different browsers. Setting PUPPETEER_PRODUCT=firefox, for example, enables Firefox-specific Launcher settings. The state is also exposed as `puppeteer.product` in the API to support adding other product-specific behaviour as needed. The bulk of the change is a refactoring in Launcher to decouple generic browser start-up from product-specific configuration. Respecting the puppeteer-core restriction for PUPPETEER_ environment variables, lazily instantiate the Launcher based on a `product` Puppeteer.launch option, if available. * test: Distinguish Juggler unit tests from Firefox The funit script is renamed to fjunit (j for Juggler, which is used only by the experimental puppeteer-firefox package. In contrast, the funit script now refers to running Puppeteer unit tests against the main puppeteer package with Firefox. To do so with Firefox Nightly, run: `BINARY=path/to/firefox npm run funit` A number of changes in this patch make it easier to run Puppeteer unit tests in Mozilla's CI.
2019-11-26 09:23:19 +00:00
docs: better describe how to install Firefox Nightly with Puppeteer (#6226) Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2020-07-16 12:28:09 +00:00
The product is set by the `PUPPETEER_PRODUCT` environment variable or the `product` option in [puppeteer.launch([options])](#puppeteerlaunchoptions) and defaults to `chrome`. Firefox support is experimental and requires to install Puppeteer via `PUPPETEER_PRODUCT=firefox npm i puppeteer`.
feat(launcher): add option to run Puppeteer with different browsers (#5137) * feat: Set which browser to launch via PUPPETEER_PRODUCT This change introduces a PUPPETEER_PRODUCT environment variable as a first step toward using Puppeteer with many different browsers. Setting PUPPETEER_PRODUCT=firefox, for example, enables Firefox-specific Launcher settings. The state is also exposed as `puppeteer.product` in the API to support adding other product-specific behaviour as needed. The bulk of the change is a refactoring in Launcher to decouple generic browser start-up from product-specific configuration. Respecting the puppeteer-core restriction for PUPPETEER_ environment variables, lazily instantiate the Launcher based on a `product` Puppeteer.launch option, if available. * test: Distinguish Juggler unit tests from Firefox The funit script is renamed to fjunit (j for Juggler, which is used only by the experimental puppeteer-firefox package. In contrast, the funit script now refers to running Puppeteer unit tests against the main puppeteer package with Firefox. To do so with Firefox Nightly, run: `BINARY=path/to/firefox npm run funit` A number of changes in this patch make it easier to run Puppeteer unit tests in Mozilla's CI.
2019-11-26 09:23:19 +00:00
chore: mark version v5.4.0 (#6542)
2020-10-23 14:28:38 +00:00
#### puppeteer.registerCustomQueryHandler(name, queryHandler)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore: mark version v5.4.0 (#6542)
2020-10-23 14:28:38 +00:00
- `name` <[string]> The name that the custom query handler will be registered under.
- `queryHandler` <[CustomQueryHandler]> The [custom query handler](#interface-customqueryhandler) to register.
docs: improve custom query handler docs (#8235)
2022-04-19 12:48:22 +00:00
Registers a [custom query handler](#interface-customqueryhandler).
docs(api): expand registerCustomQueryHandler example (#6557) This patch makes it easier to see exactly how to use the registerCustomQueryHandler API without having to follow the trail of breadcrumbs throughout the docs.
2020-10-29 14:22:03 +00:00
chore: mark version v5.4.0 (#6542)
2020-10-23 14:28:38 +00:00
Example:
docs(api): expand registerCustomQueryHandler example (#6557) This patch makes it easier to see exactly how to use the registerCustomQueryHandler API without having to follow the trail of breadcrumbs throughout the docs.
2020-10-29 14:22:03 +00:00
```js
puppeteer.registerCustomQueryHandler('getByClass', {
queryOne: (element, selector) => {
return element.querySelector(`.${selector}`);
},
queryAll: (element, selector) => {
return element.querySelectorAll(`.${selector}`);
},
});
const aHandle = await page.$('getByClass/…');
chore: mark version v5.4.0 (#6542)
2020-10-23 14:28:38 +00:00
```
#### puppeteer.unregisterCustomQueryHandler(name)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api): expand registerCustomQueryHandler example (#6557) This patch makes it easier to see exactly how to use the registerCustomQueryHandler API without having to follow the trail of breadcrumbs throughout the docs.
2020-10-29 14:22:03 +00:00
- `name` <[string]> The name of the query handler to unregister.
feat(launcher): add option to run Puppeteer with different browsers (#5137) * feat: Set which browser to launch via PUPPETEER_PRODUCT This change introduces a PUPPETEER_PRODUCT environment variable as a first step toward using Puppeteer with many different browsers. Setting PUPPETEER_PRODUCT=firefox, for example, enables Firefox-specific Launcher settings. The state is also exposed as `puppeteer.product` in the API to support adding other product-specific behaviour as needed. The bulk of the change is a refactoring in Launcher to decouple generic browser start-up from product-specific configuration. Respecting the puppeteer-core restriction for PUPPETEER_ environment variables, lazily instantiate the Launcher based on a `product` Puppeteer.launch option, if available. * test: Distinguish Juggler unit tests from Firefox The funit script is renamed to fjunit (j for Juggler, which is used only by the experimental puppeteer-firefox package. In contrast, the funit script now refers to running Puppeteer unit tests against the main puppeteer package with Firefox. To do so with Firefox Nightly, run: `BINARY=path/to/firefox npm run funit` A number of changes in this patch make it easier to run Puppeteer unit tests in Mozilla's CI.
2019-11-26 09:23:19 +00:00
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
### class: BrowserFetcher
(feat) Add option to fetch Firefox Nightly (#5467) * (feat) Add option to fetch Firefox Nightly Add Firefox support to BrowserFetcher and the install script. By default, the latest Firefox Nightly is downloaded directly from archive.mozilla.org (dmg, tar.bz2 and zip) This also required changes that impact `puppeteer.launch()` and `puppeteer.executablePath()` Fixes #5151 * Update docs/api.md Co-Authored-By: Mathias Bynens <mathias@qiwi.be> * Clean up revision promise * Improve error handling in revision check * Remove matchAll * Use explicit octal mode * Update .gitignore Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2020-03-10 20:59:03 +00:00
BrowserFetcher can download and manage different versions of Chromium and Firefox.
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
BrowserFetcher operates on revision strings that specify a precise version of Chromium, e.g. `"533271"`. Revision strings can be obtained from [omahaproxy.appspot.com](http://omahaproxy.appspot.com/).
(feat) Add option to fetch Firefox Nightly (#5467) * (feat) Add option to fetch Firefox Nightly Add Firefox support to BrowserFetcher and the install script. By default, the latest Firefox Nightly is downloaded directly from archive.mozilla.org (dmg, tar.bz2 and zip) This also required changes that impact `puppeteer.launch()` and `puppeteer.executablePath()` Fixes #5151 * Update docs/api.md Co-Authored-By: Mathias Bynens <mathias@qiwi.be> * Clean up revision promise * Improve error handling in revision check * Remove matchAll * Use explicit octal mode * Update .gitignore Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2020-03-10 20:59:03 +00:00
In the Firefox case, BrowserFetcher downloads Firefox Nightly and operates on version numbers such as `"75"`.
docs(api.md): some grammar/wording (#3057)
2018-08-10 00:49:06 +00:00
An example of using BrowserFetcher to download a specific version of Chromium and running
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
Puppeteer against it:
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
```js
const browserFetcher = puppeteer.createBrowserFetcher();
const revisionInfo = await browserFetcher.download('533271');
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
const browser = await puppeteer.launch({
executablePath: revisionInfo.executablePath,
});
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
```
> **NOTE** BrowserFetcher is not designed to work concurrently with other
> instances of BrowserFetcher that share the same downloads directory.
#### browserFetcher.canDownload(revision)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
- `revision` <[string]> a revision to check availability.
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- returns: <[Promise]<[boolean]>> returns `true` if the revision could be downloaded from the host.
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
The method initiates a HEAD request to check if the revision is available.
#### browserFetcher.download(revision[, progressCallback])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
- `revision` <[string]> a revision to download.
- `progressCallback` <[function]([number], [number])> A function that will be called with two arguments:
- `downloadedBytes` <[number]> how many bytes have been downloaded
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
- `totalBytes` <[number]> how large is the total download
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
- returns: <[Promise]<[Object]>> Resolves with revision information when the revision is downloaded and extracted
- `revision` <[string]> the revision the info was created from
- `folderPath` <[string]> path to the extracted revision folder
- `executablePath` <[string]> path to the revision executable
- `url` <[string]> URL this revision can be downloaded from
- `local` <[boolean]> whether the revision is locally available on disk
The method initiates a GET request to download the revision from the host.
(feat) Add option to fetch Firefox Nightly (#5467) * (feat) Add option to fetch Firefox Nightly Add Firefox support to BrowserFetcher and the install script. By default, the latest Firefox Nightly is downloaded directly from archive.mozilla.org (dmg, tar.bz2 and zip) This also required changes that impact `puppeteer.launch()` and `puppeteer.executablePath()` Fixes #5151 * Update docs/api.md Co-Authored-By: Mathias Bynens <mathias@qiwi.be> * Clean up revision promise * Improve error handling in revision check * Remove matchAll * Use explicit octal mode * Update .gitignore Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2020-03-10 20:59:03 +00:00
#### browserFetcher.host()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
(feat) Add option to fetch Firefox Nightly (#5467) * (feat) Add option to fetch Firefox Nightly Add Firefox support to BrowserFetcher and the install script. By default, the latest Firefox Nightly is downloaded directly from archive.mozilla.org (dmg, tar.bz2 and zip) This also required changes that impact `puppeteer.launch()` and `puppeteer.executablePath()` Fixes #5151 * Update docs/api.md Co-Authored-By: Mathias Bynens <mathias@qiwi.be> * Clean up revision promise * Improve error handling in revision check * Remove matchAll * Use explicit octal mode * Update .gitignore Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2020-03-10 20:59:03 +00:00
- returns: <[string]> The download host being used.
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
#### browserFetcher.localRevisions()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
(feat) Add option to fetch Firefox Nightly (#5467) * (feat) Add option to fetch Firefox Nightly Add Firefox support to BrowserFetcher and the install script. By default, the latest Firefox Nightly is downloaded directly from archive.mozilla.org (dmg, tar.bz2 and zip) This also required changes that impact `puppeteer.launch()` and `puppeteer.executablePath()` Fixes #5151 * Update docs/api.md Co-Authored-By: Mathias Bynens <mathias@qiwi.be> * Clean up revision promise * Improve error handling in revision check * Remove matchAll * Use explicit octal mode * Update .gitignore Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2020-03-10 20:59:03 +00:00
- returns: <[Promise]<[Array]<[string]>>> A list of all revisions (for the current `product`) available locally on disk.
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
#### browserFetcher.platform()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore(types): generate our own d.ts file from api.md (#3744) Generate `//index.d.ts` file with precise typescript definitions for all of the Puppeteer API.
2019-01-28 23:12:45 +00:00
- returns: <[string]> One of `mac`, `linux`, `win32` or `win64`.
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
(feat) Add option to fetch Firefox Nightly (#5467) * (feat) Add option to fetch Firefox Nightly Add Firefox support to BrowserFetcher and the install script. By default, the latest Firefox Nightly is downloaded directly from archive.mozilla.org (dmg, tar.bz2 and zip) This also required changes that impact `puppeteer.launch()` and `puppeteer.executablePath()` Fixes #5151 * Update docs/api.md Co-Authored-By: Mathias Bynens <mathias@qiwi.be> * Clean up revision promise * Improve error handling in revision check * Remove matchAll * Use explicit octal mode * Update .gitignore Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2020-03-10 20:59:03 +00:00
#### browserFetcher.product()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
(feat) Add option to fetch Firefox Nightly (#5467) * (feat) Add option to fetch Firefox Nightly Add Firefox support to BrowserFetcher and the install script. By default, the latest Firefox Nightly is downloaded directly from archive.mozilla.org (dmg, tar.bz2 and zip) This also required changes that impact `puppeteer.launch()` and `puppeteer.executablePath()` Fixes #5151 * Update docs/api.md Co-Authored-By: Mathias Bynens <mathias@qiwi.be> * Clean up revision promise * Improve error handling in revision check * Remove matchAll * Use explicit octal mode * Update .gitignore Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2020-03-10 20:59:03 +00:00
- returns: <[string]> One of `chrome` or `firefox`.
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
#### browserFetcher.remove(revision)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
(feat) Add option to fetch Firefox Nightly (#5467) * (feat) Add option to fetch Firefox Nightly Add Firefox support to BrowserFetcher and the install script. By default, the latest Firefox Nightly is downloaded directly from archive.mozilla.org (dmg, tar.bz2 and zip) This also required changes that impact `puppeteer.launch()` and `puppeteer.executablePath()` Fixes #5151 * Update docs/api.md Co-Authored-By: Mathias Bynens <mathias@qiwi.be> * Clean up revision promise * Improve error handling in revision check * Remove matchAll * Use explicit octal mode * Update .gitignore Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2020-03-10 20:59:03 +00:00
- `revision` <[string]> a revision to remove for the current `product`. The method will throw if the revision has not been downloaded.
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
- returns: <[Promise]> Resolves when the revision has been removed.
#### browserFetcher.revisionInfo(revision)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: Introduce BrowserFetcher class (#1983) This patch introduces `BrowserFetcher` class that manages downloaded versions of products. This patch: - shapes Downloader API to be minimal yet usable for our needs. This includes removing such methods as `Downloader.supportedPlatforms` and `Downloader.defaultRevision`. - makes most of the fs-related methods in Downloader async. The only exception is the `Downloader.revisionInfo`: it has stay sync due to the `pptr.executablePath()` method being sync. - updates `install.js` and `utils/check_availability.js` to use new API - finally, renames `Downloader` into `BrowserFetcher` Fixes #1748.
2018-02-07 17:31:53 +00:00
- `revision` <[string]> a revision to get info for.
- returns: <[Object]>
- `revision` <[string]> the revision the info was created from
- `folderPath` <[string]> path to the extracted revision folder
- `executablePath` <[string]> path to the revision executable
- `url` <[string]> URL this revision can be downloaded from
- `local` <[boolean]> whether the revision is locally available on disk
(feat) Add option to fetch Firefox Nightly (#5467) * (feat) Add option to fetch Firefox Nightly Add Firefox support to BrowserFetcher and the install script. By default, the latest Firefox Nightly is downloaded directly from archive.mozilla.org (dmg, tar.bz2 and zip) This also required changes that impact `puppeteer.launch()` and `puppeteer.executablePath()` Fixes #5151 * Update docs/api.md Co-Authored-By: Mathias Bynens <mathias@qiwi.be> * Clean up revision promise * Improve error handling in revision check * Remove matchAll * Use explicit octal mode * Update .gitignore Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2020-03-10 20:59:03 +00:00
- `product` <[string]> one of `chrome` or `firefox`
> **NOTE** Many BrowserFetcher methods, like `remove` and `revisionInfo`
> are affected by the choice of `product`. See [puppeteer.createBrowserFetcher([options])](#puppeteercreatebrowserfetcheroptions).
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
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- extends: [EventEmitter](#class-eventemitter)
docs(api.md): Note that Browser and Page extend from EventEmitter (#1541) Adds notes to the API documentation that Browser and Page classes are EventEmitters. Provides an example of using `.once` for Page. Fixes #1231
2017-12-06 07:53:27 +00:00
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]:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
```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');
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
(async () => {
const browser = await puppeteer.launch();
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const page = await browser.newPage();
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
await page.goto('https://example.com');
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
})();
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
```
Add docs/api.md This patch adds docs/api.md file which contains API description for the puppeteer API. This patch adds the API outline, which doesn't not have explanations and samples.
2017-06-13 07:28:29 +00:00
feat(Browser): make browser.close() to always terminate remote browser This patch: - changes `browser.close` to terminate browser. - introduces new `browser.disconnect` to disconnect from a browser without closing it This patch: fixes #918, fixes #989 BREAKING CHANGE: `browser.close()` will always close a browser, even if it was initialized with `puppeteer.connect`. To disconnect from a remote browser, use `browser.disconnect()` instead.
2017-10-17 22:35:00 +00:00
An example of disconnecting from and reconnecting to a [Browser]:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Browser): make browser.close() to always terminate remote browser This patch: - changes `browser.close` to terminate browser. - introduces new `browser.disconnect` to disconnect from a browser without closing it This patch: fixes #918, fixes #989 BREAKING CHANGE: `browser.close()` will always close a browser, even if it was initialized with `puppeteer.connect`. To disconnect from a remote browser, use `browser.disconnect()` instead.
2017-10-17 22:35:00 +00:00
```js
const puppeteer = require('puppeteer');
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
(async () => {
const browser = await puppeteer.launch();
feat(Browser): make browser.close() to always terminate remote browser This patch: - changes `browser.close` to terminate browser. - introduces new `browser.disconnect` to disconnect from a browser without closing it This patch: fixes #918, fixes #989 BREAKING CHANGE: `browser.close()` will always close a browser, even if it was initialized with `puppeteer.connect`. To disconnect from a remote browser, use `browser.disconnect()` instead.
2017-10-17 22:35:00 +00:00
// Store the endpoint to be able to reconnect to Chromium
const browserWSEndpoint = browser.wsEndpoint();
// Disconnect puppeteer from Chromium
browser.disconnect();
// Use the endpoint to reestablish a connection
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
const browser2 = await puppeteer.connect({browserWSEndpoint});
feat(Browser): make browser.close() to always terminate remote browser This patch: - changes `browser.close` to terminate browser. - introduces new `browser.disconnect` to disconnect from a browser without closing it This patch: fixes #918, fixes #989 BREAKING CHANGE: `browser.close()` will always close a browser, even if it was initialized with `puppeteer.connect`. To disconnect from a remote browser, use `browser.disconnect()` instead.
2017-10-17 22:35:00 +00:00
// Close Chromium
await browser2.close();
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
})();
feat(Browser): make browser.close() to always terminate remote browser This patch: - changes `browser.close` to terminate browser. - introduces new `browser.disconnect` to disconnect from a browser without closing it This patch: fixes #918, fixes #989 BREAKING CHANGE: `browser.close()` will always close a browser, even if it was initialized with `puppeteer.connect`. To disconnect from a remote browser, use `browser.disconnect()` instead.
2017-10-17 22:35:00 +00:00
```
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(browser): add browser.disconnected event (#960) This patch adds a 'disconnected' event for the browser. The event is issued when the "browser" loses connection to the chrome process. References #952
2017-11-04 01:46:17 +00:00
#### event: 'disconnected'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
Emitted when Puppeteer gets disconnected from the Chromium instance. This might happen because of one of the following:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs: update api.md This patch clarifies when the "disconnected" event is emitted and emphasizes the difference between Chromium and browser. References #1589.
2018-01-04 10:27:57 +00:00
- Chromium is closed or crashed
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- The [`browser.disconnect`](#browserdisconnect) method was called
feat(Browser): make browser.close() to always terminate remote browser This patch: - changes `browser.close` to terminate browser. - introduces new `browser.disconnect` to disconnect from a browser without closing it This patch: fixes #918, fixes #989 BREAKING CHANGE: `browser.close()` will always close a browser, even if it was initialized with `puppeteer.connect`. To disconnect from a remote browser, use `browser.disconnect()` instead.
2017-10-17 22:35:00 +00:00
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
#### event: 'targetchanged'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
- <[Target]>
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
Emitted when the URL of a target changes.
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
> **NOTE** This includes target changes in incognito browser contexts.
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
#### event: 'targetcreated'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
- <[Target]>
Emitted when a target is created, for example when a new page is opened by [`window.open`](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) or [`browser.newPage`](#browsernewpage).
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
> **NOTE** This includes target creations in incognito browser contexts.
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
#### event: 'targetdestroyed'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
- <[Target]>
Emitted when a target is destroyed, for example when a page is closed.
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
> **NOTE** This includes target destructions in incognito browser contexts.
#### browser.browserContexts()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
- returns: <[Array]<[BrowserContext]>>
Returns an array of all open browser contexts. In a newly created browser, this will return
a single instance of [BrowserContext].
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
#### browser.close()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
[api] Launcher: Close gracefully when a userDataDir is specified (#700) This patch: - makes `browser.close()` return a promise that resolves when browser gets closed - starts closing chrome gracefully if a custom `userDataDir` is supplied Fixes #527
2017-09-14 04:27:14 +00:00
- returns: <[Promise]>
Add docs/api.md This patch adds docs/api.md file which contains API description for the puppeteer API. This patch adds the API outline, which doesn't not have explanations and samples.
2017-06-13 07:28:29 +00:00
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
Closes Chromium and all of its pages (if any were opened). The [Browser] object itself is considered to be disposed and cannot be used anymore.
feat(Browser): make browser.close() to always terminate remote browser This patch: - changes `browser.close` to terminate browser. - introduces new `browser.disconnect` to disconnect from a browser without closing it This patch: fixes #918, fixes #989 BREAKING CHANGE: `browser.close()` will always close a browser, even if it was initialized with `puppeteer.connect`. To disconnect from a remote browser, use `browser.disconnect()` instead.
2017-10-17 22:35:00 +00:00
fix(browser-runner): reject promise on error (#7338) This patch adds a reject callback to the _processClosing promise and executes it if it catches an error on removeFolderAsync(...). Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-07-30 07:32:53 +00:00
During the process of closing the browser, Puppeteer attempts to delete the temp folder created exclusively for this browser instance. If this fails (either because a file in the temp folder is locked by another process or because of insufficient permissions) an error is logged. This implies that: a) the folder and/or its content is not fully deleted; and b) the connection with the browser is not properly disposed (see [browser.disconnect()](#browserdisconnect)).
feat: add proxy and bypass list parameters to createIncognitoBrowserContext (#7516) Example: (async () => { const browser = await puppeteer.launch(); const context = await browser.createIncognitoBrowserContext('myproxy.com:3128'); const page = await context.newPage() await page.authenticate({username: 'foo', password: 'bar' }); await page.goto('https://google.com'); await browser.close(); })(); Issue: #678
2021-09-18 09:56:05 +00:00
#### browser.createIncognitoBrowserContext([options])
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
feat: add proxy and bypass list parameters to createIncognitoBrowserContext (#7516) Example: (async () => { const browser = await puppeteer.launch(); const context = await browser.createIncognitoBrowserContext('myproxy.com:3128'); const page = await context.newPage() await page.authenticate({username: 'foo', password: 'bar' }); await page.goto('https://google.com'); await browser.close(); })(); Issue: #678
2021-09-18 09:56:05 +00:00
- `options` <[Object]> Set of configurable options to set on the browserContext. Can have the following fields:
- `proxyServer` <[string]> Optional proxy server with optional port to use for all requests. Username and password can be set in [page.authenticate(credentials)](#pageauthenticatecredentials).
- `proxyBypassList` <[string]> Optional: Bypass the proxy for the given semi-colon-separated list of hosts.
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
- returns: <[Promise]<[BrowserContext]>>
Creates a new incognito browser context. This won't share cookies/cache with other browser contexts.
```js
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
(async () => {
const browser = await puppeteer.launch();
// Create a new incognito browser context.
const context = await browser.createIncognitoBrowserContext();
// Create a new page in a pristine context.
const page = await context.newPage();
// Do stuff
await page.goto('https://example.com');
})();
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
```
feat(browsercontext): implement BrowserContext.overridePermissions (#3159) Introduce an API to manage permissions per browser context: - BrowserContext.overridePermissions(origin, permissions) - BrowserContext.clearPermissionOverrides() Fixes #846.
2018-08-30 22:36:09 +00:00
#### browser.defaultBrowserContext()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(browsercontext): implement BrowserContext.overridePermissions (#3159) Introduce an API to manage permissions per browser context: - BrowserContext.overridePermissions(origin, permissions) - BrowserContext.clearPermissionOverrides() Fixes #846.
2018-08-30 22:36:09 +00:00
- returns: <[BrowserContext]>
Returns the default browser context. The default browser context can not be closed.
feat(Browser): make browser.close() to always terminate remote browser This patch: - changes `browser.close` to terminate browser. - introduces new `browser.disconnect` to disconnect from a browser without closing it This patch: fixes #918, fixes #989 BREAKING CHANGE: `browser.close()` will always close a browser, even if it was initialized with `puppeteer.connect`. To disconnect from a remote browser, use `browser.disconnect()` instead.
2017-10-17 22:35:00 +00:00
#### browser.disconnect()
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
Disconnects Puppeteer from the browser but leaves the Chromium process running. After calling `disconnect`, the [Browser] object is considered disposed and cannot be used anymore.
Add docs/api.md This patch adds docs/api.md file which contains API description for the puppeteer API. This patch adds the API outline, which doesn't not have explanations and samples.
2017-06-13 07:28:29 +00:00
feat(browser): Add browser.isConnected() (#4403) Add `browser.isConnected()` to the public api to be able to tell when the browser is connected fixes https://github.com/smooth-code/jest-puppeteer/pull/237#issuecomment-490260041
2019-05-09 23:24:52 +00:00
#### browser.isConnected()
- returns: <[boolean]>
Indicates that the browser is connected.
[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()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
- returns: <[Promise]<[Page]>>
Promise which resolves to a new [Page] object. The [Page] is created in a default browser context.
Add docs/api.md This patch adds docs/api.md file which contains API description for the puppeteer API. This patch adds the API outline, which doesn't not have explanations and samples.
2017-06-13 07:28:29 +00:00
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
#### browser.pages()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(target): add support for target.page for 'backgroud_page' (#2600) This patch teaches `target.page()` method to attach to extension background pages. Fixes #2438
2018-06-14 20:58:51 +00:00
- returns: <[Promise]<[Array]<[Page]>>> Promise which resolves to an array of all open pages. Non visible pages, such as `"background_page"`, will not be listed here. You can find them using [target.page()](#targetpage).
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
feat(browsercontext): add BrowserContext.pages() method (#3003)
2018-07-31 20:24:29 +00:00
An array of all pages inside the Browser. In case of multiple browser contexts,
the method will return an array with all the pages in all browser contexts.
feat(Browser): introduce browser.process() variable (#1581) This patch adds a `browser.process()` getter to expose the child process with running browser. Fixes #1539.
2017-12-11 20:11:12 +00:00
#### browser.process()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- returns: <?[ChildProcess]> Spawned browser process. Returns `null` if the browser instance was created with [`puppeteer.connect`](#puppeteerconnectoptions) method.
feat(Browser): introduce browser.process() variable (#1581) This patch adds a `browser.process()` getter to expose the child process with running browser. Fixes #1539.
2017-12-11 20:11:12 +00:00
feat(launcher): add experimental "transport" option to pptr.connect (#3265) This patch: - adds experimental "transport" option to pptr.connect - uses "transport" option to make sure Puppeteer-Web works with Target.exposeDevToolsProtocol Drive-by: add `browser.target()` to access browser target.
2018-09-20 18:55:23 +00:00
#### browser.target()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(launcher): add experimental "transport" option to pptr.connect (#3265) This patch: - adds experimental "transport" option to pptr.connect - uses "transport" option to make sure Puppeteer-Web works with Target.exposeDevToolsProtocol Drive-by: add `browser.target()` to access browser target.
2018-09-20 18:55:23 +00:00
- returns: <[Target]>
A target associated with the browser.
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
#### browser.targets()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
- returns: <[Array]<[Target]>>
An array of all active targets inside the Browser. In case of multiple browser contexts,
the method will return an array with all the targets in all browser contexts.
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
feat: introduce browser.userAgent() (#1716) The patch introduces browser.userAgent() method to retrieve default browser user agent. Fixes #1706.
2018-01-05 18:14:30 +00:00
#### browser.userAgent()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: introduce browser.userAgent() (#1716) The patch introduces browser.userAgent() method to retrieve default browser user agent. Fixes #1706.
2018-01-05 18:14:30 +00:00
- returns: <[Promise]<[string]>> Promise which resolves to the browser's original user agent.
docs: heading ID references in docs/api.md (#7974) - `Worker` -> `WebWorker`, `#class-worker` -> `#class-webworker` - `#pagesetuseragentuseragent-useragentdata` -> `#pagesetuseragentuseragent-useragentmetadata` - `####WaitTimeoutOptions` -> `#waittimeoutoptions` - `#cooperative-intercept-mode-and-legacy-intercept-mode` -> `#cooperative-intercept-mode` Co-authored-by: jrandolf <86539915+jrandolf@users.noreply.github.com>
2022-02-11 13:43:52 +00:00
> **NOTE** Pages can override browser user agent with [page.setUserAgent](#pagesetuseragentuseragent-useragentmetadata)
feat: introduce browser.userAgent() (#1716) The patch introduces browser.userAgent() method to retrieve default browser user agent. Fixes #1706.
2018-01-05 18:14:30 +00:00
[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()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
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
feat: browser.waitForTarget (#3356) This adds `browser.waitForTarget` and `browserContext.waitForTarget`. It also fixes a flaky test that was incorrectly expecting targets to appear instantly.
2018-10-09 21:16:53 +00:00
#### browser.waitForTarget(predicate[, options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: add support for async waitForTarget (#7885) * feat: add support for async waitForTarget * fix: add timeout * fix: potential async bugs
2022-02-18 11:05:29 +00:00
- `predicate` <[function]\([Target]\):[boolean]|[Promise<boolean>]> A function to be run for every target
feat: browser.waitForTarget (#3356) This adds `browser.waitForTarget` and `browserContext.waitForTarget`. It also fixes a flaky test that was incorrectly expecting targets to appear instantly.
2018-10-09 21:16:53 +00:00
- `options` <[Object]>
- `timeout` <[number]> Maximum wait time in milliseconds. Pass `0` to disable the timeout. Defaults to 30 seconds.
- returns: <[Promise]<[Target]>> Promise which resolves to the first target found that matches the `predicate` function.
This searches for a target in all browser contexts.
An example of finding a target for a page opened via `window.open`:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: browser.waitForTarget (#3356) This adds `browser.waitForTarget` and `browserContext.waitForTarget`. It also fixes a flaky test that was incorrectly expecting targets to appear instantly.
2018-10-09 21:16:53 +00:00
```js
await page.evaluate(() => window.open('https://www.example.com/'));
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
const newWindowTarget = await browser.waitForTarget(
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
target => target.url() === 'https://www.example.com/'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
);
feat: browser.waitForTarget (#3356) This adds `browser.waitForTarget` and `browserContext.waitForTarget`. It also fixes a flaky test that was incorrectly expecting targets to appear instantly.
2018-10-09 21:16:53 +00:00
```
Rename 'remoteDebuggingURL' into 'browserWSEndpoint' (#272)
2017-08-16 08:10:55 +00:00
#### browser.wsEndpoint()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
- returns: <[string]> Browser websocket URL.
Rename 'remoteDebuggingURL' into 'browserWSEndpoint' (#272)
2017-08-16 08:10:55 +00:00
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
Browser websocket endpoint which can be used as an argument to
chore(doc): fix browser.wsEndpoint() return value format (#898)
2017-09-29 21:59:19 +00:00
[puppeteer.connect](#puppeteerconnectoptions). The format is `ws://${host}:${port}/devtools/browser/<id>`
Added info on how to find the browserWSEndpoint (#780)
2017-09-26 14:04:09 +00:00
You can find the `webSocketDebuggerUrl` from `http://${host}:${port}/json/version`. Learn more about the [devtools protocol](https://chromedevtools.github.io/devtools-protocol) and the [browser endpoint](https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target).
Rename 'remoteDebuggingURL' into 'browserWSEndpoint' (#272)
2017-08-16 08:10:55 +00:00
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
### class: BrowserContext
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- extends: [EventEmitter](#class-eventemitter)
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
BrowserContexts provide a way to operate multiple independent browser sessions. When a browser is launched, it has
a single BrowserContext used by default. The method `browser.newPage()` creates a page in the default browser context.
If a page opens another page, e.g. with a `window.open` call, the popup will belong to the parent page's browser
context.
Puppeteer allows creation of "incognito" browser contexts with `browser.createIncognitoBrowserContext()` method.
"Incognito" browser contexts don't write any browsing data to disk.
```js
// Create a new incognito browser context
const context = await browser.createIncognitoBrowserContext();
// Create a new page inside context.
const page = await context.newPage();
// ... do stuff with page ...
await page.goto('https://example.com');
// Dispose context once it's no longer needed.
await context.close();
```
#### event: 'targetchanged'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
- <[Target]>
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
Emitted when the URL of a target inside the browser context changes.
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
#### event: 'targetcreated'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
- <[Target]>
Emitted when a new target is created inside the browser context, for example when a new page is opened by [`window.open`](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) or [`browserContext.newPage`](#browsercontextnewpage).
#### event: 'targetdestroyed'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
- <[Target]>
Emitted when a target inside the browser context is destroyed, for example when a page is closed.
#### browserContext.browser()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
- returns: <[Browser]>
The browser this browser context belongs to.
feat(browsercontext): implement BrowserContext.overridePermissions (#3159) Introduce an API to manage permissions per browser context: - BrowserContext.overridePermissions(origin, permissions) - BrowserContext.clearPermissionOverrides() Fixes #846.
2018-08-30 22:36:09 +00:00
#### browserContext.clearPermissionOverrides()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(browsercontext): implement BrowserContext.overridePermissions (#3159) Introduce an API to manage permissions per browser context: - BrowserContext.overridePermissions(origin, permissions) - BrowserContext.clearPermissionOverrides() Fixes #846.
2018-08-30 22:36:09 +00:00
- returns: <[Promise]>
Clears all permission overrides for the browser context.
```js
const context = browser.defaultBrowserContext();
context.overridePermissions('https://example.com', ['clipboard-read']);
// do stuff ..
context.clearPermissionOverrides();
```
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
#### browserContext.close()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
- returns: <[Promise]>
Closes the browser context. All the targets that belong to the browser context
will be closed.
> **NOTE** only incognito browser contexts can be closed.
#### browserContext.isIncognito()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
- returns: <[boolean]>
feat(Page): introduce workers (#2560) This adds `page.workers()`, and two events `workercreated` and `workerdestroyed`. It also forwards logs from a worker into the page `console` event. Only dedicated workers are supported for now, ServiceWorkers will probably work differently because they aren't necessarily associated with a single page. Fixes #2350.
2018-05-21 21:31:11 +00:00
Returns whether BrowserContext is incognito.
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
The default browser context is the only non-incognito browser context.
> **NOTE** the default browser context cannot be closed.
#### browserContext.newPage()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
- returns: <[Promise]<[Page]>>
Creates a new page in the browser context.
feat(browsercontext): implement BrowserContext.overridePermissions (#3159) Introduce an API to manage permissions per browser context: - BrowserContext.overridePermissions(origin, permissions) - BrowserContext.clearPermissionOverrides() Fixes #846.
2018-08-30 22:36:09 +00:00
#### browserContext.overridePermissions(origin, permissions)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(browsercontext): implement BrowserContext.overridePermissions (#3159) Introduce an API to manage permissions per browser context: - BrowserContext.overridePermissions(origin, permissions) - BrowserContext.clearPermissionOverrides() Fixes #846.
2018-08-30 22:36:09 +00:00
- `origin` <[string]> The [origin] to grant permissions to, e.g. "https://example.com".
- `permissions` <[Array]<[string]>> An array of permissions to grant. All permissions that are not listed here will be automatically denied. Permissions can be one of the following values:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- `'geolocation'`
- `'midi'`
- `'midi-sysex'` (system-exclusive midi)
- `'notifications'`
- `'push'`
- `'camera'`
- `'microphone'`
- `'background-sync'`
- `'ambient-light-sensor'`
- `'accelerometer'`
- `'gyroscope'`
- `'magnetometer'`
- `'accessibility-events'`
- `'clipboard-read'`
- `'clipboard-write'`
- `'payment-handler'`
feat: add durableStorage to allowed permissions (#5295)
2021-09-16 10:35:36 +00:00
- `'persistent-storage'`
feat(browsercontext): implement BrowserContext.overridePermissions (#3159) Introduce an API to manage permissions per browser context: - BrowserContext.overridePermissions(origin, permissions) - BrowserContext.clearPermissionOverrides() Fixes #846.
2018-08-30 22:36:09 +00:00
- returns: <[Promise]>
```js
const context = browser.defaultBrowserContext();
await context.overridePermissions('https://html5demos.com', ['geolocation']);
```
feat(browsercontext): add BrowserContext.pages() method (#3003)
2018-07-31 20:24:29 +00:00
#### browserContext.pages()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(browsercontext): add BrowserContext.pages() method (#3003)
2018-07-31 20:24:29 +00:00
- returns: <[Promise]<[Array]<[Page]>>> Promise which resolves to an array of all open pages. Non visible pages, such as `"background_page"`, will not be listed here. You can find them using [target.page()](#targetpage).
An array of all pages inside the browser context.
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
#### browserContext.targets()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
- returns: <[Array]<[Target]>>
An array of all active targets inside the browser context.
feat: browser.waitForTarget (#3356) This adds `browser.waitForTarget` and `browserContext.waitForTarget`. It also fixes a flaky test that was incorrectly expecting targets to appear instantly.
2018-10-09 21:16:53 +00:00
#### browserContext.waitForTarget(predicate[, options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: add support for async waitForTarget (#7885) * feat: add support for async waitForTarget * fix: add timeout * fix: potential async bugs
2022-02-18 11:05:29 +00:00
- `predicate` <[function]\([Target]\):[boolean]|[Promise<boolean>]> A function to be run for every target
feat: browser.waitForTarget (#3356) This adds `browser.waitForTarget` and `browserContext.waitForTarget`. It also fixes a flaky test that was incorrectly expecting targets to appear instantly.
2018-10-09 21:16:53 +00:00
- `options` <[Object]>
- `timeout` <[number]> Maximum wait time in milliseconds. Pass `0` to disable the timeout. Defaults to 30 seconds.
- returns: <[Promise]<[Target]>> Promise which resolves to the first target found that matches the `predicate` function.
This searches for a target in this specific browser context.
An example of finding a target for a page opened via `window.open`:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: browser.waitForTarget (#3356) This adds `browser.waitForTarget` and `browserContext.waitForTarget`. It also fixes a flaky test that was incorrectly expecting targets to appear instantly.
2018-10-09 21:16:53 +00:00
```js
await page.evaluate(() => window.open('https://www.example.com/'));
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
const newWindowTarget = await browserContext.waitForTarget(
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
target => target.url() === 'https://www.example.com/'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
);
feat: browser.waitForTarget (#3356) This adds `browser.waitForTarget` and `browserContext.waitForTarget`. It also fixes a flaky test that was incorrectly expecting targets to appear instantly.
2018-10-09 21:16:53 +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
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- extends: [EventEmitter](#class-eventemitter)
docs(api.md): Note that Browser and Page extend from EventEmitter (#1541) Adds notes to the API documentation that Browser and Page classes are EventEmitters. Provides an example of using `.once` for Page. Fixes #1231
2017-12-06 07:53:27 +00:00
docs(api.md): expand on testing Chrome Extensions (#2893) Fixes #2823
2018-07-19 02:33:51 +00:00
Page provides methods to interact with a single tab or [extension background page](https://developer.chrome.com/extensions/background_pages) 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:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
```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');
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
(async () => {
const browser = await puppeteer.launch();
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');
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
await page.screenshot({path: 'screenshot.png'});
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
})();
Add docs/api.md This patch adds docs/api.md file which contains API description for the puppeteer API. This patch adds the API outline, which doesn't not have explanations and samples.
2017-06-13 07:28:29 +00:00
```
chore: migrate away from Node's EventEmitter (#5979)
2020-06-15 10:52:19 +00:00
The Page class emits various events (described below) which can be handled using
any of the [`EventEmitter`](#class-eventemitter) methods, such as `on`, `once`
or `off`.
docs(api.md): Note that Browser and Page extend from EventEmitter (#1541) Adds notes to the API documentation that Browser and Page classes are EventEmitters. Provides an example of using `.once` for Page. Fixes #1231
2017-12-06 07:53:27 +00:00
This example logs a message for a single page `load` event:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api.md): Note that Browser and Page extend from EventEmitter (#1541) Adds notes to the API documentation that Browser and Page classes are EventEmitters. Provides an example of using `.once` for Page. Fixes #1231
2017-12-06 07:53:27 +00:00
```js
page.once('load', () => console.log('Page loaded!'));
```
chore: migrate away from Node's EventEmitter (#5979)
2020-06-15 10:52:19 +00:00
To unsubscribe from events use the `off` method:
docs(README): Add's page.removeListener to Page class examples (#2122) This patch adds `page.removeListener` to Page class examples
2018-03-13 16:25:25 +00:00
```js
function logRequest(interceptedRequest) {
console.log('A request was made:', interceptedRequest.url());
}
page.on('request', logRequest);
// Sometime later...
chore: migrate away from Node's EventEmitter (#5979)
2020-06-15 10:52:19 +00:00
page.off('request', logRequest);
docs(README): Add's page.removeListener to Page class examples (#2122) This patch adds `page.removeListener` to Page class examples
2018-03-13 16:25:25 +00:00
```
feat(Page): page 'close' event (#2232) This patch adds 'page.close' event. References #952.
2018-03-28 20:11:51 +00:00
#### event: 'close'
Emitted when the page closes.
Rename Page's 'consolemessage' event into 'console' This patch: - renames 'consolemessage' event into 'console' - improves on 'console' event documentation References #39.
2017-07-18 03:38:11 +00:00
#### event: 'console'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Console): Introduce ConsoleMessage type (#909) This patch introduces ConsoleMessage type and starts dispatching it for the 'console' event. BREAKING CHANGE: this breaks the api of the 'console' event. Fixes #744.
2017-09-29 18:27:22 +00:00
- <[ConsoleMessage]>
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`. Also emitted if the page throws an error or a warning.
Rename Page's 'consolemessage' event into 'console' This patch: - renames 'consolemessage' event into 'console' - improves on 'console' event documentation References #39.
2017-07-18 03:38:11 +00:00
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
The arguments passed into `console.log` appear as arguments on the event handler.
Rename Page's 'consolemessage' event into 'console' This patch: - renames 'consolemessage' event into 'console' - improves on 'console' event documentation References #39.
2017-07-18 03:38:11 +00:00
An example of handling `console` event:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
```js
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('console', msg => {
fix(Docs): fix Console example (#1961) Fixes #1874
2018-02-05 22:44:22 +00:00
for (let i = 0; i < msg.args().length; ++i)
console.log(`${i}: ${msg.args()[i]}`);
Rename Page's 'consolemessage' event into 'console' This patch: - renames 'consolemessage' event into 'console' - improves on 'console' event documentation References #39.
2017-07-18 03:38:11 +00:00
});
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.evaluate(() => console.log('hello', 5, {foo: 'bar'}));
Rename Page's 'consolemessage' event into 'console' This patch: - renames 'consolemessage' event into 'console' - improves on 'console' event documentation References #39.
2017-07-18 03:38:11 +00:00
```
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
#### event: 'dialog'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- <[Dialog]>
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Puppeteer can respond to the dialog via [Dialog]'s [accept](#dialogacceptprompttext) or [dismiss](#dialogdismiss) methods.
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
feat: add Page.Events.DOMContentLoaded (#1730) Fixes #1580
2018-01-17 07:22:44 +00:00
#### event: 'domcontentloaded'
Emitted when the JavaScript [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event is dispatched.
Emit 'error' event when page crashes (#266) This patch starts emitting 'error' event when page crashes. 'error' events have special treatment in node, so page crashes become observable for users. Fixes #262.
2017-08-15 18:13:05 +00:00
#### event: 'error'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- <[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'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- <[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'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- <[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'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- <[Frame]>
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
Emitted when a frame is navigated to a new URL.
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
#### event: 'load'
docs: fix typo in `event: 'load'` section (#325) fix `JavaScriot` to `JavaScript`
2017-08-17 06:27:19 +00:00
Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched.
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
feat(Page): Support Page.getMetrics and metrics event. (#939) Provides access to the current page performance metrics. Allows to push page metrics from the page JavaScript with console.timeStamp() Fixes #309
2017-10-10 21:50:38 +00:00
#### event: 'metrics'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Page): Support Page.getMetrics and metrics event. (#939) Provides access to the current page performance metrics. Allows to push page metrics from the page JavaScript with console.timeStamp() Fixes #309
2017-10-10 21:50:38 +00:00
- <[Object]>
- `title` <[string]> The title passed to `console.timeStamp`.
- `metrics` <[Object]> Object containing metrics as key/value pairs. The values
of metrics are of <[number]> type.
Emitted when the JavaScript code makes a call to `console.timeStamp`. For the list
feat(Page): rename Page.getMetrics into Page.metrics (#1240) BREAKING CHANGE: method page.getMetrics() got renamed into page.metrics().
2017-11-01 20:39:31 +00:00
of metrics see `page.metrics`.
feat(Page): Support Page.getMetrics and metrics event. (#939) Provides access to the current page performance metrics. Allows to push page metrics from the page JavaScript with console.timeStamp() Fixes #309
2017-10-10 21:50:38 +00:00
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
#### event: 'pageerror'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api.md): `page.error` event dispatchers error
2018-02-05 22:45:35 +00:00
- <[Error]> The exception message
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
Emitted when an uncaught exception happens within the page.
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
feat(page): introduce "Popup" event (#3661) This patch adds a new "popup" event for page. "Popup" event is fired whenever page opens another page with given opener.
2018-12-13 01:09:42 +00:00
#### event: 'popup'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(page): introduce "Popup" event (#3661) This patch adds a new "popup" event for page. "Popup" event is fired whenever page opens another page with given opener.
2018-12-13 01:09:42 +00:00
- <[Page]> Page corresponding to "popup" window
Emitted when the page opens a new tab or window.
```js
const [popup] = await Promise.all([
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
new Promise(resolve => page.once('popup', resolve)),
feat(page): introduce "Popup" event (#3661) This patch adds a new "popup" event for page. "Popup" event is fired whenever page opens another page with given opener.
2018-12-13 01:09:42 +00:00
page.click('a[target=_blank]'),
]);
```
```js
const [popup] = await Promise.all([
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
new Promise(resolve => page.once('popup', resolve)),
feat(page): introduce "Popup" event (#3661) This patch adds a new "popup" event for page. "Popup" event is fired whenever page opens another page with given opener.
2018-12-13 01:09:42 +00:00
page.evaluate(() => window.open('https://example.com')),
]);
```
[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'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore: update request and response references in docs (#5942) Missed some Request => HTTPRequest and Response => HTTPResponse renames when updating the docs.
2020-05-29 11:36:04 +00:00
- <[HTTPRequest]>
[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
docs(api): fix some typos (#6672)
2020-12-22 12:34:44 +00:00
Emitted when a page issues a request. The [HTTPRequest] object is read-only.
feat(Chromium): Roll chromium to r511134 (#1153) This roll includes: - crrev.com/510651 that changes request interception methods in protocol - s/Page.setRequestInterceptionEnabled/Page.setRequestInterception BREAKING CHANGE Page.setRequestInterceptionEnabled is renamed into Page.setRequestInterception.
2017-10-24 21:45:03 +00:00
In order to intercept and mutate requests, see `page.setRequestInterception`.
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
#### event: 'requestfailed'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore: update request and response references in docs (#5942) Missed some Request => HTTPRequest and Response => HTTPResponse renames when updating the docs.
2020-05-29 11:36:04 +00:00
- <[HTTPRequest]>
[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 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
docs(api.md): clarify on HTTP error responses (#4507)
2019-06-03 21:54:30 +00:00
> **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will complete with [`'requestfinished'`](#event-requestfinished) event and not with [`'requestfailed'`](#event-requestfailed).
[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'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore: update request and response references in docs (#5942) Missed some Request => HTTPRequest and Response => HTTPResponse renames when updating the docs.
2020-05-29 11:36:04 +00:00
- <[HTTPRequest]>
[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 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'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore: update request and response references in docs (#5942) Missed some Request => HTTPRequest and Response => HTTPResponse renames when updating the docs.
2020-05-29 11:36:04 +00:00
- <[HTTPResponse]>
[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
docs(api): fix some typos (#6672)
2020-12-22 12:34:44 +00:00
Emitted when a [HTTPResponse] 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
feat(Page): introduce workers (#2560) This adds `page.workers()`, and two events `workercreated` and `workerdestroyed`. It also forwards logs from a worker into the page `console` event. Only dedicated workers are supported for now, ServiceWorkers will probably work differently because they aren't necessarily associated with a single page. Fixes #2350.
2018-05-21 21:31:11 +00:00
#### event: 'workercreated'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api): fix some typos (#6672)
2020-12-22 12:34:44 +00:00
- <[WebWorker]>
feat(Page): introduce workers (#2560) This adds `page.workers()`, and two events `workercreated` and `workerdestroyed`. It also forwards logs from a worker into the page `console` event. Only dedicated workers are supported for now, ServiceWorkers will probably work differently because they aren't necessarily associated with a single page. Fixes #2350.
2018-05-21 21:31:11 +00:00
Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is spawned by the page.
#### event: 'workerdestroyed'
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api): fix some typos (#6672)
2020-12-22 12:34:44 +00:00
- <[WebWorker]>
feat(Page): introduce workers (#2560) This adds `page.workers()`, and two events `workercreated` and `workerdestroyed`. It also forwards logs from a worker into the page `console` event. Only dedicated workers are supported for now, ServiceWorkers will probably work differently because they aren't necessarily associated with a single page. Fixes #2350.
2018-05-21 21:31:11 +00:00
Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is terminated.
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)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- `selector` <[string]> A [selector] to query page for
docs(api.md): fix return signatures that contains null (#1364)
2017-11-15 18:53:17 +00:00
- returns: <[Promise]<?[ElementHandle]>>
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
docs(api.md): minor grammar and consistency fixes (#3320)
2018-10-02 20:38:41 +00:00
The method runs `document.querySelector` within the page. If no element matches the selector, the return value resolves 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)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- `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]>>>
docs(api.md): minor grammar and consistency fixes (#3320)
2018-10-02 20:38:41 +00:00
The method runs `document.querySelectorAll` within the page. If no elements match the selector, the return value resolves to `[]`.
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
Shortcut for [page.mainFrame().$$(selector)](#frameselector-1).
feat(Page): introduce Page.$$eval method (#1006) This patch adds a `Page.$$eval` method that runs `document.querySelectorAll` and passes resulting array to the page function. Fixes #625.
2017-10-11 06:23:14 +00:00
#### page.$$eval(selector, pageFunction[, ...args])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api.md): Fix selector description for pages & frames (#2841)
2018-07-05 00:01:40 +00:00
- `selector` <[string]> A [selector] to query page for
chore(types): generate our own d.ts file from api.md (#3744) Generate `//index.d.ts` file with precise typescript definitions for all of the Puppeteer API.
2019-01-28 23:12:45 +00:00
- `pageFunction` <[function]\([Array]<[Element]>\)> Function to be evaluated in browser context
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
feat(Page): introduce Page.$$eval method (#1006) This patch adds a `Page.$$eval` method that runs `document.querySelectorAll` and passes resulting array to the page function. Fixes #625.
2017-10-11 06:23:14 +00:00
- returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
docs(api.md): mention that page.$$eval and frame.$$eval return arrays (#2595) Docs about `page.$$eval` and `frame.$$eval` are not accurate and might be confusing. `document.querySelectorAll` returns `NodeList`, while `frame.$$eval` is actually doing `Array.from(querySelectorAll(selector))`, which actually returns an array. This makes things this possible: `await page.$$eval('div', divs => divs.map...)` This patch fixes docs to mention that $$eval is actually performing: `Array.from(querySelectorAll(selector))` Which will let the user understand that the element he receives is an array, and not a NodeList.
2018-05-26 00:28:13 +00:00
This method runs `Array.from(document.querySelectorAll(selector))` within the page and passes it as the first argument to `pageFunction`.
feat(Page): introduce Page.$$eval method (#1006) This patch adds a `Page.$$eval` method that runs `document.querySelectorAll` and passes resulting array to the page function. Fixes #625.
2017-10-11 06:23:14 +00:00
If `pageFunction` returns a [Promise], then `page.$$eval` would wait for the promise to resolve and return its value.
Examples:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Page): introduce Page.$$eval method (#1006) This patch adds a `Page.$$eval` method that runs `document.querySelectorAll` and passes resulting array to the page function. Fixes #625.
2017-10-11 06:23:14 +00:00
```js
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
const divCount = await page.$$eval('div', divs => divs.length);
docs(api): add example to page.$$eval (#5200) This makes it more clear that the callback receives an actual array of nodes instead of just a NodeList. Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2020-01-27 15:19:33 +00:00
```
```js
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
const options = await page.$$eval('div > span.options', options =>
options.map(option => option.textContent)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
);
feat(Page): introduce Page.$$eval method (#1006) This patch adds a `Page.$$eval` method that runs `document.querySelectorAll` and passes resulting array to the page function. Fixes #625.
2017-10-11 06:23:14 +00:00
```
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])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- `selector` <[string]> A [selector] to query page for
chore(types): generate our own d.ts file from api.md (#3744) Generate `//index.d.ts` file with precise typescript definitions for all of the Puppeteer API.
2019-01-28 23:12:45 +00:00
- `pageFunction` <[function]\([Element]\)> Function to be evaluated in browser context
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
Implement page.$eval (#638) This patch: - implements page.$eval and frame.$eval - drops elementHandle.attribute() method in favor of the page.$eval References #625
2017-08-31 22:38:01 +00:00
- returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
This method runs `document.querySelector` within the page and passes it as the first argument to `pageFunction`. If there's no element matching `selector`, the method throws an error.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
If `pageFunction` returns a [Promise], then `page.$eval` would wait for the promise to resolve and return its value.
Implement page.$eval (#638) This patch: - implements page.$eval and frame.$eval - drops elementHandle.attribute() method in favor of the page.$eval References #625
2017-08-31 22:38:01 +00:00
Examples:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
```js
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
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);
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
```
Shortcut for [page.mainFrame().$eval(selector, pageFunction)](#frameevalselector-pagefunction-args).
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
#### page.$x(expression)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
- `expression` <[string]> Expression to [evaluate](https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate).
- returns: <[Promise]<[Array]<[ElementHandle]>>>
docs(api): add info for .$x() methods (#6711) Possibly connected issue: https://github.com/puppeteer/puppeteer/issues/6710
2021-01-05 07:22:46 +00:00
The method evaluates the XPath expression relative to the page document as its context node. If there are no such elements, the method resolves to an empty array.
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
docs(api.md): fix some links (#2253)
2018-03-28 20:18:59 +00:00
Shortcut for [page.mainFrame().$x(expression)](#framexexpression)
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
feat(accessibility): snapshot the accessibility tree (#3470) This adds `page.accessibility.snapshot()`. It serializes and returns the accessibility tree for the page. By default, uninteresting nodes are filtered out of the snapshot. fixes #2033
2018-11-02 01:54:51 +00:00
#### page.accessibility
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(accessibility): snapshot the accessibility tree (#3470) This adds `page.accessibility.snapshot()`. It serializes and returns the accessibility tree for the page. By default, uninteresting nodes are filtered out of the snapshot. fixes #2033
2018-11-02 01:54:51 +00:00
- returns: <[Accessibility]>
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
#### page.addScriptTag(options)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
- `options` <[Object]>
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- `url` <[string]> URL of a script to be added.
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
- `path` <[string]> Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
- `content` <[string]> Raw JavaScript content to be injected into frame.
feat: add id option to addScriptTag (#5477)
2021-09-14 21:02:05 +00:00
- `type` <[string]> Script type. Use 'module' in order to load a Javascript ES6 module. See [script](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) for more details.
- `id` <[string]> id attribute to add to the script tag.
docs(api.md): fix return values of page.add*Tag() (#1269)
2017-11-03 16:32:17 +00:00
- returns: <[Promise]<[ElementHandle]>> which resolves to the added tag when the script's onload fires or when the script content was injected into frame.
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
Adds a `<script>` tag into the page with the desired URL or content.
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
Shortcut for [page.mainFrame().addScriptTag(options)](#frameaddscripttagoptions).
Add docs/api.md This patch adds docs/api.md file which contains API description for the puppeteer API. This patch adds the API outline, which doesn't not have explanations and samples.
2017-06-13 07:28:29 +00:00
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
#### page.addStyleTag(options)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
- `options` <[Object]>
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- `url` <[string]> URL of the `<link>` tag.
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
- `path` <[string]> Path to the CSS file to be injected into frame. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
- `content` <[string]> Raw CSS content to be injected into frame.
docs(api.md): fix return values of page.add*Tag() (#1269)
2017-11-03 16:32:17 +00:00
- returns: <[Promise]<[ElementHandle]>> which resolves to the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.
feat(Frame): Add `addStyleTag` API to frame - fixes #892 (#947) This patch adds `Page.addStyleTag` and `Frame.addStyleTag` methods to the API. Fixes #892.
2017-10-04 20:42:26 +00:00
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
Adds a `<link rel="stylesheet">` tag into the page with the desired URL or a `<style type="text/css">` tag with the content.
feat(Frame): Add `addStyleTag` API to frame - fixes #892 (#947) This patch adds `Page.addStyleTag` and `Frame.addStyleTag` methods to the API. Fixes #892.
2017-10-04 20:42:26 +00:00
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
Shortcut for [page.mainFrame().addStyleTag(options)](#frameaddstyletagoptions).
feat(Frame): Add `addStyleTag` API to frame - fixes #892 (#947) This patch adds `Page.addStyleTag` and `Frame.addStyleTag` methods to the API. Fixes #892.
2017-10-04 20:42:26 +00:00
[api] Implement page.authenticate method (#729) This patch implements `page.authenticate` which should cover all cases of HTTP authentication. Fixes #426.
2017-09-11 23:32:13 +00:00
#### page.authenticate(credentials)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api.md): fix return signatures that contains null (#1364)
2017-11-15 18:53:17 +00:00
- `credentials` <?[Object]>
[api] Implement page.authenticate method (#729) This patch implements `page.authenticate` which should cover all cases of HTTP authentication. Fixes #426.
2017-09-11 23:32:13 +00:00
- `username` <[string]>
- `password` <[string]>
- returns: <[Promise]>
docs(api.md): minor grammar and consistency fixes (#3320)
2018-10-02 20:38:41 +00:00
Provide credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).
[api] Implement page.authenticate method (#729) This patch implements `page.authenticate` which should cover all cases of HTTP authentication. Fixes #426.
2017-09-11 23:32:13 +00:00
To disable authentication, pass `null`.
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
feat(Page): introduce Page bringToFront method (#1252) This patch introduces Page.bringToFront method to activate tabs. Fixes #1244
2017-11-07 21:17:36 +00:00
#### page.bringToFront()
- returns: <[Promise]>
Brings page to front (activates tab).
Add `Page.browser()` method (#2387) Call page.browser() to get the browser instance associated with a page. Fixes #2275
2018-04-17 17:37:17 +00:00
#### page.browser()
- returns: <[Browser]>
Get the browser the page belongs to.
feat: introduce page.browserContext() (#3655)
2018-12-12 23:08:31 +00:00
#### page.browserContext()
- returns: <[BrowserContext]>
Get the browser context that the page belongs to.
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])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
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]>
feat: add `back` and `forward` mouse buttons (#8284)
2022-04-27 21:00:07 +00:00
- `button` <"left"|"right"|"middle"|"back"|"forward"> Defaults to `left`.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `clickCount` <[number]> defaults to 1. See [UIEvent.detail].
Add delay option to input methods (#171) Add delay option to input methods for the keyboard and mouse. Closes #156
2017-08-01 01:18:15 +00:00
- `delay` <[number]> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully clicked. The Promise will be rejected if there is no element matching `selector`.
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
doc: fix descriptions of certain page methods (#424) This patch fixes descriptions of: - page.click() - page.focus() - page.hover() Fixes #397
2017-08-20 23:03:14 +00:00
This method fetches an element with `selector`, scrolls it into view if needed, and then uses [page.mouse](#pagemouse) to click in the center of the element.
If there's no element matching `selector`, the method throws an error.
Fill doc with stubs for missing documentation methods. This patch fills doc with stubs so that the command `npm run doc` does not complain.
2017-07-07 17:34:35 +00:00
docs(api.md): fix minor spelling errors (#2314)
2018-04-05 20:08:28 +00:00
Bear in mind that if `click()` triggers a navigation event and there's a separate `page.waitForNavigation()` promise to be resolved, you may end up with a race condition that yields unexpected results. The correct pattern for click and wait for navigation is the following:
docs(api.md): added page.click + waitForNavigation example (#1792) Fixes #1421.
2018-01-12 19:41:26 +00:00
docs(api): fix lint in code snippets (#7012)
2021-03-22 06:12:55 +00:00
```js
docs(api.md): added page.click + waitForNavigation example (#1792) Fixes #1421.
2018-01-12 19:41:26 +00:00
const [response] = await Promise.all([
docs(api): fix coverage example and typo (#1854)
2018-01-19 05:19:13 +00:00
page.waitForNavigation(waitOptions),
page.click(selector, clickOptions),
docs(api.md): added page.click + waitForNavigation example (#1792) Fixes #1421.
2018-01-12 19:41:26 +00:00
]);
```
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
Shortcut for [page.mainFrame().click(selector[, options])](#frameclickselector-options).
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### page.close([options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Page): add option to run 'beforeunload' when closing the page (#2478) Today, `page.close()` method doesn't run page's beforeunload listeners. This way users can be sure that `page.close()` actually closes the page. This patch adds an optional `runBeforeUnload` option to the `page.close()` method that would run beforeunload listeners. Note: running beforeunload handlers might cancel page closing. Fixes #2386.
2018-05-02 22:51:45 +00:00
- `options` <[Object]>
- `runBeforeUnload` <[boolean]> Defaults to `false`. Whether to run the
[before unload](https://developer.mozilla.org/en-US/docs/Web/Events/beforeunload)
page handlers.
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
feat(Page): add option to run 'beforeunload' when closing the page (#2478) Today, `page.close()` method doesn't run page's beforeunload listeners. This way users can be sure that `page.close()` actually closes the page. This patch adds an optional `runBeforeUnload` option to the `page.close()` method that would run beforeunload listeners. Note: running beforeunload handlers might cancel page closing. Fixes #2386.
2018-05-02 22:51:45 +00:00
By default, `page.close()` **does not** run beforeunload handlers.
> **NOTE** if `runBeforeUnload` is passed as true, a `beforeunload` dialog might be summoned
> and should be handled manually via page's ['dialog'](#event-dialog) event.
Add Page.content() method. Fixes #406. (#419)
2017-08-21 16:02:30 +00:00
#### page.content()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
fix(types): fix return types where JSDoc and api.md disagree (#3512)
2018-11-08 06:48:43 +00:00
- returns: <[Promise]<[string]>>
Add Page.content() method. Fixes #406. (#419)
2017-08-21 16:02:30 +00:00
Gets the full HTML contents of the page, including the doctype.
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### page.cookies([...urls])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
Cookies (#314) Introduce cookies API. Fixes #53.
2017-08-24 19:21:46 +00:00
- `...urls` <...[string]>
- returns: <[Promise]<[Array]<[Object]>>>
- `name` <[string]>
- `value` <[string]>
- `domain` <[string]>
- `path` <[string]>
- `expires` <[number]> Unix time in seconds.
fix(types): fix parameters where they disagree with the api (#3525)
2018-11-12 20:59:21 +00:00
- `size` <[number]>
Cookies (#314) Introduce cookies API. Fixes #53.
2017-08-24 19:21:46 +00:00
- `httpOnly` <[boolean]>
- `secure` <[boolean]>
docs: add missing session cookie property to api.md (#1672) The session value is returned from the protocol, but not accepted as a cookie parameter. Fixes #980.
2017-12-28 02:58:57 +00:00
- `session` <[boolean]>
feat(chromium): roll Chromium to r654752 (#4358) This roll includes: - https://crrev.com/653809 - FrameLoader: ignore failing provisional loads entirely - https://crrev.com/654750 - DevTools: make sure Network.requestWillBeSent is emitted on time for sync xhrs The FrameLoader patch is the reason behind the test change. It's actually desirable to fail frame navigation if the frame detaches - and that's consistent with Firefox. Fixes #4337
2019-04-29 03:19:01 +00:00
- `sameSite` <"Strict"|"Lax"|"Extended"|"None">
Cookies (#314) Introduce cookies API. Fixes #53.
2017-08-24 19:21:46 +00:00
If no URLs are specified, this method returns cookies for the current page URL.
If URLs are specified, only cookies for those URLs are returned.
feat: Implement JavaScript Coverage (#1673) This patch introduces a new `page.coverage` namespace with two methods: - `page.coverage.startJSCoverage` to initiate JavaScript coverage recording - `page.coverage.stopJSCoverage` to stop JavaScript coverage and get results
2018-01-03 03:53:53 +00:00
#### page.coverage
- returns: <[Coverage]>
feat: add a streaming version for page.pdf Co-authored-by: Jan Scheffler <janscheffler@chromium.org>
2021-06-23 12:51:38 +00:00
#### page.createPDFStream([options])
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
feat: add a streaming version for page.pdf Co-authored-by: Jan Scheffler <janscheffler@chromium.org>
2021-06-23 12:51:38 +00:00
- `options` <[Object]> Options object which might have the following properties:
- `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.
- `scale` <[number]> Scale of the webpage rendering. Defaults to `1`. Scale amount must be between 0.1 and 2.
- `displayHeaderFooter` <[boolean]> Display header and footer. Defaults to `false`.
- `headerTemplate` <[string]> HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them:
- `date` formatted print date
- `title` document title
- `url` document location
- `pageNumber` current page number
- `totalPages` total pages in the document
- `footerTemplate` <[string]> HTML template for the print footer. Should use the same format as the `headerTemplate`.
- `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]|[number]> Paper width, accepts values labeled with units.
- `height` <[string]|[number]> Paper height, accepts values labeled with units.
- `margin` <[Object]> Paper margins, defaults to none.
- `top` <[string]|[number]> Top margin, accepts values labeled with units.
- `right` <[string]|[number]> Right margin, accepts values labeled with units.
- `bottom` <[string]|[number]> Bottom margin, accepts values labeled with units.
- `left` <[string]|[number]> Left margin, accepts values labeled with units.
- `preferCSSPageSize` <[boolean]> Give any CSS `@page` size declared in the page priority over what is declared in `width` and `height` or `format` options. Defaults to `false`, which will scale the content to fit the paper size.
- `omitBackground` <[boolean]> Hides default white background and allows capturing screenshots with transparency. Defaults to `false`.
- returns: <[Promise]<[Readable]>> Promise which resolves with a Node.js stream for the PDF file.
> **NOTE** This method is identical to [page.pdf](#pagepdfoptions), except it returns the PDF as a readable stream of binary data. If you are generating very large PDFs, it may be useful to use a stream to avoid high memory usage. This version will ignore the `path` option.
```js
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
// Stream a PDF into a file
const pdfStream = await page.createPDFStream();
const writeStream = fs.createWriteStream('test.pdf');
pdfStream.pipe(writeStream);
docs(api): correct `createPDFStream` example (#7538) Prior to this patch, the example results in `browser.close()` being executed before the file is generated/written to disk. One needs to listen for the `end` event on the `ReadableStream` before closing the browser, otherwise an exception is raised: UnhandledPromiseRejectionWarning: Error: Protocol error (IO.read): Target closed
2021-09-02 07:26:55 +00:00
pdfStream.on('end', async () => {
await browser.close();
});
feat: add a streaming version for page.pdf Co-authored-by: Jan Scheffler <janscheffler@chromium.org>
2021-06-23 12:51:38 +00:00
})();
```
Cookies (#314) Introduce cookies API. Fixes #53.
2017-08-24 19:21:46 +00:00
#### page.deleteCookie(...cookies)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
Cookies (#314) Introduce cookies API. Fixes #53.
2017-08-24 19:21:46 +00:00
- `...cookies` <...[Object]>
- `name` <[string]> **required**
- `url` <[string]>
- `domain` <[string]>
- `path` <[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
#### page.emulate(options)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
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
- `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.
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
- `deviceScaleFactor` <[number]> Specify device scale factor (can be thought of as DPR). Defaults to `1`.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `isMobile` <[boolean]> Whether the `meta viewport` tag is taken into account. Defaults to `false`.
- `hasTouch`<[boolean]> Specifies if viewport supports touch events. Defaults to `false`
- `isLandscape` <[boolean]> Specifies if viewport is in landscape mode. Defaults to `false`.
- `userAgent` <[string]>
- returns: <[Promise]>
Introduce page.emulate convenience wrapper (#231) This patch: - introduces Page.emulate convenience wrapper - adds a screenshot-fullPage.js example
2017-08-11 01:42:30 +00:00
Move emulation documentation under `page.emulate` method. (#253)
2017-08-13 07:47:01 +00:00
Emulates given device metrics and user agent. This method is a shortcut for calling two methods:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs: heading ID references in docs/api.md (#7974) - `Worker` -> `WebWorker`, `#class-worker` -> `#class-webworker` - `#pagesetuseragentuseragent-useragentdata` -> `#pagesetuseragentuseragent-useragentmetadata` - `####WaitTimeoutOptions` -> `#waittimeoutoptions` - `#cooperative-intercept-mode-and-legacy-intercept-mode` -> `#cooperative-intercept-mode` Co-authored-by: jrandolf <86539915+jrandolf@users.noreply.github.com>
2022-02-11 13:43:52 +00:00
- [page.setUserAgent(userAgent)](#pagesetuseragentuseragent-useragentmetadata)
Move emulation documentation under `page.emulate` method. (#253)
2017-08-13 07:47:01 +00:00
- [page.setViewport(viewport)](#pagesetviewportviewport)
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
To aid emulation, Puppeteer provides a list of device descriptors that can be obtained via the [`puppeteer.devices`](#puppeteerdevices).
docs(api.md): add notes on race condition in page.setViewport (#4319) Fixes #2755.
2019-06-11 01:07:24 +00:00
`page.emulate` will resize the page. A lot of websites don't expect phones to change size, so you should emulate before navigating to the page.
feat(puppeteer): introduce `puppeteer.errors` and `puppeteer.devices` (#4312) These getters are introduced as a more convenient substitute for a `require('puppeteer/Errors')` and `require('puppeteer/DeviceDescriptors')`. This way we can make cross-browser story nicer - a single require of `puppeteer` or `puppeteer-firefox` fully defines Puppeteer environment.
2019-04-19 22:33:06 +00:00
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');
feat(puppeteer): introduce `puppeteer.errors` and `puppeteer.devices` (#4312) These getters are introduced as a more convenient substitute for a `require('puppeteer/Errors')` and `require('puppeteer/DeviceDescriptors')`. This way we can make cross-browser story nicer - a single require of `puppeteer` or `puppeteer-firefox` fully defines Puppeteer environment.
2019-04-19 22:33:06 +00:00
const iPhone = puppeteer.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
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
(async () => {
const browser = await puppeteer.launch();
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const page = await browser.newPage();
Move emulation documentation under `page.emulate` method. (#253)
2017-08-13 07:47:01 +00:00
await page.emulate(iPhone);
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
await page.goto('https://www.google.com');
Move emulation documentation under `page.emulate` method. (#253)
2017-08-13 07:47:01 +00:00
// other actions...
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
})();
Move emulation documentation under `page.emulate` method. (#253)
2017-08-13 07:47:01 +00:00
```
docs: fix broken link to DeviceDescriptors.ts (#6076)
2020-06-23 04:56:31 +00:00
List of all available devices is available in the source code: [src/common/DeviceDescriptors.ts](https://github.com/puppeteer/puppeteer/blob/main/src/common/DeviceDescriptors.ts).
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
feat: add page.emulateCPUThrottling (#7343)
2021-06-22 11:43:11 +00:00
#### page.emulateCPUThrottling(factor)
- `factor` <?[number]> Factor at which the CPU will be throttled (2x, 2.5x. 3x, ...). Passing `null` disables cpu throttling.
- returns: <[Promise]>
> **NOTE** Real device CPU performance is impacted by many factors that are not trivial to emulate via the Chrome DevTools Protocol / Puppeteer. e.g core count, L1/L2 cache, thermal throttling impacting performance, architecture etc. Simulating CPU performance can be a good guideline, but ideally also verify any numbers you see on a real mobile device.
```js
const puppeteer = require('puppeteer');
const slow3G = puppeteer.networkConditions['Slow 3G'];
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.emulateCPUThrottling(2);
await page.goto('https://www.google.com');
// other actions...
await browser.close();
})();
```
feat(page): emulate idle state (#6410) * https://bugs.chromium.org/p/chromium/issues/detail?id=1090802 * added `page.emulateIdleState(...)` allowing emulate or remove emulation of the idle state; * added test `emulate idle` -> `remove emulation` -> `emulate idle` -> `remove emulation`; * added launch argument `--enable-blink-features=IdleDetection` to turn IdleDetection on.
2020-09-14 09:31:23 +00:00
#### page.emulateIdleState(overrides)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(page): emulate idle state (#6410) * https://bugs.chromium.org/p/chromium/issues/detail?id=1090802 * added `page.emulateIdleState(...)` allowing emulate or remove emulation of the idle state; * added test `emulate idle` -> `remove emulation` -> `emulate idle` -> `remove emulation`; * added launch argument `--enable-blink-features=IdleDetection` to turn IdleDetection on.
2020-09-14 09:31:23 +00:00
- `overrides` <?[Object]> If not set, clears emulation
- `isUserActive` <[boolean]> **required**
- `isScreenUnlocked` <[boolean]> **required**
- returns: <[Promise]>
feat(api): add page.emulateMedia{Type,Features} (#5012)
2019-10-23 11:55:00 +00:00
#### page.emulateMediaFeatures(features)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(api): add page.emulateMedia{Type,Features} (#5012)
2019-10-23 11:55:00 +00:00
- `features` <?[Array]<[Object]>> Given an array of media feature objects, emulates CSS media features on the page. Each media feature object must have the following properties:
feat(page): add color-gamut support to Page.emulateMediaFeatures (#6857) The change updates the validation function to allow color-gamut media features and updates the documentation. Issues: #6761
2021-02-11 13:59:50 +00:00
- `name` <[string]> The CSS media feature name. Supported names are `'prefers-colors-scheme'`, `'prefers-reduced-motion'`, and `'color-gamut'`.
feat(api): add page.emulateMedia{Type,Features} (#5012)
2019-10-23 11:55:00 +00:00
- `value` <[string]> The value for the given CSS media feature.
- returns: <[Promise]>
```js
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
await page.emulateMediaFeatures([
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
{name: 'prefers-color-scheme', value: 'dark'},
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
]);
docs(api.md): improve emulateMediaFeatures section (#5807)
2020-05-05 05:43:14 +00:00
await page.evaluate(() => matchMedia('(prefers-color-scheme: dark)').matches);
feat(api): add page.emulateMedia{Type,Features} (#5012)
2019-10-23 11:55:00 +00:00
// → true
docs(api.md): improve emulateMediaFeatures section (#5807)
2020-05-05 05:43:14 +00:00
await page.evaluate(() => matchMedia('(prefers-color-scheme: light)').matches);
feat(api): add page.emulateMedia{Type,Features} (#5012)
2019-10-23 11:55:00 +00:00
// → false
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
await page.emulateMediaFeatures([
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
{name: 'prefers-reduced-motion', value: 'reduce'},
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
]);
await page.evaluate(
() => matchMedia('(prefers-reduced-motion: reduce)').matches
);
feat(api): add page.emulateMedia{Type,Features} (#5012)
2019-10-23 11:55:00 +00:00
// → true
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
await page.evaluate(
() => matchMedia('(prefers-reduced-motion: no-preference)').matches
);
feat(api): add page.emulateMedia{Type,Features} (#5012)
2019-10-23 11:55:00 +00:00
// → false
await page.emulateMediaFeatures([
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
{name: 'prefers-color-scheme', value: 'dark'},
{name: 'prefers-reduced-motion', value: 'reduce'},
feat(api): add page.emulateMedia{Type,Features} (#5012)
2019-10-23 11:55:00 +00:00
]);
docs(api.md): improve emulateMediaFeatures section (#5807)
2020-05-05 05:43:14 +00:00
await page.evaluate(() => matchMedia('(prefers-color-scheme: dark)').matches);
feat(api): add page.emulateMedia{Type,Features} (#5012)
2019-10-23 11:55:00 +00:00
// → true
docs(api.md): improve emulateMediaFeatures section (#5807)
2020-05-05 05:43:14 +00:00
await page.evaluate(() => matchMedia('(prefers-color-scheme: light)').matches);
feat(api): add page.emulateMedia{Type,Features} (#5012)
2019-10-23 11:55:00 +00:00
// → false
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
await page.evaluate(
() => matchMedia('(prefers-reduced-motion: reduce)').matches
);
feat(api): add page.emulateMedia{Type,Features} (#5012)
2019-10-23 11:55:00 +00:00
// → true
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
await page.evaluate(
() => matchMedia('(prefers-reduced-motion: no-preference)').matches
);
feat(api): add page.emulateMedia{Type,Features} (#5012)
2019-10-23 11:55:00 +00:00
// → false
feat(page): add color-gamut support to Page.emulateMediaFeatures (#6857) The change updates the validation function to allow color-gamut media features and updates the documentation. Issues: #6761
2021-02-11 13:59:50 +00:00
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
await page.emulateMediaFeatures([{name: 'color-gamut', value: 'p3'}]);
feat(page): add color-gamut support to Page.emulateMediaFeatures (#6857) The change updates the validation function to allow color-gamut media features and updates the documentation. Issues: #6761
2021-02-11 13:59:50 +00:00
await page.evaluate(() => matchMedia('(color-gamut: srgb)').matches);
// → true
await page.evaluate(() => matchMedia('(color-gamut: p3)').matches);
// → true
await page.evaluate(() => matchMedia('(color-gamut: rec2020)').matches);
// → false
feat(api): add page.emulateMedia{Type,Features} (#5012)
2019-10-23 11:55:00 +00:00
```
#### page.emulateMediaType(type)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(api): add page.emulateMedia{Type,Features} (#5012)
2019-10-23 11:55:00 +00:00
- `type` <?[string]> Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`. Passing `null` disables CSS media emulation.
- returns: <[Promise]>
```js
docs(api.md): improve emulateMediaFeatures section (#5807)
2020-05-05 05:43:14 +00:00
await page.evaluate(() => matchMedia('screen').matches);
feat(api): add page.emulateMedia{Type,Features} (#5012)
2019-10-23 11:55:00 +00:00
// → true
docs(api.md): improve emulateMediaFeatures section (#5807)
2020-05-05 05:43:14 +00:00
await page.evaluate(() => matchMedia('print').matches);
// → false
feat(api): add page.emulateMedia{Type,Features} (#5012)
2019-10-23 11:55:00 +00:00
await page.emulateMediaType('print');
docs(api.md): improve emulateMediaFeatures section (#5807)
2020-05-05 05:43:14 +00:00
await page.evaluate(() => matchMedia('screen').matches);
feat(api): add page.emulateMedia{Type,Features} (#5012)
2019-10-23 11:55:00 +00:00
// → false
docs(api.md): improve emulateMediaFeatures section (#5807)
2020-05-05 05:43:14 +00:00
await page.evaluate(() => matchMedia('print').matches);
feat(api): add page.emulateMedia{Type,Features} (#5012)
2019-10-23 11:55:00 +00:00
// → true
await page.emulateMediaType(null);
docs(api.md): improve emulateMediaFeatures section (#5807)
2020-05-05 05:43:14 +00:00
await page.evaluate(() => matchMedia('screen').matches);
feat(api): add page.emulateMedia{Type,Features} (#5012)
2019-10-23 11:55:00 +00:00
// → true
docs(api.md): improve emulateMediaFeatures section (#5807)
2020-05-05 05:43:14 +00:00
await page.evaluate(() => matchMedia('print').matches);
// → false
feat(api): add page.emulateMedia{Type,Features} (#5012)
2019-10-23 11:55:00 +00:00
```
chore: fix version number (#6803)
2021-02-02 12:32:13 +00:00
#### page.emulateNetworkConditions(networkConditions)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: add page.emulateNetworkConditions (#6759)
2021-01-21 09:00:57 +00:00
- `networkConditions` <?[Object]> Passing `null` disables network condition emulation.
- `download` <[number]> Download speed (bytes/s), `-1` to disable
- `upload` <[number]> Upload speed (bytes/s), `-1` to disable
- `latency` <[number]> Latency (ms), `0` to disable
- returns: <[Promise]>
chore: update documentation (#7446) Reference `page.setOfflineMode` and `page.emulateNetworkConditions` from each other.
2021-07-30 08:41:42 +00:00
> **NOTE** This does not affect WebSockets and WebRTC PeerConnections (see https://crbug.com/563644). To set the page offline, you can use [page.setOfflineMode(enabled)](#pagesetofflinemodeenabled).
feat: add page.emulateNetworkConditions (#6759)
2021-01-21 09:00:57 +00:00
```js
const puppeteer = require('puppeteer');
const slow3G = puppeteer.networkConditions['Slow 3G'];
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.emulateNetworkConditions(slow3G);
await page.goto('https://www.google.com');
// other actions...
await browser.close();
})();
```
feat(api): add page.emulateTimezone(timezoneId) (#4949) This enables dynamically changing the timezone of the page.
2019-10-23 13:49:39 +00:00
#### page.emulateTimezone(timezoneId)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(api): add page.emulateTimezone(timezoneId) (#4949) This enables dynamically changing the timezone of the page.
2019-10-23 13:49:39 +00:00
- `timezoneId` <?[string]> Changes the timezone of the page. See [ICU’s `metaZones.txt`](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1) for a list of supported timezone IDs. Passing `null` disables timezone emulation.
- returns: <[Promise]>
feat(api): add page.emulateVisionDeficiency(type) (#5901) Design doc: https://goo.gle/devtools-cvd
2020-05-26 15:14:20 +00:00
#### page.emulateVisionDeficiency(type)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(api): add page.emulateVisionDeficiency(type) (#5901) Design doc: https://goo.gle/devtools-cvd
2020-05-26 15:14:20 +00:00
- `type` <?[string]> Simulates the given vision deficiency on the page. Supported vision deficiency types are `'achromatopsia'`, `'deuteranopia'`, `'protanopia'`, `'tritanopia'`, `'blurredVision'`, and `'none'`.
- returns: <[Promise]>
```js
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://v8.dev/blog/10-years');
await page.emulateVisionDeficiency('achromatopsia');
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
await page.screenshot({path: 'achromatopsia.png'});
feat(api): add page.emulateVisionDeficiency(type) (#5901) Design doc: https://goo.gle/devtools-cvd
2020-05-26 15:14:20 +00:00
await page.emulateVisionDeficiency('deuteranopia');
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
await page.screenshot({path: 'deuteranopia.png'});
feat(api): add page.emulateVisionDeficiency(type) (#5901) Design doc: https://goo.gle/devtools-cvd
2020-05-26 15:14:20 +00:00
await page.emulateVisionDeficiency('blurredVision');
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
await page.screenshot({path: 'blurred-vision.png'});
feat(api): add page.emulateVisionDeficiency(type) (#5901) Design doc: https://goo.gle/devtools-cvd
2020-05-26 15:14:20 +00:00
await browser.close();
})();
```
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### page.evaluate(pageFunction[, ...args])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `pageFunction` <[function]|[string]> Function to be evaluated in the page context
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
- returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
If the function passed to the `page.evaluate` returns a [Promise], then `page.evaluate` would wait for the promise to resolve and return its value.
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
feat(executioncontext): support bigints transferring (#4016) Refs: https://chromedevtools.github.io/devtools-protocol/tot/Runtime#type-UnserializableValue
2019-03-15 17:20:48 +00:00
If the function passed to the `page.evaluate` returns a non-[Serializable] value, then `page.evaluate` resolves to `undefined`. DevTools Protocol also supports transferring some additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals.
fix: return undefined when Page.evaluate encounters circular JSON (#983)
2017-10-09 19:30:05 +00:00
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
Passing arguments to `pageFunction`:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
```js
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
const result = await page.evaluate(x => {
docs(API): add more explicit examples for page.evaluate (#1711)
2018-01-10 07:05:52 +00:00
return Promise.resolve(8 * x);
}, 7);
[api] Teach page.evaluate to accept element handles as parameters (#725) This patch: - teaches `page.evaluate` to accept ElementHandles as parameters - removes `ElementHandle.evaluate` method since it's not needed any more References #382
2017-09-12 02:20:02 +00:00
console.log(result); // prints "56"
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
```
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
A string can also be passed in instead of a function:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
```js
console.log(await page.evaluate('1 + 2')); // prints "3"
docs(API): add more explicit examples for page.evaluate (#1711)
2018-01-10 07:05:52 +00:00
const x = 10;
console.log(await page.evaluate(`1 + ${x}`)); // prints "11"
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
```
Add docs/api.md This patch adds docs/api.md file which contains API description for the puppeteer API. This patch adds the API outline, which doesn't not have explanations and samples.
2017-06-13 07:28:29 +00:00
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
[ElementHandle] instances can be passed as arguments to the `page.evaluate`:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
[api] Teach page.evaluate to accept element handles as parameters (#725) This patch: - teaches `page.evaluate` to accept ElementHandles as parameters - removes `ElementHandle.evaluate` method since it's not needed any more References #382
2017-09-12 02:20:02 +00:00
```js
const bodyHandle = await page.$('body');
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
const html = await page.evaluate(body => body.innerHTML, bodyHandle);
[api] Teach page.evaluate to accept element handles as parameters (#725) This patch: - teaches `page.evaluate` to accept ElementHandles as parameters - removes `ElementHandle.evaluate` method since it's not needed any more References #382
2017-09-12 02:20:02 +00:00
await bodyHandle.dispose();
```
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
Shortcut for [page.mainFrame().evaluate(pageFunction, ...args)](#frameevaluatepagefunction-args).
Add docs/api.md This patch adds docs/api.md file which contains API description for the puppeteer API. This patch adds the API outline, which doesn't not have explanations and samples.
2017-06-13 07:28:29 +00:00
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### page.evaluateHandle(pageFunction[, ...args])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
- `pageFunction` <[function]|[string]> Function to be evaluated in the page context
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
feat(types): add (and fix) `evaluateHandle` types (#6130) This change started as a small change to pull types from DefinitelyTyped over to Puppeteer for the `evaluateHandle` function but instead ended up also fixing what looks to be a long standing issue with our existing documentation. `evaluateHandle` can in fact return an `ElementHandle` rather than a `JSHandle`. Note that `ElementHandle` extends `JSHandle` so whilst the docs are technically correct (all ElementHandles are JSHandles) it's confusing because JSHandles don't have methods like `click` on them, but ElementHandles do. if you return something that is an HTML element: ``` const button = page.evaluateHandle(() => document.querySelector('button')); // this is an ElementHandle, not a JSHandle ``` Therefore I've updated the original docs and added a large explanation to the TSDoc for `page.evaluateHandle`. In TypeScript land we'll assume the function will return a `JSHandle` but you can tell TS otherwise via the generic argument, which can only be `JSHandle` (the default) or `ElementHandle`: ``` const button = page.evaluateHandle<ElementHandle>(() => document.querySelector('button')); ```
2020-07-01 11:44:08 +00:00
- returns: <[Promise]<[JSHandle]|[ElementHandle]>> Promise which resolves to the return value of `pageFunction` as an in-page object.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
The only difference between `page.evaluate` and `page.evaluateHandle` is that `page.evaluateHandle` returns in-page object (JSHandle).
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
If the function passed to the `page.evaluateHandle` returns a [Promise], then `page.evaluateHandle` would wait for the promise to resolve and return its value.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
A string can also be passed in instead of a function:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
```js
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
const aHandle = await page.evaluateHandle('document'); // Handle for the 'document'
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
```
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
[JSHandle] instances can be passed as arguments to the `page.evaluateHandle`:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
```js
const aHandle = await page.evaluateHandle(() => document.body);
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
const resultHandle = await page.evaluateHandle(body => body.innerHTML, aHandle);
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
console.log(await resultHandle.jsonValue());
await resultHandle.dispose();
```
feat(types): add (and fix) `evaluateHandle` types (#6130) This change started as a small change to pull types from DefinitelyTyped over to Puppeteer for the `evaluateHandle` function but instead ended up also fixing what looks to be a long standing issue with our existing documentation. `evaluateHandle` can in fact return an `ElementHandle` rather than a `JSHandle`. Note that `ElementHandle` extends `JSHandle` so whilst the docs are technically correct (all ElementHandles are JSHandles) it's confusing because JSHandles don't have methods like `click` on them, but ElementHandles do. if you return something that is an HTML element: ``` const button = page.evaluateHandle(() => document.querySelector('button')); // this is an ElementHandle, not a JSHandle ``` Therefore I've updated the original docs and added a large explanation to the TSDoc for `page.evaluateHandle`. In TypeScript land we'll assume the function will return a `JSHandle` but you can tell TS otherwise via the generic argument, which can only be `JSHandle` (the default) or `ElementHandle`: ``` const button = page.evaluateHandle<ElementHandle>(() => document.querySelector('button')); ```
2020-07-01 11:44:08 +00:00
This function will return a [JSHandle] by default, however if your `pageFunction` returns an HTML element you will get back an `ElementHandle`:
```js
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
const button = await page.evaluateHandle(() =>
document.querySelector('button')
);
feat(types): add (and fix) `evaluateHandle` types (#6130) This change started as a small change to pull types from DefinitelyTyped over to Puppeteer for the `evaluateHandle` function but instead ended up also fixing what looks to be a long standing issue with our existing documentation. `evaluateHandle` can in fact return an `ElementHandle` rather than a `JSHandle`. Note that `ElementHandle` extends `JSHandle` so whilst the docs are technically correct (all ElementHandles are JSHandles) it's confusing because JSHandles don't have methods like `click` on them, but ElementHandles do. if you return something that is an HTML element: ``` const button = page.evaluateHandle(() => document.querySelector('button')); // this is an ElementHandle, not a JSHandle ``` Therefore I've updated the original docs and added a large explanation to the TSDoc for `page.evaluateHandle`. In TypeScript land we'll assume the function will return a `JSHandle` but you can tell TS otherwise via the generic argument, which can only be `JSHandle` (the default) or `ElementHandle`: ``` const button = page.evaluateHandle<ElementHandle>(() => document.querySelector('button')); ```
2020-07-01 11:44:08 +00:00
// button is an ElementHandle, so you can call methods such as click:
await button.click();
```
chore(doc): fix nits after JSHandles PR (#976)
2017-10-07 15:31:55 +00:00
Shortcut for [page.mainFrame().executionContext().evaluateHandle(pageFunction, ...args)](#executioncontextevaluatehandlepagefunction-args).
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### page.evaluateOnNewDocument(pageFunction[, ...args])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
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:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
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
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
The function is invoked after the document was created but before any of its scripts were run. This is useful to amend the JavaScript environment, e.g. to seed `Math.random`.
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
doc(api.md): add evaluateOnNewDocument examples (#1202) Fixes #1201.
2017-11-17 18:34:20 +00:00
An example of overriding the navigator.languages property before the page loads:
```js
// preload.js
// overwrite the `languages` property to use a custom getter
docs(api): fix lint in code snippets (#7012)
2021-03-22 06:12:55 +00:00
Object.defineProperty(navigator, 'languages', {
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
get: function () {
docs(api): fix lint in code snippets (#7012)
2021-03-22 06:12:55 +00:00
return ['en-US', 'en', 'bn'];
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
},
doc(api.md): add evaluateOnNewDocument examples (#1202) Fixes #1201.
2017-11-17 18:34:20 +00:00
});
// In your puppeteer script, assuming the preload.js file is in same folder of our script
const preloadFile = fs.readFileSync('./preload.js', 'utf8');
await page.evaluateOnNewDocument(preloadFile);
```
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
#### page.exposeFunction(name, puppeteerFunction)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `name` <[string]> Name of the function on the window object
fix(page): fallback to default in exposeFunction when using imported module (#6365)
2021-09-29 16:32:49 +00:00
- `puppeteerFunction` <[function]> Callback function which will be called in Puppeteer's context. Can also be a module with a default export.
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:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
```js
const puppeteer = require('puppeteer');
const crypto = require('crypto');
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
(async () => {
const browser = await puppeteer.launch();
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();
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('console', msg => console.log(msg.text()));
await page.exposeFunction('md5', text =>
Make prettier JS snippets (#377) * Make prettier JS snippets * Conform to CS (about curly brace) * Apply feedback
2017-08-18 23:46:10 +00:00
crypto.createHash('md5').update(text).digest('hex')
);
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
await page.evaluate(async () => {
// use window.md5 to compute hashes
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const myString = 'PUPPETEER';
const myHash = await window.md5(myString);
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
console.log(`md5 of ${myString} is ${myHash}`);
});
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
})();
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
```
An example of adding a `window.readfile` function into the page:
```js
const puppeteer = require('puppeteer');
const fs = require('fs');
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
(async () => {
const browser = await puppeteer.launch();
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();
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('console', msg => console.log(msg.text()));
await page.exposeFunction('readfile', async filePath => {
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
return new Promise((resolve, reject) => {
fs.readFile(filePath, 'utf8', (err, text) => {
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
if (err) reject(err);
else resolve(text);
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
});
});
});
await page.evaluate(async () => {
// use window.readfile to read contents of a file
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const content = await window.readfile('/etc/hosts');
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
console.log(content);
});
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
})();
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
```
[doclint] Fix bug in documentation linter This patch: - fixes a typo in documentation linter, which resulted in only certain method arguments being linted. - adds missing arguments to the documentation References #14.
2017-07-12 00:01:58 +00:00
#### page.focus(selector)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `selector` <[string]> A [selector] of an element to focus. If there are multiple elements satisfying the selector, the first will be focused.
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully focused. The promise will be rejected if there is no element matching `selector`.
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
doc: fix descriptions of certain page methods (#424) This patch fixes descriptions of: - page.click() - page.focus() - page.hover() Fixes #397
2017-08-20 23:03:14 +00:00
This method fetches an element with `selector` and focuses it.
If there's no element matching `selector`, the method throws an error.
Fill doc with stubs for missing documentation methods. This patch fills doc with stubs so that the command `npm run doc` does not complain.
2017-07-07 17:34:35 +00:00
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
Shortcut for [page.mainFrame().focus(selector)](#framefocusselector).
Fill doc with stubs for missing documentation methods. This patch fills doc with stubs so that the command `npm run doc` does not complain.
2017-07-07 17:34:35 +00:00
#### page.frames()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- 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
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### page.goBack([options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
Document all options objects wherever they are used (#139) This patch adds missing documentation for all the shortcut methods, such as `page.evaluate` or `page.waitForSelector`. closes #114
2017-07-26 04:01:05 +00:00
- `options` <[Object]> Navigation parameters which might have the following properties:
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultNavigationTimeout(timeout)](#pagesetdefaultnavigationtimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
chore: migrate src/LifecycleWatcher (#5734)
2020-04-27 09:03:33 +00:00
- `waitUntil` <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Array<PuppeteerLifeCycleMethod>> When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
Document all options objects wherever they are used (#139) This patch adds missing documentation for all the shortcut methods, such as `page.evaluate` or `page.waitForSelector`. closes #114
2017-07-26 04:01:05 +00:00
- `load` - consider navigation to be finished when the `load` event is fired.
feat(Page.goto): add a 'domcontentloaded' option to the Page.goto (#1145) This patch adds a new `domcontentloaded` option to a bunch of navigation methods: - Page.goto - Page.waitForNavigation - Page.goBack - Page.goForward - Page.reload Fixes #946.
2017-10-24 07:35:18 +00:00
- `domcontentloaded` - consider navigation to be finished when the `DOMContentLoaded` event is fired.
typo in api.md (#1216) more then -> more than
2017-10-31 18:30:29 +00:00
- `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.
- `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
chore: update request and response references in docs (#5942) Missed some Request => HTTPRequest and Response => HTTPResponse renames when updating the docs.
2020-05-29 11:36:04 +00:00
- returns: <[Promise]<?[HTTPResponse]>> 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
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
can not go back, resolves to `null`.
Introduce page.goBack/page.goForward (#93) This patch introduces page.goBack/page.goForward methods to navigate the page history. References #89.
2017-07-19 02:11:37 +00:00
Navigate to the previous page in history.
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### page.goForward([options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
Document all options objects wherever they are used (#139) This patch adds missing documentation for all the shortcut methods, such as `page.evaluate` or `page.waitForSelector`. closes #114
2017-07-26 04:01:05 +00:00
- `options` <[Object]> Navigation parameters which might have the following properties:
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultNavigationTimeout(timeout)](#pagesetdefaultnavigationtimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
chore: migrate src/LifecycleWatcher (#5734)
2020-04-27 09:03:33 +00:00
- `waitUntil` <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Array<PuppeteerLifeCycleMethod>> When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
Document all options objects wherever they are used (#139) This patch adds missing documentation for all the shortcut methods, such as `page.evaluate` or `page.waitForSelector`. closes #114
2017-07-26 04:01:05 +00:00
- `load` - consider navigation to be finished when the `load` event is fired.
feat(Page.goto): add a 'domcontentloaded' option to the Page.goto (#1145) This patch adds a new `domcontentloaded` option to a bunch of navigation methods: - Page.goto - Page.waitForNavigation - Page.goBack - Page.goForward - Page.reload Fixes #946.
2017-10-24 07:35:18 +00:00
- `domcontentloaded` - consider navigation to be finished when the `DOMContentLoaded` event is fired.
typo in api.md (#1216) more then -> more than
2017-10-31 18:30:29 +00:00
- `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.
- `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
chore: update request and response references in docs (#5942) Missed some Request => HTTPRequest and Response => HTTPResponse renames when updating the docs.
2020-05-29 11:36:04 +00:00
- returns: <[Promise]<?[HTTPResponse]>> 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
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
can not go forward, resolves to `null`.
Introduce page.goBack/page.goForward (#93) This patch introduces page.goBack/page.goForward methods to navigate the page history. References #89.
2017-07-19 02:11:37 +00:00
Navigate to the next page in history.
Add docs/api.md This patch adds docs/api.md file which contains API description for the puppeteer API. This patch adds the API outline, which doesn't not have explanations and samples.
2017-06-13 07:28:29 +00:00
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### page.goto(url[, options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
- `url` <[string]> URL to navigate page to. The URL should include scheme, e.g. `https://`.
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
- `options` <[Object]> Navigation parameters which might have the following properties:
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultNavigationTimeout(timeout)](#pagesetdefaultnavigationtimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
chore: migrate src/LifecycleWatcher (#5734)
2020-04-27 09:03:33 +00:00
- `waitUntil` <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Array<PuppeteerLifeCycleMethod>> When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
- `load` - consider navigation to be finished when the `load` event is fired.
feat(Page.goto): add a 'domcontentloaded' option to the Page.goto (#1145) This patch adds a new `domcontentloaded` option to a bunch of navigation methods: - Page.goto - Page.waitForNavigation - Page.goBack - Page.goForward - Page.reload Fixes #946.
2017-10-24 07:35:18 +00:00
- `domcontentloaded` - consider navigation to be finished when the `DOMContentLoaded` event is fired.
typo in api.md (#1216) more then -> more than
2017-10-31 18:30:29 +00:00
- `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.
- `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
docs(api.md): small typo (#3188)
2018-09-04 15:34:44 +00:00
- `referer` <[string]> Referer header value. If provided it will take preference over the referer header value set by [page.setExtraHTTPHeaders()](#pagesetextrahttpheadersheaders).
chore: update request and response references in docs (#5942) Missed some Request => HTTPRequest and Response => HTTPResponse renames when updating the docs.
2020-05-29 11:36:04 +00:00
- returns: <[Promise]<?[HTTPResponse]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
docs(api.md): clarify frame/page.goto()'s handling of HTTP error statuses (#4553) The documentation for frame.goto() and page.goto() were updated to make it clear that the method will not throw an error if the HTTP requests results in any valid HTTP status code being returned by the remote server.
2019-06-10 01:32:06 +00:00
`page.goto` will throw an error if:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
- there's an SSL error (e.g. in case of self-signed certificates).
- target URL is invalid.
- the `timeout` is exceeded during navigation.
docs(api.md): clarify frame/page.goto()'s handling of HTTP error statuses (#4553) The documentation for frame.goto() and page.goto() were updated to make it clear that the method will not throw an error if the HTTP requests results in any valid HTTP status code being returned by the remote server.
2019-06-10 01:32:06 +00:00
- the remote server does not respond or is unreachable.
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
- the main resource failed to load.
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
`page.goto` will not throw an error when any valid HTTP status code is returned by the remote server, including 404 "Not Found" and 500 "Internal Server Error". The status code for such responses can be retrieved by calling [response.status()](#httpresponsestatus).
docs(api.md): clarify frame/page.goto()'s handling of HTTP error statuses (#4553) The documentation for frame.goto() and page.goto() were updated to make it clear that the method will not throw an error if the HTTP requests results in any valid HTTP status code being returned by the remote server.
2019-06-10 01:32:06 +00:00
> **NOTE** `page.goto` either throws an error or returns a main resource response. The only exceptions are navigation to `about:blank` or navigation to the same URL with a different hash, which would succeed and return `null`.
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
feat(frame): introduce Frame.goto and Frame.waitForNavigation (#3276) This patch introduces API to manage frame navigations. As a drive-by, the `response.frame()` method is added as a shortcut for `response.request().frame()`. Fixes #2918.
2018-09-20 18:31:19 +00:00
> **NOTE** Headless mode doesn't support navigation to a PDF document. See the [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295).
Shortcut for [page.mainFrame().goto(url, options)](#framegotourl-options)
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
Mouse (#101) This patch: - adds Mouse class which holds mouse state and implements mouse primitives, such as moving, button down and button up. - implements high-level mouse api, such as `page.click` and `page.hover`. References #40, References #89
2017-07-22 03:29:31 +00:00
#### page.hover(selector)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api.md): page.hover typo (#3165)
2018-08-31 10:59:49 +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.
docs(api.md): Fix typo (#3273)
2018-09-19 12:58:04 +00:00
If there's no element matching `selector`, the method throws an error.
Mouse (#101) This patch: - adds Mouse class which holds mouse state and implements mouse primitives, such as moving, button down and button up. - implements high-level mouse api, such as `page.click` and `page.hover`. References #40, References #89
2017-07-22 03:29:31 +00:00
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
Shortcut for [page.mainFrame().hover(selector)](#framehoverselector).
feat(page): add page.isClosed method (#2588) Fixes #2501.
2018-05-25 23:53:57 +00:00
#### page.isClosed()
fix(types): fix parameters where they disagree with the api (#3525)
2018-11-12 20:59:21 +00:00
- returns: <[boolean]>
feat(page): add page.isClosed method (#2588) Fixes #2501.
2018-05-25 23:53:57 +00:00
Indicates that the page has been closed.
feat(api): make `page.isDragInterceptionEnabled` a method (#7419) Having it be a getter is surprising and inconsistent, since the other `page.is*` APIs are just methods. Issue: #7150
2021-07-13 09:37:39 +00:00
#### page.isDragInterceptionEnabled()
feat: add drag-and-drop support (#7150) This commit adds drag-and-drop support, leveraging new additions to the CDP Input domain (Input.setInterceptDrags, Input.dispatchDragEvent, and Input.dragIntercepted).
2021-06-04 10:25:36 +00:00
- returns: <[boolean]>
Indicates that drag events are being intercepted.
feat(api): add Page.isJavaScriptEnabled + mark properties as private (#5993) Just one was used externally and I wrapped that up in a method. I think it's a useful method to provide (I can imagine wanting to know if JS is enabled on a page) so I think there's no harm here (I'd rather that then have JSHandle reach into a private variable).
2020-06-10 15:15:02 +00:00
#### page.isJavaScriptEnabled()
- returns: <[boolean]>
Returns `true` if the page has JavaScript enabled, `false` otherwise.
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()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore(types): generate our own d.ts file from api.md (#3744) Generate `//index.d.ts` file with precise typescript definitions for all of the Puppeteer API.
2019-01-28 23:12:45 +00:00
- returns: <[Frame]> The page's main frame.
Add docs/api.md This patch adds docs/api.md file which contains API description for the puppeteer API. This patch adds the API outline, which doesn't not have explanations and samples.
2017-06-13 07:28:29 +00:00
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
Page is guaranteed to have a main frame which persists during navigations.
Add docs/api.md This patch adds docs/api.md file which contains API description for the puppeteer API. This patch adds the API outline, which doesn't not have explanations and samples.
2017-06-13 07:28:29 +00:00
feat(Page): rename Page.getMetrics into Page.metrics (#1240) BREAKING CHANGE: method page.getMetrics() got renamed into page.metrics().
2017-11-01 20:39:31 +00:00
#### page.metrics()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Page): rename Page.getMetrics into Page.metrics (#1240) BREAKING CHANGE: method page.getMetrics() got renamed into page.metrics().
2017-11-01 20:39:31 +00:00
- returns: <[Promise]<[Object]>> Object containing metrics as key/value pairs.
- `Timestamp` <[number]> The timestamp when the metrics sample was taken.
- `Documents` <[number]> Number of documents in the page.
- `Frames` <[number]> Number of frames in the page.
- `JSEventListeners` <[number]> Number of events in the page.
- `Nodes` <[number]> Number of DOM nodes in the page.
- `LayoutCount` <[number]> Total number of full or partial page layout.
- `RecalcStyleCount` <[number]> Total number of page style recalculations.
- `LayoutDuration` <[number]> Combined durations of all page layouts.
- `RecalcStyleDuration` <[number]> Combined duration of all page style recalculations.
- `ScriptDuration` <[number]> Combined duration of JavaScript execution.
- `TaskDuration` <[number]> Combined duration of all tasks performed by the browser.
- `JSHeapUsedSize` <[number]> Used JavaScript heap size.
- `JSHeapTotalSize` <[number]> Total JavaScript heap size.
> **NOTE** All timestamps are in monotonic time: monotonically increasing time in seconds since an arbitrary point in the past.
Mouse (#101) This patch: - adds Mouse class which holds mouse state and implements mouse primitives, such as moving, button down and button up. - implements high-level mouse api, such as `page.click` and `page.hover`. References #40, References #89
2017-07-22 03:29:31 +00:00
#### page.mouse
- returns: <[Mouse]>
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### page.pdf([options])
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
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
- `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.
docs(api.md): Added cutoff values for scale option in page.pdf function (#3201) Added the cutoff values for the scale option in the page.pdf function call. Numbers based on chrome's warning message.
2018-09-05 17:12:21 +00:00
- `scale` <[number]> Scale of the webpage rendering. Defaults to `1`. Scale amount must be between 0.1 and 2.
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
- `displayHeaderFooter` <[boolean]> Display header and footer. Defaults to `false`.
feat(pdf): add `headerTemplate` and `footerTemplate` to available PDF options (#1625) This patch allows specifying header and footer templates for PDF printing. Fixes #373.
2017-12-20 00:54:34 +00:00
- `headerTemplate` <[string]> HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them:
- `date` formatted print date
- `title` document title
- `url` document location
- `pageNumber` current page number
- `totalPages` total pages in the document
- `footerTemplate` <[string]> HTML template for the print footer. Should use the same format as the `headerTemplate`.
Rename Page.printToPDF into page.pdf This patch: - renames Page.printToPDF into page.pdf - adds a 'path' option to the page.pdf options instead of a separate `filePath` parameter - improves on the documentation for the `page.pdf` References #39.
2017-07-17 09:06:52 +00:00
- `printBackground` <[boolean]> Print background graphics. Defaults to `false`.
- `landscape` <[boolean]> Paper orientation. Defaults to `false`.
- `pageRanges` <[string]> Paper ranges to print, e.g., '1-5, 8, 11-13'. Defaults to the empty string, which means print all pages.
- `format` <[string]> Paper format. If set, takes priority over `width` or `height` options. Defaults to 'Letter'.
fix(types): fix parameters where they disagree with the api (#3525)
2018-11-12 20:59:21 +00:00
- `width` <[string]|[number]> Paper width, accepts values labeled with units.
- `height` <[string]|[number]> Paper height, accepts values labeled with units.
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
- `margin` <[Object]> Paper margins, defaults to none.
fix(types): fix parameters where they disagree with the api (#3525)
2018-11-12 20:59:21 +00:00
- `top` <[string]|[number]> Top margin, accepts values labeled with units.
- `right` <[string]|[number]> Right margin, accepts values labeled with units.
- `bottom` <[string]|[number]> Bottom margin, accepts values labeled with units.
- `left` <[string]|[number]> Left margin, accepts values labeled with units.
feat(page): add 'preferCSSPageSize' to page.pdf options (#2928) Fixes #1963.
2018-07-27 01:51:44 +00:00
- `preferCSSPageSize` <[boolean]> Give any CSS `@page` size declared in the page priority over what is declared in `width` and `height` or `format` options. Defaults to `false`, which will scale the content to fit the paper size.
feat(page): add omitBackground option for page.pdf method (#6981)
2021-03-18 19:57:32 +00:00
- `omitBackground` <[boolean]> Hides default white background and allows capturing screenshots with transparency. Defaults to `false`.
feat: support timeout for page.pdf() call (#7508)
2021-09-14 16:11:14 +00:00
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout.
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
- 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.
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
`page.pdf()` generates a pdf of the page with `print` CSS media. To generate a pdf with `screen` media, call [page.emulateMediaType('screen')](#pageemulatemediatypetype) before calling `page.pdf()`:
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
docs(api.md): add note on page.pdf() color rendering behavior (#2821) Adds guidance for producing accurate colors in PDF output. page.pdf() can produce unexpected document colors unless forced to render exact colors. Fixes #2685
2018-06-29 16:57:03 +00:00
> **NOTE** By default, `page.pdf()` generates a pdf with modified colors for printing. Use the [`-webkit-print-color-adjust`](https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-print-color-adjust) property to force rendering of exact colors.
feat: add a streaming version for page.pdf Co-authored-by: Jan Scheffler <janscheffler@chromium.org>
2021-06-23 12:51:38 +00:00
> **NOTE** If you are generating very large PDFs, it may be useful to use the streaming version of this function ([page.createPDFStream](#pagecreatepdfstreamoptions)) to avoid high memory usage.
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
```js
// Generates a PDF with 'screen' media type.
docs(api): update emulateMediaType example (#5606)
2020-04-08 08:17:49 +00:00
await page.emulateMediaType('screen');
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
await page.pdf({path: 'page.pdf'});
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
```
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:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api): fix lint in code snippets (#7012)
2021-03-22 06:12:55 +00:00
- `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.
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
All possible units are:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
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
- `px` - pixel
- `in` - inch
- `cm` - centimeter
- `mm` - millimeter
The `format` options are:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
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
- `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
fix(page): fix A2 and A3 format size (#4569) 16.5 inch ~ 419.1mm 16.54 inch ~ 420.1mm Fix #4568
2019-06-11 03:59:12 +00:00
- `A2`: 16.54in x 23.4in
- `A3`: 11.7in x 16.54in
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
- `A4`: 8.27in x 11.7in
- `A5`: 5.83in x 8.27in
feat(Page.pdf): add 'A6' page format This patch adds 'A6' page format option to the Page.pdf method.
2017-10-11 20:18:14 +00:00
- `A6`: 4.13in x 5.83in
Rename Page.printToPDF into page.pdf This patch: - renames Page.printToPDF into page.pdf - adds a 'path' option to the page.pdf options instead of a separate `filePath` parameter - improves on the documentation for the `page.pdf` References #39.
2017-07-17 09:06:52 +00:00
docs(api.md): mention header/footer template limitations in `page.pdf`. (#2341) References #2167.
2018-04-10 05:30:20 +00:00
> **NOTE** `headerTemplate` and `footerTemplate` markup have the following limitations:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
>
docs(api.md): mention header/footer template limitations in `page.pdf`. (#2341) References #2167.
2018-04-10 05:30:20 +00:00
> 1. Script tags inside templates are not evaluated.
> 2. Page styles are not visible inside templates.
feat(Page): introduce Page.queryObjects (#1005) This patch introduces `Page.queryObjects` and `ExecutionContext.queryObjects` methods to query JavaScript heap for objects with a certain prototype. Fixes #304.
2017-10-11 21:41:20 +00:00
#### page.queryObjects(prototypeHandle)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Page): introduce Page.queryObjects (#1005) This patch introduces `Page.queryObjects` and `ExecutionContext.queryObjects` methods to query JavaScript heap for objects with a certain prototype. Fixes #304.
2017-10-11 21:41:20 +00:00
- `prototypeHandle` <[JSHandle]> A handle to the object prototype.
docs(api): `queryObjects` returns a Promise<JSHandle> (#1053)
2017-10-17 00:11:05 +00:00
- returns: <[Promise]<[JSHandle]>> Promise which resolves to a handle to an array of objects with this prototype.
feat(Page): introduce Page.queryObjects (#1005) This patch introduces `Page.queryObjects` and `ExecutionContext.queryObjects` methods to query JavaScript heap for objects with a certain prototype. Fixes #304.
2017-10-11 21:41:20 +00:00
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
The method iterates the JavaScript heap and finds all the objects with the given prototype.
feat(Page): introduce Page.queryObjects (#1005) This patch introduces `Page.queryObjects` and `ExecutionContext.queryObjects` methods to query JavaScript heap for objects with a certain prototype. Fixes #304.
2017-10-11 21:41:20 +00:00
```js
Roll chromium to 508268 (#1019) This gets us: - Plural metrics names https://crrev.com/507885 - TargetInfoChanged on URL changes https://crrev.com/508049 - Sending proper resource types for requests https://crrev.com/667504 Fixes #734
2017-10-12 08:17:06 +00:00
// Create a Map object
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
await page.evaluate(() => (window.map = new Map()));
feat(Page): introduce Page.queryObjects (#1005) This patch introduces `Page.queryObjects` and `ExecutionContext.queryObjects` methods to query JavaScript heap for objects with a certain prototype. Fixes #304.
2017-10-11 21:41:20 +00:00
// Get a handle to the Map object prototype
const mapPrototype = await page.evaluateHandle(() => Map.prototype);
// Query all map instances into an array
const mapInstances = await page.queryObjects(mapPrototype);
// Count amount of map objects in heap
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
const count = await page.evaluate(maps => maps.length, mapInstances);
feat(Page): introduce Page.queryObjects (#1005) This patch introduces `Page.queryObjects` and `ExecutionContext.queryObjects` methods to query JavaScript heap for objects with a certain prototype. Fixes #304.
2017-10-11 21:41:20 +00:00
await mapInstances.dispose();
await mapPrototype.dispose();
```
Shortcut for [page.mainFrame().executionContext().queryObjects(prototypeHandle)](#executioncontextqueryobjectsprototypehandle).
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### page.reload([options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
Document all options objects wherever they are used (#139) This patch adds missing documentation for all the shortcut methods, such as `page.evaluate` or `page.waitForSelector`. closes #114
2017-07-26 04:01:05 +00:00
- `options` <[Object]> Navigation parameters which might have the following properties:
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultNavigationTimeout(timeout)](#pagesetdefaultnavigationtimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
chore: migrate src/LifecycleWatcher (#5734)
2020-04-27 09:03:33 +00:00
- `waitUntil` <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Array<PuppeteerLifeCycleMethod>> When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
Document all options objects wherever they are used (#139) This patch adds missing documentation for all the shortcut methods, such as `page.evaluate` or `page.waitForSelector`. closes #114
2017-07-26 04:01:05 +00:00
- `load` - consider navigation to be finished when the `load` event is fired.
feat(Page.goto): add a 'domcontentloaded' option to the Page.goto (#1145) This patch adds a new `domcontentloaded` option to a bunch of navigation methods: - Page.goto - Page.waitForNavigation - Page.goBack - Page.goForward - Page.reload Fixes #946.
2017-10-24 07:35:18 +00:00
- `domcontentloaded` - consider navigation to be finished when the `DOMContentLoaded` event is fired.
typo in api.md (#1216) more then -> more than
2017-10-31 18:30:29 +00:00
- `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.
- `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
chore: update request and response references in docs (#5942) Missed some Request => HTTPRequest and Response => HTTPResponse renames when updating the docs.
2020-05-29 11:36:04 +00:00
- returns: <[Promise]<[HTTPResponse]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
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
Fix readme example
2017-06-19 22:01:14 +00:00
#### page.screenshot([options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
Update api.md This patch improves on api.md so that the raw md is human-readable and the rendering is still good. The next step would be linting markdown so that it's up-to-date and neat. References #14.
2017-06-21 18:17:35 +00:00
- `options` <[Object]> Options object which might have the following properties:
chore: Spelling and Markdown Consistency (#1998) - Adding missing language tags to markdown code blocks. - Fixed various spelling mistakes my IDE complained to me about.
2018-02-09 03:59:46 +00:00
- `path` <[string]> The file path to save the image to. The screenshot type will be inferred from file extension. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). If no path is provided, the image won't be saved to the disk.
feat: add webp to screenshot options (#7565)
2021-09-21 14:26:20 +00:00
- `type` <[string]> Specify screenshot type, can be either `jpeg`, `png` or `webp`. Defaults to 'png'.
chore: Spelling and Markdown Consistency (#1998) - Adding missing language tags to markdown code blocks. - Fixed various spelling mistakes my IDE complained to me about.
2018-02-09 03:59:46 +00:00
- `quality` <[number]> The quality of the image, between 0-100. Not applicable to `png` images.
- `fullPage` <[boolean]> When true, takes a screenshot of the full scrollable page. Defaults to `false`.
- `clip` <[Object]> An object which specifies clipping region of the page. Should have the following fields:
- `x` <[number]> x-coordinate of top-left corner of clip area
- `y` <[number]> y-coordinate of top-left corner of clip area
- `width` <[number]> width of clipping area
- `height` <[number]> height of clipping area
- `omitBackground` <[boolean]> Hides default white background and allows capturing screenshots with transparency. Defaults to `false`.
feat(page): allow screenshot to return a base64 string (#2586) Fixes #2566
2018-05-30 21:27:08 +00:00
- `encoding` <[string]> The encoding of the image, can be either `base64` or `binary`. Defaults to `binary`.
fix: doc typo (#8263)
2022-04-22 06:41:13 +00:00
- `captureBeyondViewport` <[boolean]> When true, captures screenshot [beyond the viewport](https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-captureScreenshot). When false, falls back to old behaviour, and cuts the screenshot by the viewport size. Defaults to `true`.
fix(types): fix return types where JSDoc and api.md disagree (#3512)
2018-11-08 06:48:43 +00:00
- returns: <[Promise]<[string]|[Buffer]>> Promise which resolves to buffer or a base64 string (depending on the value of `encoding`) 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
docs(api): warn about slow screenshots on OS X (#2326)
2018-04-08 01:01:31 +00:00
> **NOTE** Screenshots take at least 1/6 second on OS X. See https://crbug.com/741689 for discussion.
[api] Introduce Page.select method (#779) This patch adds `Page.select` method to select values in a `select` tag.
2017-09-25 09:23:34 +00:00
#### page.select(selector, ...values)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
[api] Introduce Page.select method (#779) This patch adds `Page.select` method to select values in a `select` tag.
2017-09-25 09:23:34 +00:00
- `selector` <[string]> A [selector] to query page for
- `...values` <...[string]> Values of options to select. If the `<select>` has the `multiple` attribute, all values are considered, otherwise only the first one is taken into account.
chore(types): generate our own d.ts file from api.md (#3744) Generate `//index.d.ts` file with precise typescript definitions for all of the Puppeteer API.
2019-01-28 23:12:45 +00:00
- returns: <[Promise]<[Array]<[string]>>> An array of option values that have been successfully selected.
[api] Introduce Page.select method (#779) This patch adds `Page.select` method to select values in a `select` tag.
2017-09-25 09:23:34 +00:00
Triggers a `change` and `input` event once all the provided options have been selected.
feat(Frame): introduce Frame.select This patch adds `Frame.select` method that does the same functionality as former `Page.select`, but on a per-frame level. The `Page.select` method becomes a shortcut for the ÷main frame's select. Fixes #1139
2017-11-02 05:06:04 +00:00
If there's no `<select>` element matching `selector`, the method throws an error.
[api] Introduce Page.select method (#779) This patch adds `Page.select` method to select values in a `select` tag.
2017-09-25 09:23:34 +00:00
```js
page.select('select#colors', 'blue'); // single selection
page.select('select#colors', 'red', 'green', 'blue'); // multiple selections
```
docs(api.md): add missing parentheses after page.mainFrame (#1738)
2018-01-09 01:20:02 +00:00
Shortcut for [page.mainFrame().select()](#frameselectselector-values)
feat(Frame): introduce Frame.select This patch adds `Frame.select` method that does the same functionality as former `Page.select`, but on a per-frame level. The `Page.select` method becomes a shortcut for the ÷main frame's select. Fixes #1139
2017-11-02 05:06:04 +00:00
feat(Page): introduce Page.setBypassCSP (#2324) This patch introduces `page.setBypassCSP` method that allows clients to ignore Content-Security-Policy for a given page. Fixes #1229.
2018-04-06 23:35:50 +00:00
#### page.setBypassCSP(enabled)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Page): introduce Page.setBypassCSP (#2324) This patch introduces `page.setBypassCSP` method that allows clients to ignore Content-Security-Policy for a given page. Fixes #1229.
2018-04-06 23:35:50 +00:00
- `enabled` <[boolean]> sets bypassing of page's Content-Security-Policy.
- returns: <[Promise]>
Toggles bypassing page's Content-Security-Policy.
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
> **NOTE** CSP bypassing happens at the moment of CSP initialization rather than evaluation. Usually, this means
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
> that `page.setBypassCSP` should be called before navigating to the domain.
feat(Page): introduce Page.setBypassCSP (#2324) This patch introduces `page.setBypassCSP` method that allows clients to ignore Content-Security-Policy for a given page. Fixes #1229.
2018-04-06 23:35:50 +00:00
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### page.setCacheEnabled([enabled])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Page): add `setCacheEnabled(enabled)` to Page object (#1609) This change adds in the `Page.setCacheEnabled(enabled)` method to toggle ignoring cache for each request. Fixes #1556.
2018-02-08 05:58:48 +00:00
- `enabled` <[boolean]> sets the `enabled` state of the cache.
- returns: <[Promise]>
Toggles ignoring cache for each request based on the enabled state. By default, caching is enabled.
feat(page): support waitUntil option for `page.setContent` (#3557) This patch teaches `page.setContent` to await resources in the new document. **NOTE**: This patch changes behavior: currently, `page.setContent` awaits the `"domcontentloaded"` event; with this patch, we can now await other lifecycle events, and switched default to the `"load"` event. The change is justified since current behavior made `page.setContent` unusable for its main designated usecases, pushing our client to use [dataURL workaround](https://github.com/GoogleChrome/puppeteer/issues/728#issuecomment-334301491). Fixes #728
2018-11-20 23:32:46 +00:00
#### page.setContent(html[, options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
- `html` <[string]> HTML markup to assign to the page.
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
- `options` <[Object]> Parameters that might have the following properties:
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- `timeout` <[number]> Maximum time in milliseconds for resources to load, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultNavigationTimeout(timeout)](#pagesetdefaultnavigationtimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
chore: migrate src/LifecycleWatcher (#5734)
2020-04-27 09:03:33 +00:00
- `waitUntil` <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Array<PuppeteerLifeCycleMethod>> When to consider setting markup succeeded, defaults to `load`. Given an array of event strings, setting content is considered to be successful after all events have been fired. Events can be either:
feat(page): support waitUntil option for `page.setContent` (#3557) This patch teaches `page.setContent` to await resources in the new document. **NOTE**: This patch changes behavior: currently, `page.setContent` awaits the `"domcontentloaded"` event; with this patch, we can now await other lifecycle events, and switched default to the `"load"` event. The change is justified since current behavior made `page.setContent` unusable for its main designated usecases, pushing our client to use [dataURL workaround](https://github.com/GoogleChrome/puppeteer/issues/728#issuecomment-334301491). Fixes #728
2018-11-20 23:32:46 +00:00
- `load` - consider setting content to be finished when the `load` event is fired.
- `domcontentloaded` - consider setting content to be finished when the `DOMContentLoaded` event is fired.
- `networkidle0` - consider setting content to be finished when there are no more than 0 network connections for at least `500` ms.
- `networkidle2` - consider setting content to be finished when there are no more than 2 network connections for at least `500` ms.
Revert "feat(Page): teach Page.setContent to wait for resources to load (#1152)" (#1312) This reverts commit 80ee46942908054dea3bc14e6505bc12718e0b2d. Lifecycle events are not ready yet to support the setContent scenario. The prerequisite for this is https://chromium-review.googlesource.com/c/chromium/src/+/747805 that might not land soon due to technical concerns.
2017-11-07 22:18:05 +00:00
- returns: <[Promise]>
Add docs/api.md This patch adds docs/api.md file which contains API description for the puppeteer API. This patch adds the API outline, which doesn't not have explanations and samples.
2017-06-13 07:28:29 +00:00
Cookies (#314) Introduce cookies API. Fixes #53.
2017-08-24 19:21:46 +00:00
#### page.setCookie(...cookies)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
Cookies (#314) Introduce cookies API. Fixes #53.
2017-08-24 19:21:46 +00:00
- `...cookies` <...[Object]>
- `name` <[string]> **required**
- `value` <[string]> **required**
- `url` <[string]>
- `domain` <[string]>
- `path` <[string]>
- `expires` <[number]> Unix time in seconds.
- `httpOnly` <[boolean]>
- `secure` <[boolean]>
fix(types): fix parameters where they disagree with the api (#3525)
2018-11-12 20:59:21 +00:00
- `sameSite` <"Strict"|"Lax">
Cookies (#314) Introduce cookies API. Fixes #53.
2017-08-24 19:21:46 +00:00
- returns: <[Promise]>
docs(api.md): Clarify how to call page.setCookie (#3215) Fixes #3109
2018-09-07 09:46:12 +00:00
```js
await page.setCookie(cookieObject1, cookieObject2);
```
feat(Page): Add global navigation timeout setting (#1728) This patch introduces `page.setDefaultNavigationTimeout` method to override the default 30 seconds navigation timeout. Fixes #1514
2018-01-10 21:04:01 +00:00
#### page.setDefaultNavigationTimeout(timeout)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Page): Add global navigation timeout setting (#1728) This patch introduces `page.setDefaultNavigationTimeout` method to override the default 30 seconds navigation timeout. Fixes #1514
2018-01-10 21:04:01 +00:00
- `timeout` <[number]> Maximum navigation time in milliseconds
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
This setting will change the default maximum navigation time for the following methods and related shortcuts:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- [page.goBack([options])](#pagegobackoptions)
- [page.goForward([options])](#pagegoforwardoptions)
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
- [page.goto(url[, options])](#pagegotourl-options)
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- [page.reload([options])](#pagereloadoptions)
- [page.setContent(html[, options])](#pagesetcontenthtml-options)
- [page.waitForNavigation([options])](#pagewaitfornavigationoptions)
> **NOTE** [`page.setDefaultNavigationTimeout`](#pagesetdefaultnavigationtimeouttimeout) takes priority over [`page.setDefaultTimeout`](#pagesetdefaulttimeouttimeout)
#### page.setDefaultTimeout(timeout)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- `timeout` <[number]> Maximum time in milliseconds
This setting will change the default maximum time for the following methods and related shortcuts:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
- [page.goBack([options])](#pagegobackoptions)
- [page.goForward([options])](#pagegoforwardoptions)
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- [page.goto(url[, options])](#pagegotourl-options)
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
- [page.reload([options])](#pagereloadoptions)
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- [page.setContent(html[, options])](#pagesetcontenthtml-options)
- [page.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#pagewaitforselectororfunctionortimeout-options-args)
feat(page): introduce file chooser interception (#4653) This patch introduces a page.waitForFileChooser() method that adds a watchdog to wait for file chooser dialogs. This lets Puppeteer users to capture file chooser requests and fulfill/cancel them if necessary. Fixes #2946
2019-07-23 04:30:49 +00:00
- [page.waitForFileChooser([options])](#pagewaitforfilechooseroptions)
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- [page.waitForFunction(pageFunction[, options[, ...args]])](#pagewaitforfunctionpagefunction-options-args)
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
- [page.waitForNavigation([options])](#pagewaitfornavigationoptions)
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- [page.waitForRequest(urlOrPredicate[, options])](#pagewaitforrequesturlorpredicate-options)
- [page.waitForResponse(urlOrPredicate[, options])](#pagewaitforresponseurlorpredicate-options)
- [page.waitForSelector(selector[, options])](#pagewaitforselectorselector-options)
- [page.waitForXPath(xpath[, options])](#pagewaitforxpathxpath-options)
> **NOTE** [`page.setDefaultNavigationTimeout`](#pagesetdefaultnavigationtimeouttimeout) takes priority over [`page.setDefaultTimeout`](#pagesetdefaulttimeouttimeout)
feat(Page): Add global navigation timeout setting (#1728) This patch introduces `page.setDefaultNavigationTimeout` method to override the default 30 seconds navigation timeout. Fixes #1514
2018-01-10 21:04:01 +00:00
feat: add drag-and-drop support (#7150) This commit adds drag-and-drop support, leveraging new additions to the CDP Input domain (Input.setInterceptDrags, Input.dispatchDragEvent, and Input.dragIntercepted).
2021-06-04 10:25:36 +00:00
#### page.setDragInterception(enabled)
- `enabled` <[boolean]>
- returns: <[Promise]>
docs: typos and minor documentation issues (#8211)
2022-04-08 09:58:55 +00:00
Enables the Input.drag methods. This provides the capability to capture drag events emitted on the page, which can then be used to simulate drag-and-drop.
feat: add drag-and-drop support (#7150) This commit adds drag-and-drop support, leveraging new additions to the CDP Input domain (Input.setInterceptDrags, Input.dispatchDragEvent, and Input.dragIntercepted).
2021-06-04 10:25:36 +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
#### page.setExtraHTTPHeaders(headers)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api.md): minor grammar and consistency fixes (#3320)
2018-10-02 20:38:41 +00:00
- `headers` <[Object]> An object containing additional HTTP headers to be sent with every request. All header values must be strings.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- returns: <[Promise]>
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
Rename page.setHTTPHeaders into page.setExtraHTTPHeaders This patch: - renames page.setHTTPHeaders into page.setExtraHTTPHeaders - starts using Map instead of Object to align with other headers arguments Fixes #112.
2017-07-27 19:25:52 +00:00
The extra HTTP headers will be sent with every request the page initiates.
docs: mention lowercasing of HTTP headers (#7224)
2021-05-10 14:27:50 +00:00
> **NOTE** All HTTP header names are lowercased. (HTTP headers are case-insensitive, so this shouldn’t impact your server code.)
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
> **NOTE** page.setExtraHTTPHeaders does not guarantee the order of headers in the outgoing requests.
feat(page): Introduce page.setGeolocation method (#3160) Fixes #1077
2018-08-31 17:04:12 +00:00
#### page.setGeolocation(options)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api): fix GeolocationOptions link (#6670)
2020-12-22 13:46:50 +00:00
- `options` <[GeolocationOptions](#geolocationoptions)>
feat(page): Introduce page.setGeolocation method (#3160) Fixes #1077
2018-08-31 17:04:12 +00:00
- returns: <[Promise]>
Sets the page's geolocation.
```js
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
await page.setGeolocation({latitude: 59.95, longitude: 30.31667});
feat(page): Introduce page.setGeolocation method (#3160) Fixes #1077
2018-08-31 17:04:12 +00:00
```
> **NOTE** Consider using [browserContext.overridePermissions](#browsercontextoverridepermissionsorigin-permissions) to grant permissions for the page to read its geolocation.
Implement page.setJavaScriptEnabled method Fixes #462.
2017-08-23 21:08:56 +00:00
#### page.setJavaScriptEnabled(enabled)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
fix a typo in the api.md (#505)
2017-08-23 21:29:47 +00:00
- `enabled` <[boolean]> Whether or not to enable JavaScript on the page.
Implement page.setJavaScriptEnabled method Fixes #462.
2017-08-23 21:08:56 +00:00
- returns: <[Promise]>
> **NOTE** changing this value won't affect scripts that have already been run. It will take full effect on the next [navigation](#pagegotourl-options).
Implement browser 'ignoreHTTPSErrors' option. (#177) This patch implements Browser 'ignoreHTTPSErrors' option. Fixes #84.
2017-08-01 22:17:57 +00:00
feat(Page): implement page.setOfflineMode (#1032) This patch implements page.setOfflineMode method. Fixes #63.
2017-10-13 21:41:39 +00:00
#### page.setOfflineMode(enabled)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: support timeout for page.pdf() call (#7508)
2021-09-14 16:11:14 +00:00
- `enabled` <[boolean]> When `true`, enables offline mode for the page.
feat(Page): implement page.setOfflineMode (#1032) This patch implements page.setOfflineMode method. Fixes #63.
2017-10-13 21:41:39 +00:00
- returns: <[Promise]>
chore: update documentation (#7446) Reference `page.setOfflineMode` and `page.emulateNetworkConditions` from each other.
2021-07-30 08:41:42 +00:00
> **NOTE** while this method sets the network connection to offline, it does not change the parameters used in [page.emulateNetworkConditions(networkConditions)](#pageemulatenetworkconditionsnetworkconditions).
feat(requestinterception): remove cacheSafe flag (#7217)
2021-05-20 12:09:56 +00:00
#### page.setRequestInterception(value)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- `value` <[boolean]> Whether to enable request interception.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- returns: <[Promise]>
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
Activating request interception enables `request.abort`, `request.continue` and `request.respond` methods. This provides the capability to modify network requests that are made by 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
docs(api.md): clarification note on request interception (#3042) Fixes #3040.
2018-08-07 21:24:27 +00:00
Once request interception is enabled, every request will stall unless it's continued, responded or aborted.
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
feat(interception): Implement request.mockResponse method (#1064) feat(interception): Implement request.respond method This patch implements a new Request.respond method. This allows users to fulfill the intercepted request with a hand-crafted response if they wish so. References #1020.
2017-10-20 23:55:15 +00:00
An example of a naïve request interceptor that aborts all image requests:
docs(api.md): clarification note on request interception (#3042) Fixes #3040.
2018-08-07 21:24:27 +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
```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
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
(async () => {
const browser = await puppeteer.launch();
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const page = await browser.newPage();
feat(Chromium): Roll chromium to r511134 (#1153) This roll includes: - crrev.com/510651 that changes request interception methods in protocol - s/Page.setRequestInterceptionEnabled/Page.setRequestInterception BREAKING CHANGE Page.setRequestInterceptionEnabled is renamed into Page.setRequestInterception.
2017-10-24 21:45:03 +00:00
await page.setRequestInterception(true);
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', interceptedRequest => {
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
if (interceptedRequest.isInterceptResolutionHandled()) return;
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
if (
interceptedRequest.url().endsWith('.png') ||
interceptedRequest.url().endsWith('.jpg')
)
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
interceptedRequest.abort();
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
else interceptedRequest.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
});
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
await page.goto('https://example.com');
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +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 stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
##### Multiple Intercept Handlers and Asynchronous Resolutions
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
By default Puppeteer will raise a `Request is already handled!` exception if `request.abort`, `request.continue`, or `request.respond` are called after any of them have already been called.
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
Always assume that an unknown handler may have already called `abort/continue/respond`. Even if your handler is the only one you registered,
3rd party packages may register their own handlers. It is therefore
important to always check the resolution status using [request.isInterceptResolutionHandled](#httprequestisinterceptresolutionhandled)
before calling `abort/continue/respond`.
Importantly, the intercept resolution may get handled by another listener while your handler is awaiting an asynchronous operation. Therefore, the return value of `request.isInterceptResolutionHandled` is only safe in a synchronous code block. Always execute `request.isInterceptResolutionHandled` and `abort/continue/respond` **synchronously** together.
This example demonstrates two synchronous handlers working together:
```js
/*
This first handler will succeed in calling request.continue because the request interception has never been resolved.
*/
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', interceptedRequest => {
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
if (interceptedRequest.isInterceptResolutionHandled()) return;
interceptedRequest.continue();
});
/*
This second handler will return before calling request.abort because request.continue was already
called by the first handler.
*/
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', interceptedRequest => {
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
if (interceptedRequest.isInterceptResolutionHandled()) return;
interceptedRequest.abort();
});
```
This example demonstrates asynchronous handlers working together:
```js
/*
This first handler will succeed in calling request.continue because the request interception has never been resolved.
*/
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', interceptedRequest => {
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
// The interception has not been handled yet. Control will pass through this guard.
if (interceptedRequest.isInterceptResolutionHandled()) return;
// It is not strictly necessary to return a promise, but doing so will allow Puppeteer to await this handler.
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
return new Promise(resolve => {
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
// Continue after 500ms
setTimeout(() => {
// Inside, check synchronously to verify that the intercept wasn't handled already.
// It might have been handled during the 500ms while the other handler awaited an async op of its own.
if (interceptedRequest.isInterceptResolutionHandled()) {
resolve();
return;
}
interceptedRequest.continue();
resolve();
}, 500);
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
});
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
});
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', async interceptedRequest => {
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
// The interception has not been handled yet. Control will pass through this guard.
if (interceptedRequest.isInterceptResolutionHandled()) return;
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
await someLongAsyncOperation();
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
// The interception *MIGHT* have been handled by the first handler, we can't be sure.
// Therefore, we must check again before calling continue() or we risk Puppeteer raising an exception.
if (interceptedRequest.isInterceptResolutionHandled()) return;
interceptedRequest.continue();
});
```
For finer-grained introspection (see Cooperative Intercept Mode below), you may also call [request.interceptResolutionState](#httprequestinterceptresolutionstate) synchronously before using `abort/continue/respond`.
Here is the example above rewritten using `request.interceptResolutionState`
```js
/*
This first handler will succeed in calling request.continue because the request interception has never been resolved.
*/
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', interceptedRequest => {
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
// The interception has not been handled yet. Control will pass through this guard.
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
const {action} = interceptedRequest.interceptResolutionState();
fix!: typo in 'already-handled' constant of the request interception API (#7813) Issues: #7745, #7747, #7780 Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-09 14:57:40 +00:00
if (action === InterceptResolutionAction.AlreadyHandled) return;
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
// It is not strictly necessary to return a promise, but doing so will allow Puppeteer to await this handler.
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
return new Promise(resolve => {
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
// Continue after 500ms
setTimeout(() => {
// Inside, check synchronously to verify that the intercept wasn't handled already.
// It might have been handled during the 500ms while the other handler awaited an async op of its own.
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
const {action} = interceptedRequest.interceptResolutionState();
fix!: typo in 'already-handled' constant of the request interception API (#7813) Issues: #7745, #7747, #7780 Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-09 14:57:40 +00:00
if (action === InterceptResolutionAction.AlreadyHandled) {
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
resolve();
return;
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
}
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
interceptedRequest.continue();
resolve();
}, 500);
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
});
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
});
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', async interceptedRequest => {
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
// The interception has not been handled yet. Control will pass through this guard.
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
if (
interceptedRequest.interceptResolutionState().action ===
InterceptResolutionAction.AlreadyHandled
)
return;
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
await someLongAsyncOperation();
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
// The interception *MIGHT* have been handled by the first handler, we can't be sure.
// Therefore, we must check again before calling continue() or we risk Puppeteer raising an exception.
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
if (
interceptedRequest.interceptResolutionState().action ===
InterceptResolutionAction.AlreadyHandled
)
return;
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
interceptedRequest.continue();
});
```
##### Cooperative Intercept Mode
`request.abort`, `request.continue`, and `request.respond` can accept an optional `priority` to work in Cooperative Intercept Mode. When all
handlers are using Cooperative Intercept Mode, Puppeteer guarantees that all intercept handlers will run and be awaited in order of registration. The interception is resolved to the highest-priority resolution. Here are the rules of Cooperative Intercept Mode:
- All resolutions must supply a numeric `priority` argument to `abort/continue/respond`.
- If any resolution does not supply a numeric `priority`, Legacy Mode is active and Cooperative Intercept Mode is inactive.
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
- Async handlers finish before intercept resolution is finalized.
- The highest priority interception resolution "wins", i.e. the interception is ultimately aborted/responded/continued according to which resolution was given the highest priority.
- In the event of a tie, `abort` > `respond` > `continue`.
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
For standardization, when specifying a Cooperative Intercept Mode priority use `0` or `DEFAULT_INTERCEPT_RESOLUTION_PRIORITY` (exported from `HTTPRequest`) unless you have a clear reason to use a higher priority. This gracefully prefers `respond` over `continue` and `abort` over `respond` and allows other handlers to work cooperatively. If you do intentionally want to use a different priority, higher priorities win over lower priorities. Negative priorities are allowed. For example, `continue({}, 4)` would win over `continue({}, -2)`.
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
To preserve backward compatibility, any handler resolving the intercept without specifying `priority` (Legacy Mode) causes immediate resolution. For Cooperative Intercept Mode to work, all resolutions must use a `priority`. In practice, this means you must still test for
`request.isInterceptResolutionHandled` because a handler beyond your control may have called `abort/continue/respond` without a
priority (Legacy Mode).
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
In this example, Legacy Mode prevails and the request is aborted immediately because at least one handler omits `priority` when resolving the intercept:
```ts
// Final outcome: immediate abort()
page.setRequestInterception(true);
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', request => {
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
if (request.isInterceptResolutionHandled()) return;
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
// Legacy Mode: interception is aborted immediately.
request.abort('failed');
});
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', request => {
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
if (request.isInterceptResolutionHandled()) return;
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
// Control will never reach this point because the request was already aborted in Legacy Mode
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
// Cooperative Intercept Mode: votes for continue at priority 0.
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
request.continue({}, 0);
});
```
In this example, Legacy Mode prevails and the request is continued because at least one handler does not specify a `priority`:
```ts
// Final outcome: immediate continue()
page.setRequestInterception(true);
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', request => {
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
if (request.isInterceptResolutionHandled()) return;
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
// Cooperative Intercept Mode: votes to abort at priority 0.
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
request.abort('failed', 0);
});
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', request => {
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
if (request.isInterceptResolutionHandled()) return;
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
// Control reaches this point because the request was cooperatively aborted which postpones resolution.
fix!: typo in 'already-handled' constant of the request interception API (#7813) Issues: #7745, #7747, #7780 Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-09 14:57:40 +00:00
// { action: InterceptResolutionAction.Abort, priority: 0 }, because abort @ 0 is the current winning resolution
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
console.log(request.interceptResolutionState());
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
// Legacy Mode: intercept continues immediately.
request.continue({});
});
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', request => {
fix!: typo in 'already-handled' constant of the request interception API (#7813) Issues: #7745, #7747, #7780 Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-09 14:57:40 +00:00
// { action: InterceptResolutionAction.AlreadyHandled }, because continue in Legacy Mode was called
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
console.log(request.interceptResolutionState());
});
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
```
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
In this example, Cooperative Intercept Mode is active because all handlers specify a `priority`. `continue()` wins because it has a higher priority than `abort()`.
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
```ts
// Final outcome: cooperative continue() @ 5
page.setRequestInterception(true);
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', request => {
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
if (request.isInterceptResolutionHandled()) return;
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
// Cooperative Intercept Mode: votes to abort at priority 10
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
request.abort('failed', 0);
});
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', request => {
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
if (request.isInterceptResolutionHandled()) return;
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
// Cooperative Intercept Mode: votes to continue at priority 5
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
request.continue(request.continueRequestOverrides(), 5);
});
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', request => {
fix!: typo in 'already-handled' constant of the request interception API (#7813) Issues: #7745, #7747, #7780 Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-09 14:57:40 +00:00
// { action: InterceptResolutionAction.Continue, priority: 5 }, because continue @ 5 > abort @ 0
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
console.log(request.interceptResolutionState());
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
});
```
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
In this example, Cooperative Intercept Mode is active because all handlers specify `priority`. `respond()` wins because its priority ties with `continue()`, but `respond()` beats `continue()`.
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
```ts
// Final outcome: cooperative respond() @ 15
page.setRequestInterception(true);
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', request => {
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
if (request.isInterceptResolutionHandled()) return;
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
// Cooperative Intercept Mode: votes to abort at priority 10
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
request.abort('failed', 10);
});
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', request => {
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
if (request.isInterceptResolutionHandled()) return;
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
// Cooperative Intercept Mode: votes to continue at priority 15
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
request.continue(request.continueRequestOverrides(), 15);
});
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', request => {
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
if (request.isInterceptResolutionHandled()) return;
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
// Cooperative Intercept Mode: votes to respond at priority 15
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
request.respond(request.responseForRequest(), 15);
});
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', request => {
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
if (request.isInterceptResolutionHandled()) return;
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
// Cooperative Intercept Mode: votes to respond at priority 12
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
request.respond(request.responseForRequest(), 12);
});
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', request => {
fix!: typo in 'already-handled' constant of the request interception API (#7813) Issues: #7745, #7747, #7780 Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-09 14:57:40 +00:00
// { action: InterceptResolutionAction.Respond, priority: 15 }, because respond @ 15 > continue @ 15 > respond @ 12 > abort @ 10
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
console.log(request.interceptResolutionState());
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
});
```
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
##### Cooperative Request Continuation
fix!: typo in 'already-handled' constant of the request interception API (#7813) Issues: #7745, #7747, #7780 Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-09 14:57:40 +00:00
Puppeteer requires `request.continue()` to be called explicitly or the request will hang. Even if
your handler means to take no special action, or 'opt out', `request.continue()` must still be called.
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
With the introduction of Cooperative Intercept Mode, two use cases arise for cooperative request continuations:
Unopinionated and Opinionated.
fix!: typo in 'already-handled' constant of the request interception API (#7813) Issues: #7745, #7747, #7780 Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-09 14:57:40 +00:00
The first case (common) is that your handler means to opt out of doing anything special the request. It has no opinion on further action and simply intends to continue by default and/or defer to other handlers that might have an opinion. But in case there are no other handlers, we must call `request.continue()` to ensure that the request doesn't hang.
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
We call this an **Unopinionated continuation** because the intent is to continue the request if nobody else has a better idea. Use `request.continue({...}, DEFAULT_INTERCEPT_RESOLUTION_PRIORITY)` (or `0`) for this type of continuation.
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
fix!: typo in 'already-handled' constant of the request interception API (#7813) Issues: #7745, #7747, #7780 Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-09 14:57:40 +00:00
The second case (uncommon) is that your handler actually does have an opinion and means to force continuation by overriding a lower-priority `abort()` or `respond()` issued elsewhere. We call this an **Opinionated continuation**. In these rare cases where you mean to specify an overriding continuation priority, use a custom priority.
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
To summarize, reason through whether your use of `request.continue` is just meant to be default/bypass behavior vs falling within the intended use case of your handler. Consider using a custom priority for in-scope use cases, and a default priority otherwise. Be aware that your handler may have both Opinionated and Unopinionated cases.
##### Upgrading to Cooperative Intercept Mode for package maintainers
If you are package maintainer and your package uses intercept handlers, you can update your intercept handlers to use Cooperative Intercept Mode. Suppose you have the following existing handler:
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
```ts
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', interceptedRequest => {
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
if (request.isInterceptResolutionHandled()) return;
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
if (
interceptedRequest.url().endsWith('.png') ||
interceptedRequest.url().endsWith('.jpg')
)
interceptedRequest.abort();
else interceptedRequest.continue();
});
```
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
To use Cooperative Intercept Mode, upgrade `continue()` and `abort()`:
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
```ts
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', interceptedRequest => {
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
if (request.isInterceptResolutionHandled()) return;
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
if (
interceptedRequest.url().endsWith('.png') ||
interceptedRequest.url().endsWith('.jpg')
)
interceptedRequest.abort('failed', 0);
else
interceptedRequest.continue(
interceptedRequest.continueRequestOverrides(),
0
);
});
```
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
With those simple upgrades, your handler now uses Cooperative Intercept Mode instead.
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
However, we recommend a slightly more robust solution because the above introduces several subtle issues:
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
1. **Backward compatibility.** If any handler still uses a Legacy Mode resolution (ie, does not specify a priority), that handler will resolve the interception immediately even if your handler runs first. This could cause disconcerting behavior for your users because suddenly your handler is not resolving the interception and a different handler is taking priority when all the user did was upgrade your package.
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
2. **Hard-coded priority.** Your package user has no ability to specify the default resolution priority for your handlers. This can become important when the user wishes to manipulate the priorities based on use case. For example, one user might want your package to take a high priority while another user might want it to take a low priority.
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
To resolve both of these issues, our recommended approach is to export a `setInterceptResolutionConfig()` from your package. The user can then call `setInterceptResolutionConfig()` to explicitly activate Cooperative Intercept Mode in your package so they aren't surprised by changes in how the interception is resolved. They can also optionally specify a custom priority using `setInterceptResolutionConfig(priority)` that works for their use case:
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
```ts
// Defaults to undefined which preserves Legacy Mode behavior
let _priority = undefined;
// Export a module configuration function
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
export const setInterceptResolutionConfig = (priority = 0) =>
(_priority = priority);
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
/**
* Note that this handler uses `DEFAULT_INTERCEPT_RESOLUTION_PRIORITY` to "pass" on this request. It is important to use
* the default priority when your handler has no opinion on the request and the intent is to continue() by default.
*/
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', interceptedRequest => {
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
if (request.isInterceptResolutionHandled()) return;
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
if (
interceptedRequest.url().endsWith('.png') ||
interceptedRequest.url().endsWith('.jpg')
)
interceptedRequest.abort('failed', _priority);
else
interceptedRequest.continue(
interceptedRequest.continueRequestOverrides(),
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
DEFAULT_INTERCEPT_RESOLUTION_PRIORITY // Unopinionated continuation
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
);
});
```
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
If your package calls for more fine-grained control over resolution priorities, use a config pattern like this:
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
```ts
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
interface InterceptResolutionConfig {
abortPriority?: number;
continuePriority?: number;
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
}
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
// This approach supports multiple priorities based on situational
// differences. You could, for example, create a config that
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
// allowed separate priorities for PNG vs JPG.
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
const DEFAULT_CONFIG: InterceptResolutionConfig = {
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
abortPriority: undefined, // Default to Legacy Mode
continuePriority: undefined, // Default to Legacy Mode
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
};
// Defaults to undefined which preserves Legacy Mode behavior
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
let _config: Partial<InterceptResolutionConfig> = {};
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
export const setInterceptResolutionConfig = (
config: InterceptResolutionConfig
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
) => (_config = {...DEFAULT_CONFIG, ...config});
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', interceptedRequest => {
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
if (request.isInterceptResolutionHandled()) return;
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
if (
interceptedRequest.url().endsWith('.png') ||
interceptedRequest.url().endsWith('.jpg')
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
) {
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
interceptedRequest.abort('failed', _config.abortPriority);
} else {
// Here we use a custom-configured priority to allow for Opinionated
// continuation.
// We would only want to allow this if we had a very clear reason why
// some use cases required Opinionated continuation.
interceptedRequest.continue(
interceptedRequest.continueRequestOverrides(),
_config.continuePriority // Why would we ever want priority!==0 here?
);
}
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
});
```
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
The above solutions ensure backward compatibility while also allowing the user to adjust the importance of your package in the resolution chain when Cooperative Intercept Mode is being used. Your package continues to work as expected until the user has fully upgraded their code and all third party packages to use Cooperative Intercept Mode. If any handler or package still uses Legacy Mode, your package can still operate in Legacy Mode too.
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
feat: add support for useragentdata (#7378) Adds userAgentData to setUserAgent that supports specifying user agent data for the new navigator.userAgentData and Client Hints headers.
2021-06-29 16:29:55 +00:00
#### page.setUserAgent(userAgent[, userAgentMetadata])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
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
feat: add support for useragentdata (#7378) Adds userAgentData to setUserAgent that supports specifying user agent data for the new navigator.userAgentData and Client Hints headers.
2021-06-29 16:29:55 +00:00
- `userAgentMetadata` <[Object]> Optional user agent data to use in this page. Any
values not provided will use the client's default.
- `brands` <[Array]<[Object]>> Optional brand information
- `brand` <[string]> Browser or client brand name.
- `version` <[string]> Browser or client major version.
- `fullVersion` <[string]> Optional browser or client full version.
- `platform` <[string]> Operating system name.
- `platformVersion` <[string]> Operating system version.
- `architecture` <[string]> CPU architecture.
- `model` <[string]> Device model.
- `mobile` <[boolean]> Indicate if this is a mobile device.
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
- returns: <[Promise]> Promise which resolves when the user agent is set.
feat: add support for useragentdata (#7378) Adds userAgentData to setUserAgent that supports specifying user agent data for the new navigator.userAgentData and Client Hints headers.
2021-06-29 16:29:55 +00:00
> **NOTE** support for `userAgentMetadata` is experimental in the DevTools
> protocol and more properties will be added.
Providing the optional `userAgentMetadata` header will update the related
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
entries in `navigator.userAgentData` and associated `Sec-CH-UA`\* headers.
feat: add support for useragentdata (#7378) Adds userAgentData to setUserAgent that supports specifying user agent data for the new navigator.userAgentData and Client Hints headers.
2021-06-29 16:29:55 +00:00
```js
const page = await browser.newPage();
await page.setUserAgent('MyBrowser', {
architecture: 'My1',
mobile: false,
model: 'Mybook',
platform: 'MyOS',
platformVersion: '3.1',
});
```
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)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `viewport` <[Object]>
docs(api.md): fixes #3517 (#3561) Add required to height and width properties in setViewport function
2018-11-19 20:35:16 +00:00
- `width` <[number]> page width in pixels. **required**
- `height` <[number]> page height in pixels. **required**
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
- `deviceScaleFactor` <[number]> Specify device scale factor (can be thought of as DPR). Defaults to `1`.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `isMobile` <[boolean]> Whether the `meta viewport` tag is taken into account. Defaults to `false`.
- `hasTouch`<[boolean]> Specifies if viewport supports touch events. Defaults to `false`
- `isLandscape` <[boolean]> Specifies if viewport is in landscape mode. Defaults to `false`.
- returns: <[Promise]>
Get rid of page.emulate() / page.emulatedDevices() methods This patch: - gets rid of `page.emulate` and `page.emulatedDevices` methods. Instead, it is suggested to use `page.setViewport()` and `page.setUserAgent()` methods. - moves DeviceDescriptors to the top level of the puppeteer so that it is convenient to require them. - improves on documentation to describe the suggested emulation approach. References #88.
2017-07-21 01:14:43 +00:00
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
> **NOTE** in certain cases, setting viewport will reload the page in order to set the `isMobile` or `hasTouch` properties.
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
In the case of multiple pages in a single browser, each page can have its own viewport size.
Add docs/api.md This patch adds docs/api.md file which contains API description for the puppeteer API. This patch adds the API outline, which doesn't not have explanations and samples.
2017-06-13 07:28:29 +00:00
docs(api.md): add notes on race condition in page.setViewport (#4319) Fixes #2755.
2019-06-11 01:07:24 +00:00
`page.setViewport` will resize the page. A lot of websites don't expect phones to change size, so you should set the viewport before navigating to the page.
```js
const page = await browser.newPage();
await page.setViewport({
width: 640,
height: 480,
deviceScaleFactor: 1,
});
await page.goto('https://example.com');
```
[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)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- `selector` <[string]> A [selector] to search for element to tap. If there are multiple elements satisfying the selector, the first will be tapped.
- returns: <[Promise]>
This method fetches an element with `selector`, scrolls it into view if needed, and then uses [page.touchscreen](#pagetouchscreen) to tap in the center of the element.
If there's no element matching `selector`, the method throws an error.
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
Shortcut for [page.mainFrame().tap(selector)](#frametapselector).
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
#### page.target()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
- returns: <[Target]> a target this page was created from.
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
#### page.title()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore(types): generate our own d.ts file from api.md (#3744) Generate `//index.d.ts` file with precise typescript definitions for all of the Puppeteer API.
2019-01-28 23:12:45 +00:00
- returns: <[Promise]<[string]>> The 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
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- 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
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
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: <[Tracing]>
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
#### page.type(selector, text[, options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
- `selector` <[string]> A [selector] of an element to type into. If there are multiple elements satisfying the selector, the first will be used.
[doclint] Fix bug in documentation linter This patch: - fixes a typo in documentation linter, which resulted in only certain method arguments being linted. - adds missing arguments to the documentation References #14.
2017-07-12 00:01:58 +00:00
- `text` <[string]> A text to type into a focused element.
Add delay option to input methods (#171) Add delay option to input methods for the keyboard and mouse. Closes #156
2017-08-01 01:18:15 +00:00
- `options` <[Object]>
- `delay` <[number]> Time to wait between key presses in milliseconds. Defaults to 0.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- returns: <[Promise]>
Add docs/api.md This patch adds docs/api.md file which contains API description for the puppeteer API. This patch adds the API outline, which doesn't not have explanations and samples.
2017-06-13 07:28:29 +00:00
Remove keyboard.type and keyboard.press (#98) This patch removes keyboard.type and keyboard.press methods. The motivation behind this is to keep only low-level API in the `keyboard` namespace.
2017-07-22 03:00:09 +00:00
Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
chore(doc): fix a link (#977)
2017-10-07 15:32:40 +00:00
To press a special key, like `Control` or `ArrowDown`, use [`keyboard.press`](#keyboardpresskey-options).
Remove keyboard.type and keyboard.press (#98) This patch removes keyboard.type and keyboard.press methods. The motivation behind this is to keep only low-level API in the `keyboard` namespace.
2017-07-22 03:00:09 +00:00
Add delay option to input methods (#171) Add delay option to input methods for the keyboard and mouse. Closes #156
2017-08-01 01:18:15 +00:00
```js
docs(api): clarify `type` method examples (#5010)
2019-10-07 06:32:35 +00:00
await page.type('#mytextarea', 'Hello'); // Types instantly
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
await page.type('#mytextarea', 'World', {delay: 100}); // Types slower, like a user
Add delay option to input methods (#171) Add delay option to input methods for the keyboard and mouse. Closes #156
2017-08-01 01:18:15 +00:00
```
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
Shortcut for [page.mainFrame().type(selector, text[, options])](#frametypeselector-text-options).
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
#### page.url()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- 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()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: add option to specify the default viewport (#3005) Fixes #1183.
2018-08-01 23:23:03 +00:00
- returns: <?[Object]>
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `width` <[number]> page width in pixels.
- `height` <[number]> page height in pixels.
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
- `deviceScaleFactor` <[number]> Specify device scale factor (can be though of as dpr). Defaults to `1`.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `isMobile` <[boolean]> Whether the `meta viewport` tag is taken into account. Defaults to `false`.
- `hasTouch`<[boolean]> Specifies if viewport supports touch events. Defaults to `false`
- `isLandscape` <[boolean]> Specifies if viewport is in landscape mode. Defaults to `false`.
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
page.waitFor should send ...args to page.waitForFunction (#775) This lets the user pass `...args` into `page.waitFor`. It also clarifies that the docs that `options` is not optional if `...args` are specified. Fixes #770
2017-09-15 21:28:15 +00:00
#### page.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- `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
docs(api.md): improve page.waitFor docs for the `options` object (#5021)
2019-10-24 09:22:21 +00:00
- `visible` <[boolean]> wait for element to be present in DOM and to be visible. Defaults to `false`.
- `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) method.
- `hidden` <[boolean]> wait for element to not be found in the DOM or to be hidden. Defaults to `false`.
- `polling` <[string]|[number]> An interval at which the `pageFunction` is executed, defaults to `raf`. If `polling` is a number, then it is treated as an interval in milliseconds at which the function would be executed. If `polling` is a string, then it can be one of the following values:
- `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.
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- returns: <[Promise]<[JSHandle]>> Promise which resolves to a JSHandle of the success value
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
feat: page.waitForTimeout (#6268)
2020-07-28 08:37:49 +00:00
**This method is deprecated**. You should use the more explicit API methods available:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- `page.waitForSelector`
- `page.waitForXPath`
- `page.waitForFunction`
- `page.waitForTimeout`
feat: page.waitForTimeout (#6268)
2020-07-28 08:37:49 +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
This method behaves differently with respect to the type of the first parameter:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
- if `selectorOrFunctionOrTimeout` is a `string`, then the first argument is treated as a [selector] or [xpath], depending on whether or not it starts with '//', and the method is a shortcut for
[page.waitForSelector](#pagewaitforselectorselector-options) or [page.waitForXPath](#pagewaitforxpathxpath-options)
docs(api): fix typo 'Than' was used in a few places instead of 'then'.
2017-10-10 18:07:39 +00:00
- if `selectorOrFunctionOrTimeout` is a `function`, then the first argument is treated as a predicate to wait for and the method is a shortcut for [page.waitForFunction()](#pagewaitforfunctionpagefunction-options-args).
- if `selectorOrFunctionOrTimeout` is a `number`, then the first argument is treated as a timeout in milliseconds and the method returns a promise which resolves after the timeout
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
- otherwise, an exception is thrown
Added frame.waitFor(selector) (#59) This patch adds `frame.waitFor(selector)` method. Fixes #42.
2017-07-07 22:39:02 +00:00
docs(api.md): elaborate on passing arguments in waitForFunction (#2921)
2018-07-26 23:26:37 +00:00
```js
// wait for selector
await page.waitFor('.foo');
// wait for 1 second
await page.waitFor(1000);
// wait for predicate
await page.waitFor(() => !!document.querySelector('.foo'));
```
To pass arguments from node.js to the predicate of `page.waitFor` function:
```js
const selector = '.foo';
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
await page.waitFor(
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
selector => !!document.querySelector(selector),
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
{},
selector
);
docs(api.md): elaborate on passing arguments in waitForFunction (#2921)
2018-07-26 23:26:37 +00:00
```
page.waitFor should send ...args to page.waitForFunction (#775) This lets the user pass `...args` into `page.waitFor`. It also clarifies that the docs that `options` is not optional if `...args` are specified. Fixes #770
2017-09-15 21:28:15 +00:00
Shortcut for [page.mainFrame().waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#framewaitforselectororfunctionortimeout-options-args).
Implement waitFor which survives navigation (#99) This patch implements page.waitFor method which survives navigation. References #89.
2017-07-20 02:04:51 +00:00
feat(page): introduce file chooser interception (#4653) This patch introduces a page.waitForFileChooser() method that adds a watchdog to wait for file chooser dialogs. This lets Puppeteer users to capture file chooser requests and fulfill/cancel them if necessary. Fixes #2946
2019-07-23 04:30:49 +00:00
#### page.waitForFileChooser([options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs: heading ID references in docs/api.md (#7974) - `Worker` -> `WebWorker`, `#class-worker` -> `#class-webworker` - `#pagesetuseragentuseragent-useragentdata` -> `#pagesetuseragentuseragent-useragentmetadata` - `####WaitTimeoutOptions` -> `#waittimeoutoptions` - `#cooperative-intercept-mode-and-legacy-intercept-mode` -> `#cooperative-intercept-mode` Co-authored-by: jrandolf <86539915+jrandolf@users.noreply.github.com>
2022-02-11 13:43:52 +00:00
- `options` <[WaitTimeoutOptions](#waittimeoutoptions)> Optional waiting parameters
feat(page): introduce file chooser interception (#4653) This patch introduces a page.waitForFileChooser() method that adds a watchdog to wait for file chooser dialogs. This lets Puppeteer users to capture file chooser requests and fulfill/cancel them if necessary. Fixes #2946
2019-07-23 04:30:49 +00:00
- returns: <[Promise]<[FileChooser]>> A promise that resolves after a page requests a file picker.
> **NOTE** In non-headless Chromium, this method results in the native file picker dialog **not showing up** for the user.
This method is typically coupled with an action that triggers file choosing.
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
The following example clicks a button that issues a file chooser and then
feat(page): introduce file chooser interception (#4653) This patch introduces a page.waitForFileChooser() method that adds a watchdog to wait for file chooser dialogs. This lets Puppeteer users to capture file chooser requests and fulfill/cancel them if necessary. Fixes #2946
2019-07-23 04:30:49 +00:00
responds with `/tmp/myfile.pdf` as if a user has selected this file.
```js
const [fileChooser] = await Promise.all([
page.waitForFileChooser(),
page.click('#upload-file-button'), // some button that triggers file selection
]);
await fileChooser.accept(['/tmp/myfile.pdf']);
```
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
> **NOTE** This must be called _before_ the file chooser is launched. It will not return a currently active file chooser.
feat(page): introduce file chooser interception (#4653) This patch introduces a page.waitForFileChooser() method that adds a watchdog to wait for file chooser dialogs. This lets Puppeteer users to capture file chooser requests and fulfill/cancel them if necessary. Fixes #2946
2019-07-23 04:30:49 +00:00
docs(api): clarify “file chooser” meaning (#7534) Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-09-01 07:51:09 +00:00
> **NOTE** “File picker” refers to the operating system’s file selection UI that lets you browse to a folder and select file(s) to be shared with the web app. It’s not the “Save file” dialog.
feat(oop iframes)!: integrate OOP iframes with the frame manager (#7556) This pull request to adds better support for OOP iframes (see #2548) The current problem with OOP iframes is that they are moved to a different target. Because of this, the previous versions of Puppeteer pretty much ignored them. This change extends the FrameManager to already take OOP iframes into account and hides the fact that those frames are actually in different targets. Further work needs to be done to also make the NetworkManager aware of these and to make sure that settings like emulations etc. are also properly passed down to the new targets.
2021-10-28 09:25:49 +00:00
#### page.waitForFrame(urlOrPredicate[, options])
- `urlOrPredicate` <[string]|[Function]> A URL or predicate to wait for.
- `options` <[Object]> Optional waiting parameters
- `timeout` <[number]> Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to disable the timeout. The default value can be changed by using the [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) method.
- returns: <[Promise]<[Frame]>> Promise which resolves to the matched frame.
```js
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
const frame = await page.waitForFrame(async frame => {
feat(oop iframes)!: integrate OOP iframes with the frame manager (#7556) This pull request to adds better support for OOP iframes (see #2548) The current problem with OOP iframes is that they are moved to a different target. Because of this, the previous versions of Puppeteer pretty much ignored them. This change extends the FrameManager to already take OOP iframes into account and hides the fact that those frames are actually in different targets. Further work needs to be done to also make the NetworkManager aware of these and to make sure that settings like emulations etc. are also properly passed down to the new targets.
2021-10-28 09:25:49 +00:00
return frame.name() === 'Test';
});
```
page.waitFor should send ...args to page.waitForFunction (#775) This lets the user pass `...args` into `page.waitFor`. It also clarifies that the docs that `options` is not optional if `...args` are specified. Fixes #770
2017-09-15 21:28:15 +00:00
#### page.waitForFunction(pageFunction[, options[, ...args]])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
Implement page.waitForFunction method The page.waitForFunction method allows to wait for a general predicate. The predicate will be continiously polled for in page, until it either returns true or the timeout happens. The polling parameter could be one of the following: - 'raf' - to poll on every animation frame - 'mutation' - to poll on every dom mutation - <number> - to poll every X milliseconds References #91
2017-07-27 22:17:43 +00:00
- `pageFunction` <[function]|[string]> Function to be evaluated in browser context
- `options` <[Object]> Optional waiting parameters
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
- `polling` <[string]|[number]> An interval at which the `pageFunction` is executed, defaults to `raf`. If `polling` is a number, then it is treated as an interval in milliseconds at which the function would be executed. If `polling` is a string, then it can be one of the following values:
Implement page.waitForFunction method The page.waitForFunction method allows to wait for a general predicate. The predicate will be continiously polled for in page, until it either returns true or the timeout happens. The polling parameter could be one of the following: - 'raf' - to poll on every animation frame - 'mutation' - to poll on every dom mutation - <number> - to poll every X milliseconds References #91
2017-07-27 22:17:43 +00:00
- `raf` - to constantly execute `pageFunction` in `requestAnimationFrame` callback. This is the tightest polling mode which is suitable to observe styling changes.
- `mutation` - to execute `pageFunction` on every DOM mutation.
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) method.
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- returns: <[Promise]<[JSHandle]>> Promise which resolves when the `pageFunction` returns a truthy value. It resolves to a JSHandle of the truthy value.
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
The `waitForFunction` can be used to observe viewport size change:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
```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
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
(async () => {
const browser = await puppeteer.launch();
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');
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
await page.setViewport({width: 50, height: 50});
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
await watchDog;
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +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
```
docs(api.md): elaborate on passing arguments in waitForFunction (#2921)
2018-07-26 23:26:37 +00:00
To pass arguments from node.js to the predicate of `page.waitForFunction` function:
```js
const selector = '.foo';
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
await page.waitForFunction(
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
selector => !!document.querySelector(selector),
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
{},
selector
);
docs(api.md): elaborate on passing arguments in waitForFunction (#2921)
2018-07-26 23:26:37 +00:00
```
fix: support async functions as an argument for waitForFunction (#5682)
2020-05-19 07:09:31 +00:00
The predicate of `page.waitForFunction` can be asynchronous too:
```js
const username = 'github-username';
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
await page.waitForFunction(
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
async username => {
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
const githubResponse = await fetch(
`https://api.github.com/users/${username}`
);
const githubUser = await githubResponse.json();
// show the avatar
const img = document.createElement('img');
img.src = githubUser.avatar_url;
// wait 3 seconds
await new Promise((resolve, reject) => setTimeout(resolve, 3000));
img.remove();
},
{},
username
);
fix: support async functions as an argument for waitForFunction (#5682)
2020-05-19 07:09:31 +00:00
```
page.waitFor should send ...args to page.waitForFunction (#775) This lets the user pass `...args` into `page.waitFor`. It also clarifies that the docs that `options` is not optional if `...args` are specified. Fixes #770
2017-09-15 21:28:15 +00:00
Shortcut for [page.mainFrame().waitForFunction(pageFunction[, options[, ...args]])](#framewaitforfunctionpagefunction-options-args).
Implement page.waitForFunction method The page.waitForFunction method allows to wait for a general predicate. The predicate will be continiously polled for in page, until it either returns true or the timeout happens. The polling parameter could be one of the following: - 'raf' - to poll on every animation frame - 'mutation' - to poll on every dom mutation - <number> - to poll every X milliseconds References #91
2017-07-27 22:17:43 +00:00
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### page.waitForNavigation([options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
Document all options objects wherever they are used (#139) This patch adds missing documentation for all the shortcut methods, such as `page.evaluate` or `page.waitForSelector`. closes #114
2017-07-26 04:01:05 +00:00
- `options` <[Object]> Navigation parameters which might have the following properties:
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultNavigationTimeout(timeout)](#pagesetdefaultnavigationtimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
chore: migrate src/LifecycleWatcher (#5734)
2020-04-27 09:03:33 +00:00
- `waitUntil` <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Array<PuppeteerLifeCycleMethod>> When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
Document all options objects wherever they are used (#139) This patch adds missing documentation for all the shortcut methods, such as `page.evaluate` or `page.waitForSelector`. closes #114
2017-07-26 04:01:05 +00:00
- `load` - consider navigation to be finished when the `load` event is fired.
feat(Page.goto): add a 'domcontentloaded' option to the Page.goto (#1145) This patch adds a new `domcontentloaded` option to a bunch of navigation methods: - Page.goto - Page.waitForNavigation - Page.goBack - Page.goForward - Page.reload Fixes #946.
2017-10-24 07:35:18 +00:00
- `domcontentloaded` - consider navigation to be finished when the `DOMContentLoaded` event is fired.
typo in api.md (#1216) more then -> more than
2017-10-31 18:30:29 +00:00
- `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.
- `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
chore: update request and response references in docs (#5942) Missed some Request => HTTPRequest and Response => HTTPResponse renames when updating the docs.
2020-05-29 11:36:04 +00:00
- returns: <[Promise]<?[HTTPResponse]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to History API usage, the navigation will resolve with `null`.
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
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
This resolves when the page navigates to a new URL or reloads. It is useful when you run code
that will indirectly cause the page to navigate. Consider this example:
docs(api.md): add explanation to page.waitForNavigation (#2354) Fixes #1860
2018-04-26 20:32:40 +00:00
```js
feat(frame): introduce Frame.goto and Frame.waitForNavigation (#3276) This patch introduces API to manage frame navigations. As a drive-by, the `response.frame()` method is added as a shortcut for `response.request().frame()`. Fixes #2918.
2018-09-20 18:31:19 +00:00
const [response] = await Promise.all([
page.waitForNavigation(), // The promise resolves after navigation has finished
page.click('a.my-link'), // Clicking the link will indirectly cause a navigation
]);
docs(api.md): add explanation to page.waitForNavigation (#2354) Fixes #1860
2018-04-26 20:32:40 +00:00
```
**NOTE** Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to change the URL is considered a navigation.
feat(frame): introduce Frame.goto and Frame.waitForNavigation (#3276) This patch introduces API to manage frame navigations. As a drive-by, the `response.frame()` method is added as a shortcut for `response.request().frame()`. Fixes #2918.
2018-09-20 18:31:19 +00:00
Shortcut for [page.mainFrame().waitForNavigation(options)](#framewaitfornavigationoptions).
feat(api): implement `Page.waitForNetworkIdle()` (#5140) which will wait for there to be no network requests in progress during the `idleTime` before resolving.
2021-09-11 20:28:12 +00:00
#### page.waitForNetworkIdle([options])
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
feat(api): implement `Page.waitForNetworkIdle()` (#5140) which will wait for there to be no network requests in progress during the `idleTime` before resolving.
2021-09-11 20:28:12 +00:00
- `options` <[Object]> Optional waiting parameters
- `timeout` <[number]> Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to disable the timeout. The default value can be changed by using the [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) method.
- `idleTime` <[number]> How long to wait for no network requests in milliseconds, defaults to 500 milliseconds.
- returns: <[Promise]<void>> Promise which resolves when network is idle.
```js
page.evaluate(() => fetch('some-url'));
page.waitForNetworkIdle(); // The promise resolves after fetch above finishes
```
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### page.waitForRequest(urlOrPredicate[, options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(page): introduce waitForRequest and waitForResponse methods (#2776) This patch introduces `page.waitForRequest` and `page.waitForResponse` helper methods. Fixes #2362
2018-07-12 21:36:31 +00:00
- `urlOrPredicate` <[string]|[Function]> A URL or predicate to wait for.
- `options` <[Object]> Optional waiting parameters
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- `timeout` <[number]> Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to disable the timeout. The default value can be changed by using the [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) method.
chore: update request and response references in docs (#5942) Missed some Request => HTTPRequest and Response => HTTPResponse renames when updating the docs.
2020-05-29 11:36:04 +00:00
- returns: <[Promise]<[HTTPRequest]>> Promise which resolves to the matched request.
feat(page): introduce waitForRequest and waitForResponse methods (#2776) This patch introduces `page.waitForRequest` and `page.waitForResponse` helper methods. Fixes #2362
2018-07-12 21:36:31 +00:00
```js
const firstRequest = await page.waitForRequest('http://example.com/resource');
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
const finalRequest = await page.waitForRequest(
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
request =>
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
request.url() === 'http://example.com' && request.method() === 'GET'
);
feat(page): introduce waitForRequest and waitForResponse methods (#2776) This patch introduces `page.waitForRequest` and `page.waitForResponse` helper methods. Fixes #2362
2018-07-12 21:36:31 +00:00
return firstRequest.url();
```
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### page.waitForResponse(urlOrPredicate[, options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(page): introduce waitForRequest and waitForResponse methods (#2776) This patch introduces `page.waitForRequest` and `page.waitForResponse` helper methods. Fixes #2362
2018-07-12 21:36:31 +00:00
- `urlOrPredicate` <[string]|[Function]> A URL or predicate to wait for.
- `options` <[Object]> Optional waiting parameters
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- `timeout` <[number]> Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to disable the timeout. The default value can be changed by using the [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) method.
chore: update request and response references in docs (#5942) Missed some Request => HTTPRequest and Response => HTTPResponse renames when updating the docs.
2020-05-29 11:36:04 +00:00
- returns: <[Promise]<[HTTPResponse]>> Promise which resolves to the matched response.
feat(page): introduce waitForRequest and waitForResponse methods (#2776) This patch introduces `page.waitForRequest` and `page.waitForResponse` helper methods. Fixes #2362
2018-07-12 21:36:31 +00:00
```js
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
const firstResponse = await page.waitForResponse(
'https://example.com/resource'
);
const finalResponse = await page.waitForResponse(
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
response =>
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
response.url() === 'https://example.com' && response.status() === 200
);
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
const finalResponse = await page.waitForResponse(async response => {
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
return (await response.text()).includes('<html>');
});
feat(page): introduce waitForRequest and waitForResponse methods (#2776) This patch introduces `page.waitForRequest` and `page.waitForResponse` helper methods. Fixes #2362
2018-07-12 21:36:31 +00:00
return finalResponse.ok();
```
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])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- `selector` <[string]> A [selector] of an element to wait for
Document all options objects wherever they are used (#139) This patch adds missing documentation for all the shortcut methods, such as `page.evaluate` or `page.waitForSelector`. closes #114
2017-07-26 04:01:05 +00:00
- `options` <[Object]> Optional waiting parameters
- `visible` <[boolean]> wait for element to be present in DOM and to be visible, i.e. to not have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
feat(page): waitForSelector hidden option (#967) This patch adds a 'hidden' option for the `page.waitForSelector` method.
2017-10-13 16:11:11 +00:00
- `hidden` <[boolean]> wait for element to not be found in the DOM or to be hidden, i.e. have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) method.
fix(page): teach waitForSelector to return `null` (#3846) `page.waitForSelector` should return `null` if waiting for `hidden: true` and there's no matching node in DOM. Before this patch, `page.waitForSelector` would return some JSHandle pointing to boolean value.
2019-01-28 19:24:53 +00:00
- returns: <[Promise]<?[ElementHandle]>> Promise which resolves when element specified by selector string is added to DOM. Resolves to `null` if waiting for `hidden: true` and selector is not found in 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:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
```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
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
(async () => {
const browser = await puppeteer.launch();
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));
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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);
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
}
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +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
```
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
Shortcut for [page.mainFrame().waitForSelector(selector[, options])](#framewaitforselectorselector-options).
Introduce polymorphic page.waitFor method This patch: - introduces page.waitForSelector to wait for the selector to appear - introduces polymorphic page.waitFor method, which accepts either string (and in this case is a shortcut for page.waitForSelector) or number (and in this case it's a promisified timeout). References #91.
2017-07-21 19:41:49 +00:00
feat: page.waitForTimeout (#6268)
2020-07-28 08:37:49 +00:00
#### page.waitForTimeout(milliseconds)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: page.waitForTimeout (#6268)
2020-07-28 08:37:49 +00:00
- `milliseconds` <[number]> The number of milliseconds to wait for.
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
- returns: <[Promise]> Promise which resolves after the timeout has been completed.
feat: page.waitForTimeout (#6268)
2020-07-28 08:37:49 +00:00
docs(api): fix misleading “seconds” for waitForTimeout (#6619)
2020-11-24 08:24:36 +00:00
Pauses script execution for the given number of milliseconds before continuing:
feat: page.waitForTimeout (#6268)
2020-07-28 08:37:49 +00:00
```js
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
page.waitForTimeout(1000).then(() => console.log('Waited a second!'));
feat: page.waitForTimeout (#6268)
2020-07-28 08:37:49 +00:00
await browser.close();
})();
```
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
#### page.waitForXPath(xpath[, options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- `xpath` <[string]> A [xpath] of an element to wait for
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
- `options` <[Object]> Optional waiting parameters
- `visible` <[boolean]> wait for element to be present in DOM and to be visible, i.e. to not have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
- `hidden` <[boolean]> wait for element to not be found in the DOM or to be hidden, i.e. have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) method.
fix(page): teach waitForSelector to return `null` (#3846) `page.waitForSelector` should return `null` if waiting for `hidden: true` and there's no matching node in DOM. Before this patch, `page.waitForSelector` would return some JSHandle pointing to boolean value.
2019-01-28 19:24:53 +00:00
- returns: <[Promise]<?[ElementHandle]>> Promise which resolves when element specified by xpath string is added to DOM. Resolves to `null` if waiting for `hidden: true` and xpath is not found in DOM.
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
Wait for the `xpath` to appear in page. If at the moment of calling
the method the `xpath` already exists, the method will return
immediately. If the xpath doesn't appear after the `timeout` milliseconds of waiting, the function will throw.
This method works across navigations:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
```js
const puppeteer = require('puppeteer');
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
(async () => {
const browser = await puppeteer.launch();
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
const page = await browser.newPage();
let currentURL;
page
.waitForXPath('//img')
.then(() => console.log('First URL with image: ' + currentURL));
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
for (currentURL of [
'https://example.com',
'https://google.com',
'https://bbc.com',
]) {
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
await page.goto(currentURL);
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
}
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
await browser.close();
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
})();
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
```
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
Shortcut for [page.mainFrame().waitForXPath(xpath[, options])](#framewaitforxpathxpath-options).
feat(Page): introduce workers (#2560) This adds `page.workers()`, and two events `workercreated` and `workerdestroyed`. It also forwards logs from a worker into the page `console` event. Only dedicated workers are supported for now, ServiceWorkers will probably work differently because they aren't necessarily associated with a single page. Fixes #2350.
2018-05-21 21:31:11 +00:00
#### page.workers()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api): fix some typos (#6672)
2020-12-22 12:34:44 +00:00
- returns: <[Array]<[WebWorker]>>
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
This method returns all of the dedicated [WebWorkers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) associated with the page.
feat(Page): introduce workers (#2560) This adds `page.workers()`, and two events `workercreated` and `workerdestroyed`. It also forwards logs from a worker into the page `console` event. Only dedicated workers are supported for now, ServiceWorkers will probably work differently because they aren't necessarily associated with a single page. Fixes #2350.
2018-05-21 21:31:11 +00:00
> **NOTE** This does not contain ServiceWorkers
docs(new): migrate Page.ts to TSDoc (part 0 / 2) (#6104) * docs(new): migrate Page.ts to TSDoc (part 0 / 2) Co-authored-by: Changhao Han <changhaohan@chromium.org>
2020-06-26 07:24:56 +00:00
#### GeolocationOptions
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(new): migrate Page.ts to TSDoc (part 0 / 2) (#6104) * docs(new): migrate Page.ts to TSDoc (part 0 / 2) Co-authored-by: Changhao Han <changhaohan@chromium.org>
2020-06-26 07:24:56 +00:00
- `latitude` <[number]> Latitude between -90 and 90.
- `longitude` <[number]> Longitude between -180 and 180.
- `accuracy` <[number]> Optional non-negative accuracy value.
#### WaitTimeoutOptions
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- `timeout` <[number]> Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to disable the timeout. The default value can be changed by using the [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) method.
docs(new): migrate Page.ts to TSDoc (part 0 / 2) (#6104) * docs(new): migrate Page.ts to TSDoc (part 0 / 2) Co-authored-by: Changhao Han <changhaohan@chromium.org>
2020-06-26 07:24:56 +00:00
chore: rename Worker to WebWorker (#5941) To avoid TS name conflicts.
2020-05-29 11:57:54 +00:00
### class: WebWorker
feat(Page): introduce workers (#2560) This adds `page.workers()`, and two events `workercreated` and `workerdestroyed`. It also forwards logs from a worker into the page `console` event. Only dedicated workers are supported for now, ServiceWorkers will probably work differently because they aren't necessarily associated with a single page. Fixes #2350.
2018-05-21 21:31:11 +00:00
chore: rename Worker to WebWorker (#5941) To avoid TS name conflicts.
2020-05-29 11:57:54 +00:00
The WebWorker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API).
feat(Page): introduce workers (#2560) This adds `page.workers()`, and two events `workercreated` and `workerdestroyed`. It also forwards logs from a worker into the page `console` event. Only dedicated workers are supported for now, ServiceWorkers will probably work differently because they aren't necessarily associated with a single page. Fixes #2350.
2018-05-21 21:31:11 +00:00
The events `workercreated` and `workerdestroyed` are emitted on the page object to signal the worker lifecycle.
```js
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('workercreated', worker =>
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
console.log('Worker created: ' + worker.url())
);
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('workerdestroyed', worker =>
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
console.log('Worker destroyed: ' + worker.url())
);
feat(Page): introduce workers (#2560) This adds `page.workers()`, and two events `workercreated` and `workerdestroyed`. It also forwards logs from a worker into the page `console` event. Only dedicated workers are supported for now, ServiceWorkers will probably work differently because they aren't necessarily associated with a single page. Fixes #2350.
2018-05-21 21:31:11 +00:00
console.log('Current workers:');
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
for (const worker of page.workers()) console.log(' ' + worker.url());
feat(Page): introduce workers (#2560) This adds `page.workers()`, and two events `workercreated` and `workerdestroyed`. It also forwards logs from a worker into the page `console` event. Only dedicated workers are supported for now, ServiceWorkers will probably work differently because they aren't necessarily associated with a single page. Fixes #2350.
2018-05-21 21:31:11 +00:00
```
chore: rename Worker to WebWorker (#5941) To avoid TS name conflicts.
2020-05-29 11:57:54 +00:00
#### webWorker.evaluate(pageFunction[, ...args])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: worker convenience methods (#2677) This patch: - adds `worker.evaluate` and `worker.evaluateHandle` methods as a shortcut to their execution context equivalents. - makes the error messages a bit nicer when interacting with a closed worker (as opposed to a closed page). - moves the worker tests into their own spec file.
2018-06-07 01:16:17 +00:00
- `pageFunction` <[function]|[string]> Function to be evaluated in the worker context
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
- returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
If the function passed to the `worker.evaluate` returns a [Promise], then `worker.evaluate` would wait for the promise to resolve and return its value.
feat(executioncontext): support bigints transferring (#4016) Refs: https://chromedevtools.github.io/devtools-protocol/tot/Runtime#type-UnserializableValue
2019-03-15 17:20:48 +00:00
If the function passed to the `worker.evaluate` returns a non-[Serializable] value, then `worker.evaluate` resolves to `undefined`. DevTools Protocol also supports transferring some additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals.
feat: worker convenience methods (#2677) This patch: - adds `worker.evaluate` and `worker.evaluateHandle` methods as a shortcut to their execution context equivalents. - makes the error messages a bit nicer when interacting with a closed worker (as opposed to a closed page). - moves the worker tests into their own spec file.
2018-06-07 01:16:17 +00:00
Shortcut for [(await worker.executionContext()).evaluate(pageFunction, ...args)](#executioncontextevaluatepagefunction-args).
chore: rename Worker to WebWorker (#5941) To avoid TS name conflicts.
2020-05-29 11:57:54 +00:00
#### webWorker.evaluateHandle(pageFunction[, ...args])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: worker convenience methods (#2677) This patch: - adds `worker.evaluate` and `worker.evaluateHandle` methods as a shortcut to their execution context equivalents. - makes the error messages a bit nicer when interacting with a closed worker (as opposed to a closed page). - moves the worker tests into their own spec file.
2018-06-07 01:16:17 +00:00
- `pageFunction` <[function]|[string]> Function to be evaluated in the page context
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
feat(types): add (and fix) `evaluateHandle` types (#6130) This change started as a small change to pull types from DefinitelyTyped over to Puppeteer for the `evaluateHandle` function but instead ended up also fixing what looks to be a long standing issue with our existing documentation. `evaluateHandle` can in fact return an `ElementHandle` rather than a `JSHandle`. Note that `ElementHandle` extends `JSHandle` so whilst the docs are technically correct (all ElementHandles are JSHandles) it's confusing because JSHandles don't have methods like `click` on them, but ElementHandles do. if you return something that is an HTML element: ``` const button = page.evaluateHandle(() => document.querySelector('button')); // this is an ElementHandle, not a JSHandle ``` Therefore I've updated the original docs and added a large explanation to the TSDoc for `page.evaluateHandle`. In TypeScript land we'll assume the function will return a `JSHandle` but you can tell TS otherwise via the generic argument, which can only be `JSHandle` (the default) or `ElementHandle`: ``` const button = page.evaluateHandle<ElementHandle>(() => document.querySelector('button')); ```
2020-07-01 11:44:08 +00:00
- returns: <[Promise]<[JSHandle]|[ElementHandle]>> Promise which resolves to the return value of `pageFunction` as an in-page object.
feat: worker convenience methods (#2677) This patch: - adds `worker.evaluate` and `worker.evaluateHandle` methods as a shortcut to their execution context equivalents. - makes the error messages a bit nicer when interacting with a closed worker (as opposed to a closed page). - moves the worker tests into their own spec file.
2018-06-07 01:16:17 +00:00
The only difference between `worker.evaluate` and `worker.evaluateHandle` is that `worker.evaluateHandle` returns in-page object (JSHandle).
If the function passed to the `worker.evaluateHandle` returns a [Promise], then `worker.evaluateHandle` would wait for the promise to resolve and return its value.
feat(types): add (and fix) `evaluateHandle` types (#6130) This change started as a small change to pull types from DefinitelyTyped over to Puppeteer for the `evaluateHandle` function but instead ended up also fixing what looks to be a long standing issue with our existing documentation. `evaluateHandle` can in fact return an `ElementHandle` rather than a `JSHandle`. Note that `ElementHandle` extends `JSHandle` so whilst the docs are technically correct (all ElementHandles are JSHandles) it's confusing because JSHandles don't have methods like `click` on them, but ElementHandles do. if you return something that is an HTML element: ``` const button = page.evaluateHandle(() => document.querySelector('button')); // this is an ElementHandle, not a JSHandle ``` Therefore I've updated the original docs and added a large explanation to the TSDoc for `page.evaluateHandle`. In TypeScript land we'll assume the function will return a `JSHandle` but you can tell TS otherwise via the generic argument, which can only be `JSHandle` (the default) or `ElementHandle`: ``` const button = page.evaluateHandle<ElementHandle>(() => document.querySelector('button')); ```
2020-07-01 11:44:08 +00:00
If the function returns an element, the returned handle is an [ElementHandle].
feat: worker convenience methods (#2677) This patch: - adds `worker.evaluate` and `worker.evaluateHandle` methods as a shortcut to their execution context equivalents. - makes the error messages a bit nicer when interacting with a closed worker (as opposed to a closed page). - moves the worker tests into their own spec file.
2018-06-07 01:16:17 +00:00
Shortcut for [(await worker.executionContext()).evaluateHandle(pageFunction, ...args)](#executioncontextevaluatehandlepagefunction-args).
chore: rename Worker to WebWorker (#5941) To avoid TS name conflicts.
2020-05-29 11:57:54 +00:00
#### webWorker.executionContext()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Page): introduce workers (#2560) This adds `page.workers()`, and two events `workercreated` and `workerdestroyed`. It also forwards logs from a worker into the page `console` event. Only dedicated workers are supported for now, ServiceWorkers will probably work differently because they aren't necessarily associated with a single page. Fixes #2350.
2018-05-21 21:31:11 +00:00
- returns: <[Promise]<[ExecutionContext]>>
chore: rename Worker to WebWorker (#5941) To avoid TS name conflicts.
2020-05-29 11:57:54 +00:00
#### webWorker.url()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Page): introduce workers (#2560) This adds `page.workers()`, and two events `workercreated` and `workerdestroyed`. It also forwards logs from a worker into the page `console` event. Only dedicated workers are supported for now, ServiceWorkers will probably work differently because they aren't necessarily associated with a single page. Fixes #2350.
2018-05-21 21:31:11 +00:00
- returns: <[string]>
feat(accessibility): snapshot the accessibility tree (#3470) This adds `page.accessibility.snapshot()`. It serializes and returns the accessibility tree for the page. By default, uninteresting nodes are filtered out of the snapshot. fixes #2033
2018-11-02 01:54:51 +00:00
### class: Accessibility
fix(docs): screen readers aren't the only kind of assistive technology (#4349) The docs incorrectly implied that screen readers were the only assistive technology to do filtering on the tree. @alice
2019-04-26 20:40:08 +00:00
The Accessibility class provides methods for inspecting Chromium's accessibility tree. The accessibility tree is used by assistive technology such as [screen readers](https://en.wikipedia.org/wiki/Screen_reader) or [switches](https://en.wikipedia.org/wiki/Switch_access).
feat(accessibility): snapshot the accessibility tree (#3470) This adds `page.accessibility.snapshot()`. It serializes and returns the accessibility tree for the page. By default, uninteresting nodes are filtered out of the snapshot. fixes #2033
2018-11-02 01:54:51 +00:00
Accessibility is a very platform-specific thing. On different platforms, there are different screen readers that might have wildly different output.
docs(api.md): fix typo (#5120)
2019-11-02 22:42:29 +00:00
Blink - Chrome's rendering engine - has a concept of "accessibility tree", which is then translated into different platform-specific APIs. Accessibility namespace gives users
feat(accessibility): snapshot the accessibility tree (#3470) This adds `page.accessibility.snapshot()`. It serializes and returns the accessibility tree for the page. By default, uninteresting nodes are filtered out of the snapshot. fixes #2033
2018-11-02 01:54:51 +00:00
access to the Blink Accessibility Tree.
fix(docs): screen readers aren't the only kind of assistive technology (#4349) The docs incorrectly implied that screen readers were the only assistive technology to do filtering on the tree. @alice
2019-04-26 20:40:08 +00:00
Most of the accessibility tree gets filtered out when converting from Blink AX Tree to Platform-specific AX-Tree or by assistive technologies themselves. By default, Puppeteer tries to approximate this filtering, exposing only the "interesting" nodes of the tree.
feat(accessibility): snapshot the accessibility tree (#3470) This adds `page.accessibility.snapshot()`. It serializes and returns the accessibility tree for the page. By default, uninteresting nodes are filtered out of the snapshot. fixes #2033
2018-11-02 01:54:51 +00:00
#### accessibility.snapshot([options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(accessibility): snapshot the accessibility tree (#3470) This adds `page.accessibility.snapshot()`. It serializes and returns the accessibility tree for the page. By default, uninteresting nodes are filtered out of the snapshot. fixes #2033
2018-11-02 01:54:51 +00:00
- `options` <[Object]>
- `interestingOnly` <[boolean]> Prune uninteresting nodes from the tree. Defaults to `true`.
feat: `root` option in page.accessibility.snapshot() (#4318) Going from `AXNode` -> `ElementHandle` is turning out to be controversial. This patch instead adds a way to go from `ElementHandle` -> `AXNode`. If the API looks good, I'll add it into Firefox as well. References #3641
2019-05-10 06:39:42 +00:00
- `root` <[ElementHandle]> The root DOM element for the snapshot. Defaults to the whole page.
chore(types): generate our own d.ts file from api.md (#3744) Generate `//index.d.ts` file with precise typescript definitions for all of the Puppeteer API.
2019-01-28 23:12:45 +00:00
- returns: <[Promise]<[Object]>> An [AXNode] object with the following properties:
feat(accessibility): snapshot the accessibility tree (#3470) This adds `page.accessibility.snapshot()`. It serializes and returns the accessibility tree for the page. By default, uninteresting nodes are filtered out of the snapshot. fixes #2033
2018-11-02 01:54:51 +00:00
- `role` <[string]> The [role](https://www.w3.org/TR/wai-aria/#usage_intro).
- `name` <[string]> A human readable name for the node.
- `value` <[string]|[number]> The current value of the node.
- `description` <[string]> An additional human readable description of the node.
- `keyshortcuts` <[string]> Keyboard shortcuts associated with this node.
- `roledescription` <[string]> A human readable alternative to the role.
- `valuetext` <[string]> A description of the current value.
- `disabled` <[boolean]> Whether the node is disabled.
- `expanded` <[boolean]> Whether the node is expanded or collapsed.
- `focused` <[boolean]> Whether the node is focused.
- `modal` <[boolean]> Whether the node is [modal](https://en.wikipedia.org/wiki/Modal_window).
- `multiline` <[boolean]> Whether the node text input supports multiline.
- `multiselectable` <[boolean]> Whether more than one child can be selected.
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
- `readonly` <[boolean]> Whether the node is read-only.
feat(accessibility): snapshot the accessibility tree (#3470) This adds `page.accessibility.snapshot()`. It serializes and returns the accessibility tree for the page. By default, uninteresting nodes are filtered out of the snapshot. fixes #2033
2018-11-02 01:54:51 +00:00
- `required` <[boolean]> Whether the node is required.
- `selected` <[boolean]> Whether the node is selected in its parent node.
fix(types): fix parameters where they disagree with the api (#3525)
2018-11-12 20:59:21 +00:00
- `checked` <[boolean]|"mixed"> Whether the checkbox is checked, or "mixed".
- `pressed` <[boolean]|"mixed"> Whether the toggle button is checked, or "mixed".
feat(accessibility): snapshot the accessibility tree (#3470) This adds `page.accessibility.snapshot()`. It serializes and returns the accessibility tree for the page. By default, uninteresting nodes are filtered out of the snapshot. fixes #2033
2018-11-02 01:54:51 +00:00
- `level` <[number]> The level of a heading.
- `valuemin` <[number]> The minimum value in a node.
- `valuemax` <[number]> The maximum value in a node.
- `autocomplete` <[string]> What kind of autocomplete is supported by a control.
- `haspopup` <[string]> What kind of popup is currently being shown for a node.
- `invalid` <[string]> Whether and in what way this node's value is invalid.
- `orientation` <[string]> Whether the node is oriented horizontally or vertically.
fix(types): fix parameters where they disagree with the api (#3525)
2018-11-12 20:59:21 +00:00
- `children` <[Array]<[Object]>> Child [AXNode]s of this node, if any.
feat(accessibility): snapshot the accessibility tree (#3470) This adds `page.accessibility.snapshot()`. It serializes and returns the accessibility tree for the page. By default, uninteresting nodes are filtered out of the snapshot. fixes #2033
2018-11-02 01:54:51 +00:00
Captures the current state of the accessibility tree. The returned object represents the root accessible node of the page.
> **NOTE** The Chromium accessibility tree contains nodes that go unused on most platforms and by
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
> most screen readers. Puppeteer will discard them as well for an easier to process tree,
> unless `interestingOnly` is set to `false`.
feat(accessibility): snapshot the accessibility tree (#3470) This adds `page.accessibility.snapshot()`. It serializes and returns the accessibility tree for the page. By default, uninteresting nodes are filtered out of the snapshot. fixes #2033
2018-11-02 01:54:51 +00:00
An example of dumping the entire accessibility tree:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(accessibility): snapshot the accessibility tree (#3470) This adds `page.accessibility.snapshot()`. It serializes and returns the accessibility tree for the page. By default, uninteresting nodes are filtered out of the snapshot. fixes #2033
2018-11-02 01:54:51 +00:00
```js
const snapshot = await page.accessibility.snapshot();
console.log(snapshot);
```
An example of logging the focused node's name:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(accessibility): snapshot the accessibility tree (#3470) This adds `page.accessibility.snapshot()`. It serializes and returns the accessibility tree for the page. By default, uninteresting nodes are filtered out of the snapshot. fixes #2033
2018-11-02 01:54:51 +00:00
```js
const snapshot = await page.accessibility.snapshot();
const node = findFocusedNode(snapshot);
console.log(node && node.name);
function findFocusedNode(node) {
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
if (node.focused) return node;
feat(accessibility): snapshot the accessibility tree (#3470) This adds `page.accessibility.snapshot()`. It serializes and returns the accessibility tree for the page. By default, uninteresting nodes are filtered out of the snapshot. fixes #2033
2018-11-02 01:54:51 +00:00
for (const child of node.children || []) {
const foundNode = findFocusedNode(child);
return foundNode;
}
return null;
}
```
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
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
Keyboard provides an API for managing a virtual keyboard. The high-level API is [`keyboard.type`](#keyboardtypetext-options), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page.
Intorduce Page.keyboard (#74) Introduce page.keyboard to provide low-level access to the keyboard.
2017-07-18 01:49:52 +00:00
Rename keyboard.hold and release to up and down (#95) References #89
2017-07-19 21:27:01 +00:00
For finer control, you can use [`keyboard.down`](#keyboarddownkey-options), [`keyboard.up`](#keyboardupkey), and [`keyboard.sendCharacter`](#keyboardsendcharacterchar) to manually fire events as if they were generated from a real keyboard.
Intorduce Page.keyboard (#74) Introduce page.keyboard to provide low-level access to the keyboard.
2017-07-18 01:49:52 +00:00
An example of holding down `Shift` in order to select and delete some text:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
```js
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
await page.keyboard.type('Hello World!');
await page.keyboard.press('ArrowLeft');
Intorduce Page.keyboard (#74) Introduce page.keyboard to provide low-level access to the keyboard.
2017-07-18 01:49:52 +00:00
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
await page.keyboard.down('Shift');
Remove keyboard.type and keyboard.press (#98) This patch removes keyboard.type and keyboard.press methods. The motivation behind this is to keep only low-level API in the `keyboard` namespace.
2017-07-22 03:00:09 +00:00
for (let i = 0; i < ' World'.length; i++)
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
await page.keyboard.press('ArrowLeft');
await page.keyboard.up('Shift');
Intorduce Page.keyboard (#74) Introduce page.keyboard to provide low-level access to the keyboard.
2017-07-18 01:49:52 +00:00
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
await page.keyboard.press('Backspace');
Intorduce Page.keyboard (#74) Introduce page.keyboard to provide low-level access to the keyboard.
2017-07-18 01:49:52 +00:00
// Result text will end up saying 'Hello!'
```
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
An example of pressing `A`
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
```js
await page.keyboard.down('Shift');
await page.keyboard.press('KeyA');
await page.keyboard.up('Shift');
```
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
> **NOTE** On macOS, keyboard shortcuts like `⌘ A` -> Select All does not work. See [#1313](https://github.com/puppeteer/puppeteer/issues/1313)
docs: document osx keyboard shortcuts not working (#1311) Fixes #776
2017-11-08 00:22:58 +00:00
Rename keyboard.hold and release to up and down (#95) References #89
2017-07-19 21:27:01 +00:00
#### keyboard.down(key[, options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(keyboard): Accept codes (#1116) BREAKING CHANGE: This patch lets key names be code in addition to key. When specifying a code, the proper text is generated assuming a standard US keyboard layout. e.g Digit5 -> "5" or "%" depending on Shift. * location is now specified. #777 * Using unknown key names now throws an error. #723 * Typing newlines now correctly presses enter. #681
2017-10-23 19:43:45 +00:00
- `key` <[string]> Name of key to press, such as `ArrowLeft`. See [USKeyboardLayout] for a list of all key names.
Intorduce Page.keyboard (#74) Introduce page.keyboard to provide low-level access to the keyboard.
2017-07-18 01:49:52 +00:00
- `options` <[Object]>
- `text` <[string]> If specified, generates an input event with this text.
- returns: <[Promise]>
Dispatches a `keydown` event.
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`/`input` event will also be generated. The `text` option can be specified to force an input event to be generated.
Intorduce Page.keyboard (#74) Introduce page.keyboard to provide low-level access to the keyboard.
2017-07-18 01:49:52 +00:00
Rename keyboard.hold and release to up and down (#95) References #89
2017-07-19 21:27:01 +00:00
If `key` is a modifier key, `Shift`, `Meta`, `Control`, or `Alt`, subsequent key presses will be sent with that modifier active. To release the modifier key, use [`keyboard.up`](#keyboardupkey).
Intorduce Page.keyboard (#74) Introduce page.keyboard to provide low-level access to the keyboard.
2017-07-18 01:49:52 +00:00
Specify repeat property on repeated keypresses (#172) This patch implements 'autoRepeat' functionality for `keyboard.down`. With this patch, the subsequent calls to `keyboard.down` would generate an event with 'autoRepeat` flag set to true. Closes #157
2017-07-31 19:05:46 +00:00
After the key is pressed once, subsequent calls to [`keyboard.down`](#keyboarddownkey-options) will have [repeat](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/repeat) set to true. To release the key, use [`keyboard.up`](#keyboardupkey).
docs: use less confusing synonym This change was suggested in #1636.
2017-12-28 03:35:14 +00:00
> **NOTE** Modifier keys DO influence `keyboard.down`. Holding down `Shift` will type the text in upper case.
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
#### keyboard.press(key[, options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(keyboard): Accept codes (#1116) BREAKING CHANGE: This patch lets key names be code in addition to key. When specifying a code, the proper text is generated assuming a standard US keyboard layout. e.g Digit5 -> "5" or "%" depending on Shift. * location is now specified. #777 * Using unknown key names now throws an error. #723 * Typing newlines now correctly presses enter. #681
2017-10-23 19:43:45 +00:00
- `key` <[string]> Name of key to press, such as `ArrowLeft`. See [USKeyboardLayout] for a list of all key names.
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
- `options` <[Object]>
- `text` <[string]> If specified, generates an input event with this text.
- `delay` <[number]> Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
- returns: <[Promise]>
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`/`input` event will also be generated. The `text` option can be specified to force an input event to be generated.
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
docs: fix effect -> affect typos (#5985)
2020-06-23 05:24:15 +00:00
> **NOTE** Modifier keys DO affect `keyboard.press`. Holding down `Shift` will type the text in upper case.
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
Shortcut for [`keyboard.down`](#keyboarddownkey-options) and [`keyboard.up`](#keyboardupkey).
Intorduce Page.keyboard (#74) Introduce page.keyboard to provide low-level access to the keyboard.
2017-07-18 01:49:52 +00:00
#### keyboard.sendCharacter(char)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- `char` <[string]> Character to send into the page.
- returns: <[Promise]>
Dispatches a `keypress` and `input` event. This does not send a `keydown` or `keyup` event.
```js
page.keyboard.sendCharacter('嗨');
```
docs: fix effect -> affect typos (#5985)
2020-06-23 05:24:15 +00:00
> **NOTE** Modifier keys DO NOT affect `keyboard.sendCharacter`. Holding down `Shift` will not type the text in upper case.
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### keyboard.type(text[, options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
- `text` <[string]> A text to type into a focused element.
- `options` <[Object]>
- `delay` <[number]> Time to wait between key presses in milliseconds. Defaults to 0.
- returns: <[Promise]>
Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
To press a special key, like `Control` or `ArrowDown`, use [`keyboard.press`](#keyboardpresskey-options).
```js
docs(api): clarify `type` method examples (#5010)
2019-10-07 06:32:35 +00:00
await page.keyboard.type('Hello'); // Types instantly
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
await page.keyboard.type('World', {delay: 100}); // Types slower, like a user
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
```
docs: fix effect -> affect typos (#5985)
2020-06-23 05:24:15 +00:00
> **NOTE** Modifier keys DO NOT affect `keyboard.type`. Holding down `Shift` will not type the text in upper case.
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
Rename keyboard.hold and release to up and down (#95) References #89
2017-07-19 21:27:01 +00:00
#### keyboard.up(key)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(keyboard): Accept codes (#1116) BREAKING CHANGE: This patch lets key names be code in addition to key. When specifying a code, the proper text is generated assuming a standard US keyboard layout. e.g Digit5 -> "5" or "%" depending on Shift. * location is now specified. #777 * Using unknown key names now throws an error. #723 * Typing newlines now correctly presses enter. #681
2017-10-23 19:43:45 +00:00
- `key` <[string]> Name of key to release, such as `ArrowLeft`. See [USKeyboardLayout] for a list of all key names.
Rename keyboard.hold and release to up and down (#95) References #89
2017-07-19 21:27:01 +00:00
- returns: <[Promise]>
Dispatches a `keyup` event.
Mouse (#101) This patch: - adds Mouse class which holds mouse state and implements mouse primitives, such as moving, button down and button up. - implements high-level mouse api, such as `page.click` and `page.hover`. References #40, References #89
2017-07-22 03:29:31 +00:00
### class: Mouse
docs(api.md): clarify coordinate system in mouse (#3041)
2018-08-07 21:24:38 +00:00
The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport.
docs(api): fixed grammatical error (it's -> its) #3352 Fixed incorrect use of "it's".
2018-10-04 23:09:08 +00:00
Every `page` object has its own Mouse, accessible with [`page.mouse`](#pagemouse).
docs(api.md): add example for Mouse class (#3244) Fixes #3221.
2018-09-14 18:48:47 +00:00
```js
// Using ‘page.mouse’ to trace a 100x100 square.
await page.mouse.move(0, 0);
await page.mouse.down();
await page.mouse.move(0, 100);
await page.mouse.move(100, 100);
await page.mouse.move(100, 0);
await page.mouse.move(0, 0);
await page.mouse.up();
```
docs(api): add copy-pasting text example to Mouse class (#6000) There are numerous issues on the Puppeteer issue tracker about selecting and copy-pasting of text (#3252, #4954, #423, #1366, #343) as well as several StackOverflow questions: - https://stackoverflow.com/questions/57101467/how-do-you-paste-text-using-puppeteer - https://stackoverflow.com/questions/49131516/how-to-copy-text-from-browser-clipboard-using-puppeteer-in-nodejs - https://stackoverflow.com/questions/60158746/how-do-i-access-the-contents-of-the-clipboard-from-within-a-headless-puppeteer-t - https://stackoverflow.com/questions/56306153/domexception-on-calling-navigator-clipboard-readtext I propose we include this commonly-asked question in the main documentation. Fixes #3252. Fixes #4954.
2020-06-12 05:32:59 +00:00
Note that the mouse events trigger synthetic `MouseEvent`s.
This means that it does not fully replicate the functionality of what a normal user would be able to do with their mouse.
For example, dragging and selecting text is not possible using `page.mouse`.
Instead, you can use the [`DocumentOrShadowRoot.getSelection()`](https://developer.mozilla.org/en-US/docs/Web/API/DocumentOrShadowRoot/getSelection) functionality implemented in the platform.
For example, if you want to select all content between nodes:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api): add copy-pasting text example to Mouse class (#6000) There are numerous issues on the Puppeteer issue tracker about selecting and copy-pasting of text (#3252, #4954, #423, #1366, #343) as well as several StackOverflow questions: - https://stackoverflow.com/questions/57101467/how-do-you-paste-text-using-puppeteer - https://stackoverflow.com/questions/49131516/how-to-copy-text-from-browser-clipboard-using-puppeteer-in-nodejs - https://stackoverflow.com/questions/60158746/how-do-i-access-the-contents-of-the-clipboard-from-within-a-headless-puppeteer-t - https://stackoverflow.com/questions/56306153/domexception-on-calling-navigator-clipboard-readtext I propose we include this commonly-asked question in the main documentation. Fixes #3252. Fixes #4954.
2020-06-12 05:32:59 +00:00
```js
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
await page.evaluate(
(from, to) => {
const selection = from.getRootNode().getSelection();
const range = document.createRange();
range.setStartBefore(from);
range.setEndAfter(to);
selection.removeAllRanges();
selection.addRange(range);
},
fromJSHandle,
toJSHandle
);
docs(api): add copy-pasting text example to Mouse class (#6000) There are numerous issues on the Puppeteer issue tracker about selecting and copy-pasting of text (#3252, #4954, #423, #1366, #343) as well as several StackOverflow questions: - https://stackoverflow.com/questions/57101467/how-do-you-paste-text-using-puppeteer - https://stackoverflow.com/questions/49131516/how-to-copy-text-from-browser-clipboard-using-puppeteer-in-nodejs - https://stackoverflow.com/questions/60158746/how-do-i-access-the-contents-of-the-clipboard-from-within-a-headless-puppeteer-t - https://stackoverflow.com/questions/56306153/domexception-on-calling-navigator-clipboard-readtext I propose we include this commonly-asked question in the main documentation. Fixes #3252. Fixes #4954.
2020-06-12 05:32:59 +00:00
```
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
If you then would want to copy-paste your selection, you can use the clipboard API:
docs(api): add copy-pasting text example to Mouse class (#6000) There are numerous issues on the Puppeteer issue tracker about selecting and copy-pasting of text (#3252, #4954, #423, #1366, #343) as well as several StackOverflow questions: - https://stackoverflow.com/questions/57101467/how-do-you-paste-text-using-puppeteer - https://stackoverflow.com/questions/49131516/how-to-copy-text-from-browser-clipboard-using-puppeteer-in-nodejs - https://stackoverflow.com/questions/60158746/how-do-i-access-the-contents-of-the-clipboard-from-within-a-headless-puppeteer-t - https://stackoverflow.com/questions/56306153/domexception-on-calling-navigator-clipboard-readtext I propose we include this commonly-asked question in the main documentation. Fixes #3252. Fixes #4954.
2020-06-12 05:32:59 +00:00
```js
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
// The clipboard API does not allow you to copy, unless the tab is focused.
docs(api): add copy-pasting text example to Mouse class (#6000) There are numerous issues on the Puppeteer issue tracker about selecting and copy-pasting of text (#3252, #4954, #423, #1366, #343) as well as several StackOverflow questions: - https://stackoverflow.com/questions/57101467/how-do-you-paste-text-using-puppeteer - https://stackoverflow.com/questions/49131516/how-to-copy-text-from-browser-clipboard-using-puppeteer-in-nodejs - https://stackoverflow.com/questions/60158746/how-do-i-access-the-contents-of-the-clipboard-from-within-a-headless-puppeteer-t - https://stackoverflow.com/questions/56306153/domexception-on-calling-navigator-clipboard-readtext I propose we include this commonly-asked question in the main documentation. Fixes #3252. Fixes #4954.
2020-06-12 05:32:59 +00:00
await page.bringToFront();
await page.evaluate(() => {
// Copy the selected content to the clipboard
document.execCommand('copy');
// Obtain the content of the clipboard as a string
return navigator.clipboard.readText();
});
```
Note that if you want access to the clipboard API, you have to give it permission to do so:
```js
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
await browser
.defaultBrowserContext()
.overridePermissions('<your origin>', ['clipboard-read', 'clipboard-write']);
docs(api): add copy-pasting text example to Mouse class (#6000) There are numerous issues on the Puppeteer issue tracker about selecting and copy-pasting of text (#3252, #4954, #423, #1366, #343) as well as several StackOverflow questions: - https://stackoverflow.com/questions/57101467/how-do-you-paste-text-using-puppeteer - https://stackoverflow.com/questions/49131516/how-to-copy-text-from-browser-clipboard-using-puppeteer-in-nodejs - https://stackoverflow.com/questions/60158746/how-do-i-access-the-contents-of-the-clipboard-from-within-a-headless-puppeteer-t - https://stackoverflow.com/questions/56306153/domexception-on-calling-navigator-clipboard-readtext I propose we include this commonly-asked question in the main documentation. Fixes #3252. Fixes #4954.
2020-06-12 05:32:59 +00:00
```
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### mouse.click(x, y[, options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
Implement mouse.click(x,y) (#131) Closes #107
2017-07-25 23:05:23 +00:00
- `x` <[number]>
- `y` <[number]>
- `options` <[Object]>
feat: add `back` and `forward` mouse buttons (#8284)
2022-04-27 21:00:07 +00:00
- `button` <"left"|"right"|"middle"|"back"|"forward"> Defaults to `left`.
Readme fixup part 1 (#278)
2017-08-16 06:04:16 +00:00
- `clickCount` <[number]> defaults to 1. See [UIEvent.detail].
Add delay option to input methods (#171) Add delay option to input methods for the keyboard and mouse. Closes #156
2017-08-01 01:18:15 +00:00
- `delay` <[number]> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
Implement mouse.click(x,y) (#131) Closes #107
2017-07-25 23:05:23 +00:00
- returns: <[Promise]>
doc: fix a link (#856)
2017-09-22 23:16:52 +00:00
Shortcut for [`mouse.move`](#mousemovex-y-options), [`mouse.down`](#mousedownoptions) and [`mouse.up`](#mouseupoptions).
Implement mouse.click(x,y) (#131) Closes #107
2017-07-25 23:05:23 +00:00
Mouse (#101) This patch: - adds Mouse class which holds mouse state and implements mouse primitives, such as moving, button down and button up. - implements high-level mouse api, such as `page.click` and `page.hover`. References #40, References #89
2017-07-22 03:29:31 +00:00
#### mouse.down([options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- `options` <[Object]>
feat: add `back` and `forward` mouse buttons (#8284)
2022-04-27 21:00:07 +00:00
- `button` <"left"|"right"|"middle"|"back"|"forward"> 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.
feat: add drag-and-drop support (#7150) This commit adds drag-and-drop support, leveraging new additions to the CDP Input domain (Input.setInterceptDrags, Input.dispatchDragEvent, and Input.dragIntercepted).
2021-06-04 10:25:36 +00:00
#### mouse.drag(start, target)
- `start` <[Object]> the position to start dragging from
- `x` <[number]> x coordinate
- `y` <[number]> y coordinate
- `target` <[Object]> the position to drag to
- `x` <[number]> x coordinate
- `y` <[number]> y coordinate
- returns: <[Promise<[DragData]>]>
This method creates and captures a dragevent from a given point.
#### mouse.dragAndDrop(start, target[, options])
- `start` <[Object]>
- `x` <[number]> x coordinate
- `y` <[number]> y coordinate
- `target` <[Object]>
- `x` <[number]> x coordinate
- `y` <[number]> y coordinate
- `options` <[Object]>
- `delay` <[number]> how long to delay before dropping onto the target point
- returns: <[Promise<[DragData]>]>
This method drags from a given start point and drops onto a target point.
#### mouse.dragEnter(target, data)
- `target` <[Object]>
- `x` <[number]> x coordinate
- `y` <[number]> y coordinate
- `data` <[Object]>
- returns: <[Promise]]>
This method triggers a dragenter event from the target point.
#### mouse.dragOver(target, data)
- `target` <[Object]>
- `x` <[number]> x coordinate
- `y` <[number]> y coordinate
- `data` <[Object]>
- returns: <[Promise]]>
This method triggers a dragover event from the target point.
#### mouse.drop(target, data)
- `target` <[Object]>
- `x` <[number]> x coordinate
- `y` <[number]> y coordinate
- `data` <[Object]>
- returns: <[Promise]]>
This method triggers a drop event from the target point.
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### mouse.move(x, y[, options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- `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])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- `options` <[Object]>
feat: add `back` and `forward` mouse buttons (#8284)
2022-04-27 21:00:07 +00:00
- `button` <"left"|"right"|"middle"|"back"|"forward"> 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.
feat: add Mouse#wheel (#6141)
2020-07-06 07:27:17 +00:00
#### mouse.wheel([options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: add Mouse#wheel (#6141)
2020-07-06 07:27:17 +00:00
- `options` <[Object]>
docs(api): fix description of mouse wheel options (#6643)
2020-12-02 14:41:11 +00:00
- `deltaX` X delta in CSS pixels for mouse wheel event (default: 0). Positive values emulate a scroll right and negative values a scroll left event.
- `deltaY` Y delta in CSS pixels for mouse wheel event (default: 0). Positive values emulate a scroll down and negative values a scroll up event.
feat: add Mouse#wheel (#6141)
2020-07-06 07:27:17 +00:00
- returns: <[Promise]>
Dispatches a `mousewheel` event.
Examples:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: add Mouse#wheel (#6141)
2020-07-06 07:27:17 +00:00
```js
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
await page.goto(
'https://mdn.mozillademos.org/en-US/docs/Web/API/Element/wheel_event$samples/Scaling_an_element_via_the_wheel?revision=1587366'
);
feat: add Mouse#wheel (#6141)
2020-07-06 07:27:17 +00:00
const elem = await page.$('div');
const boundingBox = await elem.boundingBox();
await page.mouse.move(
boundingBox.x + boundingBox.width / 2,
boundingBox.y + boundingBox.height / 2
);
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
await page.mouse.wheel({deltaY: -100});
feat: add Mouse#wheel (#6141)
2020-07-06 07:27:17 +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
### class: Touchscreen
#### touchscreen.tap(x, y)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- `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
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +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
```
fix(tracing): start without options (#4388)
2019-05-10 00:15:33 +00:00
#### tracing.start([options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
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]>
feat(Tracing): return a buffer from tracing.stop (#2360) Fixes #2148
2018-04-12 15:26:50 +00:00
- `path` <[string]> A path to write the trace file to.
Introduce page.tracing (#181) This patch introduces page.tracing, which allows to start and stop trace recording for a page. The trace could be then saved to file.
2017-08-02 17:45:11 +00:00
- `screenshots` <[boolean]> captures screenshots in the trace.
docs(api.md): Note that Browser and Page extend from EventEmitter (#1541) Adds notes to the API documentation that Browser and Page classes are EventEmitters. Provides an example of using `.once` for Page. Fixes #1231
2017-12-06 07:53:27 +00:00
- `categories` <[Array]<[string]>> specify custom categories to use instead of default.
Introduce page.tracing (#181) This patch introduces page.tracing, which allows to start and stop trace recording for a page. The trace could be then saved to file.
2017-08-02 17:45:11 +00:00
- returns: <[Promise]>
[doc] Remove mention of broken javascript dialogs from api.md (#210)
2017-08-04 08:12:18 +00:00
Only one trace can be active at a time per browser.
Move path option into tracing.start (#192) This consolidates all the tracing options in the tracing.start()
2017-08-02 22:41:05 +00:00
#### tracing.stop()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Tracing): return a buffer from tracing.stop (#2360) Fixes #2148
2018-04-12 15:26:50 +00:00
- returns: <[Promise]<[Buffer]>> Promise which resolves to buffer with trace data.
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
feat(page): introduce file chooser interception (#4653) This patch introduces a page.waitForFileChooser() method that adds a watchdog to wait for file chooser dialogs. This lets Puppeteer users to capture file chooser requests and fulfill/cancel them if necessary. Fixes #2946
2019-07-23 04:30:49 +00:00
### class: FileChooser
[FileChooser] objects are returned via the ['page.waitForFileChooser'](#pagewaitforfilechooseroptions) method.
docs(api): clarify “file chooser” meaning (#7534) Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-09-01 07:51:09 +00:00
File choosers let you react to the page requesting for file(s) to be loaded by the web app. (This file chooser does not cover the “Save file” dialog.)
feat(page): introduce file chooser interception (#4653) This patch introduces a page.waitForFileChooser() method that adds a watchdog to wait for file chooser dialogs. This lets Puppeteer users to capture file chooser requests and fulfill/cancel them if necessary. Fixes #2946
2019-07-23 04:30:49 +00:00
An example of using [FileChooser]:
```js
const [fileChooser] = await Promise.all([
page.waitForFileChooser(),
page.click('#upload-file-button'), // some button that triggers file selection
]);
await fileChooser.accept(['/tmp/myfile.pdf']);
```
> **NOTE** In browsers, only one file chooser can be opened at a time.
> All file choosers must be accepted or canceled. Not doing so will prevent subsequent file choosers from appearing.
#### fileChooser.accept(filePaths)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- `filePaths` <[Array]<[string]>> Accept the file chooser request with given paths. If some of the `filePaths` are relative paths, then they are resolved relative to the [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
feat(page): introduce file chooser interception (#4653) This patch introduces a page.waitForFileChooser() method that adds a watchdog to wait for file chooser dialogs. This lets Puppeteer users to capture file chooser requests and fulfill/cancel them if necessary. Fixes #2946
2019-07-23 04:30:49 +00:00
- returns: <[Promise]>
#### fileChooser.cancel()
Closes the file chooser without selecting any files.
#### fileChooser.isMultiple()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(page): introduce file chooser interception (#4653) This patch introduces a page.waitForFileChooser() method that adds a watchdog to wait for file chooser dialogs. This lets Puppeteer users to capture file chooser requests and fulfill/cancel them if necessary. Fixes #2946
2019-07-23 04:30:49 +00:00
- returns: <[boolean]> Whether file chooser allow for [multiple](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#attr-multiple) file selection.
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:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
[doc] add examples for Dialog and Frame classes
2017-07-17 18:02:13 +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');
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
(async () => {
const browser = await puppeteer.launch();
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();
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('dialog', async dialog => {
[doc] add examples for Dialog and Frame classes
2017-07-17 18:02:13 +00:00
console.log(dialog.message());
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
await dialog.dismiss();
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
[doc] add examples for Dialog and Frame classes
2017-07-17 18:02:13 +00:00
});
page.evaluate(() => alert('1'));
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
})();
[doc] add examples for Dialog and Frame classes
2017-07-17 18:02:13 +00:00
```
[doclint] Fix bug in documentation linter This patch: - fixes a typo in documentation linter, which resulted in only certain method arguments being linted. - adds missing arguments to the documentation References #14.
2017-07-12 00:01:58 +00:00
#### dialog.accept([promptText])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- `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()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- 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()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
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()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- returns: <[string]> A message displayed in the dialog.
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
#### dialog.type()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
- returns: <[string]> Dialog's type, can be one of `alert`, `beforeunload`, `confirm` or `prompt`.
[doclint] add linting for class properties This patch: - adds linting for class properties - adds documentation for the missing class properties References #14.
2017-07-12 15:01:21 +00:00
feat(Console): Introduce ConsoleMessage type (#909) This patch introduces ConsoleMessage type and starts dispatching it for the 'console' event. BREAKING CHANGE: this breaks the api of the 'console' event. Fixes #744.
2017-09-29 18:27:22 +00:00
### class: ConsoleMessage
[ConsoleMessage] objects are dispatched by page via the ['console'](#event-console) event.
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
#### consoleMessage.args()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
- returns: <[Array]<[JSHandle]>>
feat(Console): Introduce ConsoleMessage type (#909) This patch introduces ConsoleMessage type and starts dispatching it for the 'console' event. BREAKING CHANGE: this breaks the api of the 'console' event. Fixes #744.
2017-09-29 18:27:22 +00:00
feat(page): introduce consoleMessage.location() (#3365) This patch adds a new consoleMessage.location() method that returns console message origins. Fixes #3029
2019-01-11 00:51:13 +00:00
#### consoleMessage.location()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(page): introduce consoleMessage.location() (#3365) This patch adds a new consoleMessage.location() method that returns console message origins. Fixes #3029
2019-01-11 00:51:13 +00:00
- returns: <[Object]>
fix(page): consoleMessage.location() should work with workers (#3752) This patch: - refactors consoleMessage.location() implementation to make it work for workers - re-writes tests to avoid 5 second delay
2019-01-11 02:05:28 +00:00
- `url` <[string]> URL of the resource if known or `undefined` otherwise.
feat(firefox): support consoleMessage.location() (#4002)
2019-02-14 03:56:56 +00:00
- `lineNumber` <[number]> 0-based line number in the resource if known or `undefined` otherwise.
- `columnNumber` <[number]> 0-based column number in the resource if known or `undefined` otherwise.
feat(console): expose stack trace for console messages (#6445)
2020-09-25 13:27:13 +00:00
#### consoleMessage.stackTrace()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(console): expose stack trace for console messages (#6445)
2020-09-25 13:27:13 +00:00
- returns: <[Array]<[Object]>>
- `url` <[string]> URL of the resource if known or `undefined` otherwise.
- `lineNumber` <[number]> 0-based line number in the resource if known or `undefined` otherwise.
- `columnNumber` <[number]> 0-based column number in the resource if known or `undefined` otherwise.
feat(page): introduce consoleMessage.location() (#3365) This patch adds a new consoleMessage.location() method that returns console message origins. Fixes #3029
2019-01-11 00:51:13 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
#### consoleMessage.text()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
- returns: <[string]>
feat(Console): Introduce ConsoleMessage type (#909) This patch introduces ConsoleMessage type and starts dispatching it for the 'console' event. BREAKING CHANGE: this breaks the api of the 'console' event. Fixes #744.
2017-09-29 18:27:22 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
#### consoleMessage.type()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
- returns: <[string]>
feat(Console): Introduce ConsoleMessage type (#909) This patch introduces ConsoleMessage type and starts dispatching it for the 'console' event. BREAKING CHANGE: this breaks the api of the 'console' event. Fixes #744.
2017-09-29 18:27:22 +00:00
One of the following values: `'log'`, `'debug'`, `'info'`, `'error'`, `'warning'`, `'dir'`, `'dirxml'`, `'table'`, `'trace'`, `'clear'`, `'startGroup'`, `'startGroupCollapsed'`, `'endGroup'`, `'assert'`, `'profile'`, `'profileEnd'`, `'count'`, `'timeEnd'`.
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
### class: Frame
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
At every point of time, page exposes its current frame tree via the [page.mainFrame()](#pagemainframe) and [frame.childFrames()](#framechildframes) methods.
[Frame] object's lifecycle is controlled by three events, dispatched on the page object:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
- ['frameattached'](#event-frameattached) - fired when the frame gets attached to the page. A Frame can be attached to the page only once.
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
- ['framenavigated'](#event-framenavigated) - fired when the frame commits navigation to a different URL.
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- ['framedetached'](#event-framedetached) - fired when the frame gets detached from the page. A Frame can be detached from the page only once.
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
[doc] add examples for Dialog and Frame classes
2017-07-17 18:02:13 +00:00
An example of dumping frame tree:
```js
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
const puppeteer = require('puppeteer');
[doc] add examples for Dialog and Frame classes
2017-07-17 18:02:13 +00:00
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
(async () => {
const browser = await puppeteer.launch();
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const page = await browser.newPage();
Rename Page.navigate into Page.goto (#232) Fixes #228.
2017-08-10 07:02:10 +00:00
await page.goto('https://www.google.com/chrome/browser/canary.html');
[doc] add examples for Dialog and Frame classes
2017-07-17 18:02:13 +00:00
dumpFrameTree(page.mainFrame(), '');
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
[doc] add examples for Dialog and Frame classes
2017-07-17 18:02:13 +00:00
function dumpFrameTree(frame, indent) {
console.log(indent + frame.url());
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
for (const child of frame.childFrames()) {
[doc] add examples for Dialog and Frame classes
2017-07-17 18:02:13 +00:00
dumpFrameTree(child, indent + ' ');
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
}
[doc] add examples for Dialog and Frame classes
2017-07-17 18:02:13 +00:00
}
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
})();
[doc] add examples for Dialog and Frame classes
2017-07-17 18:02:13 +00:00
```
docs(api.md): add frame example (#3237) Add an example on how to work with frame's API. Fixes #3232.
2018-09-13 18:25:15 +00:00
An example of getting text from an iframe element:
```js
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
const frame = page.frames().find(frame => frame.name() === 'myframe');
const text = await frame.$eval('.selector', element => element.textContent);
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
console.log(text);
docs(api.md): add frame example (#3237) Add an example on how to work with frame's API. Fixes #3232.
2018-09-13 18:25:15 +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
#### frame.$(selector)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api.md): Fix selector description for pages & frames (#2841)
2018-07-05 00:01:40 +00:00
- `selector` <[string]> A [selector] to query frame for
docs(api.md): fix return signatures that contains null (#1364)
2017-11-15 18:53:17 +00:00
- returns: <[Promise]<?[ElementHandle]>> Promise which resolves to ElementHandle pointing to the frame element.
Implement page.$$ method (#463) This patch implements page.$$ which runs document.querySelectorAll in page and returns results as an array of ElementHandle instances. Fixes #384.
2017-08-23 05:56:55 +00:00
docs(api): add info for .$x() methods (#6711) Possibly connected issue: https://github.com/puppeteer/puppeteer/issues/6710
2021-01-05 07:22:46 +00:00
The method queries frame for the selector. If there's no such element within the frame, the method resolves 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)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api.md): Fix selector description for pages & frames (#2841)
2018-07-05 00:01:40 +00:00
- `selector` <[string]> A [selector] to query frame 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]>>> 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
docs(api.md): minor grammar and consistency fixes (#3320)
2018-10-02 20:38:41 +00:00
The method runs `document.querySelectorAll` within the frame. If no elements match the selector, the return value resolves to `[]`.
Introduce Page.$ and Page.$$ (#75) This patch introduces Page.$ and Page.$$ methods which are aliases for `document.querySelector` and `document.querySelectorAll`. Fixes #78.
2017-07-18 01:56:56 +00:00
feat(Page): introduce Page.$$eval method (#1006) This patch adds a `Page.$$eval` method that runs `document.querySelectorAll` and passes resulting array to the page function. Fixes #625.
2017-10-11 06:23:14 +00:00
#### frame.$$eval(selector, pageFunction[, ...args])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Page): introduce Page.$$eval method (#1006) This patch adds a `Page.$$eval` method that runs `document.querySelectorAll` and passes resulting array to the page function. Fixes #625.
2017-10-11 06:23:14 +00:00
- `selector` <[string]> A [selector] to query frame for
chore(types): generate our own d.ts file from api.md (#3744) Generate `//index.d.ts` file with precise typescript definitions for all of the Puppeteer API.
2019-01-28 23:12:45 +00:00
- `pageFunction` <[function]\([Array]<[Element]>\)> Function to be evaluated in browser context
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
feat(Page): introduce Page.$$eval method (#1006) This patch adds a `Page.$$eval` method that runs `document.querySelectorAll` and passes resulting array to the page function. Fixes #625.
2017-10-11 06:23:14 +00:00
- returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
docs(api.md): mention that page.$$eval and frame.$$eval return arrays (#2595) Docs about `page.$$eval` and `frame.$$eval` are not accurate and might be confusing. `document.querySelectorAll` returns `NodeList`, while `frame.$$eval` is actually doing `Array.from(querySelectorAll(selector))`, which actually returns an array. This makes things this possible: `await page.$$eval('div', divs => divs.map...)` This patch fixes docs to mention that $$eval is actually performing: `Array.from(querySelectorAll(selector))` Which will let the user understand that the element he receives is an array, and not a NodeList.
2018-05-26 00:28:13 +00:00
This method runs `Array.from(document.querySelectorAll(selector))` within the frame and passes it as the first argument to `pageFunction`.
feat(Page): introduce Page.$$eval method (#1006) This patch adds a `Page.$$eval` method that runs `document.querySelectorAll` and passes resulting array to the page function. Fixes #625.
2017-10-11 06:23:14 +00:00
If `pageFunction` returns a [Promise], then `frame.$$eval` would wait for the promise to resolve and return its value.
Examples:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Page): introduce Page.$$eval method (#1006) This patch adds a `Page.$$eval` method that runs `document.querySelectorAll` and passes resulting array to the page function. Fixes #625.
2017-10-11 06:23:14 +00:00
```js
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
const divsCounts = await frame.$$eval('div', divs => divs.length);
feat(Page): introduce Page.$$eval method (#1006) This patch adds a `Page.$$eval` method that runs `document.querySelectorAll` and passes resulting array to the page function. Fixes #625.
2017-10-11 06:23:14 +00:00
```
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])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- `selector` <[string]> A [selector] to query frame for
chore(types): generate our own d.ts file from api.md (#3744) Generate `//index.d.ts` file with precise typescript definitions for all of the Puppeteer API.
2019-01-28 23:12:45 +00:00
- `pageFunction` <[function]\([Element]\)> Function to be evaluated in browser context
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
Implement page.$eval (#638) This patch: - implements page.$eval and frame.$eval - drops elementHandle.attribute() method in favor of the page.$eval References #625
2017-08-31 22:38:01 +00:00
- returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
This method runs `document.querySelector` within the frame and passes it as the first argument to `pageFunction`. If there's no element matching `selector`, the method throws an error.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
If `pageFunction` returns a [Promise], then `frame.$eval` would wait for the promise to resolve and return its value.
Implement page.$eval (#638) This patch: - implements page.$eval and frame.$eval - drops elementHandle.attribute() method in favor of the page.$eval References #625
2017-08-31 22:38:01 +00:00
Examples:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
```js
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
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);
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
```
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
#### frame.$x(expression)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
- `expression` <[string]> Expression to [evaluate](https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate).
- returns: <[Promise]<[Array]<[ElementHandle]>>>
docs(api): add info for .$x() methods (#6711) Possibly connected issue: https://github.com/puppeteer/puppeteer/issues/6710
2021-01-05 07:22:46 +00:00
The method evaluates the XPath expression relative to the frame document as its context node. If there are no such elements, the method resolves to an empty array.
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
#### frame.addScriptTag(options)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
- `options` <[Object]>
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- `url` <[string]> URL of a script to be added.
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
- `path` <[string]> Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
- `content` <[string]> Raw JavaScript content to be injected into frame.
feat: add id option to addScriptTag (#5477)
2021-09-14 21:02:05 +00:00
- `type` <[string]> Script type. Use 'module' in order to load a Javascript ES6 module. See [script](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) for more details.
- `id` <[string]> id attribute to add to the script tag.
feat(Frame): addStyleTag and addScriptTag now return ElementHandles. This patch teaches `page.addStyleTag` and `page.addScriptTag` to return ElementHandles to the added tags. Fixes #1179.
2017-11-03 07:05:38 +00:00
- returns: <[Promise]<[ElementHandle]>> which resolves to the added tag when the script's onload fires or when the script content was injected into frame.
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
Adds a `<script>` tag into the page with the desired URL or content.
Move missing methods from page onto frame. (#125) Closes #113
2017-07-25 18:37:46 +00:00
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
#### frame.addStyleTag(options)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
- `options` <[Object]>
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- `url` <[string]> URL of the `<link>` tag.
feat(Frame): Support options in `addScriptTag` and `addStyleTag` (#996) This patch: - deprecates injectFile as it was confused with the addScriptTag - accepts an options object in addScriptTag which supports properties url, path and content. - accepts an options object in addStyleTag which supports properties url, path and content. Fixes #949. BREAKING CHANGE: - the addStyleTag/addScriptTag have changed; - the injectFile was removed in favor of (addStyleTag({path:}).
2017-10-12 08:26:44 +00:00
- `path` <[string]> Path to the CSS file to be injected into frame. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
- `content` <[string]> Raw CSS content to be injected into frame.
feat(Frame): addStyleTag and addScriptTag now return ElementHandles. This patch teaches `page.addStyleTag` and `page.addScriptTag` to return ElementHandles to the added tags. Fixes #1179.
2017-11-03 07:05:38 +00:00
- returns: <[Promise]<[ElementHandle]>> which resolves to the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.
feat(Frame): Add `addStyleTag` API to frame - fixes #892 (#947) This patch adds `Page.addStyleTag` and `Frame.addStyleTag` methods to the API. Fixes #892.
2017-10-04 20:42:26 +00:00
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
Adds a `<link rel="stylesheet">` tag into the page with the desired URL or a `<style type="text/css">` tag with the content.
feat(Frame): Add `addStyleTag` API to frame - fixes #892 (#947) This patch adds `Page.addStyleTag` and `Frame.addStyleTag` methods to the API. Fixes #892.
2017-10-04 20:42:26 +00:00
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
#### frame.childFrames()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- returns: <[Array]<[Frame]>>
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
#### frame.click(selector[, options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
- `selector` <[string]> A [selector] to search for element to click. If there are multiple elements satisfying the selector, the first will be clicked.
- `options` <[Object]>
feat: add `back` and `forward` mouse buttons (#8284)
2022-04-27 21:00:07 +00:00
- `button` <"left"|"right"|"middle"|"back"|"forward"> Defaults to `left`.
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
- `clickCount` <[number]> defaults to 1. See [UIEvent.detail].
- `delay` <[number]> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully clicked. The Promise will be rejected if there is no element matching `selector`.
This method fetches an element with `selector`, scrolls it into view if needed, and then uses [page.mouse](#pagemouse) to click in the center of the element.
If there's no element matching `selector`, the method throws an error.
docs(api.md): fix minor spelling errors (#2314)
2018-04-05 20:08:28 +00:00
Bear in mind that if `click()` triggers a navigation event and there's a separate `page.waitForNavigation()` promise to be resolved, you may end up with a race condition that yields unexpected results. The correct pattern for click and wait for navigation is the following:
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
docs(api): fix lint in code snippets (#7012)
2021-03-22 06:12:55 +00:00
```js
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
const [response] = await Promise.all([
page.waitForNavigation(waitOptions),
frame.click(selector, clickOptions),
]);
```
feat(Frame): implement frame.content and frame.setContent methods (#1447) This refactors the page.content and page.setContent methods to be defined on the Frame class. This allows access from the Page still but also on all frames. Fixes #754
2017-11-23 02:44:33 +00:00
#### frame.content()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
fix(types): fix return types where JSDoc and api.md disagree (#3512)
2018-11-08 06:48:43 +00:00
- returns: <[Promise]<[string]>>
feat(Frame): implement frame.content and frame.setContent methods (#1447) This refactors the page.content and page.setContent methods to be defined on the Frame class. This allows access from the Page still but also on all frames. Fixes #754
2017-11-23 02:44:33 +00:00
Gets the full HTML contents of the frame, including the doctype.
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### frame.evaluate(pageFunction[, ...args])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
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
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
- returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
If the function passed to the `frame.evaluate` returns a [Promise], then `frame.evaluate` would wait for the promise to resolve and return its value.
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
feat(executioncontext): support bigints transferring (#4016) Refs: https://chromedevtools.github.io/devtools-protocol/tot/Runtime#type-UnserializableValue
2019-03-15 17:20:48 +00:00
If the function passed to the `frame.evaluate` returns a non-[Serializable] value, then `frame.evaluate` resolves to `undefined`. DevTools Protocol also supports transferring some additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals.
fix: return undefined when Page.evaluate encounters circular JSON (#983)
2017-10-09 19:30:05 +00:00
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
```js
[api] Teach page.evaluate to accept element handles as parameters (#725) This patch: - teaches `page.evaluate` to accept ElementHandles as parameters - removes `ElementHandle.evaluate` method since it's not needed any more References #382
2017-09-12 02:20:02 +00:00
const result = await frame.evaluate(() => {
return Promise.resolve(8 * 7);
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
});
[api] Teach page.evaluate to accept element handles as parameters (#725) This patch: - teaches `page.evaluate` to accept ElementHandles as parameters - removes `ElementHandle.evaluate` method since it's not needed any more References #382
2017-09-12 02:20:02 +00:00
console.log(result); // prints "56"
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
```
Implement Frame.evaluate This patch implements Frame.evaluate method. References #4.
2017-06-27 19:40:46 +00:00
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
A string can also be passed in instead of a function.
```js
[api] Teach page.evaluate to accept element handles as parameters (#725) This patch: - teaches `page.evaluate` to accept ElementHandles as parameters - removes `ElementHandle.evaluate` method since it's not needed any more References #382
2017-09-12 02:20:02 +00:00
console.log(await frame.evaluate('1 + 2')); // prints "3"
```
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
[ElementHandle] instances can be passed as arguments to the `frame.evaluate`:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
[api] Teach page.evaluate to accept element handles as parameters (#725) This patch: - teaches `page.evaluate` to accept ElementHandles as parameters - removes `ElementHandle.evaluate` method since it's not needed any more References #382
2017-09-12 02:20:02 +00:00
```js
const bodyHandle = await frame.$('body');
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
const html = await frame.evaluate(body => body.innerHTML, bodyHandle);
[api] Teach page.evaluate to accept element handles as parameters (#725) This patch: - teaches `page.evaluate` to accept ElementHandles as parameters - removes `ElementHandle.evaluate` method since it's not needed any more References #382
2017-09-12 02:20:02 +00:00
await bodyHandle.dispose();
[doclint] introduce preprocessor's gen:copy and gen:paste tasks The two tasks allow to copy text from one part of document to another. This comes handy in organizing the documentation for our shortcut methods, which should be exactly the same as the original methods. The tasks work like this: - the gen:copy(id) task saves a part of document under the name 'ID'. - the gen:paste(id) task pastes text saved with id 'ID' This patch also fixes a bunch of links in documentation, as well as migrating `api.md` to use the two tasks.
2017-07-31 10:23:29 +00:00
```
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### frame.evaluateHandle(pageFunction[, ...args])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Frame): add Frame.evaluateHandle (#1885) This patch adds Frame.evaluateHandle method. The method is a shortcut for frame.executionContext().evaluateHandle. Fixes #1051
2018-01-25 05:16:01 +00:00
- `pageFunction` <[function]|[string]> Function to be evaluated in the page context
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
feat(types): add (and fix) `evaluateHandle` types (#6130) This change started as a small change to pull types from DefinitelyTyped over to Puppeteer for the `evaluateHandle` function but instead ended up also fixing what looks to be a long standing issue with our existing documentation. `evaluateHandle` can in fact return an `ElementHandle` rather than a `JSHandle`. Note that `ElementHandle` extends `JSHandle` so whilst the docs are technically correct (all ElementHandles are JSHandles) it's confusing because JSHandles don't have methods like `click` on them, but ElementHandles do. if you return something that is an HTML element: ``` const button = page.evaluateHandle(() => document.querySelector('button')); // this is an ElementHandle, not a JSHandle ``` Therefore I've updated the original docs and added a large explanation to the TSDoc for `page.evaluateHandle`. In TypeScript land we'll assume the function will return a `JSHandle` but you can tell TS otherwise via the generic argument, which can only be `JSHandle` (the default) or `ElementHandle`: ``` const button = page.evaluateHandle<ElementHandle>(() => document.querySelector('button')); ```
2020-07-01 11:44:08 +00:00
- returns: <[Promise]<[JSHandle]|[ElementHandle]>> Promise which resolves to the return value of `pageFunction` as an in-page object.
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
The only difference between `frame.evaluate` and `frame.evaluateHandle` is that `frame.evaluateHandle` returns in-page object (JSHandle).
feat(Frame): add Frame.evaluateHandle (#1885) This patch adds Frame.evaluateHandle method. The method is a shortcut for frame.executionContext().evaluateHandle. Fixes #1051
2018-01-25 05:16:01 +00:00
If the function, passed to the `frame.evaluateHandle`, returns a [Promise], then `frame.evaluateHandle` would wait for the promise to resolve and return its value.
feat(types): add (and fix) `evaluateHandle` types (#6130) This change started as a small change to pull types from DefinitelyTyped over to Puppeteer for the `evaluateHandle` function but instead ended up also fixing what looks to be a long standing issue with our existing documentation. `evaluateHandle` can in fact return an `ElementHandle` rather than a `JSHandle`. Note that `ElementHandle` extends `JSHandle` so whilst the docs are technically correct (all ElementHandles are JSHandles) it's confusing because JSHandles don't have methods like `click` on them, but ElementHandles do. if you return something that is an HTML element: ``` const button = page.evaluateHandle(() => document.querySelector('button')); // this is an ElementHandle, not a JSHandle ``` Therefore I've updated the original docs and added a large explanation to the TSDoc for `page.evaluateHandle`. In TypeScript land we'll assume the function will return a `JSHandle` but you can tell TS otherwise via the generic argument, which can only be `JSHandle` (the default) or `ElementHandle`: ``` const button = page.evaluateHandle<ElementHandle>(() => document.querySelector('button')); ```
2020-07-01 11:44:08 +00:00
If the function returns an element, the returned handle is an [ElementHandle].
feat(Frame): add Frame.evaluateHandle (#1885) This patch adds Frame.evaluateHandle method. The method is a shortcut for frame.executionContext().evaluateHandle. Fixes #1051
2018-01-25 05:16:01 +00:00
```js
const aWindowHandle = await frame.evaluateHandle(() => Promise.resolve(window));
aWindowHandle; // Handle for the window object.
```
A string can also be passed in instead of a function.
```js
const aHandle = await frame.evaluateHandle('document'); // Handle for the 'document'.
```
[JSHandle] instances can be passed as arguments to the `frame.evaluateHandle`:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Frame): add Frame.evaluateHandle (#1885) This patch adds Frame.evaluateHandle method. The method is a shortcut for frame.executionContext().evaluateHandle. Fixes #1051
2018-01-25 05:16:01 +00:00
```js
const aHandle = await frame.evaluateHandle(() => document.body);
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
const resultHandle = await frame.evaluateHandle(
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
body => body.innerHTML,
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
aHandle
);
feat(Frame): add Frame.evaluateHandle (#1885) This patch adds Frame.evaluateHandle method. The method is a shortcut for frame.executionContext().evaluateHandle. Fixes #1051
2018-01-25 05:16:01 +00:00
console.log(await resultHandle.jsonValue());
await resultHandle.dispose();
```
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
#### frame.executionContext()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: expose frame's execution contexts (#3048) This patch exposes frame's execution contexts, making it possible to debug extension's content scripts. This is a resurrected #2812.
2018-08-09 21:57:08 +00:00
- returns: <[Promise]<[ExecutionContext]>>
Returns promise that resolves to the frame's default execution context.
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
#### frame.focus(selector)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
- `selector` <[string]> A [selector] of an element to focus. If there are multiple elements satisfying the selector, the first will be focused.
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully focused. The promise will be rejected if there is no element matching `selector`.
This method fetches an element with `selector` and focuses it.
If there's no element matching `selector`, the method throws an error.
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### frame.goto(url[, options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
- `url` <[string]> URL to navigate frame to. The URL should include scheme, e.g. `https://`.
feat(frame): introduce Frame.goto and Frame.waitForNavigation (#3276) This patch introduces API to manage frame navigations. As a drive-by, the `response.frame()` method is added as a shortcut for `response.request().frame()`. Fixes #2918.
2018-09-20 18:31:19 +00:00
- `options` <[Object]> Navigation parameters which might have the following properties:
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultNavigationTimeout(timeout)](#pagesetdefaultnavigationtimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
chore: migrate src/LifecycleWatcher (#5734)
2020-04-27 09:03:33 +00:00
- `waitUntil` <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Array<PuppeteerLifeCycleMethod>> When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
feat(frame): introduce Frame.goto and Frame.waitForNavigation (#3276) This patch introduces API to manage frame navigations. As a drive-by, the `response.frame()` method is added as a shortcut for `response.request().frame()`. Fixes #2918.
2018-09-20 18:31:19 +00:00
- `load` - consider navigation to be finished when the `load` event is fired.
- `domcontentloaded` - consider navigation to be finished when the `DOMContentLoaded` event is fired.
- `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.
- `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
- `referer` <[string]> Referer header value. If provided it will take preference over the referer header value set by [page.setExtraHTTPHeaders()](#pagesetextrahttpheadersheaders).
chore: update request and response references in docs (#5942) Missed some Request => HTTPRequest and Response => HTTPResponse renames when updating the docs.
2020-05-29 11:36:04 +00:00
- returns: <[Promise]<?[HTTPResponse]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
feat(frame): introduce Frame.goto and Frame.waitForNavigation (#3276) This patch introduces API to manage frame navigations. As a drive-by, the `response.frame()` method is added as a shortcut for `response.request().frame()`. Fixes #2918.
2018-09-20 18:31:19 +00:00
docs(api.md): clarify frame/page.goto()'s handling of HTTP error statuses (#4553) The documentation for frame.goto() and page.goto() were updated to make it clear that the method will not throw an error if the HTTP requests results in any valid HTTP status code being returned by the remote server.
2019-06-10 01:32:06 +00:00
`frame.goto` will throw an error if:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(frame): introduce Frame.goto and Frame.waitForNavigation (#3276) This patch introduces API to manage frame navigations. As a drive-by, the `response.frame()` method is added as a shortcut for `response.request().frame()`. Fixes #2918.
2018-09-20 18:31:19 +00:00
- there's an SSL error (e.g. in case of self-signed certificates).
- target URL is invalid.
- the `timeout` is exceeded during navigation.
docs(api.md): clarify frame/page.goto()'s handling of HTTP error statuses (#4553) The documentation for frame.goto() and page.goto() were updated to make it clear that the method will not throw an error if the HTTP requests results in any valid HTTP status code being returned by the remote server.
2019-06-10 01:32:06 +00:00
- the remote server does not respond or is unreachable.
feat(frame): introduce Frame.goto and Frame.waitForNavigation (#3276) This patch introduces API to manage frame navigations. As a drive-by, the `response.frame()` method is added as a shortcut for `response.request().frame()`. Fixes #2918.
2018-09-20 18:31:19 +00:00
- the main resource failed to load.
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
`frame.goto` will not throw an error when any valid HTTP status code is returned by the remote server, including 404 "Not Found" and 500 "Internal Server Error". The status code for such responses can be retrieved by calling [response.status()](#httpresponsestatus).
docs(api.md): clarify frame/page.goto()'s handling of HTTP error statuses (#4553) The documentation for frame.goto() and page.goto() were updated to make it clear that the method will not throw an error if the HTTP requests results in any valid HTTP status code being returned by the remote server.
2019-06-10 01:32:06 +00:00
> **NOTE** `frame.goto` either throws an error or returns a main resource response. The only exceptions are navigation to `about:blank` or navigation to the same URL with a different hash, which would succeed and return `null`.
feat(frame): introduce Frame.goto and Frame.waitForNavigation (#3276) This patch introduces API to manage frame navigations. As a drive-by, the `response.frame()` method is added as a shortcut for `response.request().frame()`. Fixes #2918.
2018-09-20 18:31:19 +00:00
> **NOTE** Headless mode doesn't support navigation to a PDF document. See the [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295).
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
#### frame.hover(selector)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
- `selector` <[string]> A [selector] to search for element to hover. If there are multiple elements satisfying the selector, the first will be hovered.
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully hovered. Promise gets rejected if there's no element matching `selector`.
This method fetches an element with `selector`, scrolls it into view if needed, and then uses [page.mouse](#pagemouse) to hover over the center of the element.
If there's no element matching `selector`, the method throws an error.
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
#### frame.isDetached()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- 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
feat(oop iframes)!: integrate OOP iframes with the frame manager (#7556) This pull request to adds better support for OOP iframes (see #2548) The current problem with OOP iframes is that they are moved to a different target. Because of this, the previous versions of Puppeteer pretty much ignored them. This change extends the FrameManager to already take OOP iframes into account and hides the fact that those frames are actually in different targets. Further work needs to be done to also make the NetworkManager aware of these and to make sure that settings like emulations etc. are also properly passed down to the new targets.
2021-10-28 09:25:49 +00:00
#### frame.isOOPFrame()
- returns: <[boolean]>
Returns `true` if the frame is an OOP frame, or `false` otherwise.
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
#### frame.name()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- 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()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore(types): generate our own d.ts file from api.md (#3744) Generate `//index.d.ts` file with precise typescript definitions for all of the Puppeteer API.
2019-01-28 23:12:45 +00:00
- returns: <?[Frame]> Parent frame, if any. Detached frames and main frames return `null`.
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
feat(Frame): introduce Frame.select This patch adds `Frame.select` method that does the same functionality as former `Page.select`, but on a per-frame level. The `Page.select` method becomes a shortcut for the ÷main frame's select. Fixes #1139
2017-11-02 05:06:04 +00:00
#### frame.select(selector, ...values)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Frame): introduce Frame.select This patch adds `Frame.select` method that does the same functionality as former `Page.select`, but on a per-frame level. The `Page.select` method becomes a shortcut for the ÷main frame's select. Fixes #1139
2017-11-02 05:06:04 +00:00
- `selector` <[string]> A [selector] to query frame for
- `...values` <...[string]> Values of options to select. If the `<select>` has the `multiple` attribute, all values are considered, otherwise only the first one is taken into account.
chore(types): generate our own d.ts file from api.md (#3744) Generate `//index.d.ts` file with precise typescript definitions for all of the Puppeteer API.
2019-01-28 23:12:45 +00:00
- returns: <[Promise]<[Array]<[string]>>> An array of option values that have been successfully selected.
feat(Frame): introduce Frame.select This patch adds `Frame.select` method that does the same functionality as former `Page.select`, but on a per-frame level. The `Page.select` method becomes a shortcut for the ÷main frame's select. Fixes #1139
2017-11-02 05:06:04 +00:00
Triggers a `change` and `input` event once all the provided options have been selected.
If there's no `<select>` element matching `selector`, the method throws an error.
```js
frame.select('select#colors', 'blue'); // single selection
frame.select('select#colors', 'red', 'green', 'blue'); // multiple selections
```
feat(page): support waitUntil option for `page.setContent` (#3557) This patch teaches `page.setContent` to await resources in the new document. **NOTE**: This patch changes behavior: currently, `page.setContent` awaits the `"domcontentloaded"` event; with this patch, we can now await other lifecycle events, and switched default to the `"load"` event. The change is justified since current behavior made `page.setContent` unusable for its main designated usecases, pushing our client to use [dataURL workaround](https://github.com/GoogleChrome/puppeteer/issues/728#issuecomment-334301491). Fixes #728
2018-11-20 23:32:46 +00:00
#### frame.setContent(html[, options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Frame): implement frame.content and frame.setContent methods (#1447) This refactors the page.content and page.setContent methods to be defined on the Frame class. This allows access from the Page still but also on all frames. Fixes #754
2017-11-23 02:44:33 +00:00
- `html` <[string]> HTML markup to assign to the page.
feat(page): support waitUntil option for `page.setContent` (#3557) This patch teaches `page.setContent` to await resources in the new document. **NOTE**: This patch changes behavior: currently, `page.setContent` awaits the `"domcontentloaded"` event; with this patch, we can now await other lifecycle events, and switched default to the `"load"` event. The change is justified since current behavior made `page.setContent` unusable for its main designated usecases, pushing our client to use [dataURL workaround](https://github.com/GoogleChrome/puppeteer/issues/728#issuecomment-334301491). Fixes #728
2018-11-20 23:32:46 +00:00
- `options` <[Object]> Parameters which might have the following properties:
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- `timeout` <[number]> Maximum time in milliseconds for resources to load, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultNavigationTimeout(timeout)](#pagesetdefaultnavigationtimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
chore: migrate src/LifecycleWatcher (#5734)
2020-04-27 09:03:33 +00:00
- `waitUntil` <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Array<PuppeteerLifeCycleMethod>> When to consider setting markup succeeded, defaults to `load`. Given an array of event strings, setting content is considered to be successful after all events have been fired. Events can be either:
feat(page): support waitUntil option for `page.setContent` (#3557) This patch teaches `page.setContent` to await resources in the new document. **NOTE**: This patch changes behavior: currently, `page.setContent` awaits the `"domcontentloaded"` event; with this patch, we can now await other lifecycle events, and switched default to the `"load"` event. The change is justified since current behavior made `page.setContent` unusable for its main designated usecases, pushing our client to use [dataURL workaround](https://github.com/GoogleChrome/puppeteer/issues/728#issuecomment-334301491). Fixes #728
2018-11-20 23:32:46 +00:00
- `load` - consider setting content to be finished when the `load` event is fired.
- `domcontentloaded` - consider setting content to be finished when the `DOMContentLoaded` event is fired.
- `networkidle0` - consider setting content to be finished when there are no more than 0 network connections for at least `500` ms.
- `networkidle2` - consider setting content to be finished when there are no more than 2 network connections for at least `500` ms.
feat(Frame): implement frame.content and frame.setContent methods (#1447) This refactors the page.content and page.setContent methods to be defined on the Frame class. This allows access from the Page still but also on all frames. Fixes #754
2017-11-23 02:44:33 +00:00
- returns: <[Promise]>
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
#### frame.tap(selector)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
- `selector` <[string]> A [selector] to search for element to tap. If there are multiple elements satisfying the selector, the first will be tapped.
- returns: <[Promise]>
This method fetches an element with `selector`, scrolls it into view if needed, and then uses [page.touchscreen](#pagetouchscreen) to tap in the center of the element.
If there's no element matching `selector`, the method throws an error.
Move missing methods from page onto frame. (#125) Closes #113
2017-07-25 18:37:46 +00:00
#### frame.title()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore(types): generate our own d.ts file from api.md (#3744) Generate `//index.d.ts` file with precise typescript definitions for all of the Puppeteer API.
2019-01-28 23:12:45 +00:00
- returns: <[Promise]<[string]>> The page's title.
Move missing methods from page onto frame. (#125) Closes #113
2017-07-25 18:37:46 +00:00
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
#### frame.type(selector, text[, options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
- `selector` <[string]> A [selector] of an element to type into. If there are multiple elements satisfying the selector, the first will be used.
- `text` <[string]> A text to type into a focused element.
- `options` <[Object]>
- `delay` <[number]> Time to wait between key presses in milliseconds. Defaults to 0.
- returns: <[Promise]>
Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
To press a special key, like `Control` or `ArrowDown`, use [`keyboard.press`](#keyboardpresskey-options).
```js
docs(api): clarify `type` method examples (#5010)
2019-10-07 06:32:35 +00:00
await frame.type('#mytextarea', 'Hello'); // Types instantly
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
await frame.type('#mytextarea', 'World', {delay: 100}); // Types slower, like a user
feat(Frame): add click(), focus(), hover(), tap() and type() (#1970) This patch adds frame shortcuts to drive input: - `Frame.click()` - `Frame.focus()` - `Frame.hover()` - `Frame.tap()` - `Frame.type()`
2018-02-05 22:58:03 +00:00
```
add stubs for methods in api.md References #14
2017-06-27 19:15:21 +00:00
#### frame.url()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- returns: <[string]>
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
Returns frame's URL.
Added frame.waitFor(selector) (#59) This patch adds `frame.waitFor(selector)` method. Fixes #42.
2017-07-07 22:39:02 +00:00
page.waitFor should send ...args to page.waitForFunction (#775) This lets the user pass `...args` into `page.waitFor`. It also clarifies that the docs that `options` is not optional if `...args` are specified. Fixes #770
2017-09-15 21:28:15 +00:00
#### frame.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- `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
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- returns: <[Promise]<[JSHandle]>> Promise which resolves to a JSHandle of the success value
Implement function as a part of a page.waitFor shortcut This patch adds a function as a possible argument to page.waitFor shortcut. Fixes #91.
2017-07-28 00:09:28 +00:00
feat: page.waitForTimeout (#6268)
2020-07-28 08:37:49 +00:00
**This method is deprecated**. You should use the more explicit API methods available:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- `frame.waitForSelector`
- `frame.waitForXPath`
- `frame.waitForFunction`
- `frame.waitForTimeout`
feat: page.waitForTimeout (#6268)
2020-07-28 08:37:49 +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:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
- if `selectorOrFunctionOrTimeout` is a `string`, then the first argument is treated as a [selector] or [xpath], depending on whether or not it starts with '//', and the method is a shortcut for
docs(api.md): fix some links (#2253)
2018-03-28 20:18:59 +00:00
[frame.waitForSelector](#framewaitforselectorselector-options) or [frame.waitForXPath](#framewaitforxpathxpath-options)
docs(api): fix typo 'Than' was used in a few places instead of 'then'.
2017-10-10 18:07:39 +00:00
- if `selectorOrFunctionOrTimeout` is a `function`, then the first argument is treated as a predicate to wait for and the method is a shortcut for [frame.waitForFunction()](#framewaitforfunctionpagefunction-options-args).
- if `selectorOrFunctionOrTimeout` is a `number`, then the first argument is treated as a timeout in milliseconds and the method returns a promise which resolves after the timeout
Introduce polymorphic page.waitFor method This patch: - introduces page.waitForSelector to wait for the selector to appear - introduces polymorphic page.waitFor method, which accepts either string (and in this case is a shortcut for page.waitForSelector) or number (and in this case it's a promisified timeout). References #91.
2017-07-21 19:41:49 +00:00
- otherwise, an exception is thrown
[doc] Bring back examples to page shortcut methods The motivation behind the patch: - examples are probably the most valuable thing in the doc - currently, one would need to navigate to `page.evaluate` and then click to the `frame.evaluate` to see the example. - with this patch, all the descriptions for the shortcut methods are copied as well. So there's an example for `page.evaluate` right away. Drive-by: fix links for `page.$` and `page.$$`
2017-07-31 11:29:54 +00:00
docs(api.md): elaborate on passing arguments in waitForFunction (#2921)
2018-07-26 23:26:37 +00:00
```js
// wait for selector
await page.waitFor('.foo');
// wait for 1 second
await page.waitFor(1000);
// wait for predicate
await page.waitFor(() => !!document.querySelector('.foo'));
```
To pass arguments from node.js to the predicate of `page.waitFor` function:
```js
const selector = '.foo';
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
await page.waitFor(
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
selector => !!document.querySelector(selector),
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
{},
selector
);
docs(api.md): elaborate on passing arguments in waitForFunction (#2921)
2018-07-26 23:26:37 +00:00
```
page.waitFor should send ...args to page.waitForFunction (#775) This lets the user pass `...args` into `page.waitFor`. It also clarifies that the docs that `options` is not optional if `...args` are specified. Fixes #770
2017-09-15 21:28:15 +00:00
#### frame.waitForFunction(pageFunction[, options[, ...args]])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
Implement page.waitForFunction method The page.waitForFunction method allows to wait for a general predicate. The predicate will be continiously polled for in page, until it either returns true or the timeout happens. The polling parameter could be one of the following: - 'raf' - to poll on every animation frame - 'mutation' - to poll on every dom mutation - <number> - to poll every X milliseconds References #91
2017-07-27 22:17:43 +00:00
- `pageFunction` <[function]|[string]> Function to be evaluated in browser context
- `options` <[Object]> Optional waiting parameters
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
- `polling` <[string]|[number]> An interval at which the `pageFunction` is executed, defaults to `raf`. If `polling` is a number, then it is treated as an interval in milliseconds at which the function would be executed. If `polling` is a string, then it can be one of the following values:
Implement page.waitForFunction method The page.waitForFunction method allows to wait for a general predicate. The predicate will be continiously polled for in page, until it either returns true or the timeout happens. The polling parameter could be one of the following: - 'raf' - to poll on every animation frame - 'mutation' - to poll on every dom mutation - <number> - to poll every X milliseconds References #91
2017-07-27 22:17:43 +00:00
- `raf` - to constantly execute `pageFunction` in `requestAnimationFrame` callback. This is the tightest polling mode which is suitable to observe styling changes.
- `mutation` - to execute `pageFunction` on every DOM mutation.
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) method.
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- returns: <[Promise]<[JSHandle]>> Promise which resolves when the `pageFunction` returns a truthy value. It resolves to a JSHandle of the truthy value.
Implement page.waitForFunction method The page.waitForFunction method allows to wait for a general predicate. The predicate will be continiously polled for in page, until it either returns true or the timeout happens. The polling parameter could be one of the following: - 'raf' - to poll on every animation frame - 'mutation' - to poll on every dom mutation - <number> - to poll every X milliseconds References #91
2017-07-27 22:17:43 +00:00
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
The `waitForFunction` can be used to observe viewport size change:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
Implement page.waitForFunction method The page.waitForFunction method allows to wait for a general predicate. The predicate will be continiously polled for in page, until it either returns true or the timeout happens. The polling parameter could be one of the following: - 'raf' - to poll on every animation frame - 'mutation' - to poll on every dom mutation - <number> - to poll every X milliseconds References #91
2017-07-27 22:17:43 +00:00
```js
Use `puppeteer.launch` instead of browser constructor (#255) This patch: - split browser launching logic from Browser into `lib/Launcher.js` - introduce `puppeteer` namespace which currently has a single `launch` method to start a browser With this patch, the browser is no longer created with the `new Browser(..)` command. Instead, it should be "launched" via the `puppeteer.launch` method: ```js const puppeteer = require('puppeteer'); puppeteer.launch().then(async browser => { ... }); ``` With this approach browser instance lifetime matches the lifetime of actual browser process. This helps us: - remove proxy streams, e.g. browser.stderr and browser.stdout - cleanup browser class and make it possible to connect to remote browser - introduce events on the browser instance, e.g. 'page' event. In case of lazy-launching browser, we should've launch browser when an event listener is added, which is unneded comlpexity.
2017-08-15 01:08:06 +00:00
const puppeteer = require('puppeteer');
Implement page.waitForFunction method The page.waitForFunction method allows to wait for a general predicate. The predicate will be continiously polled for in page, until it either returns true or the timeout happens. The polling parameter could be one of the following: - 'raf' - to poll on every animation frame - 'mutation' - to poll on every dom mutation - <number> - to poll every X milliseconds References #91
2017-07-27 22:17:43 +00:00
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
(async () => {
const browser = await puppeteer.launch();
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');
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.setViewport({width: 50, height: 50});
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
await watchDog;
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
})();
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
```
docs(api.md): elaborate on passing arguments in waitForFunction (#2921)
2018-07-26 23:26:37 +00:00
To pass arguments from node.js to the predicate of `page.waitForFunction` function:
```js
const selector = '.foo';
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
await page.waitForFunction(
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
selector => !!document.querySelector(selector),
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
{},
selector
);
docs(api.md): elaborate on passing arguments in waitForFunction (#2921)
2018-07-26 23:26:37 +00:00
```
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### frame.waitForNavigation([options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(frame): introduce Frame.goto and Frame.waitForNavigation (#3276) This patch introduces API to manage frame navigations. As a drive-by, the `response.frame()` method is added as a shortcut for `response.request().frame()`. Fixes #2918.
2018-09-20 18:31:19 +00:00
- `options` <[Object]> Navigation parameters which might have the following properties:
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultNavigationTimeout(timeout)](#pagesetdefaultnavigationtimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
chore: migrate src/LifecycleWatcher (#5734)
2020-04-27 09:03:33 +00:00
- `waitUntil` <"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Array<PuppeteerLifeCycleMethod>> When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
feat(frame): introduce Frame.goto and Frame.waitForNavigation (#3276) This patch introduces API to manage frame navigations. As a drive-by, the `response.frame()` method is added as a shortcut for `response.request().frame()`. Fixes #2918.
2018-09-20 18:31:19 +00:00
- `load` - consider navigation to be finished when the `load` event is fired.
- `domcontentloaded` - consider navigation to be finished when the `DOMContentLoaded` event is fired.
- `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.
- `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
chore: update request and response references in docs (#5942) Missed some Request => HTTPRequest and Response => HTTPResponse renames when updating the docs.
2020-05-29 11:36:04 +00:00
- returns: <[Promise]<?[HTTPResponse]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to History API usage, the navigation will resolve with `null`.
feat(frame): introduce Frame.goto and Frame.waitForNavigation (#3276) This patch introduces API to manage frame navigations. As a drive-by, the `response.frame()` method is added as a shortcut for `response.request().frame()`. Fixes #2918.
2018-09-20 18:31:19 +00:00
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
This resolves when the frame navigates to a new URL. It is useful when you run code
that will indirectly cause the frame to navigate. Consider this example:
feat(frame): introduce Frame.goto and Frame.waitForNavigation (#3276) This patch introduces API to manage frame navigations. As a drive-by, the `response.frame()` method is added as a shortcut for `response.request().frame()`. Fixes #2918.
2018-09-20 18:31:19 +00:00
```js
const [response] = await Promise.all([
frame.waitForNavigation(), // The navigation promise resolves after navigation has finished
frame.click('a.my-link'), // Clicking the link will indirectly cause a navigation
]);
```
**NOTE** Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to change the URL is considered a navigation.
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])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
- `selector` <[string]> A [selector] of an element to wait for
Implement visible option for Page.waitFor method This patch adds a 'visible' option to the Page.waitFor method, making it possible to wait for the element to become actually visible. References #89, #91.
2017-07-21 07:58:38 +00:00
- `options` <[Object]> Optional waiting parameters
Implement timeout option for page.waitFor This patch implements timeout option for page.waitFor. The function will throw if the selector doesn't appear during timeout milliseconds of waittime. References #89, #91.
2017-07-21 18:46:57 +00:00
- `visible` <[boolean]> wait for element to be present in DOM and to be visible, i.e. to not have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
docs(api): add missing 'hidden' option on frame.waitForSelector
2017-10-15 05:57:56 +00:00
- `hidden` <[boolean]> wait for element to not be found in the DOM or to be hidden, i.e. have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) method.
fix(page): teach waitForSelector to return `null` (#3846) `page.waitForSelector` should return `null` if waiting for `hidden: true` and there's no matching node in DOM. Before this patch, `page.waitForSelector` would return some JSHandle pointing to boolean value.
2019-01-28 19:24:53 +00:00
- returns: <[Promise]<?[ElementHandle]>> Promise which resolves when element specified by selector string is added to DOM. Resolves to `null` if waiting for `hidden: true` and selector is not found in DOM.
Added frame.waitFor(selector) (#59) This patch adds `frame.waitFor(selector)` method. Fixes #42.
2017-07-07 22:39:02 +00:00
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
Wait for the `selector` to appear in page. If at the moment of calling
the method the `selector` already exists, the method will return
Implement timeout option for page.waitFor This patch implements timeout option for page.waitFor. The function will throw if the selector doesn't appear during timeout milliseconds of waittime. References #89, #91.
2017-07-21 18:46:57 +00:00
immediately. If the selector doesn't appear after the `timeout` milliseconds of waiting, the function will throw.
[doclint] validate return statements This patch teaches doclint to validate presence of return statements. It also adds a bunch of documentation to the api.md. References #14.
2017-07-13 22:54:37 +00:00
Implement visible option for Page.waitFor method This patch adds a 'visible' option to the Page.waitFor method, making it possible to wait for the element to become actually visible. References #89, #91.
2017-07-21 07:58:38 +00:00
This method works across navigations:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
```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
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
(async () => {
const browser = await puppeteer.launch();
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;
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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));
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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);
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
}
doc: add await to browser.close in usage examples (#797) browser.close returns a promise after f398e69, so it should be awaited.
2017-09-16 04:27:14 +00:00
await browser.close();
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +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
```
feat: page.waitForTimeout (#6268)
2020-07-28 08:37:49 +00:00
#### frame.waitForTimeout(milliseconds)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: page.waitForTimeout (#6268)
2020-07-28 08:37:49 +00:00
- `milliseconds` <[number]> The number of milliseconds to wait for.
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
- returns: <[Promise]> Promise which resolves after the timeout has been completed.
feat: page.waitForTimeout (#6268)
2020-07-28 08:37:49 +00:00
Pauses script execution for the given number of seconds before continuing:
```js
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
page
.mainFrame()
feat: page.waitForTimeout (#6268)
2020-07-28 08:37:49 +00:00
.waitForTimeout(1000)
.then(() => console.log('Waited a second!'));
await browser.close();
})();
```
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
#### frame.waitForXPath(xpath[, options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
- `xpath` <[string]> A [xpath] of an element to wait for
- `options` <[Object]> Optional waiting parameters
- `visible` <[boolean]> wait for element to be present in DOM and to be visible, i.e. to not have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
- `hidden` <[boolean]> wait for element to not be found in the DOM or to be hidden, i.e. have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
feat(page): introduce page.setDefaultTimeout (#3854) Method `page.setDefaultTimeout` overrides default 30 seconds timeout for all `page.waitFor*` methods, including navigation and waiting for selectors. Fix #3319.
2019-01-29 01:16:12 +00:00
- `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) method.
fix(page): teach waitForSelector to return `null` (#3846) `page.waitForSelector` should return `null` if waiting for `hidden: true` and there's no matching node in DOM. Before this patch, `page.waitForSelector` would return some JSHandle pointing to boolean value.
2019-01-28 19:24:53 +00:00
- returns: <[Promise]<?[ElementHandle]>> Promise which resolves when element specified by xpath string is added to DOM. Resolves to `null` if waiting for `hidden: true` and xpath is not found in DOM.
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
Wait for the `xpath` to appear in page. If at the moment of calling
the method the `xpath` already exists, the method will return
immediately. If the xpath doesn't appear after the `timeout` milliseconds of waiting, the function will throw.
This method works across navigations:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
```js
const puppeteer = require('puppeteer');
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
(async () => {
const browser = await puppeteer.launch();
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
const page = await browser.newPage();
let currentURL;
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
page
.mainFrame()
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
.waitForXPath('//img')
.then(() => console.log('First URL with image: ' + currentURL));
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
for (currentURL of [
'https://example.com',
'https://google.com',
'https://bbc.com',
]) {
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
await page.goto(currentURL);
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
}
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
await browser.close();
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
})();
feat(Page): introduce Page.waitForXPath (#1767) This patch: - introduces `page.waitForXPath` method - introduces `frame.waitForXPath` method - amends `page.waitFor` to treat strings that start with `//` as xpath queries. Fixes #1757.
2018-01-22 23:16:20 +00:00
```
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
### class: ExecutionContext
docs(api.md): some grammar/wording (#3057)
2018-08-10 00:49:06 +00:00
The class represents a context for JavaScript execution. A [Page] might have many execution contexts:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: expose frame's execution contexts (#3048) This patch exposes frame's execution contexts, making it possible to debug extension's content scripts. This is a resurrected #2812.
2018-08-09 21:57:08 +00:00
- each [frame](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) has "default" execution context that is
docs(api.md): some grammar/wording (#3057)
2018-08-10 00:49:06 +00:00
always created after frame is attached to DOM. This context is returned by the [`frame.executionContext()`](#frameexecutioncontext) method.
fix: revert ExecutionContext reporting. (#3058) It turned out that almost any usecase requires helper methods to access DOM inside the ExecutionContext. Instead of exposing execution contexts as-is, we should introduce IsolatedWorld as a first-class citizen that will hold execution contexts inside.
2018-08-10 01:14:21 +00:00
- [Extensions](https://developer.chrome.com/extensions)'s content scripts create additional execution contexts.
feat: expose frame's execution contexts (#3048) This patch exposes frame's execution contexts, making it possible to debug extension's content scripts. This is a resurrected #2812.
2018-08-09 21:57:08 +00:00
docs(api.md): some grammar/wording (#3057)
2018-08-10 00:49:06 +00:00
Besides pages, execution contexts can be found in [workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API).
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### executionContext.evaluate(pageFunction[, ...args])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore(doc): fix nits after JSHandles PR (#976)
2017-10-07 15:31:55 +00:00
- `pageFunction` <[function]|[string]> Function to be evaluated in `executionContext`
feat: support JSHandles for page.waitFor* calls (#1712) This patch: - teaches page.waitFor* methods to accept JSHandles - starts returning JSHandles from page.waitFor* calls. BREAKING CHANGE: this patch starts allocating `JSHandle`/`ElementHandle` instances for every call to `page.waitFor*` functions. These handles should be disposed manually to avoid memory consumption. Fixes #1703, fixes #1654, fixes #1724.
2018-01-04 22:49:13 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
- returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
If the function passed to the `executionContext.evaluate` returns a [Promise], then `executionContext.evaluate` would wait for the promise to resolve and return its value.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
feat(executioncontext): support bigints transferring (#4016) Refs: https://chromedevtools.github.io/devtools-protocol/tot/Runtime#type-UnserializableValue
2019-03-15 17:20:48 +00:00
If the function passed to the `executionContext.evaluate` returns a non-[Serializable] value, then `executionContext.evaluate` resolves to `undefined`. DevTools Protocol also supports transferring some additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
```js
docs(api.md): fix missing await in examples (#1801) `frame.executionContext()` returns a Promise, so running examples without `await` results in exceptions
2018-01-17 00:59:00 +00:00
const executionContext = await page.mainFrame().executionContext();
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
const result = await executionContext.evaluate(() => Promise.resolve(8 * 7));
console.log(result); // prints "56"
```
A string can also be passed in instead of a function.
```js
console.log(await executionContext.evaluate('1 + 2')); // prints "3"
```
chore(doc): fix nits after JSHandles PR (#976)
2017-10-07 15:31:55 +00:00
[JSHandle] instances can be passed as arguments to the `executionContext.evaluate`:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
```js
const oneHandle = await executionContext.evaluateHandle(() => 1);
const twoHandle = await executionContext.evaluateHandle(() => 2);
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
const result = await executionContext.evaluate(
(a, b) => a + b,
oneHandle,
twoHandle
);
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
await oneHandle.dispose();
await twoHandle.dispose();
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
console.log(result); // prints '3'.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
```
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### executionContext.evaluateHandle(pageFunction[, ...args])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore(doc): fix nits after JSHandles PR (#976)
2017-10-07 15:31:55 +00:00
- `pageFunction` <[function]|[string]> Function to be evaluated in the `executionContext`
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
feat(types): add (and fix) `evaluateHandle` types (#6130) This change started as a small change to pull types from DefinitelyTyped over to Puppeteer for the `evaluateHandle` function but instead ended up also fixing what looks to be a long standing issue with our existing documentation. `evaluateHandle` can in fact return an `ElementHandle` rather than a `JSHandle`. Note that `ElementHandle` extends `JSHandle` so whilst the docs are technically correct (all ElementHandles are JSHandles) it's confusing because JSHandles don't have methods like `click` on them, but ElementHandles do. if you return something that is an HTML element: ``` const button = page.evaluateHandle(() => document.querySelector('button')); // this is an ElementHandle, not a JSHandle ``` Therefore I've updated the original docs and added a large explanation to the TSDoc for `page.evaluateHandle`. In TypeScript land we'll assume the function will return a `JSHandle` but you can tell TS otherwise via the generic argument, which can only be `JSHandle` (the default) or `ElementHandle`: ``` const button = page.evaluateHandle<ElementHandle>(() => document.querySelector('button')); ```
2020-07-01 11:44:08 +00:00
- returns: <[Promise]<[JSHandle]|[ElementHandle]>> Promise which resolves to the return value of `pageFunction` as an in-page object.
docs(api.md): Add more explanation for page.evaluateHandle() (#1867) Fixes #2062
2018-02-22 01:11:24 +00:00
The only difference between `executionContext.evaluate` and `executionContext.evaluateHandle` is that `executionContext.evaluateHandle` returns in-page object (JSHandle).
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
feat(types): add (and fix) `evaluateHandle` types (#6130) This change started as a small change to pull types from DefinitelyTyped over to Puppeteer for the `evaluateHandle` function but instead ended up also fixing what looks to be a long standing issue with our existing documentation. `evaluateHandle` can in fact return an `ElementHandle` rather than a `JSHandle`. Note that `ElementHandle` extends `JSHandle` so whilst the docs are technically correct (all ElementHandles are JSHandles) it's confusing because JSHandles don't have methods like `click` on them, but ElementHandles do. if you return something that is an HTML element: ``` const button = page.evaluateHandle(() => document.querySelector('button')); // this is an ElementHandle, not a JSHandle ``` Therefore I've updated the original docs and added a large explanation to the TSDoc for `page.evaluateHandle`. In TypeScript land we'll assume the function will return a `JSHandle` but you can tell TS otherwise via the generic argument, which can only be `JSHandle` (the default) or `ElementHandle`: ``` const button = page.evaluateHandle<ElementHandle>(() => document.querySelector('button')); ```
2020-07-01 11:44:08 +00:00
If the function returns an element, the returned handle is an [ElementHandle].
docs(api.md): fix typo (#2177)
2018-03-13 14:42:37 +00:00
If the function passed to the `executionContext.evaluateHandle` returns a [Promise], then `executionContext.evaluateHandle` would wait for the promise to resolve and return its value.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
```js
docs(api.md): fix missing await in examples (#1801) `frame.executionContext()` returns a Promise, so running examples without `await` results in exceptions
2018-01-17 00:59:00 +00:00
const context = await page.mainFrame().executionContext();
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
const aHandle = await context.evaluateHandle(() => Promise.resolve(self));
aHandle; // Handle for the global object.
```
A string can also be passed in instead of a function.
```js
const aHandle = await context.evaluateHandle('1 + 2'); // Handle for the '3' object.
```
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
[JSHandle] instances can be passed as arguments to the `executionContext.evaluateHandle`:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
```js
const aHandle = await context.evaluateHandle(() => document.body);
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
const resultHandle = await context.evaluateHandle(
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
body => body.innerHTML,
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
aHandle
);
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
console.log(await resultHandle.jsonValue()); // prints body's innerHTML
await aHandle.dispose();
await resultHandle.dispose();
```
feat(ExecutionContext): introduce ExecutionContext.frame() (#1972) This patch introduces ExecutionContext.frame() that returns Frame associated with this Execution Context. This allows to associate console messages with the originating frame, if any.
2018-02-13 22:02:44 +00:00
#### executionContext.frame()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(ExecutionContext): introduce ExecutionContext.frame() (#1972) This patch introduces ExecutionContext.frame() that returns Frame associated with this Execution Context. This allows to associate console messages with the originating frame, if any.
2018-02-13 22:02:44 +00:00
- returns: <?[Frame]> Frame associated with this execution context.
> **NOTE** Not every execution context is associated with a frame. For example, workers and extensions have execution contexts that are not associated with frames.
feat(Page): introduce Page.queryObjects (#1005) This patch introduces `Page.queryObjects` and `ExecutionContext.queryObjects` methods to query JavaScript heap for objects with a certain prototype. Fixes #304.
2017-10-11 21:41:20 +00:00
#### executionContext.queryObjects(prototypeHandle)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Page): introduce Page.queryObjects (#1005) This patch introduces `Page.queryObjects` and `ExecutionContext.queryObjects` methods to query JavaScript heap for objects with a certain prototype. Fixes #304.
2017-10-11 21:41:20 +00:00
- `prototypeHandle` <[JSHandle]> A handle to the object prototype.
fix(types): fix return types where JSDoc and api.md disagree (#3512)
2018-11-08 06:48:43 +00:00
- returns: <[Promise]<[JSHandle]>> A handle to an array of objects with this prototype
feat(Page): introduce Page.queryObjects (#1005) This patch introduces `Page.queryObjects` and `ExecutionContext.queryObjects` methods to query JavaScript heap for objects with a certain prototype. Fixes #304.
2017-10-11 21:41:20 +00:00
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
The method iterates the JavaScript heap and finds all the objects with the given prototype.
feat(Page): introduce Page.queryObjects (#1005) This patch introduces `Page.queryObjects` and `ExecutionContext.queryObjects` methods to query JavaScript heap for objects with a certain prototype. Fixes #304.
2017-10-11 21:41:20 +00:00
```js
Roll chromium to 508268 (#1019) This gets us: - Plural metrics names https://crrev.com/507885 - TargetInfoChanged on URL changes https://crrev.com/508049 - Sending proper resource types for requests https://crrev.com/667504 Fixes #734
2017-10-12 08:17:06 +00:00
// Create a Map object
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
await page.evaluate(() => (window.map = new Map()));
feat(Page): introduce Page.queryObjects (#1005) This patch introduces `Page.queryObjects` and `ExecutionContext.queryObjects` methods to query JavaScript heap for objects with a certain prototype. Fixes #304.
2017-10-11 21:41:20 +00:00
// Get a handle to the Map object prototype
const mapPrototype = await page.evaluateHandle(() => Map.prototype);
// Query all map instances into an array
const mapInstances = await page.queryObjects(mapPrototype);
// Count amount of map objects in heap
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
const count = await page.evaluate(maps => maps.length, mapInstances);
feat(Page): introduce Page.queryObjects (#1005) This patch introduces `Page.queryObjects` and `ExecutionContext.queryObjects` methods to query JavaScript heap for objects with a certain prototype. Fixes #304.
2017-10-11 21:41:20 +00:00
await mapInstances.dispose();
await mapPrototype.dispose();
```
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
### class: JSHandle
docs(api): javascript -> JavaScript (#1338)
2017-11-10 21:35:22 +00:00
JSHandle represents an in-page JavaScript object. JSHandles can be created with the [page.evaluateHandle](#pageevaluatehandlepagefunction-args) method.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
```js
chore(doc): fix nits after JSHandles PR (#976)
2017-10-07 15:31:55 +00:00
const windowHandle = await page.evaluateHandle(() => window);
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
// ...
```
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
JSHandle prevents the referenced JavaScript object from garbage collection unless the handle is [disposed](#jshandledispose). JSHandles are auto-disposed when their origin frame gets navigated or the parent context gets destroyed.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
chore(doc): fix nits after JSHandles PR (#976)
2017-10-07 15:31:55 +00:00
JSHandle instances can be used as arguments in [`page.$eval()`](#pageevalselector-pagefunction-args), [`page.evaluate()`](#pageevaluatepagefunction-args) and [`page.evaluateHandle`](#pageevaluatehandlepagefunction-args) methods.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
#### jsHandle.asElement()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api.md): fix return signatures that contains null (#1364)
2017-11-15 18:53:17 +00:00
- returns: <?[ElementHandle]>
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
Returns either `null` or the object handle itself if the object handle is an instance of [ElementHandle].
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
#### jsHandle.dispose()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
- returns: <[Promise]> Promise which resolves when the object handle is successfully disposed.
The `jsHandle.dispose` method stops referencing the element handle.
feat(api): add element.select and element.evaluate for consistency (#4892)
2019-09-04 22:19:34 +00:00
#### jsHandle.evaluate(pageFunction[, ...args])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(api): add element.select and element.evaluate for consistency (#4892)
2019-09-04 22:19:34 +00:00
- `pageFunction` <[function]\([Object]\)> Function to be evaluated in browser context
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
- returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
This method passes this handle as the first argument to `pageFunction`.
If `pageFunction` returns a [Promise], then `handle.evaluate` would wait for the promise to resolve and return its value.
Examples:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(api): add element.select and element.evaluate for consistency (#4892)
2019-09-04 22:19:34 +00:00
```js
const tweetHandle = await page.$('.tweet .retweets');
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
expect(await tweetHandle.evaluate(node => node.innerText)).toBe('10');
feat(api): add element.select and element.evaluate for consistency (#4892)
2019-09-04 22:19:34 +00:00
```
#### jsHandle.evaluateHandle(pageFunction[, ...args])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(api): add element.select and element.evaluate for consistency (#4892)
2019-09-04 22:19:34 +00:00
- `pageFunction` <[function]|[string]> Function to be evaluated
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
feat(types): add (and fix) `evaluateHandle` types (#6130) This change started as a small change to pull types from DefinitelyTyped over to Puppeteer for the `evaluateHandle` function but instead ended up also fixing what looks to be a long standing issue with our existing documentation. `evaluateHandle` can in fact return an `ElementHandle` rather than a `JSHandle`. Note that `ElementHandle` extends `JSHandle` so whilst the docs are technically correct (all ElementHandles are JSHandles) it's confusing because JSHandles don't have methods like `click` on them, but ElementHandles do. if you return something that is an HTML element: ``` const button = page.evaluateHandle(() => document.querySelector('button')); // this is an ElementHandle, not a JSHandle ``` Therefore I've updated the original docs and added a large explanation to the TSDoc for `page.evaluateHandle`. In TypeScript land we'll assume the function will return a `JSHandle` but you can tell TS otherwise via the generic argument, which can only be `JSHandle` (the default) or `ElementHandle`: ``` const button = page.evaluateHandle<ElementHandle>(() => document.querySelector('button')); ```
2020-07-01 11:44:08 +00:00
- returns: <[Promise]<[JSHandle]|[ElementHandle]>> Promise which resolves to the return value of `pageFunction` as an in-page object.
feat(api): add element.select and element.evaluate for consistency (#4892)
2019-09-04 22:19:34 +00:00
This method passes this handle as the first argument to `pageFunction`.
The only difference between `jsHandle.evaluate` and `jsHandle.evaluateHandle` is that `executionContext.evaluateHandle` returns in-page object (JSHandle).
feat(types): add (and fix) `evaluateHandle` types (#6130) This change started as a small change to pull types from DefinitelyTyped over to Puppeteer for the `evaluateHandle` function but instead ended up also fixing what looks to be a long standing issue with our existing documentation. `evaluateHandle` can in fact return an `ElementHandle` rather than a `JSHandle`. Note that `ElementHandle` extends `JSHandle` so whilst the docs are technically correct (all ElementHandles are JSHandles) it's confusing because JSHandles don't have methods like `click` on them, but ElementHandles do. if you return something that is an HTML element: ``` const button = page.evaluateHandle(() => document.querySelector('button')); // this is an ElementHandle, not a JSHandle ``` Therefore I've updated the original docs and added a large explanation to the TSDoc for `page.evaluateHandle`. In TypeScript land we'll assume the function will return a `JSHandle` but you can tell TS otherwise via the generic argument, which can only be `JSHandle` (the default) or `ElementHandle`: ``` const button = page.evaluateHandle<ElementHandle>(() => document.querySelector('button')); ```
2020-07-01 11:44:08 +00:00
If the function returns an element, the returned handle is an [ElementHandle].
feat(api): add element.select and element.evaluate for consistency (#4892)
2019-09-04 22:19:34 +00:00
If the function passed to the `jsHandle.evaluateHandle` returns a [Promise], then `jsHandle.evaluateHandle` would wait for the promise to resolve and return its value.
See [Page.evaluateHandle](#pageevaluatehandlepagefunction-args) for more details.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
#### jsHandle.executionContext()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
fix(types): fix parameters where they disagree with the api (#3525)
2018-11-12 20:59:21 +00:00
- returns: <[ExecutionContext]>
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
Returns execution context the handle belongs to.
#### jsHandle.getProperties()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
- returns: <[Promise]<[Map]<[string], [JSHandle]>>>
The method returns a map with property names as keys and JSHandle instances for the property values.
```js
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
const handle = await page.evaluateHandle(() => ({window, document}));
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
const properties = await handle.getProperties();
const windowHandle = properties.get('window');
const documentHandle = properties.get('document');
await handle.dispose();
```
#### jsHandle.getProperty(propertyName)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
- `propertyName` <[string]> property to get
- returns: <[Promise]<[JSHandle]>>
Fetches a single property from the referenced object.
#### jsHandle.jsonValue()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
- returns: <[Promise]<[Object]>>
fix(page.evaluate): jsonValue should ignore toJSON property (#1098) Currently, JSHandle.jsonValue() is implemented as in-page JSON.stringify call and consequent JSON.parse in node. This approach proved to be unfortunate for automation purposes: if page author overrode the Object.prototype.toJSON method, then it's harder for puppeteer to interact with the page. This patch switches JSHandle.jsonValue to use protocol serialization that ignores toJSON property. THis also changes the `page.evaluate` behavior since it is based on JSHandle.jsonValue(). Fixes #1003. BREAKING CHANGE: `page.evaluate` no longer calls toJSON when generating return value. For the old behavior, do JSON.parse/JSON.stringify manually: ```js const json = JSON.parse(await page.evaluate(() => JSON.stringify(obj))); ```
2017-10-20 17:45:49 +00:00
Returns a JSON representation of the object. If the object has a
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
[`toJSON`](<https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#toJSON()_behavior>)
fix(page.evaluate): jsonValue should ignore toJSON property (#1098) Currently, JSHandle.jsonValue() is implemented as in-page JSON.stringify call and consequent JSON.parse in node. This approach proved to be unfortunate for automation purposes: if page author overrode the Object.prototype.toJSON method, then it's harder for puppeteer to interact with the page. This patch switches JSHandle.jsonValue to use protocol serialization that ignores toJSON property. THis also changes the `page.evaluate` behavior since it is based on JSHandle.jsonValue(). Fixes #1003. BREAKING CHANGE: `page.evaluate` no longer calls toJSON when generating return value. For the old behavior, do JSON.parse/JSON.stringify manually: ```js const json = JSON.parse(await page.evaluate(() => JSON.stringify(obj))); ```
2017-10-20 17:45:49 +00:00
function, it **will not be called**.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
> **NOTE** The method will return an empty JSON object if the referenced object is not stringifiable. It will throw an error if the object has circular references.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
### class: ElementHandle
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- extends: [JSHandle]
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
ElementHandle represents an in-page DOM element. ElementHandles can be created with the [page.$](#pageselector) method.
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
```js
const puppeteer = require('puppeteer');
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
(async () => {
const browser = await puppeteer.launch();
doc: fix some nits in code examples from api.md (#407) * Replace let with const in examples when appropriate. * Unify spacing. * Fix possible copy-paste artifacts. * Eliminate one unhandled promise rejection ('Target closed').
2017-08-20 21:50:24 +00:00
const page = await browser.newPage();
docs(api.md): update ElementHandle example (#4169) Fix #4150
2019-03-19 19:53:47 +00:00
await page.goto('https://example.com');
const hrefElement = await page.$('a');
await hrefElement.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
// ...
docs(api.md): prefer async/await over Promise#then (#5089) Fixes #5082.
2019-10-26 09:00:39 +00:00
})();
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
```
Rename ElementHandle.release into ElementHandle.dispose (#284) The ElementHandle.release feels related to ElementHandle.click. The dispose is a more clear name.
2017-08-16 07:49:20 +00:00
ElementHandle prevents DOM element from garbage collection unless the handle is [disposed](#elementhandledispose). ElementHandles are auto-disposed when their origin frame gets navigated.
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
chore(doc): add a note about using ElementHandle instances (#925)
2017-10-01 22:47:40 +00:00
ElementHandle instances can be used as arguments in [`page.$eval()`](#pageevalselector-pagefunction-args) and [`page.evaluate()`](#pageevaluatepagefunction-args) methods.
feat(ElementHandle): add ElementHandle.$ and ElementHandle.$$ (#1151) This patch adds `ElementHandle.$` and `ElementHandle.$$` methods to query nested elements. Fixes #508
2017-10-27 09:08:58 +00:00
#### elementHandle.$(selector)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(ElementHandle): add ElementHandle.$ and ElementHandle.$$ (#1151) This patch adds `ElementHandle.$` and `ElementHandle.$$` methods to query nested elements. Fixes #508
2017-10-27 09:08:58 +00:00
- `selector` <[string]> A [selector] to query element for
docs(api.md): fix return signatures that contains null (#1364)
2017-11-15 18:53:17 +00:00
- returns: <[Promise]<?[ElementHandle]>>
feat(ElementHandle): add ElementHandle.$ and ElementHandle.$$ (#1151) This patch adds `ElementHandle.$` and `ElementHandle.$$` methods to query nested elements. Fixes #508
2017-10-27 09:08:58 +00:00
docs(api.md): minor grammar and consistency fixes (#3320)
2018-10-02 20:38:41 +00:00
The method runs `element.querySelector` within the page. If no element matches the selector, the return value resolves to `null`.
feat(ElementHandle): add ElementHandle.$ and ElementHandle.$$ (#1151) This patch adds `ElementHandle.$` and `ElementHandle.$$` methods to query nested elements. Fixes #508
2017-10-27 09:08:58 +00:00
#### elementHandle.$$(selector)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(ElementHandle): add ElementHandle.$ and ElementHandle.$$ (#1151) This patch adds `ElementHandle.$` and `ElementHandle.$$` methods to query nested elements. Fixes #508
2017-10-27 09:08:58 +00:00
- `selector` <[string]> A [selector] to query element for
- returns: <[Promise]<[Array]<[ElementHandle]>>>
docs(api.md): minor grammar and consistency fixes (#3320)
2018-10-02 20:38:41 +00:00
The method runs `element.querySelectorAll` within the page. If no elements match the selector, the return value resolves to `[]`.
feat(ElementHandle): add ElementHandle.$ and ElementHandle.$$ (#1151) This patch adds `ElementHandle.$` and `ElementHandle.$$` methods to query nested elements. Fixes #508
2017-10-27 09:08:58 +00:00
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### elementHandle.$$eval(selector, pageFunction[, ...args])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(elementhandle): add elementHandle.$$eval method (#2589) Fixes #2401
2018-05-25 23:56:51 +00:00
- `selector` <[string]> A [selector] to query page for
chore(types): generate our own d.ts file from api.md (#3744) Generate `//index.d.ts` file with precise typescript definitions for all of the Puppeteer API.
2019-01-28 23:12:45 +00:00
- `pageFunction` <[function]\([Array]<[Element]>\)> Function to be evaluated in browser context
feat(elementhandle): add elementHandle.$$eval method (#2589) Fixes #2401
2018-05-25 23:56:51 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
- returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
This method runs `document.querySelectorAll` within the element 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 its value.
Examples:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(elementhandle): add elementHandle.$$eval method (#2589) Fixes #2401
2018-05-25 23:56:51 +00:00
```html
<div class="feed">
<div class="tweet">Hello!</div>
<div class="tweet">Hi!</div>
</div>
```
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(elementhandle): add elementHandle.$$eval method (#2589) Fixes #2401
2018-05-25 23:56:51 +00:00
```js
const feedHandle = await page.$('.feed');
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
expect(
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
await feedHandle.$$eval('.tweet', nodes => nodes.map(n => n.innerText))
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
).toEqual(['Hello!', 'Hi!']);
feat(elementhandle): add elementHandle.$$eval method (#2589) Fixes #2401
2018-05-25 23:56:51 +00:00
```
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### elementHandle.$eval(selector, pageFunction[, ...args])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(ElementHandle): introduce elementHandle.$eval (#2407) This patch introduces `elementHandle.$eval` method. References #2401.
2018-05-09 01:17:59 +00:00
- `selector` <[string]> A [selector] to query page for
chore(types): generate our own d.ts file from api.md (#3744) Generate `//index.d.ts` file with precise typescript definitions for all of the Puppeteer API.
2019-01-28 23:12:45 +00:00
- `pageFunction` <[function]\([Element]\)> Function to be evaluated in browser context
feat(ElementHandle): introduce elementHandle.$eval (#2407) This patch introduces `elementHandle.$eval` method. References #2401.
2018-05-09 01:17:59 +00:00
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
- returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
This method runs `document.querySelector` within the element 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 its value.
Examples:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(ElementHandle): introduce elementHandle.$eval (#2407) This patch introduces `elementHandle.$eval` method. References #2401.
2018-05-09 01:17:59 +00:00
```js
const tweetHandle = await page.$('.tweet');
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
expect(await tweetHandle.$eval('.like', node => node.innerText)).toBe('100');
expect(await tweetHandle.$eval('.retweets', node => node.innerText)).toBe('10');
feat(ElementHandle): introduce elementHandle.$eval (#2407) This patch introduces `elementHandle.$eval` method. References #2401.
2018-05-09 01:17:59 +00:00
```
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
#### elementHandle.$x(expression)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
- `expression` <[string]> Expression to [evaluate](https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate).
docs(api.md): fix return type docs of ElementHandle.$x (#2723)
2018-06-14 03:49:24 +00:00
- returns: <[Promise]<[Array]<[ElementHandle]>>>
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
docs(api): add info for .$x() methods (#6711) Possibly connected issue: https://github.com/puppeteer/puppeteer/issues/6710
2021-01-05 07:22:46 +00:00
The method evaluates the XPath expression relative to the `elementHandle` as its context node. If there are no such elements, the method resolves to an empty array.
The `expression` should have the context node to be evaluated properly:
```js
const [childHandle] = await parentHandle.$x('./div');
```
feat: rename page.xpath into page.$x, return an array of elements (#1713) Fixes #1705.
2018-01-03 23:37:08 +00:00
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
#### elementHandle.asElement()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api.md): fix typo (#2890)
2018-07-16 22:07:54 +00:00
- returns: <[ElementHandle]>
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
feat(ElementHandle): add EH.boundingBox and EH.screenshot This patch: - adds `ElementHandle.boundingBox()` method to get bounding box of element relative to the page - adds `ElementHandle.screenshot()` method to capture a screenshot of an element
2017-10-10 06:14:09 +00:00
#### elementHandle.boundingBox()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
doc(api.md): ElementHandle.boundingBox() returns a promise (#1437)
2017-11-21 07:13:44 +00:00
- returns: <[Promise]<?[Object]>>
chore: Spelling and Markdown Consistency (#1998) - Adding missing language tags to markdown code blocks. - Fixed various spelling mistakes my IDE complained to me about.
2018-02-09 03:59:46 +00:00
- x <[number]> the x coordinate of the element in pixels.
- y <[number]> the y coordinate of the element in pixels.
- width <[number]> the width of the element in pixels.
- height <[number]> the height of the element in pixels.
feat(ElementHandle): add EH.boundingBox and EH.screenshot This patch: - adds `ElementHandle.boundingBox()` method to get bounding box of element relative to the page - adds `ElementHandle.screenshot()` method to capture a screenshot of an element
2017-10-10 06:14:09 +00:00
fix(Page.click): throw a meaningful message for invisible elements (#1309) This patch starts throwing a meaningful error message when trying to click the hidden node. References #1294
2017-11-07 21:54:40 +00:00
This method returns the bounding box of the element (relative to the main frame), or `null` if the element is not visible.
feat(ElementHandle): add EH.boundingBox and EH.screenshot This patch: - adds `ElementHandle.boundingBox()` method to get bounding box of element relative to the page - adds `ElementHandle.screenshot()` method to capture a screenshot of an element
2017-10-10 06:14:09 +00:00
feat(ElementHandle): add ElementHandle.boxModel method (#2256) This patch introduces ElementHandle.boxModel to get element's box model. Fixes #1357
2018-03-29 20:52:28 +00:00
#### elementHandle.boxModel()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(ElementHandle): add ElementHandle.boxModel method (#2256) This patch introduces ElementHandle.boxModel to get element's box model. Fixes #1357
2018-03-29 20:52:28 +00:00
- returns: <[Promise]<?[Object]>>
fix(types): fix parameters where they disagree with the api (#3525)
2018-11-12 20:59:21 +00:00
- content <[Array]<[Object]>> Content box.
- x <[number]>
- y <[number]>
- padding <[Array]<[Object]>> Padding box.
- x <[number]>
- y <[number]>
- border <[Array]<[Object]>> Border box.
- x <[number]>
- y <[number]>
- margin <[Array]<[Object]>> Margin box.
- x <[number]>
- y <[number]>
feat(ElementHandle): add ElementHandle.boxModel method (#2256) This patch introduces ElementHandle.boxModel to get element's box model. Fixes #1357
2018-03-29 20:52:28 +00:00
- width <[number]> Element's width.
- height <[number]> Element's height.
test(ElementHandle.boxModel): remake test to make it more readable (#2287) This patch: - re-makes test for EH.boxModel to make it more readable - slightly changes wording in the `docs/api.md`. References #1357.
2018-03-30 00:25:52 +00:00
This method returns boxes of the element, or `null` if the element is not visible. Boxes are represented as an array of points; each Point is an object `{x, y}`. Box points are sorted clock-wise.
feat(ElementHandle): add ElementHandle.boxModel method (#2256) This patch introduces ElementHandle.boxModel to get element's box model. Fixes #1357
2018-03-29 20:52:28 +00:00
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
#### elementHandle.click([options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- `options` <[Object]>
feat: add `back` and `forward` mouse buttons (#8284)
2022-04-27 21:00:07 +00:00
- `button` <"left"|"right"|"middle"|"back"|"forward"> 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.
fix: typos in documentation (#7968)
2022-02-07 13:03:54 +00:00
- `offset` <[Object]> Offset in pixels relative to the top-left corner of the border box of the element.
- `x` <number> x-offset in pixels relative to the top-left corner of the border box of the element.
- `y` <number> y-offset in pixels relative to the top-left corner of the border box of the element.
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
- returns: <[Promise]> Promise which resolves when the element is successfully clicked. Promise gets rejected if the element is detached from DOM.
This method scrolls element into view if needed, and then uses [page.mouse](#pagemouse) to click in the center of the element.
If the element is detached from DOM, the method throws an error.
feat: add ability to specify offsets for JSHandle.click (#7573) Until now, the click would be always sent to the middle point of the target element. With this change, one can define offsets relative to the border box of the elements and click different areas of an element.
2021-09-20 09:01:32 +00:00
#### elementHandle.clickablePoint([offset])
feat: add drag-and-drop support (#7150) This commit adds drag-and-drop support, leveraging new additions to the CDP Input domain (Input.setInterceptDrags, Input.dispatchDragEvent, and Input.dragIntercepted).
2021-06-04 10:25:36 +00:00
feat: add ability to specify offsets for JSHandle.click (#7573) Until now, the click would be always sent to the middle point of the target element. With this change, one can define offsets relative to the border box of the elements and click different areas of an element.
2021-09-20 09:01:32 +00:00
- `offset` <[Object]>
fix: typos in documentation (#7968)
2022-02-07 13:03:54 +00:00
- `x` <number> x-offset in pixels relative to the top-left corner of the border box of the element.
- `y` <number> y-offset in pixels relative to the top-left corner of the border box of the element.
feat: add drag-and-drop support (#7150) This commit adds drag-and-drop support, leveraging new additions to the CDP Input domain (Input.setInterceptDrags, Input.dispatchDragEvent, and Input.dragIntercepted).
2021-06-04 10:25:36 +00:00
- returns: <[Promise<[Point]>]> Resolves to the x, y point that describes the element's position.
feat(ElementHandle): implement ElementHandle.contentFrame() (#2094) This patch adds ElementHandle.contentFrame() method that allows to get a reference to the Frame owned by the iframe. Fixes #433.
2018-02-24 05:22:53 +00:00
#### elementHandle.contentFrame()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(ElementHandle): implement ElementHandle.contentFrame() (#2094) This patch adds ElementHandle.contentFrame() method that allows to get a reference to the Frame owned by the iframe. Fixes #433.
2018-02-24 05:22:53 +00:00
- returns: <[Promise]<?[Frame]>> Resolves to the content frame for element handles referencing iframe nodes, or null otherwise
Rename ElementHandle.release into ElementHandle.dispose (#284) The ElementHandle.release feels related to ElementHandle.click. The dispose is a more clear name.
2017-08-16 07:49:20 +00:00
#### elementHandle.dispose()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- returns: <[Promise]> Promise which resolves when the element handle is successfully disposed.
The `elementHandle.dispose` method stops referencing the element handle.
feat: add drag-and-drop support (#7150) This commit adds drag-and-drop support, leveraging new additions to the CDP Input domain (Input.setInterceptDrags, Input.dispatchDragEvent, and Input.dragIntercepted).
2021-06-04 10:25:36 +00:00
#### elementHandle.drag(target)
- `target` <[Object]>
- `x` <[number]> x coordinate
- `y` <[number]> y coordinate
- returns: <[Promise<[DragData]>]>
This method creates and captures a drag event from the element.
#### elementHandle.dragAndDrop(target[, options])
- `target` <[ElementHandle]>
- `options` <[Object]>
- `delay` <[number]> how long to delay before dropping onto the target element
- returns: <[Promise]>
This method will drag a given element and drop it onto a target element.
#### elementHandle.dragEnter([data])
- `data` <[Object]> drag data created from `element.drag`
- returns: <[Promise]>
This method will trigger a dragenter event from the given element.
#### elementHandle.dragOver([data])
- `data` <[Object]> drag data created from `element.drag`
- returns: <[Promise]>
This method will trigger a dragover event from the given element.
#### elementHandle.drop([data])
- `data` <[Object]> drag data created from `element.drag`
- returns: <[Promise]>
This method will trigger a drop event from the given element.
feat(api): add element.select and element.evaluate for consistency (#4892)
2019-09-04 22:19:34 +00:00
#### elementHandle.evaluate(pageFunction[, ...args])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(api): add element.select and element.evaluate for consistency (#4892)
2019-09-04 22:19:34 +00:00
- `pageFunction` <[function]\([Object]\)> Function to be evaluated in browser context
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
- returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
This method passes this handle as the first argument to `pageFunction`.
If `pageFunction` returns a [Promise], then `handle.evaluate` would wait for the promise to resolve and return its value.
Examples:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(api): add element.select and element.evaluate for consistency (#4892)
2019-09-04 22:19:34 +00:00
```js
const tweetHandle = await page.$('.tweet .retweets');
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
expect(await tweetHandle.evaluate(node => node.innerText)).toBe('10');
feat(api): add element.select and element.evaluate for consistency (#4892)
2019-09-04 22:19:34 +00:00
```
#### elementHandle.evaluateHandle(pageFunction[, ...args])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(api): add element.select and element.evaluate for consistency (#4892)
2019-09-04 22:19:34 +00:00
- `pageFunction` <[function]|[string]> Function to be evaluated
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
feat(types): add (and fix) `evaluateHandle` types (#6130) This change started as a small change to pull types from DefinitelyTyped over to Puppeteer for the `evaluateHandle` function but instead ended up also fixing what looks to be a long standing issue with our existing documentation. `evaluateHandle` can in fact return an `ElementHandle` rather than a `JSHandle`. Note that `ElementHandle` extends `JSHandle` so whilst the docs are technically correct (all ElementHandles are JSHandles) it's confusing because JSHandles don't have methods like `click` on them, but ElementHandles do. if you return something that is an HTML element: ``` const button = page.evaluateHandle(() => document.querySelector('button')); // this is an ElementHandle, not a JSHandle ``` Therefore I've updated the original docs and added a large explanation to the TSDoc for `page.evaluateHandle`. In TypeScript land we'll assume the function will return a `JSHandle` but you can tell TS otherwise via the generic argument, which can only be `JSHandle` (the default) or `ElementHandle`: ``` const button = page.evaluateHandle<ElementHandle>(() => document.querySelector('button')); ```
2020-07-01 11:44:08 +00:00
- returns: <[Promise]<[JSHandle]|[ElementHandle]>> Promise which resolves to the return value of `pageFunction` as an in-page object.
feat(api): add element.select and element.evaluate for consistency (#4892)
2019-09-04 22:19:34 +00:00
This method passes this handle as the first argument to `pageFunction`.
docs(api): fix typo in elementHandle.evaluateHandle() (#6276)
2020-07-27 06:14:19 +00:00
The only difference between `elementHandle.evaluate` and `elementHandle.evaluateHandle` is that `executionContext.evaluateHandle` returns in-page object (JSHandle).
feat(api): add element.select and element.evaluate for consistency (#4892)
2019-09-04 22:19:34 +00:00
feat(types): add (and fix) `evaluateHandle` types (#6130) This change started as a small change to pull types from DefinitelyTyped over to Puppeteer for the `evaluateHandle` function but instead ended up also fixing what looks to be a long standing issue with our existing documentation. `evaluateHandle` can in fact return an `ElementHandle` rather than a `JSHandle`. Note that `ElementHandle` extends `JSHandle` so whilst the docs are technically correct (all ElementHandles are JSHandles) it's confusing because JSHandles don't have methods like `click` on them, but ElementHandles do. if you return something that is an HTML element: ``` const button = page.evaluateHandle(() => document.querySelector('button')); // this is an ElementHandle, not a JSHandle ``` Therefore I've updated the original docs and added a large explanation to the TSDoc for `page.evaluateHandle`. In TypeScript land we'll assume the function will return a `JSHandle` but you can tell TS otherwise via the generic argument, which can only be `JSHandle` (the default) or `ElementHandle`: ``` const button = page.evaluateHandle<ElementHandle>(() => document.querySelector('button')); ```
2020-07-01 11:44:08 +00:00
If the function returns an element, the returned handle is an [ElementHandle].
docs(api): fix typo in elementHandle.evaluateHandle() (#6276)
2020-07-27 06:14:19 +00:00
If the function passed to the `elementHandle.evaluateHandle` returns a [Promise], then `elementHandle.evaluateHandle` would wait for the promise to resolve and return its value.
feat(api): add element.select and element.evaluate for consistency (#4892)
2019-09-04 22:19:34 +00:00
See [Page.evaluateHandle](#pageevaluatehandlepagefunction-args) for more details.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
#### elementHandle.executionContext()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
fix(types): fix parameters where they disagree with the api (#3525)
2018-11-12 20:59:21 +00:00
- returns: <[ExecutionContext]>
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
#### elementHandle.focus()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
- returns: <[Promise]>
Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
#### elementHandle.getProperties()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
- returns: <[Promise]<[Map]<[string], [JSHandle]>>>
The method returns a map with property names as keys and JSHandle instances for the property values.
```js
const listHandle = await page.evaluateHandle(() => document.body.children);
chore(doc): fix nits after JSHandles PR (#976)
2017-10-07 15:31:55 +00:00
const properties = await listHandle.getProperties();
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
const children = [];
for (const property of properties.values()) {
const element = property.asElement();
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
if (element) children.push(element);
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
}
children; // holds elementHandles to all children of document.body
```
#### elementHandle.getProperty(propertyName)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
- `propertyName` <[string]> property to get
- returns: <[Promise]<[JSHandle]>>
Fetches a single property from the objectHandle.
Implement basic element handles (#248) This patch implements basic element handles which a backed with remote objects. Fixes #111
2017-08-15 21:54:02 +00:00
#### elementHandle.hover()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- returns: <[Promise]> Promise which resolves when the element is successfully hovered.
This method scrolls element into view if needed, and then uses [page.mouse](#pagemouse) to hover over the center of the element.
If the element is detached from DOM, the method throws an error.
feat: add threshold to Page.isIntersectingViewport (#6497)
2021-09-15 20:56:50 +00:00
#### elementHandle.isIntersectingViewport([options])
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
feat: add threshold to Page.isIntersectingViewport (#6497)
2021-09-15 20:56:50 +00:00
- `options` <[Object]>
- `threshold` <[number]> threshold for the intersection between 0 (no intersection) and 1 (full intersection). Defaults to 1.
feat(elementhandle): introduce elementHandle.isIntersectingViewport() method. (#2673) This patch introduces `elementHandle.isIntersectingViewport()` method returns true if element is visible in the viewport. Fixes #2629.
2018-07-12 00:51:04 +00:00
- returns: <[Promise]<[boolean]>> Resolves to true if the element is visible in the current viewport.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
#### elementHandle.jsonValue()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
- returns: <[Promise]<[Object]>>
Returns a JSON representation of the object. The JSON is generated by running [`JSON.stringify`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) on the object in page and consequent [`JSON.parse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) in puppeteer.
> **NOTE** The method will throw if the referenced object is not stringifiable.
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
#### elementHandle.press(key[, options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(keyboard): Accept codes (#1116) BREAKING CHANGE: This patch lets key names be code in addition to key. When specifying a code, the proper text is generated assuming a standard US keyboard layout. e.g Digit5 -> "5" or "%" depending on Shift. * location is now specified. #777 * Using unknown key names now throws an error. #723 * Typing newlines now correctly presses enter. #681
2017-10-23 19:43:45 +00:00
- `key` <[string]> Name of key to press, such as `ArrowLeft`. See [USKeyboardLayout] for a list of all key names.
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
- `options` <[Object]>
- `text` <[string]> If specified, generates an input event with this text.
- `delay` <[number]> Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
- returns: <[Promise]>
Focuses the element, and then uses [`keyboard.down`](#keyboarddownkey-options) and [`keyboard.up`](#keyboardupkey).
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`/`input` event will also be generated. The `text` option can be specified to force an input event to be generated.
docs: fix effect -> affect typos (#5985)
2020-06-23 05:24:15 +00:00
> **NOTE** Modifier keys DO affect `elementHandle.press`. Holding down `Shift` will type the text in upper case.
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
feat(ElementHandle): add EH.boundingBox and EH.screenshot This patch: - adds `ElementHandle.boundingBox()` method to get bounding box of element relative to the page - adds `ElementHandle.screenshot()` method to capture a screenshot of an element
2017-10-10 06:14:09 +00:00
#### elementHandle.screenshot([options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(ElementHandle): add EH.boundingBox and EH.screenshot This patch: - adds `ElementHandle.boundingBox()` method to get bounding box of element relative to the page - adds `ElementHandle.screenshot()` method to capture a screenshot of an element
2017-10-10 06:14:09 +00:00
- `options` <[Object]> Same options as in [page.screenshot](#pagescreenshotoptions).
docs(api.md): update returned value description (#3514)
2018-11-09 02:33:22 +00:00
- returns: <[Promise]<[string]|[Buffer]>> Promise which resolves to buffer or a base64 string (depending on the value of `options.encoding`) with captured screenshot.
feat(ElementHandle): add EH.boundingBox and EH.screenshot This patch: - adds `ElementHandle.boundingBox()` method to get bounding box of element relative to the page - adds `ElementHandle.screenshot()` method to capture a screenshot of an element
2017-10-10 06:14:09 +00:00
This method scrolls element into view if needed, and then uses [page.screenshot](#pagescreenshotoptions) to take a screenshot of the element.
If the element is detached from DOM, the method throws an error.
feat(api): add element.select and element.evaluate for consistency (#4892)
2019-09-04 22:19:34 +00:00
#### elementHandle.select(...values)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(api): add element.select and element.evaluate for consistency (#4892)
2019-09-04 22:19:34 +00:00
- `...values` <...[string]> Values of options to select. If the `<select>` has the `multiple` attribute, all values are considered, otherwise only the first one is taken into account.
- returns: <[Promise]<[Array]<[string]>>> An array of option values that have been successfully selected.
Triggers a `change` and `input` event once all the provided options have been selected.
If there's no `<select>` element matching `selector`, the method throws an error.
```js
handle.select('blue'); // single selection
handle.select('red', 'green', 'blue'); // multiple selections
```
[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()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +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
- returns: <[Promise]> Promise which resolves when the element is successfully tapped. Promise gets rejected if the element is detached from DOM.
This method scrolls element into view if needed, and then uses [touchscreen.tap](#touchscreentapx-y) to tap in the center of the element.
If the element is detached from DOM, the method throws an error.
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
#### elementHandle.toString()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(JSHandles): introduce JSHandles (#943) This patch: - introduces ExecutionContext class that incapsulates javascript execution context. An examples of execution contexts are workers and frames - introduces JSHandle that holds a references to the javascript object in ExecutionContext - inherits ElementHandle from JSHandle Fixes #382.
2017-10-06 22:35:02 +00:00
- returns: <[string]>
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
#### elementHandle.type(text[, options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
- `text` <[string]> A text to type into a focused element.
- `options` <[Object]>
- `delay` <[number]> Time to wait between key presses in milliseconds. Defaults to 0.
- returns: <[Promise]>
Focuses the element, and then sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
To press a special key, like `Control` or `ArrowDown`, use [`elementHandle.press`](#elementhandlepresskey-options).
```js
docs(api): clarify `type` method examples (#5010)
2019-10-07 06:32:35 +00:00
await elementHandle.type('Hello'); // Types instantly
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
await elementHandle.type('World', {delay: 100}); // Types slower, like a user
feat(Input): Add keyboard methods to elementHandle (#801) This patch: - adds input methods to ElementHandle, such as ElementHandle.type and ElementHandle.press - changes `page.type` to accept selector as the first argument - removes `page.press` method. The `page.press` is rarely used and doesn't operate with selectors; if there's a need to press a button, `page.keyboard.press` should be used. BREAKING CHANGE: `page.type` is changed, `page.press` is removed. Fixes #241.
2017-10-07 07:28:24 +00:00
```
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
An example of typing into a text field and then submitting the form:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs: add more keyboard examples for typing (#1176) This adds more examples for using `keyboard.type` and `keyboard.press`. It adds warnings about Shift affecting or not affecting the text generated by certain methods. fixes #723
2017-10-27 09:12:56 +00:00
```js
const elementHandle = await page.$('input');
await elementHandle.type('some text');
await elementHandle.press('Enter');
```
Move uploadFiles onto ElementHandle (#348) This patch: - removes the `page.uploadFile` method - adds `elementHandle.uploadFile` method. Motivation: `elementHandle.uploadFile` is rarely used, so it doesn't worth it to keep it on page.
2017-08-17 21:53:37 +00:00
#### elementHandle.uploadFile(...filePaths)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- `...filePaths` <...[string]> Sets the value of the file input to these paths. If some of the `filePaths` are relative paths, then they are resolved relative to the [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
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
- returns: <[Promise]>
This method expects `elementHandle` to point to an [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
feat: implement Element.waitForSelector (#7825) Co-authored-by: Johan Bay <jobay@google.com> Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-12-09 11:51:14 +00:00
#### elementHandle.waitForSelector(selector[, options])
- `selector` <[string]> A [selector] of an element to wait for
- `options` <[Object]> Optional waiting parameters
- `visible` <[boolean]> wait for element to be present in DOM and to be visible, i.e. to not have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
- `hidden` <[boolean]> wait for element to not be found in the DOM or to be hidden, i.e. have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
- `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) method.
- returns: <[Promise]<?[ElementHandle]>> Promise which resolves when element specified by selector string is added to DOM. Resolves to `null` if waiting for `hidden: true` and selector is not found in DOM.
Wait for an element matching `selector` to appear within the `elementHandle`’s subtree. If the `selector` already matches an element at the moment of calling the method, the promise returned by the method resolves immediately. If the selector doesn’t appear after `timeout` milliseconds of waiting, the promise rejects.
This method does not work across navigations or if the element is detached from DOM.
feat: add waitForXPath to ElementHandle (#8329)
2022-05-10 10:45:20 +00:00
#### elementHandle.waitForXPath(xpath[, options])
- `xpath` <[string]> A [xpath] of an element to wait for
- `options` <[Object]> Optional waiting parameters
- `visible` <[boolean]> wait for element to be present in DOM and to be visible, i.e. to not have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
- `hidden` <[boolean]> wait for element to not be found in the DOM or to be hidden, i.e. have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
- `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) method.
- returns: <[Promise]<?[ElementHandle]>> Promise which resolves when element specified by xpath string is added to DOM. Resolves to `null` if waiting for `hidden: true` and xpath is not found in DOM.
Wait for the `xpath` to appear within the element. If at the moment of calling
the method the `xpath` already exists, the method will return
immediately. If the xpath doesn't appear after the `timeout` milliseconds of waiting, the function will throw.
If `xpath` starts with `//` instead of `.//`, the dot will be appended automatically.
This method works across navigations:
```js
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
let currentURL;
page
.waitForXPath('//img')
.then(() => console.log('First URL with image: ' + currentURL));
for (currentURL of [
'https://example.com',
'https://google.com',
'https://bbc.com',
]) {
await page.goto(currentURL);
}
await browser.close();
})();
```
chore: rename Request class to HTTPRequest (#5934) It conflicts with an inbuilt TypeScript `Request` type so can cause confusion when in TS land. Note: `Response.ts` and `Worker.ts` also suffer from this; PRs to rename them are incoming.
2020-05-29 08:38:40 +00:00
### class: HTTPRequest
[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
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
Whenever the page sends a request, such as for a network resource, the following events are emitted by Puppeteer's page:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api.md): clarify on HTTP error responses (#4507)
2019-06-03 21:54:30 +00:00
- [`'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.
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
If request fails at some point, then instead of `'requestfinished'` event (and possibly instead of 'response' event), the [`'requestfailed'`](#event-requestfailed) event is emitted.
[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
docs(api.md): clarify on HTTP error responses (#4507)
2019-06-03 21:54:30 +00:00
> **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will complete with `'requestfinished'` event.
[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
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
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.
[doclint] lint events This patch: - adds event linting to the doclint - improves `api.md` to add events and more information about classes reported by events. References #14.
2017-07-14 20:03:21 +00:00
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
#### httpRequest.abort([errorCode], [priority])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Request): allow aborting intercepted requests with custom reasons (#1080) This patch adds optional parameter to the `request.abort()` method that specifies abort reason. References #1020.
2017-10-18 07:26:48 +00:00
- `errorCode` <[string]> Optional error code. Defaults to `failed`, could be
one of the following:
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
- `aborted` - An operation was aborted (due to user action).
- `accessdenied` - Permission to access a resource, other than the network, was denied.
feat(Request): allow aborting intercepted requests with custom reasons (#1080) This patch adds optional parameter to the `request.abort()` method that specifies abort reason. References #1020.
2017-10-18 07:26:48 +00:00
- `addressunreachable` - The IP address is unreachable. This usually means
that there is no route to the specified host or network.
feat(request): add new error reasons for request.abort() (#2771) As the title indicated, adds two allowed error codes that are specified in the Chrome Developer Tools Protocol specifications but missing from the Puppeteer enum: https://chromedevtools.github.io/devtools-protocol/tot/Network#type-ErrorReason
2018-06-19 17:46:17 +00:00
- `blockedbyclient` - The client chose to block the request.
- `blockedbyresponse` - The request failed because the response was delivered along with requirements which are not met ('X-Frame-Options' and 'Content-Security-Policy' ancestor checks, for instance).
feat(Request): allow aborting intercepted requests with custom reasons (#1080) This patch adds optional parameter to the `request.abort()` method that specifies abort reason. References #1020.
2017-10-18 07:26:48 +00:00
- `connectionaborted` - A connection timed out as a result of not receiving an ACK for data sent.
- `connectionclosed` - A connection was closed (corresponding to a TCP FIN).
- `connectionfailed` - A connection attempt failed.
- `connectionrefused` - A connection attempt was refused.
- `connectionreset` - A connection was reset (corresponding to a TCP RST).
- `internetdisconnected` - The Internet connection has been lost.
- `namenotresolved` - The host name could not be resolved.
- `timedout` - An operation timed out.
- `failed` - A generic failure occurred.
docs: heading ID references in docs/api.md (#7974) - `Worker` -> `WebWorker`, `#class-worker` -> `#class-webworker` - `#pagesetuseragentuseragent-useragentdata` -> `#pagesetuseragentuseragent-useragentmetadata` - `####WaitTimeoutOptions` -> `#waittimeoutoptions` - `#cooperative-intercept-mode-and-legacy-intercept-mode` -> `#cooperative-intercept-mode` Co-authored-by: jrandolf <86539915+jrandolf@users.noreply.github.com>
2022-02-11 13:43:52 +00:00
- `priority` <[number]> - Optional intercept abort priority. If provided, intercept will be resolved using [cooperative](#cooperative-intercept-mode) handling rules. Otherwise, intercept will be resolved immediately.
Do not leave dangling promises when sending messages over protocol (#742) It's very bad to have 'unhandled promise rejection' that can't be handled in user code. These errors will exit node process in a near future. This patch avoids 'unhandled promise rejection' while sending protocol messages. This patch: - introduces `puppeteer:error` debug scope and starts using it for all swalloed errors. - makes sure that every `client.send` method is either awaited or its errors are handled. - starts return promises from Request.continue() and Request.abort(). - starts swallow errors from Request.contine() and Request.abort(). The last is the most important part of the patch. Since `Request.continue()` might try to continue canceled request, we should disregard the error. Fixes #627.
2017-09-11 23:21:51 +00:00
- returns: <[Promise]>
Introduce new interception API (#242) This patch introduces new interception API, via killing InterceptedRequest and giving the `abort` and `continue` methods to the Request object.
2017-08-12 00:24:31 +00:00
feat(Chromium): Roll chromium to r511134 (#1153) This roll includes: - crrev.com/510651 that changes request interception methods in protocol - s/Page.setRequestInterceptionEnabled/Page.setRequestInterception BREAKING CHANGE Page.setRequestInterceptionEnabled is renamed into Page.setRequestInterception.
2017-10-24 21:45:03 +00:00
Aborts request. To use this, request interception should be enabled with `page.setRequestInterception`.
Introduce new interception API (#242) This patch introduces new interception API, via killing InterceptedRequest and giving the `abort` and `continue` methods to the Request object.
2017-08-12 00:24:31 +00:00
Exception is immediately thrown if the request interception is not enabled.
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
#### httpRequest.abortErrorReason()
- returns: <[string]> of type [Protocol.Network.ErrorReason](https://chromedevtools.github.io/devtools-protocol/tot/Network/#type-ErrorReason).
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
Returns the most recent reason for aborting set by the previous call to abort() in Cooperative Intercept Mode.
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
#### httpRequest.continue([overrides], [priority])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore(doc): replace 'could' with 'can'
2017-10-09 20:28:48 +00:00
- `overrides` <[Object]> Optional request overwrites, which can be one of the following:
docs(api): major grammatical corrections (#7011) * docs(api): major grammatical corrections * fix: own typo in Keyboard comment Co-authored-by: Jack Franklin <jacktfranklin@chromium.org>
2021-04-06 10:10:00 +00:00
- `url` <[string]> If set changes the request URL. This is not a redirect. The request will be silently forwarded to the new URL. For example, the address bar will show the original URL.
- `method` <[string]> If set changes the request method (e.g. `GET` or `POST`).
- `postData` <[string]> If set changes the post data of request.
fix(network): stringify response headers for intercepted requests (#4436) Stringifying the headers was the behaviour before v1.15 References #4379
2019-05-20 08:05:32 +00:00
- `headers` <[Object]> If set changes the request HTTP headers. Header values will be converted to a string.
docs: fix typo (#7839)
2021-12-13 06:56:26 +00:00
- `priority` <[number]> - Optional intercept abort priority. If provided, intercept will be resolved using coopeative handling rules. Otherwise, intercept will be resolved immediately.
Do not leave dangling promises when sending messages over protocol (#742) It's very bad to have 'unhandled promise rejection' that can't be handled in user code. These errors will exit node process in a near future. This patch avoids 'unhandled promise rejection' while sending protocol messages. This patch: - introduces `puppeteer:error` debug scope and starts using it for all swalloed errors. - makes sure that every `client.send` method is either awaited or its errors are handled. - starts return promises from Request.continue() and Request.abort(). - starts swallow errors from Request.contine() and Request.abort(). The last is the most important part of the patch. Since `Request.continue()` might try to continue canceled request, we should disregard the error. Fixes #627.
2017-09-11 23:21:51 +00:00
- returns: <[Promise]>
Introduce new interception API (#242) This patch introduces new interception API, via killing InterceptedRequest and giving the `abort` and `continue` methods to the Request object.
2017-08-12 00:24:31 +00:00
feat(Chromium): Roll chromium to r511134 (#1153) This roll includes: - crrev.com/510651 that changes request interception methods in protocol - s/Page.setRequestInterceptionEnabled/Page.setRequestInterception BREAKING CHANGE Page.setRequestInterceptionEnabled is renamed into Page.setRequestInterception.
2017-10-24 21:45:03 +00:00
Continues request with optional request overrides. To use this, request interception should be enabled with `page.setRequestInterception`.
Introduce new interception API (#242) This patch introduces new interception API, via killing InterceptedRequest and giving the `abort` and `continue` methods to the Request object.
2017-08-12 00:24:31 +00:00
Exception is immediately thrown if the request interception is not enabled.
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
Note: Pass `DEFAULT_INTERCEPT_RESOLUTION_PRIORITY` to continue a request if your intent is to bypass/defer the request because
your handler has no opinion about it.
docs(api.md): add example to override request headers (#3475) References #3458.
2018-11-01 22:44:04 +00:00
```js
await page.setRequestInterception(true);
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', request => {
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
if (request.isInterceptResolutionHandled()) return;
chore: update prettier globs and format files (#7856) * chore: update prettier globs and format files * fix: remove reference to Markdownlint
2022-02-11 19:29:43 +00:00
// Override headers
docs(api.md): add example to override request headers (#3475) References #3458.
2018-11-01 22:44:04 +00:00
const headers = Object.assign({}, request.headers(), {
foo: 'bar', // set "foo" header
origin: undefined, // remove "origin" header
});
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
request.continue({headers});
docs(api.md): add example to override request headers (#3475) References #3458.
2018-11-01 22:44:04 +00:00
});
```
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
#### httpRequest.continueRequestOverrides()
- returns: <[Object]> Optional request overwrites, which can be one of the following:
- `url` <[string]> If set changes the request URL. This is not a redirect. The request will be silently forwarded to the new URL. For example, the address bar will show the original URL.
- `method` <[string]> If set changes the request method (e.g. `GET` or `POST`).
- `postData` <[string]> If set changes the post data of request.
- `headers` <[Object]> If set changes the request HTTP headers. Header values will be converted to a string.
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
Returns the most recent set of request overrides set with a previous call to continue() in Cooperative Intercept Mode.
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
#### httpRequest.enqueueInterceptAction(pendingHandler)
- `pendingHandler` <[function]> The request interception handler to enqueue
Enqueues a request handler for processing. This facilitates proper execution of async handlers.
chore: rename Request class to HTTPRequest (#5934) It conflicts with an inbuilt TypeScript `Request` type so can cause confusion when in TS land. Note: `Response.ts` and `Worker.ts` also suffer from this; PRs to rename them are incoming.
2020-05-29 08:38:40 +00:00
#### httpRequest.failure()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api.md): fix return signatures that contains null (#1364)
2017-11-15 18:53:17 +00:00
- returns: <?[Object]> Object describing request failure, if any
feat(Request): introduce Request.failure() method (#1065) Similarly to the `request.response()` method, this patch adds `request.failure()` method that returns error details for the failed requests. Fixes #901.
2017-10-18 00:48:04 +00:00
- `errorText` <[string]> Human-readable error message, e.g. `'net::ERR_FAILED'`.
docs(api.md): fix return signatures that contains null (#1364)
2017-11-15 18:53:17 +00:00
The method returns `null` unless this request was failed, as reported by
feat(Request): introduce Request.failure() method (#1065) Similarly to the `request.response()` method, this patch adds `request.failure()` method that returns error details for the failed requests. Fixes #901.
2017-10-18 00:48:04 +00:00
`requestfailed` event.
Example of logging all failed requests:
```js
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('requestfailed', request => {
docs(api.md): fix sample code in API doc, `request.url` -> `request.url()` (#1889)
2018-01-25 05:09:37 +00:00
console.log(request.url() + ' ' + request.failure().errorText);
feat(Request): introduce Request.failure() method (#1065) Similarly to the `request.response()` method, this patch adds `request.failure()` method that returns error details for the failed requests. Fixes #901.
2017-10-18 00:48:04 +00:00
});
```
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
#### httpRequest.finalizeInterceptions()
- returns: <[Promise<unknown>]>
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
When in Cooperative Intercept Mode, awaits pending interception handlers and then decides how to fulfill the request interception.
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
chore: rename Request class to HTTPRequest (#5934) It conflicts with an inbuilt TypeScript `Request` type so can cause confusion when in TS land. Note: `Response.ts` and `Worker.ts` also suffer from this; PRs to rename them are incoming.
2020-05-29 08:38:40 +00:00
#### httpRequest.frame()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(frame): introduce Frame.goto and Frame.waitForNavigation (#3276) This patch introduces API to manage frame navigations. As a drive-by, the `response.frame()` method is added as a shortcut for `response.request().frame()`. Fixes #2918.
2018-09-20 18:31:19 +00:00
- returns: <?[Frame]> A [Frame] that initiated this request, or `null` if navigating to error pages.
feat: Attribute network requests to frames (#1646) This patch introduces `request.frame()` method that returns the frame that initiated request. Fixes #1579
2018-01-10 02:47:21 +00:00
chore: rename Request class to HTTPRequest (#5934) It conflicts with an inbuilt TypeScript `Request` type so can cause confusion when in TS land. Note: `Response.ts` and `Worker.ts` also suffer from this; PRs to rename them are incoming.
2020-05-29 08:38:40 +00:00
#### httpRequest.headers()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
- returns: <[Object]> An object with HTTP headers associated with the request. All header names are lower-case.
[doclint] add linting for class properties This patch: - adds linting for class properties - adds documentation for the missing class properties References #14.
2017-07-12 15:01:21 +00:00
feat: add initiator to HTTPRequest (#7614) Co-Authored-By: atersolis <atersolis@atersolis.net>
2021-09-29 15:14:21 +00:00
#### httpRequest.initiator()
- returns: <[Object]> An object describing the initiator of the request
- `type` <[string]> Type of this initiator. Possible values: `parser`, `script`, `preload`, `SignedExchange` and `other`.
- `stack` <?[Object]> JavaScript stack trace for the initiator, set for `script` only.
- `url` <?[string]> Initiator URL, set for `parser`, `script` and `SignedExchange` type.
- `lineNumber` <?[number]> 0 based initiator line number, set for `parser` and `script`.
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
#### httpRequest.interceptResolutionState()
- returns: <[InterceptResolutionState]>
fix!: typo in 'already-handled' constant of the request interception API (#7813) Issues: #7745, #7747, #7780 Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-09 14:57:40 +00:00
- `action` <[InterceptResolutionAction]> Current resolution action.
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
- `priority` <?[number]> The current priority of the winning action.
`InterceptResolutionAction` is one of:
- `abort` - The request will be aborted if no higher priority arises.
- `respond` - The request will be responded if no higher priority arises.
- `continue` - The request will be continued if no higher priority arises.
- `disabled` - Request interception is not currently enabled (see `page.setRequestInterception`).
- `none` - `abort/continue/respond` have not been called yet.
fix!: typo in 'already-handled' constant of the request interception API (#7813) Issues: #7745, #7747, #7780 Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-09 14:57:40 +00:00
- `already-handled` - The interception has already been handled in Legacy Mode by a call to `abort/continue/respond` with
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
a `priority` of `undefined`. Subsequent calls to `abort/continue/respond` will throw an exception.
fix!: typo in 'already-handled' constant of the request interception API (#7813) Issues: #7745, #7747, #7780 Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-09 14:57:40 +00:00
This example will `continue()` a request at a slightly higher priority than the current action if the interception has not
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
already handled and is not already being continued.
```js
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', interceptedRequest => {
const {action, priority} = interceptedRequest.interceptResolutionState();
fix!: typo in 'already-handled' constant of the request interception API (#7813) Issues: #7745, #7747, #7780 Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-09 14:57:40 +00:00
if (action === InterceptResolutionAction.AlreadyHandled) return;
if (action === InterceptResolutionAction.Continue) return;
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
// Change the action to `continue` and bump the priority so `continue` becomes the new winner
interceptedRequest.continue(
interceptedRequest.continueRequestOverrides(),
priority + 1
);
});
```
#### httpRequest.isInterceptResolutionHandled()
- returns: <[boolean]>
Whether this request's interception has been handled (i.e., `abort`, `continue`, or `respond` has already been called
with a `priority` of `undefined`).
chore: rename Request class to HTTPRequest (#5934) It conflicts with an inbuilt TypeScript `Request` type so can cause confusion when in TS land. Note: `Response.ts` and `Worker.ts` also suffer from this; PRs to rename them are incoming.
2020-05-29 08:38:40 +00:00
#### httpRequest.isNavigationRequest()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(network): introduce Request.isNavigationRequest() method (#2633) This patch introduces `Request.isNavigationRequest()` method. Fixes #2627, #1132.
2018-06-01 00:38:30 +00:00
- returns: <[boolean]>
Whether this request is driving frame's navigation.
chore: rename Request class to HTTPRequest (#5934) It conflicts with an inbuilt TypeScript `Request` type so can cause confusion when in TS land. Note: `Response.ts` and `Worker.ts` also suffer from this; PRs to rename them are incoming.
2020-05-29 08:38:40 +00:00
#### httpRequest.method()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
- returns: <[string]> Request's method (GET, POST, etc.)
Get rid of Body class The Body class was inlined in the Request and Response classes. This patch: - removes the Body class - adds Request.postData public property - adds Response.buffer(), Response.text() and Response.json() methods Fixes #106.
2017-07-28 06:11:24 +00:00
chore: rename Request class to HTTPRequest (#5934) It conflicts with an inbuilt TypeScript `Request` type so can cause confusion when in TS land. Note: `Response.ts` and `Worker.ts` also suffer from this; PRs to rename them are incoming.
2020-05-29 08:38:40 +00:00
#### httpRequest.postData()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
- returns: <[string]> Request's post body, if any.
[doclint] introduce class members This patch unifies Documentation.Method with Documentation.Property, making it possible to verify sorting order across methods and properties. References #14.
2017-07-14 05:52:02 +00:00
chore: rename Request class to HTTPRequest (#5934) It conflicts with an inbuilt TypeScript `Request` type so can cause confusion when in TS land. Note: `Response.ts` and `Worker.ts` also suffer from this; PRs to rename them are incoming.
2020-05-29 08:38:40 +00:00
#### httpRequest.redirectChain()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore: update request and response references in docs (#5942) Missed some Request => HTTPRequest and Response => HTTPResponse renames when updating the docs.
2020-05-29 11:36:04 +00:00
- returns: <[Array]<[HTTPRequest]>>
feat(Network): implement request.redirectChain() api (#2194) The request.redirectChain() returns all the requests issued to fetch the resource. Fixes #1816.
2018-03-16 00:17:38 +00:00
A `redirectChain` is a chain of requests initiated to fetch a resource.
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Network): implement request.redirectChain() api (#2194) The request.redirectChain() returns all the requests issued to fetch the resource. Fixes #1816.
2018-03-16 00:17:38 +00:00
- If there are no redirects and the request was successful, the chain will be empty.
- If a server responds with at least a single redirect, then the chain will
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
contain all the requests that were redirected.
feat(Network): implement request.redirectChain() api (#2194) The request.redirectChain() returns all the requests issued to fetch the resource. Fixes #1816.
2018-03-16 00:17:38 +00:00
`redirectChain` is shared between all the requests of the same chain.
For example, if the website `http://example.com` has a single redirect to
`https://example.com`, then the chain will contain one request:
```js
const response = await page.goto('http://example.com');
const chain = response.request().redirectChain();
console.log(chain.length); // 1
console.log(chain[0].url()); // 'http://example.com'
```
If the website `https://google.com` has no redirects, then the chain will be empty:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Network): implement request.redirectChain() api (#2194) The request.redirectChain() returns all the requests issued to fetch the resource. Fixes #1816.
2018-03-16 00:17:38 +00:00
```js
const response = await page.goto('https://google.com');
const chain = response.request().redirectChain();
console.log(chain.length); // 0
```
chore: rename Request class to HTTPRequest (#5934) It conflicts with an inbuilt TypeScript `Request` type so can cause confusion when in TS land. Note: `Response.ts` and `Worker.ts` also suffer from this; PRs to rename them are incoming.
2020-05-29 08:38:40 +00:00
#### httpRequest.resourceType()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
- returns: <[string]>
Implement Request.resourceType getter (#590) This patch plumbs `resourceType` parameter of RequestWillBeSent and requestIntercepted methods.
2017-08-29 23:27:59 +00:00
Contains the request's resource type as it was perceived by the rendering engine.
fix(Request): convert resourceType to all small-caps (#990) This patch moves resourceType to be all small-caps. This aligns with our convention that all string constants should be smallcaps. BREAKING CHANGE: this patch changes the constants of the request.resourceType to be all small-caps.
2017-10-10 17:53:37 +00:00
ResourceType will be one of the following: `document`, `stylesheet`, `image`, `media`, `font`, `script`, `texttrack`, `xhr`, `fetch`, `eventsource`, `websocket`, `manifest`, `other`.
Implement Request.resourceType getter (#590) This patch plumbs `resourceType` parameter of RequestWillBeSent and requestIntercepted methods.
2017-08-29 23:27:59 +00:00
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
#### httpRequest.respond(response, [priority])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(interception): Implement request.mockResponse method (#1064) feat(interception): Implement request.respond method This patch implements a new Request.respond method. This allows users to fulfill the intercepted request with a hand-crafted response if they wish so. References #1020.
2017-10-20 23:55:15 +00:00
- `response` <[Object]> Response that will fulfill this request
- `status` <[number]> Response status code, defaults to `200`.
feat: respond multiple headers with same key (#8183)
2022-04-05 09:06:35 +00:00
- `headers` <[Object]> Optional response headers. Header values should be a string or a string array.
feat(interception): Implement request.mockResponse method (#1064) feat(interception): Implement request.respond method This patch implements a new Request.respond method. This allows users to fulfill the intercepted request with a hand-crafted response if they wish so. References #1020.
2017-10-20 23:55:15 +00:00
- `contentType` <[string]> If set, equals to setting `Content-Type` response header
fix(types): fix parameters where they disagree with the api (#3525)
2018-11-12 20:59:21 +00:00
- `body` <[string]|[Buffer]> Optional response body
docs: fix typo (#7839)
2021-12-13 06:56:26 +00:00
- `priority` <[number]> - Optional intercept abort priority. If provided, intercept will be resolved using coopeative handling rules. Otherwise, intercept will be resolved immediately.
feat(interception): Implement request.mockResponse method (#1064) feat(interception): Implement request.respond method This patch implements a new Request.respond method. This allows users to fulfill the intercepted request with a hand-crafted response if they wish so. References #1020.
2017-10-20 23:55:15 +00:00
- returns: <[Promise]>
Fulfills request with given response. To use this, request interception should
feat(Chromium): Roll chromium to r511134 (#1153) This roll includes: - crrev.com/510651 that changes request interception methods in protocol - s/Page.setRequestInterceptionEnabled/Page.setRequestInterception BREAKING CHANGE Page.setRequestInterceptionEnabled is renamed into Page.setRequestInterception.
2017-10-24 21:45:03 +00:00
be enabled with `page.setRequestInterception`. Exception is thrown if
feat(interception): Implement request.mockResponse method (#1064) feat(interception): Implement request.respond method This patch implements a new Request.respond method. This allows users to fulfill the intercepted request with a hand-crafted response if they wish so. References #1020.
2017-10-20 23:55:15 +00:00
request interception is not enabled.
An example of fulfilling all requests with 404 responses:
```js
feat(Chromium): Roll chromium to r511134 (#1153) This roll includes: - crrev.com/510651 that changes request interception methods in protocol - s/Page.setRequestInterceptionEnabled/Page.setRequestInterception BREAKING CHANGE Page.setRequestInterceptionEnabled is renamed into Page.setRequestInterception.
2017-10-24 21:45:03 +00:00
await page.setRequestInterception(true);
chore: use Google's TS style guide's format config (#8542)
2022-06-22 13:25:44 +00:00
page.on('request', request => {
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
if (request.isInterceptResolutionHandled()) return;
feat(interception): Implement request.mockResponse method (#1064) feat(interception): Implement request.respond method This patch implements a new Request.respond method. This allows users to fulfill the intercepted request with a hand-crafted response if they wish so. References #1020.
2017-10-20 23:55:15 +00:00
request.respond({
status: 404,
contentType: 'text/plain',
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
body: 'Not Found!',
feat(interception): Implement request.mockResponse method (#1064) feat(interception): Implement request.respond method This patch implements a new Request.respond method. This allows users to fulfill the intercepted request with a hand-crafted response if they wish so. References #1020.
2017-10-20 23:55:15 +00:00
});
});
```
fix: support PlzNavigate in puppeteer. (#1239) This patch migrates puppeteer to support PlzNavigate chromium project. As a consequence of this patch, we no longer wait for both requestWillBeSent and requestIntercepted events to happen. This should resolve a ton of request interception bugs that "hanged" the loading. Fixes #877.
2017-11-01 21:04:10 +00:00
> **NOTE** Mocking responses for dataURL requests is not supported.
> Calling `request.respond` for a dataURL request is a noop.
feat(interception): Implement request.mockResponse method (#1064) feat(interception): Implement request.respond method This patch implements a new Request.respond method. This allows users to fulfill the intercepted request with a hand-crafted response if they wish so. References #1020.
2017-10-20 23:55:15 +00:00
chore: rename Request class to HTTPRequest (#5934) It conflicts with an inbuilt TypeScript `Request` type so can cause confusion when in TS land. Note: `Response.ts` and `Worker.ts` also suffer from this; PRs to rename them are incoming.
2020-05-29 08:38:40 +00:00
#### httpRequest.response()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore: update request and response references in docs (#5942) Missed some Request => HTTPRequest and Response => HTTPResponse renames when updating the docs.
2020-05-29 11:36:04 +00:00
- returns: <?[HTTPResponse]> A matching [HTTPResponse] 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
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
#### httpRequest.responseForRequest()
- returns: <?[HTTPResponse]> A matching [HTTPResponse] object, or `null` if the response has not been received yet.
feat: expose HTTPRequest intercept resolution state and clarify docs (#7796) Co-authored-by: Rodrigo Fernández <fdez.romero@gmail.com>
2021-12-07 07:48:42 +00:00
Returns the current response object set by the previous call to respond() in Cooperative Intercept Mode.
feat: add cooperative request intercepts (#6735) With this change,`request.respond`, `request.abort`, and `request.continue` can accept an optional `priority` to activate Cooperative Intercept Mode. In Cooperative Mode, all intercept handlers are guaranteed to run and all async handlers are awaited. The interception is resolved to the highest-priority resolution. See _Cooperative Intercept Mode and Legacy Intercept Mode_ in `docs/api.md` for details.
2021-07-02 17:58:32 +00:00
chore: rename Request class to HTTPRequest (#5934) It conflicts with an inbuilt TypeScript `Request` type so can cause confusion when in TS land. Note: `Response.ts` and `Worker.ts` also suffer from this; PRs to rename them are incoming.
2020-05-29 08:38:40 +00:00
#### httpRequest.url()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
- returns: <[string]> URL of the request.
Fill doc with stubs for missing documentation methods. This patch fills doc with stubs so that the command `npm run doc` does not complain.
2017-07-07 17:34:35 +00:00
chore: rename `Response` to `HTTPResponse` (#5940) To avoid any conflicts with the TS `Response` type.
2020-05-29 10:49:30 +00:00
### class: HTTPResponse
[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
chore: update request and response references in docs (#5942) Missed some Request => HTTPRequest and Response => HTTPResponse renames when updating the docs.
2020-05-29 11:36:04 +00:00
[HTTPResponse] 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
chore: rename `Response` to `HTTPResponse` (#5940) To avoid any conflicts with the TS `Response` type.
2020-05-29 10:49:30 +00:00
#### httpResponse.buffer()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api): fix some typos (#6712)
2020-12-31 05:30:27 +00:00
- returns: <[Promise]<[Buffer]>> Promise which resolves to a buffer with response body.
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
chore: rename `Response` to `HTTPResponse` (#5940) To avoid any conflicts with the TS `Response` type.
2020-05-29 10:49:30 +00:00
#### httpResponse.frame()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(frame): introduce Frame.goto and Frame.waitForNavigation (#3276) This patch introduces API to manage frame navigations. As a drive-by, the `response.frame()` method is added as a shortcut for `response.request().frame()`. Fixes #2918.
2018-09-20 18:31:19 +00:00
- returns: <?[Frame]> A [Frame] that initiated this response, or `null` if navigating to error pages.
chore: rename `Response` to `HTTPResponse` (#5940) To avoid any conflicts with the TS `Response` type.
2020-05-29 10:49:30 +00:00
#### httpResponse.fromCache()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Response): add Response.fromCache / Response.fromServiceWorker (#1971) This patch: - introduces `test/assets/cached` folder and teaches server to cache all the assets from the folder - introduces `test/assets/serviceworkers` folder that stores all the service workers and makes them register with unique URL prefix - introduces `Response.fromCache()` and `Response.fromServiceWorker()` methods Fixes #1551.
2018-02-05 22:59:07 +00:00
- returns: <[boolean]>
True if the response was served from either the browser's disk cache or memory cache.
chore: rename `Response` to `HTTPResponse` (#5940) To avoid any conflicts with the TS `Response` type.
2020-05-29 10:49:30 +00:00
#### httpResponse.fromServiceWorker()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Response): add Response.fromCache / Response.fromServiceWorker (#1971) This patch: - introduces `test/assets/cached` folder and teaches server to cache all the assets from the folder - introduces `test/assets/serviceworkers` folder that stores all the service workers and makes them register with unique URL prefix - introduces `Response.fromCache()` and `Response.fromServiceWorker()` methods Fixes #1551.
2018-02-05 22:59:07 +00:00
- returns: <[boolean]>
True if the response was served by a service worker.
chore: rename `Response` to `HTTPResponse` (#5940) To avoid any conflicts with the TS `Response` type.
2020-05-29 10:49:30 +00:00
#### httpResponse.headers()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
- returns: <[Object]> An object with HTTP headers associated with the response. All header names are lower-case.
[doclint] add linting for class properties This patch: - adds linting for class properties - adds documentation for the missing class properties References #14.
2017-07-12 15:01:21 +00:00
chore: rename `Response` to `HTTPResponse` (#5940) To avoid any conflicts with the TS `Response` type.
2020-05-29 10:49:30 +00:00
#### httpResponse.json()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api): fix some typos (#6712)
2020-12-31 05:30:27 +00:00
- returns: <[Promise]<[Object]>> Promise which resolves to a JSON representation of response body.
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
This method will throw if the response body is not parsable via `JSON.parse`.
chore: rename `Response` to `HTTPResponse` (#5940) To avoid any conflicts with the TS `Response` type.
2020-05-29 10:49:30 +00:00
#### httpResponse.ok()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
- returns: <[boolean]>
[doclint] add linting for class properties This patch: - adds linting for class properties - adds documentation for the missing class properties References #14.
2017-07-12 15:01:21 +00:00
Contains a boolean stating whether the response was successful (status in the range 200-299) or not.
chore: rename `Response` to `HTTPResponse` (#5940) To avoid any conflicts with the TS `Response` type.
2020-05-29 10:49:30 +00:00
#### httpResponse.remoteAddress()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(network): introduce Response.remoteAddress() (#3192) Closes #2171.
2018-09-04 19:39:59 +00:00
- returns: <[Object]>
fix!: strict mode fixes for HTTPRequest/Response classes (#8297) Solves type issues in HTTPRequest/Response with some slight changes in the behaviour and API. Issues #6769
2022-05-05 06:48:03 +00:00
- `ip` <[string]> the IP address of the remote server if known and `undefined` otherwise.
- `port` <[number]> the port used to connect to the remote server if known and `undefined` otherwise.
feat(network): introduce Response.remoteAddress() (#3192) Closes #2171.
2018-09-04 19:39:59 +00:00
chore: rename `Response` to `HTTPResponse` (#5940) To avoid any conflicts with the TS `Response` type.
2020-05-29 10:49:30 +00:00
#### httpResponse.request()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore: update request and response references in docs (#5942) Missed some Request => HTTPRequest and Response => HTTPResponse renames when updating the docs.
2020-05-29 11:36:04 +00:00
- returns: <[HTTPRequest]> A matching [HTTPRequest] object.
[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
chore: rename `Response` to `HTTPResponse` (#5940) To avoid any conflicts with the TS `Response` type.
2020-05-29 10:49:30 +00:00
#### httpResponse.securityDetails()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
fix(Network): fulfill security details for response redirects (#2025) This patch: - starts fulfilling security details for redirect responses - changes `response.securityDetails()` to return null if the response is served over non-secure connection
2018-02-15 00:08:20 +00:00
- returns: <?[SecurityDetails]> Security details if the response was received over the secure connection, or `null` otherwise.
feat(Network): introduce response.securityDetails() method (#1880) This patch: - introduces `SecurityDetails` class that exposes a set of fields that describe properties of secure connection - introduces method `response.securityDetails()` that returns an instance of `SecurityDetails` object.
2018-02-13 19:26:18 +00:00
chore: rename `Response` to `HTTPResponse` (#5940) To avoid any conflicts with the TS `Response` type.
2020-05-29 10:49:30 +00:00
#### httpResponse.status()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
- returns: <[number]>
[doclint] add linting for class properties This patch: - adds linting for class properties - adds documentation for the missing class properties References #14.
2017-07-12 15:01:21 +00:00
Contains the status code of the response (e.g., 200 for a success).
chore: rename `Response` to `HTTPResponse` (#5940) To avoid any conflicts with the TS `Response` type.
2020-05-29 10:49:30 +00:00
#### httpResponse.statusText()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(network): introduce Response.statusText() (#3193) Fixes #317.
2018-09-05 20:03:24 +00:00
- returns: <[string]>
Contains the status text of the response (e.g. usually an "OK" for a success).
chore: rename `Response` to `HTTPResponse` (#5940) To avoid any conflicts with the TS `Response` type.
2020-05-29 10:49:30 +00:00
#### httpResponse.text()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
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
feat(HTTPResponse): expose timing information (#8025)
2022-02-15 10:16:49 +00:00
#### httpResponse.timing()
- returns: <?[Object]>
- `requestTime` <[number]> baseline in seconds
- `proxyStart` <[number]> started resolving proxy (milliseconds since requestTime)
- `proxyEnd` <[number]> finished resolving proxy (milliseconds since requestTime)
- `dnsStart` <[number]> started DNS address resolve (milliseconds since requestTime)
- `dnsEnd` <[number]> finished DNS address resolve (milliseconds since requestTime)
- `connectStart` <[number]> started connecting to the remote host (milliseconds since requestTime)
- `connectEnd` <[number]> connected to the remote host (milliseconds since requestTime)
- `sslStart` <[number]> started SSL handshake (milliseconds since requestTime)
- `sslEnd` <[number]> finished SSL handshake (milliseconds since requestTime)
- `workerStart` <[number]> started running ServiceWorker (milliseconds since requestTime)
- `workerReady` <[number]> finished Starting ServiceWorker (milliseconds since requestTime)
- `workerFetchStart` <[number]> started fetch event (milliseconds since requestTime)
- `workerRespondWithSettled` <[number]> settled fetch event respondWith promise (milliseconds since requestTime)
- `sendStart` <[number]> started sending request (milliseconds since requestTime)
- `sendEnd` <[number]> finished sending request (milliseconds since requestTime)
- `pushStart` <[number]> time the server started pushing request (milliseconds since requestTime)
- `pushEnd` <[number]> time the server finished pushing request (milliseconds since requestTime)
- `receiveHeadersEnd` <[number]> finished receiving response headers (milliseconds since requestTime)
Timing information related to the response.
chore: rename `Response` to `HTTPResponse` (#5940) To avoid any conflicts with the TS `Response` type.
2020-05-29 10:49:30 +00:00
#### httpResponse.url()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
fix: convert all getters to methods (#1621) The patch converts all the getters in the codebase into the methods. For example, the `request.url` getter becomes the `request.url()` method. This is done in order to unify the API and make it more predictable. The general rule for all further changes would be: - there are no getters/fields exposed in the api - the only exceptions are "namespaces", e.g. `page.keyboard` Fixes #280. BREAKING CHANGE: This patch ditches getters and replaces them with methods throughout the API. The following methods were added instead of the fields: - dialog.type() - consoleMessage.args() - consoleMessage.text() - consoleMessage.type() - request.headers() - request.method() - request.postData() - request.resourceType() - request.url() - response.headers() - response.ok() - response.status() - response.url()
2017-12-19 01:05:57 +00:00
- returns: <[string]>
[doclint] add linting for class properties This patch: - adds linting for class properties - adds documentation for the missing class properties References #14.
2017-07-12 15:01:21 +00:00
Contains the URL of the response.
feat(Network): introduce response.securityDetails() method (#1880) This patch: - introduces `SecurityDetails` class that exposes a set of fields that describe properties of secure connection - introduces method `response.securityDetails()` that returns an instance of `SecurityDetails` object.
2018-02-13 19:26:18 +00:00
### class: SecurityDetails
docs(api.md): Fix description of SecurityDetails class (#3277)
2018-09-20 14:48:30 +00:00
[SecurityDetails] class represents the security details when response was received over the secure connection.
feat(Network): introduce response.securityDetails() method (#1880) This patch: - introduces `SecurityDetails` class that exposes a set of fields that describe properties of secure connection - introduces method `response.securityDetails()` that returns an instance of `SecurityDetails` object.
2018-02-13 19:26:18 +00:00
#### securityDetails.issuer()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Network): introduce response.securityDetails() method (#1880) This patch: - introduces `SecurityDetails` class that exposes a set of fields that describe properties of secure connection - introduces method `response.securityDetails()` that returns an instance of `SecurityDetails` object.
2018-02-13 19:26:18 +00:00
- returns: <[string]> A string with the name of issuer of the certificate.
#### securityDetails.protocol()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Network): introduce response.securityDetails() method (#1880) This patch: - introduces `SecurityDetails` class that exposes a set of fields that describe properties of secure connection - introduces method `response.securityDetails()` that returns an instance of `SecurityDetails` object.
2018-02-13 19:26:18 +00:00
- returns: <[string]> String with the security protocol, eg. "TLS 1.2".
feat: add securityDetails.subjectAlternativeNames() #5628 (#5881) Co-authored-by: Michal TOMA <michaltoma2205@gmail.com> Co-authored-by: Alex Rudenko <alexrudenko@chromium.org> Fixes #5625. Closes #5628.
2020-05-18 10:58:46 +00:00
#### securityDetails.subjectAlternativeNames()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: add securityDetails.subjectAlternativeNames() #5628 (#5881) Co-authored-by: Michal TOMA <michaltoma2205@gmail.com> Co-authored-by: Alex Rudenko <alexrudenko@chromium.org> Fixes #5625. Closes #5628.
2020-05-18 10:58:46 +00:00
- returns: <[Array]<[string]>> Returns the list of SANs (subject alternative names) of the certificate.
feat(Network): introduce response.securityDetails() method (#1880) This patch: - introduces `SecurityDetails` class that exposes a set of fields that describe properties of secure connection - introduces method `response.securityDetails()` that returns an instance of `SecurityDetails` object.
2018-02-13 19:26:18 +00:00
#### securityDetails.subjectName()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Network): introduce response.securityDetails() method (#1880) This patch: - introduces `SecurityDetails` class that exposes a set of fields that describe properties of secure connection - introduces method `response.securityDetails()` that returns an instance of `SecurityDetails` object.
2018-02-13 19:26:18 +00:00
- returns: <[string]> Name of the subject to which the certificate was issued to.
#### securityDetails.validFrom()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
fix(Network): fulfill security details for response redirects (#2025) This patch: - starts fulfilling security details for redirect responses - changes `response.securityDetails()` to return null if the response is served over non-secure connection
2018-02-15 00:08:20 +00:00
- returns: <[number]> [UnixTime] stating the start of validity of the certificate.
feat(Network): introduce response.securityDetails() method (#1880) This patch: - introduces `SecurityDetails` class that exposes a set of fields that describe properties of secure connection - introduces method `response.securityDetails()` that returns an instance of `SecurityDetails` object.
2018-02-13 19:26:18 +00:00
#### securityDetails.validTo()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
fix(Network): fulfill security details for response redirects (#2025) This patch: - starts fulfilling security details for redirect responses - changes `response.securityDetails()` to return null if the response is served over non-secure connection
2018-02-15 00:08:20 +00:00
- returns: <[number]> [UnixTime] stating the end of validity of the certificate.
feat(Network): introduce response.securityDetails() method (#1880) This patch: - introduces `SecurityDetails` class that exposes a set of fields that describe properties of secure connection - introduces method `response.securityDetails()` that returns an instance of `SecurityDetails` object.
2018-02-13 19:26:18 +00:00
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
### class: Target
Add `Page.browser()` method (#2387) Call page.browser() to get the browser instance associated with a page. Fixes #2275
2018-04-17 17:37:17 +00:00
#### target.browser()
- returns: <[Browser]>
Get the browser the target belongs to.
feat(BrowserContext): introduce Browser Contexts. (#2523) This patch introduces Browser Contexts and methods to manage them: - `browser.createIncognitoBrowserContext()` - to create new incognito context - `browser.browserContext()` - to get all existing contexts - `browserContext.dispose()` - to dispose incognito context. Fixes #85.
2018-05-10 20:26:08 +00:00
#### target.browserContext()
- returns: <[BrowserContext]>
The browser context the target belongs to.
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
#### target.createCDPSession()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
- returns: <[Promise]<[CDPSession]>>
Creates a Chrome Devtools Protocol session attached to the target.
feat(targets): add target.opener() (#2641) This adds a `.opener` property to a target so that its origin can be tracked. For now returns `null` when there's no `openerId`. Fixes #1830
2018-06-01 00:06:29 +00:00
#### target.opener()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(targets): add target.opener() (#2641) This adds a `.opener` property to a target so that its origin can be tracked. For now returns `null` when there's no `openerId`. Fixes #1830
2018-06-01 00:06:29 +00:00
- returns: <?[Target]>
Get the target that opened this target. Top-level targets return `null`.
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
#### target.page()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api.md): fix return signatures that contains null (#1364)
2017-11-15 18:53:17 +00:00
- returns: <[Promise]<?[Page]>>
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
feat(target): add support for target.page for 'backgroud_page' (#2600) This patch teaches `target.page()` method to attach to extension background pages. Fixes #2438
2018-06-14 20:58:51 +00:00
If the target is not of type `"page"` or `"background_page"`, returns `null`.
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
#### target.type()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(workers): create workers from service workers and shared workers (#4397) This allows users to easily evaluate javascript inside service workers and shared workers by creating a Worker object for them.
2019-05-10 00:29:18 +00:00
- returns: <"page"|"background_page"|"service_worker"|"shared_worker"|"other"|"browser">
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
feat(workers): create workers from service workers and shared workers (#4397) This allows users to easily evaluate javascript inside service workers and shared workers by creating a Worker object for them.
2019-05-10 00:29:18 +00:00
Identifies what kind of target this is. Can be `"page"`, [`"background_page"`](https://developer.chrome.com/extensions/background_pages), `"service_worker"`, `"shared_worker"`, `"browser"` or `"other"`.
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
#### target.url()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(Browser): introduce Browser.pages() (#554) This patch: - introduces Target class that represents any inspectable target, such as service worker or page - emits events when targets come and go - introduces target.page() to instantiate a page from a target Fixes #386, fixes #443.
2017-10-18 02:14:57 +00:00
- returns: <[string]>
feat(workers): create workers from service workers and shared workers (#4397) This allows users to easily evaluate javascript inside service workers and shared workers by creating a Worker object for them.
2019-05-10 00:29:18 +00:00
#### target.worker()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore: rename Worker to WebWorker (#5941) To avoid TS name conflicts.
2020-05-29 11:57:54 +00:00
- returns: <[Promise]<?[WebWorker]>>
feat(workers): create workers from service workers and shared workers (#4397) This allows users to easily evaluate javascript inside service workers and shared workers by creating a Worker object for them.
2019-05-10 00:29:18 +00:00
If the target is not of type `"service_worker"` or `"shared_worker"`, returns `null`.
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
### class: CDPSession
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- extends: [EventEmitter](#class-eventemitter)
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
The `CDPSession` instances are used to talk raw Chrome Devtools Protocol:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
- protocol methods can be called with `session.send` method.
- protocol events can be subscribed to with `session.on` method.
docs(api.md): add links to CDP guide and pptr.dev (#4159)
2019-03-13 20:17:10 +00:00
Useful links:
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api.md): add links to CDP guide and pptr.dev (#4159)
2019-03-13 20:17:10 +00:00
- Documentation on DevTools Protocol can be found here: [DevTools Protocol Viewer](https://chromedevtools.github.io/devtools-protocol/).
chore: remove references to upstream `master` branches (#7412) Chromium had its branch renamed to `main`, and for other projects we can just point to the `HEAD`.
2021-09-14 15:02:39 +00:00
- Getting Started with DevTools Protocol: https://github.com/aslushnikov/getting-started-with-cdp/blob/HEAD/README.md
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
```js
const client = await page.target().createCDPSession();
await client.send('Animation.enable');
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
client.on('Animation.animationCreated', () =>
console.log('Animation created!')
);
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
const response = await client.send('Animation.getPlaybackRate');
console.log('playback rate is ' + response.playbackRate);
await client.send('Animation.setPlaybackRate', {
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
playbackRate: response.playbackRate / 2,
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
});
```
feat: expose other sessions from connection (#6863)
2021-05-07 08:31:39 +00:00
#### cdpSession.connection()
- returns: <[Connection]>
Returns the underlying connection associated with the session. Can be used to obtain other related sessions.
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
#### cdpSession.detach()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
- returns: <[Promise]>
docs: add the word `the` everywhere (#1988)
2018-02-07 22:20:28 +00:00
Detaches the cdpSession from the target. Once detached, the cdpSession object won't emit any events and can't be used
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
to send messages.
feat(oop iframes)!: integrate OOP iframes with the frame manager (#7556) This pull request to adds better support for OOP iframes (see #2548) The current problem with OOP iframes is that they are moved to a different target. Because of this, the previous versions of Puppeteer pretty much ignored them. This change extends the FrameManager to already take OOP iframes into account and hides the fact that those frames are actually in different targets. Further work needs to be done to also make the NetworkManager aware of these and to make sure that settings like emulations etc. are also properly passed down to the new targets.
2021-10-28 09:25:49 +00:00
#### cdpSession.id()
- returns: <[string]>
Returns the session's id.
chore: use devtools-protocol package (#6172) * chore: Use devtools-protocol package Rather than maintain our own protocol we can instead use the devtools-protocol package and pin it to the version of Chromium that Puppeteer is shipping with. The only changes are naming changes between the bespoke protocol that Puppeteer created and the devtools-protocol one.
2020-07-10 10:51:52 +00:00
#### cdpSession.send(method[, ...paramArgs])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
- `method` <[string]> protocol method name
chore: use devtools-protocol package (#6172) * chore: Use devtools-protocol package Rather than maintain our own protocol we can instead use the devtools-protocol package and pin it to the version of Chromium that Puppeteer is shipping with. The only changes are naming changes between the bespoke protocol that Puppeteer created and the devtools-protocol one.
2020-07-10 10:51:52 +00:00
- `...paramArgs` <[Object]> Optional method parameters
feat: expose raw devtools protocol connection (#1770) feat: expose raw devtools protocol connection This patch introduces `target.createCDPSession` method that allows directly communicating with the target over the Chrome DevTools Protocol. Fixes #31.
2018-01-11 03:33:22 +00:00
- returns: <[Promise]<[Object]>>
feat: Implement JavaScript Coverage (#1673) This patch introduces a new `page.coverage` namespace with two methods: - `page.coverage.startJSCoverage` to initiate JavaScript coverage recording - `page.coverage.stopJSCoverage` to stop JavaScript coverage and get results
2018-01-03 03:53:53 +00:00
### class: Coverage
feat: implement CSS Coverage (#1714) This patch adds two new methods to the `page.coverage` namespace: - `page.coverage.startCSSCoverage()` - to initiate css coverage - `page.coverage.stopCSSCoverage()` - to stop css coverage The coverage format is consistent with the JavaScript coverage.
2018-01-04 02:21:40 +00:00
Coverage gathers information about parts of JavaScript and CSS that were used by the page.
An example of using JavaScript and CSS coverage to get percentage of initially
executed code:
```js
// Enable both JavaScript and CSS coverage
await Promise.all([
docs(api): fix coverage example and typo (#1854)
2018-01-19 05:19:13 +00:00
page.coverage.startJSCoverage(),
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
page.coverage.startCSSCoverage(),
feat: implement CSS Coverage (#1714) This patch adds two new methods to the `page.coverage` namespace: - `page.coverage.startCSSCoverage()` - to initiate css coverage - `page.coverage.stopCSSCoverage()` - to stop css coverage The coverage format is consistent with the JavaScript coverage.
2018-01-04 02:21:40 +00:00
]);
// Navigate to page
await page.goto('https://example.com');
// Disable both JavaScript and CSS coverage
const [jsCoverage, cssCoverage] = await Promise.all([
docs(api): fix coverage example and typo (#1854)
2018-01-19 05:19:13 +00:00
page.coverage.stopJSCoverage(),
page.coverage.stopCSSCoverage(),
feat: implement CSS Coverage (#1714) This patch adds two new methods to the `page.coverage` namespace: - `page.coverage.startCSSCoverage()` - to initiate css coverage - `page.coverage.stopCSSCoverage()` - to stop css coverage The coverage format is consistent with the JavaScript coverage.
2018-01-04 02:21:40 +00:00
]);
let totalBytes = 0;
let usedBytes = 0;
docs(api): fix coverage example and typo (#1854)
2018-01-19 05:19:13 +00:00
const coverage = [...jsCoverage, ...cssCoverage];
feat: implement CSS Coverage (#1714) This patch adds two new methods to the `page.coverage` namespace: - `page.coverage.startCSSCoverage()` - to initiate css coverage - `page.coverage.stopCSSCoverage()` - to stop css coverage The coverage format is consistent with the JavaScript coverage.
2018-01-04 02:21:40 +00:00
for (const entry of coverage) {
totalBytes += entry.text.length;
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
for (const range of entry.ranges) usedBytes += range.end - range.start - 1;
feat: implement CSS Coverage (#1714) This patch adds two new methods to the `page.coverage` namespace: - `page.coverage.startCSSCoverage()` - to initiate css coverage - `page.coverage.stopCSSCoverage()` - to stop css coverage The coverage format is consistent with the JavaScript coverage.
2018-01-04 02:21:40 +00:00
}
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
console.log(`Bytes used: ${(usedBytes / totalBytes) * 100}%`);
feat: implement CSS Coverage (#1714) This patch adds two new methods to the `page.coverage` namespace: - `page.coverage.startCSSCoverage()` - to initiate css coverage - `page.coverage.stopCSSCoverage()` - to stop css coverage The coverage format is consistent with the JavaScript coverage.
2018-01-04 02:21:40 +00:00
```
docs: add documentation referencing puppeteer-to-istanbul (#2135) Fixes #1768.
2018-03-07 05:49:01 +00:00
_To output coverage in a form consumable by [Istanbul](https://github.com/istanbuljs),
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
see [puppeteer-to-istanbul](https://github.com/istanbuljs/puppeteer-to-istanbul)._
docs: add documentation referencing puppeteer-to-istanbul (#2135) Fixes #1768.
2018-03-07 05:49:01 +00:00
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### coverage.startCSSCoverage([options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- `options` <[Object]> Set of configurable options for coverage
feat: implement CSS Coverage (#1714) This patch adds two new methods to the `page.coverage` namespace: - `page.coverage.startCSSCoverage()` - to initiate css coverage - `page.coverage.stopCSSCoverage()` - to stop css coverage The coverage format is consistent with the JavaScript coverage.
2018-01-04 02:21:40 +00:00
- `resetOnNavigation` <[boolean]> Whether to reset coverage on every navigation. Defaults to `true`.
- returns: <[Promise]> Promise that resolves when coverage is started
docs(api.md): mark optional arguments in signatures (#3565) Some `[]` marks were missing.
2018-11-19 20:36:28 +00:00
#### coverage.startJSCoverage([options])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- `options` <[Object]> Set of configurable options for coverage
feat: Implement JavaScript Coverage (#1673) This patch introduces a new `page.coverage` namespace with two methods: - `page.coverage.startJSCoverage` to initiate JavaScript coverage recording - `page.coverage.stopJSCoverage` to stop JavaScript coverage and get results
2018-01-03 03:53:53 +00:00
- `resetOnNavigation` <[boolean]> Whether to reset coverage on every navigation. Defaults to `true`.
feat(coverage): add an option to collect coverage of anonymous scripts (#2796) This patch adds `reportAnonymousScripts` option to the `coverage.startJSCoverage` method. With this option, anonymous scripts are reported as well. Fixes #2777
2018-07-12 01:38:34 +00:00
- `reportAnonymousScripts` <[boolean]> Whether anonymous scripts generated by the page should be reported. Defaults to `false`.
feat: Implement JavaScript Coverage (#1673) This patch introduces a new `page.coverage` namespace with two methods: - `page.coverage.startJSCoverage` to initiate JavaScript coverage recording - `page.coverage.stopJSCoverage` to stop JavaScript coverage and get results
2018-01-03 03:53:53 +00:00
- returns: <[Promise]> Promise that resolves when coverage is started
feat: use absolute URL for EVALUATION_SCRIPT_URL (#8481) Closes #8424
2022-06-07 13:36:51 +00:00
> **NOTE** Anonymous scripts are ones that don't have an associated URL. These are scripts that are dynamically created on the page using `eval` or `new Function`. If `reportAnonymousScripts` is set to `true`, anonymous scripts will have `pptr://__puppeteer_evaluation_script__` as their URL.
feat(coverage): add an option to collect coverage of anonymous scripts (#2796) This patch adds `reportAnonymousScripts` option to the `coverage.startJSCoverage` method. With this option, anonymous scripts are reported as well. Fixes #2777
2018-07-12 01:38:34 +00:00
feat: implement CSS Coverage (#1714) This patch adds two new methods to the `page.coverage` namespace: - `page.coverage.startCSSCoverage()` - to initiate css coverage - `page.coverage.stopCSSCoverage()` - to stop css coverage The coverage format is consistent with the JavaScript coverage.
2018-01-04 02:21:40 +00:00
#### coverage.stopCSSCoverage()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat: implement CSS Coverage (#1714) This patch adds two new methods to the `page.coverage` namespace: - `page.coverage.startCSSCoverage()` - to initiate css coverage - `page.coverage.stopCSSCoverage()` - to stop css coverage The coverage format is consistent with the JavaScript coverage.
2018-01-04 02:21:40 +00:00
- returns: <[Promise]<[Array]<[Object]>>> Promise that resolves to the array of coverage reports for all stylesheets
- `url` <[string]> StyleSheet URL
- `text` <[string]> StyleSheet content
- `ranges` <[Array]<[Object]>> StyleSheet ranges that were used. Ranges are sorted and non-overlapping.
- `start` <[number]> A start offset in text, inclusive
- `end` <[number]> An end offset in text, exclusive
> **NOTE** CSS Coverage doesn't include dynamically injected style tags without sourceURLs.
feat: Implement JavaScript Coverage (#1673) This patch introduces a new `page.coverage` namespace with two methods: - `page.coverage.startJSCoverage` to initiate JavaScript coverage recording - `page.coverage.stopJSCoverage` to stop JavaScript coverage and get results
2018-01-03 03:53:53 +00:00
#### coverage.stopJSCoverage()
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
feat(coverage): add an option to collect coverage of anonymous scripts (#2796) This patch adds `reportAnonymousScripts` option to the `coverage.startJSCoverage` method. With this option, anonymous scripts are reported as well. Fixes #2777
2018-07-12 01:38:34 +00:00
- returns: <[Promise]<[Array]<[Object]>>> Promise that resolves to the array of coverage reports for all scripts
feat: Implement JavaScript Coverage (#1673) This patch introduces a new `page.coverage` namespace with two methods: - `page.coverage.startJSCoverage` to initiate JavaScript coverage recording - `page.coverage.stopJSCoverage` to stop JavaScript coverage and get results
2018-01-03 03:53:53 +00:00
- `url` <[string]> Script URL
- `text` <[string]> Script content
- `ranges` <[Array]<[Object]>> Script ranges that were executed. Ranges are sorted and non-overlapping.
- `start` <[number]> A start offset in text, inclusive
- `end` <[number]> An end offset in text, exclusive
feat(coverage): add an option to collect coverage of anonymous scripts (#2796) This patch adds `reportAnonymousScripts` option to the `coverage.startJSCoverage` method. With this option, anonymous scripts are reported as well. Fixes #2777
2018-07-12 01:38:34 +00:00
> **NOTE** JavaScript Coverage doesn't include anonymous scripts by default. However, scripts with sourceURLs are
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
> reported.
feat: Implement JavaScript Coverage (#1673) This patch introduces a new `page.coverage` namespace with two methods: - `page.coverage.startJSCoverage` to initiate JavaScript coverage recording - `page.coverage.stopJSCoverage` to stop JavaScript coverage and get results
2018-01-03 03:53:53 +00:00
feat: introduce puppeteer/Errors (#3056) This patch adds a new require, `puppeteer/Errors`, that holds all the Puppeteer-specific error classes. Currently, the only custom error class we use is `TimeoutError`. We'll expand in future with `CrashError` and some others. Fixes #1694.
2018-08-09 23:51:12 +00:00
### class: TimeoutError
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
- extends: [Error]
feat: introduce puppeteer/Errors (#3056) This patch adds a new require, `puppeteer/Errors`, that holds all the Puppeteer-specific error classes. Currently, the only custom error class we use is `TimeoutError`. We'll expand in future with `CrashError` and some others. Fixes #1694.
2018-08-09 23:51:12 +00:00
TimeoutError is emitted whenever certain operations are terminated due to timeout, e.g. [page.waitForSelector(selector[, options])](#pagewaitforselectorselector-options) or [puppeteer.launch([options])](#puppeteerlaunchoptions).
chore: migrate away from Node's EventEmitter (#5979)
2020-06-15 10:52:19 +00:00
### class: EventEmitter
feat: introduce puppeteer/Errors (#3056) This patch adds a new require, `puppeteer/Errors`, that holds all the Puppeteer-specific error classes. Currently, the only custom error class we use is `TimeoutError`. We'll expand in future with `CrashError` and some others. Fixes #1694.
2018-08-09 23:51:12 +00:00
chore: migrate away from Node's EventEmitter (#5979)
2020-06-15 10:52:19 +00:00
A small EventEmitter class backed by [Mitt](https://github.com/developit/mitt/).
#### eventEmitter.addListener(event, handler)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
docs(api): fix typo (#6911) Issue: #6903 Co-authored-by: susan51531 <804885378@qq.com>
2021-02-20 10:31:37 +00:00
- `event` <[string]|[symbol]> the event to add the handler to.
chore: migrate away from Node's EventEmitter (#5979)
2020-06-15 10:52:19 +00:00
- `handler` <[Function]> the event listener that will be added.
- returns: `this` so you can chain method calls
This method is identical to `on` and maintained for compatibility with Node's EventEmitter. We recommend using `on` by default.
#### eventEmitter.emit(event, [eventData])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore: migrate away from Node's EventEmitter (#5979)
2020-06-15 10:52:19 +00:00
- `event` <[string]|[symbol]> the event to trigger.
- `eventData` <[Object]> additional data to send with the event.
- returns: `boolean`; `true` if there are any listeners for the event, `false` if there are none.
#### eventEmitter.listenerCount(event)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore: migrate away from Node's EventEmitter (#5979)
2020-06-15 10:52:19 +00:00
- `event` <[string]|[symbol]> the event to check for listeners.
- returns: <[number]> the number of listeners for the given event.
#### eventEmitter.off(event, handler)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore: migrate away from Node's EventEmitter (#5979)
2020-06-15 10:52:19 +00:00
- `event` <[string]|[symbol]> the event to remove the handler from.
- `handler` <[Function]> the event listener that will be removed.
- returns: `this` so you can chain method calls
#### eventEmitter.on(event, handler)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore: migrate away from Node's EventEmitter (#5979)
2020-06-15 10:52:19 +00:00
- `event` <[string]|[symbol]> the event to add the handler to.
- `handler` <[Function]> the event listener that will be added.
- returns: `this` so you can chain method calls
#### eventEmitter.once(event, handler)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore: migrate away from Node's EventEmitter (#5979)
2020-06-15 10:52:19 +00:00
- `event` <[string]|[symbol]> the event to add the handler to.
- `handler` <[Function]> the event listener that will be added.
- returns: `this` so you can chain method calls
#### eventEmitter.removeAllListeners([event])
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore: migrate away from Node's EventEmitter (#5979)
2020-06-15 10:52:19 +00:00
- `event` <[string]|[symbol]> optional argument to remove all listeners for the given event. If it's not given this method will remove all listeners for all events.
- returns: `this` so you can chain method calls
#### eventEmitter.removeListener(event, handler)
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
chore: migrate away from Node's EventEmitter (#5979)
2020-06-15 10:52:19 +00:00
- `event` <[string]|[symbol]> the event to remove the handler from.
- `handler` <[Function]> the event listener that will be removed.
- returns: `this` so you can chain method calls
This method is identical to `off` and maintained for compatibility with Node's EventEmitter. We recommend using `off` by default.
feat: introduce puppeteer/Errors (#3056) This patch adds a new require, `puppeteer/Errors`, that holds all the Puppeteer-specific error classes. Currently, the only custom error class we use is `TimeoutError`. We'll expand in future with `CrashError` and some others. Fixes #1694.
2018-08-09 23:51:12 +00:00
chore: mark version v5.4.0 (#6542)
2020-10-23 14:28:38 +00:00
### interface: CustomQueryHandler
docs: improve custom query handler docs (#8235)
2022-04-19 12:48:22 +00:00
After [registration](#puppeteerregistercustomqueryhandlername-queryhandler), the handler can be used everywhere where a selector is expected by prepending the selection string with `<name>/`. The name is only allowed to consist of lower and upper case Latin letters.
Contains two functions `queryOne` and `queryAll` that are executed in the page context. `queryOne` should take an `Element` and a selector string as argument and return a single `Element` or `null` if no element is found. `queryAll` takes the same arguments but should instead return a `NodeList<Element>` or `Array<Element>` with all the elements that match the given query selector.
**NOTE:** Because the function code needs to be serialized, it is **not possible** to access anything outside its scope or use imports. See e.g. [the pierce handler](https://github.com/puppeteer/puppeteer/blob/v13.5.2/src/common/QueryHandler.ts#L115) which has redundancies because of this limitation.
chore: mark version v5.4.0 (#6542)
2020-10-23 14:28:38 +00:00
docs(api.md): add documentation on custom handlers (#8074)
2022-02-28 09:43:59 +00:00
### interface: Selector
A selector is a [string] for querying elements in the page.
The default behavior is to regard the string as a [CSS selector] and query using `querySelector` or `querySelectorAll`.
If a selector string contains a forward slash `/` the selector is instead regarded as custom selector where everything before the slash is the [custom handler](#puppeteerregistercustomqueryhandlername-queryhandler) name and everything after is the selector: `<handler>/<selector>`.
Puppeteer ships with two such custom handlers pre-registered:
docs: improve custom query handler docs (#8235)
2022-04-19 12:48:22 +00:00
- `aria`: Queries the accessibilty tree for computed accessibility properties.
docs(api.md): add documentation on custom handlers (#8074)
2022-02-28 09:43:59 +00:00
The selectors consist of an accessible name to query for and optionally
further aria attributes on the form `[<attribute>=<value>]`.
Currently, we only support the `name` and `role` attribute.
The following examples showcase how the syntax works wrt. querying:
- `title[role="heading"]` queries for elements with name 'title' and role 'heading'.
- `[role="img"]` queries for elements with role 'img' and any name.
- `label` queries for elements with name 'label' and any role.
- `[name=""][role="button"]` queries for elements with no name and role 'button'.
- `pierce`: Takes a [CSS selector] and queries the page using `querySelector` or `querySeletorAll` but pierces through shadow roots.
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
[axnode]: #accessibilitysnapshotoptions 'AXNode'
[accessibility]: #class-accessibility 'Accessibility'
[array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array 'Array'
[body]: #class-body 'Body'
[browsercontext]: #class-browsercontext 'BrowserContext'
[browserfetcher]: #class-browserfetcher 'BrowserFetcher'
[browser]: #class-browser 'Browser'
[buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer 'Buffer'
[cdpsession]: #class-cdpsession 'CDPSession'
[childprocess]: https://nodejs.org/api/child_process.html 'ChildProcess'
[connectiontransport]: ../src/WebSocketTransport.js 'ConnectionTransport'
[consolemessage]: #class-consolemessage 'ConsoleMessage'
[coverage]: #class-coverage 'Coverage'
[dialog]: #class-dialog 'Dialog'
[elementhandle]: #class-elementhandle 'ElementHandle'
[element]: https://developer.mozilla.org/en-US/docs/Web/API/element 'Element'
[error]: https://nodejs.org/api/errors.html#errors_class_error 'Error'
[executioncontext]: #class-executioncontext 'ExecutionContext'
[filechooser]: #class-filechooser 'FileChooser'
[frame]: #class-frame 'Frame'
[jshandle]: #class-jshandle 'JSHandle'
[keyboard]: #class-keyboard 'Keyboard'
[map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map 'Map'
[mouse]: #class-mouse 'Mouse'
[object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object 'Object'
[page]: #class-page 'Page'
[promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise 'Promise'
[httprequest]: #class-httprequest 'HTTPRequest'
[httpresponse]: #class-httpresponse 'HTTPResponse'
[securitydetails]: #class-securitydetails 'SecurityDetails'
[serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description 'Serializable'
[target]: #class-target 'Target'
[timeouterror]: #class-timeouterror 'TimeoutError'
[touchscreen]: #class-touchscreen 'Touchscreen'
[tracing]: #class-tracing 'Tracing'
[uievent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail 'UIEvent.detail'
[uskeyboardlayout]: ../src/common/USKeyboardLayout.ts 'USKeyboardLayout'
[unixtime]: https://en.wikipedia.org/wiki/Unix_time 'Unix Time'
[webworker]: #class-webworker 'Worker'
[boolean]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type 'Boolean'
[function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function 'Function'
[iterator]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols 'Iterator'
[number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type 'Number'
[origin]: https://developer.mozilla.org/en-US/docs/Glossary/Origin 'Origin'
docs(api.md): fix missing space in reference (#8075)
2022-02-28 11:11:41 +00:00
[selector]: #interface-selector 'Selector'
docs(api.md): add documentation on custom handlers (#8074)
2022-02-28 09:43:59 +00:00
[css selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors
chore: automate prettier in docs (#7014) Issue: #7012 Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2021-03-23 09:02:34 +00:00
[stream.readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable 'stream.Readable'
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type 'String'
[symbol]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Symbol_type 'Symbol'
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath 'xpath'
[customqueryhandler]: #interface-customqueryhandler 'CustomQueryHandler'
Reference in New Issue Copy Permalink