docs: pref docs to be language-specific (#4916)
This commit is contained in:
Pavel Feldman
GitHub
parent
cc1a79eceb
commit
2311c282d6
|
|
@ -1,109 +0,0 @@
|
|||
---
|
||||
id: README
|
||||
title: "Documentation"
|
||||
---
|
||||
|
||||
### Capabilities
|
||||
|
||||
Playwright is a library to automate [Chromium](https://www.chromium.org/Home), [Firefox](https://www.mozilla.org/en-US/firefox/new/) and [WebKit](https://webkit.org/) with a single API. Playwright is built to enable cross-browser web automation that is **ever-green**, **capable**, **reliable** and **fast**.
|
||||
* Ever-green browser engines
|
||||
* Headless execution
|
||||
* Scenarios that span multiple pages, domains and iframes
|
||||
* Auto-wait for elements to be ready before executing actions (like click, fill)
|
||||
* Reliable signals instead of timeouts (like network response, popup, navigation)
|
||||
* Intercept network activity for stubbing and mocking network requests
|
||||
* Emulate mobile devices, geolocation, permissions
|
||||
* Support for web components via shadow-piercing selectors
|
||||
* Native input events for mouse and keyboard
|
||||
* Upload and download files
|
||||
|
||||
### Table of contents
|
||||
1. Introduction
|
||||
- [Why Playwright?](./why-playwright.md)
|
||||
- [Get started](./intro.md)
|
||||
- [Core concepts](./core-concepts.md)
|
||||
- [Debugging](./debug.md)
|
||||
- [Supported languages](./languages.md)
|
||||
1. Guides
|
||||
- [Selectors](./selectors.md)
|
||||
- [Input](./input.md)
|
||||
- [Emulation](./emulation.md)
|
||||
- [Network](./network.md)
|
||||
- [Assertions](./assertions.md)
|
||||
- [Verification](./verification.md)
|
||||
- [Navigations](./navigations.md)
|
||||
- [Multi-page scenarios](./multi-pages.md)
|
||||
1. Tutorials
|
||||
- [Authentication](./auth.md)
|
||||
- [Page object models](./pom.md)
|
||||
1. Integrations
|
||||
- [Test runners](./test-runners.md)
|
||||
- [Docker](./docker.md)
|
||||
- [Continuous integration](./ci.md)
|
||||
1. Reference
|
||||
- [API Reference](./api/class-playwright.md)
|
||||
- [Actionability](./actionability.md)
|
||||
- [Advanced installation](./installation.md)
|
||||
- [Extensibility](./extensibility.md)
|
||||
1. Get help
|
||||
- [Slack community](https://join.slack.com/t/playwright/shared_invite/enQtOTEyMTUxMzgxMjIwLThjMDUxZmIyNTRiMTJjNjIyMzdmZDA3MTQxZWUwZTFjZjQwNGYxZGM5MzRmNzZlMWI5ZWUyOTkzMjE5Njg1NDg)
|
||||
- [Stack Overflow](https://stackoverflow.com/tags/playwright)
|
||||
- [GitHub](https://github.com/microsoft/playwright/issues)
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,117 +0,0 @@
|
|||
---
|
||||
id: actionability
|
||||
title: "Actionability"
|
||||
---
|
||||
|
||||
Playwright does a range of actionability checks on the elements before performing certain actions. These checks ensure that action behaves as expected, for example Playwright does not click on a disabled button.
|
||||
|
||||
Playwright waits until all the relevant actionability checks pass before performing an action. This means that action will fail with `TimeoutError` if checks do not pass within the specified `timeout`.
|
||||
|
||||
Some actions like `page.click()` support `{force: true}` option that disable non-essential actionability checks, for example passing `force` to `click()` method will not check that the target element actually receives click events.
|
||||
|
||||
| Actions | Performed checks |
|
||||
| ------ | ------- |
|
||||
| `check()`<br></br>`click()`<br></br>`dblclick()`<br></br>`tap()`<br></br>`uncheck()` | [Visible]<br></br>[Stable]<br></br>[Enabled]<br></br>[Receiving Events]<br></br>[Attached] |
|
||||
| `hover()` | [Visible]<br></br>[Stable]<br></br>[Receiving Events]<br></br>[Attached] |
|
||||
| `fill()` | [Visible]<br></br>[Enabled]<br></br>[Editable]<br></br>[Attached] |
|
||||
| `dispatchEvent()`<br></br>`focus()`<br></br>`press()`<br></br>`setInputFiles()`<br></br>`selectOption()`<br></br>`type()` | [Attached] |
|
||||
| `scrollIntoViewIfNeeded()`<br></br>`screenshot()` | [Visible]<br></br>[Stable]<br></br>[Attached] |
|
||||
| `selectText()` | [Visible]<br></br>[Attached] |
|
||||
| `getAttribute()`<br></br>`innerText()`<br></br>`innerHTML()`<br></br>`textContent()` | [Attached] |
|
||||
|
||||
### Visible
|
||||
|
||||
Element is considered visible when it has non-empty bounding box and does not have `visibility:hidden` computed style. Note that elements of zero size or with `display:none` are not considered visible.
|
||||
|
||||
### Stable
|
||||
|
||||
Element is considered stable when it has maintained the same bounding box for at least two consecutive animation frames.
|
||||
|
||||
### Enabled
|
||||
|
||||
Element is considered enabled when it is not a `<button>`, `<select>` or `<input>` with a `disabled` property set.
|
||||
|
||||
### Editable
|
||||
|
||||
Element is considered editable when it does not have `readonly` property set.
|
||||
|
||||
### Receiving events
|
||||
|
||||
Element is considered receiving pointer events when it is the hit target of the pointer event at the action point. For example, when clicking at the point `(10;10)`, Playwright checks whether some other element (usually an overlay) will instead capture the click at `(10;10)`.
|
||||
|
||||
### Attached
|
||||
|
||||
Element is considered attached when it is [connected](https://developer.mozilla.org/en-US/docs/Web/API/Node/isConnected) to a Document or a ShadowRoot.
|
||||
|
||||
Attached check differs between selector-based and handle-based actions, like `page.click(selector, options)` as opposite to `elementHandle.click(options)`:
|
||||
- For selector-based actions, Playwright first waits for an element matching `selector` to be attached to the DOM, and then checks that element is still attached before performing the action. If element was detached, the action is retried from the start.
|
||||
- For handle-based actions, Playwright throws if the element is not attached.
|
||||
|
||||
For example, consider a scenario where Playwright will click `Sign Up` button regardless of when the `page.click()` call was made:
|
||||
- page is checking that user name is unique and `Sign Up` button is disabled;
|
||||
- after checking with the server, the disabled `Sign Up` button is replaced with another one that is now enabled.
|
||||
|
||||
[Visible]: #visible "Visible"
|
||||
[Stable]: #stable "Stable"
|
||||
[Enabled]: #enabled "Enabled"
|
||||
[Editable]: #editable "Editable"
|
||||
[Receiving Events]: #receiving-events "Receiving Events"
|
||||
[Attached]: #attached "Attached"
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,136 +0,0 @@
|
|||
---
|
||||
id: class-accessibility
|
||||
title: "Accessibility"
|
||||
---
|
||||
|
||||
|
||||
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).
|
||||
|
||||
Accessibility is a very platform-specific thing. On different platforms, there are different screen readers that might have wildly different output.
|
||||
|
||||
Blink - Chromium's rendering engine - has a concept of "accessibility tree", which is then translated into different platform-specific APIs. Accessibility namespace gives users access to the Blink Accessibility Tree.
|
||||
|
||||
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, Playwright tries to approximate this filtering, exposing only the "interesting" nodes of the tree.
|
||||
|
||||
|
||||
- [accessibility.snapshot([options])](api/class-accessibility.md#accessibilitysnapshotoptions)
|
||||
|
||||
## accessibility.snapshot([options])
|
||||
- `options` <[Object]>
|
||||
- `interestingOnly` <[boolean]> Prune uninteresting nodes from the tree. Defaults to `true`.
|
||||
- `root` <[ElementHandle]> The root DOM element for the snapshot. Defaults to the whole page.
|
||||
- returns: <[Promise]<[null]|[Object]>>
|
||||
- `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, if applicable.
|
||||
- `description` <[string]> An additional human readable description of the node, if applicable.
|
||||
- `keyshortcuts` <[string]> Keyboard shortcuts associated with this node, if applicable.
|
||||
- `roledescription` <[string]> A human readable alternative to the role, if applicable.
|
||||
- `valuetext` <[string]> A description of the current value, if applicable.
|
||||
- `disabled` <[boolean]> Whether the node is disabled, if applicable.
|
||||
- `expanded` <[boolean]> Whether the node is expanded or collapsed, if applicable.
|
||||
- `focused` <[boolean]> Whether the node is focused, if applicable.
|
||||
- `modal` <[boolean]> Whether the node is [modal](https://en.wikipedia.org/wiki/Modal_window), if applicable.
|
||||
- `multiline` <[boolean]> Whether the node text input supports multiline, if applicable.
|
||||
- `multiselectable` <[boolean]> Whether more than one child can be selected, if applicable.
|
||||
- `readonly` <[boolean]> Whether the node is read only, if applicable.
|
||||
- `required` <[boolean]> Whether the node is required, if applicable.
|
||||
- `selected` <[boolean]> Whether the node is selected in its parent node, if applicable.
|
||||
- `checked` <[boolean]|"mixed"> Whether the checkbox is checked, or "mixed", if applicable.
|
||||
- `pressed` <[boolean]|"mixed"> Whether the toggle button is checked, or "mixed", if applicable.
|
||||
- `level` <[number]> The level of a heading, if applicable.
|
||||
- `valuemin` <[number]> The minimum value in a node, if applicable.
|
||||
- `valuemax` <[number]> The maximum value in a node, if applicable.
|
||||
- `autocomplete` <[string]> What kind of autocomplete is supported by a control, if applicable.
|
||||
- `haspopup` <[string]> What kind of popup is currently being shown for a node, if applicable.
|
||||
- `invalid` <[string]> Whether and in what way this node's value is invalid, if applicable.
|
||||
- `orientation` <[string]> Whether the node is oriented horizontally or vertically, if applicable.
|
||||
- `children` <[Array]<[Object]>> Child nodes, if any, if applicable.
|
||||
|
||||
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 most screen readers. Playwright will discard them as well for an easier to process tree, unless `interestingOnly` is set to `false`.
|
||||
|
||||
An example of dumping the entire accessibility tree:
|
||||
|
||||
```js
|
||||
const snapshot = await page.accessibility.snapshot();
|
||||
console.log(snapshot);
|
||||
```
|
||||
|
||||
An example of logging the focused node's name:
|
||||
|
||||
```js
|
||||
const snapshot = await page.accessibility.snapshot();
|
||||
const node = findFocusedNode(snapshot);
|
||||
console.log(node && node.name);
|
||||
|
||||
function findFocusedNode(node) {
|
||||
if (node.focused)
|
||||
return node;
|
||||
for (const child of node.children || []) {
|
||||
const foundNode = findFocusedNode(child);
|
||||
return foundNode;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,269 +0,0 @@
|
|||
---
|
||||
id: class-browser
|
||||
title: "Browser"
|
||||
---
|
||||
|
||||
* extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
|
||||
|
||||
A Browser is created when Playwright connects to a browser instance, either through [browserType.launch([options])](api/class-browsertype.md#browsertypelaunchoptions) or [browserType.connect(params)](api/class-browsertype.md#browsertypeconnectparams).
|
||||
|
||||
An example of using a [Browser] to create a [Page]:
|
||||
|
||||
```js
|
||||
const { firefox } = require('playwright'); // Or 'chromium' or 'webkit'.
|
||||
|
||||
(async () => {
|
||||
const browser = await firefox.launch();
|
||||
const page = await browser.newPage();
|
||||
await page.goto('https://example.com');
|
||||
await browser.close();
|
||||
})();
|
||||
```
|
||||
|
||||
See [ChromiumBrowser], [FirefoxBrowser] and [WebKitBrowser] for browser-specific features. Note that [browserType.connect(params)](api/class-browsertype.md#browsertypeconnectparams) and [browserType.launch([options])](api/class-browsertype.md#browsertypelaunchoptions) always return a specific browser instance, based on the browser being connected to or launched.
|
||||
|
||||
|
||||
- [browser.on('disconnected')](api/class-browser.md#browserondisconnected)
|
||||
- [browser.close()](api/class-browser.md#browserclose)
|
||||
- [browser.contexts()](api/class-browser.md#browsercontexts)
|
||||
- [browser.isConnected()](api/class-browser.md#browserisconnected)
|
||||
- [browser.newContext([options])](api/class-browser.md#browsernewcontextoptions)
|
||||
- [browser.newPage([options])](api/class-browser.md#browsernewpageoptions)
|
||||
- [browser.version()](api/class-browser.md#browserversion)
|
||||
|
||||
## browser.on('disconnected')
|
||||
|
||||
Emitted when Browser gets disconnected from the browser application. This might happen because of one of the following:
|
||||
* Browser application is closed or crashed.
|
||||
* The [browser.close()](api/class-browser.md#browserclose) method was called.
|
||||
|
||||
## browser.close()
|
||||
- returns: <[Promise]>
|
||||
|
||||
In case this browser is obtained using [browserType.launch([options])](api/class-browsertype.md#browsertypelaunchoptions), closes the browser and all of its pages (if any were opened).
|
||||
|
||||
In case this browser is obtained using [browserType.connect(params)](api/class-browsertype.md#browsertypeconnectparams), clears all created contexts belonging to this browser and disconnects from the browser server.
|
||||
|
||||
The [Browser] object itself is considered to be disposed and cannot be used anymore.
|
||||
|
||||
## browser.contexts()
|
||||
- returns: <[Array]<[BrowserContext]>>
|
||||
|
||||
Returns an array of all open browser contexts. In a newly created browser, this will return zero browser contexts.
|
||||
|
||||
```js
|
||||
const browser = await pw.webkit.launch();
|
||||
console.log(browser.contexts().length); // prints `0`
|
||||
|
||||
const context = await browser.newContext();
|
||||
console.log(browser.contexts().length); // prints `1`
|
||||
```
|
||||
|
||||
## browser.isConnected()
|
||||
- returns: <[boolean]>
|
||||
|
||||
Indicates that the browser is connected.
|
||||
|
||||
## browser.newContext([options])
|
||||
- `options` <[Object]>
|
||||
- `acceptDownloads` <[boolean]> Whether to automatically download all the attachments. Defaults to `false` where all the downloads are canceled.
|
||||
- `bypassCSP` <[boolean]> Toggles bypassing page's Content-Security-Policy.
|
||||
- `colorScheme` <"light"|"dark"|"no-preference"> Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See [page.emulateMedia(params)](api/class-page.md#pageemulatemediaparams) for more details. Defaults to '`light`'.
|
||||
- `deviceScaleFactor` <[number]> Specify device scale factor (can be thought of as dpr). Defaults to `1`.
|
||||
- `extraHTTPHeaders` <[Object]<[string], [string]>> An object containing additional HTTP headers to be sent with every request. All header values must be strings.
|
||||
- `geolocation` <[Object]>
|
||||
- `latitude` <[number]> Latitude between -90 and 90.
|
||||
- `longitude` <[number]> Longitude between -180 and 180.
|
||||
- `accuracy` <[number]> Non-negative accuracy value. Defaults to `0`.
|
||||
- `hasTouch` <[boolean]> Specifies if viewport supports touch events. Defaults to false.
|
||||
- `httpCredentials` <[Object]> Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).
|
||||
- `username` <[string]>
|
||||
- `password` <[string]>
|
||||
- `ignoreHTTPSErrors` <[boolean]> Whether to ignore HTTPS errors during navigation. Defaults to `false`.
|
||||
- `isMobile` <[boolean]> Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not supported in Firefox.
|
||||
- `javaScriptEnabled` <[boolean]> Whether or not to enable JavaScript in the context. Defaults to `true`.
|
||||
- `locale` <[string]> Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value, `Accept-Language` request header value as well as number and date formatting rules.
|
||||
- `logger` <[Logger]> Logger sink for Playwright logging.
|
||||
- `offline` <[boolean]> Whether to emulate network being offline. Defaults to `false`.
|
||||
- `permissions` <[Array]<[string]>> A list of permissions to grant to all pages in this context. See [browserContext.grantPermissions(permissions[, options])](api/class-browsercontext.md#browsercontextgrantpermissionspermissions-options) for more details.
|
||||
- `proxy` <[Object]> Network proxy settings to use with this context. Note that browser needs to be launched with the global proxy for this option to work. If all contexts override the proxy, global proxy will be never used and can be any string, for example `launch({ proxy: { server: 'per-context' } })`.
|
||||
- `server` <[string]> Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example `http://myproxy.com:3128` or `socks5://myproxy.com:3128`. Short form `myproxy.com:3128` is considered an HTTP proxy.
|
||||
- `bypass` <[string]> Optional coma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`.
|
||||
- `username` <[string]> Optional username to use if HTTP proxy requires authentication.
|
||||
- `password` <[string]> Optional password to use if HTTP proxy requires authentication.
|
||||
- `recordHar` <[Object]> Enables [HAR](http://www.softwareishard.com/blog/har-12-spec) recording for all pages into `recordHar.path` file. If not specified, the HAR is not recorded. Make sure to await [browserContext.close()](api/class-browsercontext.md#browsercontextclose) for the HAR to be saved.
|
||||
- `omitContent` <[boolean]> Optional setting to control whether to omit request content from the HAR. Defaults to `false`.
|
||||
- `path` <[string]> Path on the filesystem to write the HAR file to.
|
||||
- `recordVideo` <[Object]> Enables video recording for all pages into `recordVideo.dir` directory. If not specified videos are not recorded. Make sure to await [browserContext.close()](api/class-browsercontext.md#browsercontextclose) for videos to be saved.
|
||||
- `dir` <[string]> Path to the directory to put videos into.
|
||||
- `size` <[Object]> Optional dimensions of the recorded videos. If not specified the size will be equal to `viewport`. If `viewport` is not configured explicitly the video size defaults to 1280x720. Actual picture of each page will be scaled down if necessary to fit the specified size.
|
||||
- `width` <[number]> Video frame width.
|
||||
- `height` <[number]> Video frame height.
|
||||
- `storageState` <[string]|[Object]> Populates context with given storage state. This method can be used to initialize context with logged-in information obtained via [browserContext.storageState([options])](api/class-browsercontext.md#browsercontextstoragestateoptions). Either a path to the file with saved storage, or an object with the following fields:
|
||||
- `cookies` <[Array]<[Object]>> Optional cookies to set for context
|
||||
- `name` <[string]> **required**
|
||||
- `value` <[string]> **required**
|
||||
- `url` <[string]> Optional either url or domain / path are required
|
||||
- `domain` <[string]> Optional either url or domain / path are required
|
||||
- `path` <[string]> Optional either url or domain / path are required
|
||||
- `expires` <[number]> Optional Unix time in seconds.
|
||||
- `httpOnly` <[boolean]> Optional httpOnly flag
|
||||
- `secure` <[boolean]> Optional secure flag
|
||||
- `sameSite` <"Strict"|"Lax"|"None"> Optional sameSite flag
|
||||
- `origins` <[Array]<[Object]>> Optional localStorage to set for context
|
||||
- `origin` <[string]>
|
||||
- `localStorage` <[Array]<[Object]>>
|
||||
- `name` <[string]>
|
||||
- `value` <[string]>
|
||||
- `timezoneId` <[string]> Changes the timezone of the context. 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.
|
||||
- `userAgent` <[string]> Specific user agent to use in this context.
|
||||
- `videoSize` <[Object]> **NOTE** Use `recordVideo` instead, it takes precedence over `videoSize`. Specifies dimensions of the automatically recorded video. Can only be used if `videosPath` is set. If not specified the size will be equal to `viewport`. If `viewport` is not configured explicitly the video size defaults to 1280x720. Actual picture of the page will be scaled down if necessary to fit specified size.
|
||||
- `width` <[number]> Video frame width.
|
||||
- `height` <[number]> Video frame height.
|
||||
- `videosPath` <[string]> **NOTE** Use `recordVideo` instead, it takes precedence over `videosPath`. Enables video recording for all pages to `videosPath` directory. If not specified, videos are not recorded. Make sure to await [browserContext.close()](api/class-browsercontext.md#browsercontextclose) for videos to be saved.
|
||||
- `viewport` <[null]|[Object]> Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport.
|
||||
- `width` <[number]> page width in pixels.
|
||||
- `height` <[number]> page height in pixels.
|
||||
- returns: <[Promise]<[BrowserContext]>>
|
||||
|
||||
Creates a new browser context. It won't share cookies/cache with other browser contexts.
|
||||
|
||||
```js
|
||||
(async () => {
|
||||
const browser = await playwright.firefox.launch(); // Or 'chromium' or 'webkit'.
|
||||
// Create a new incognito browser context.
|
||||
const context = await browser.newContext();
|
||||
// Create a new page in a pristine context.
|
||||
const page = await context.newPage();
|
||||
await page.goto('https://example.com');
|
||||
})();
|
||||
```
|
||||
|
||||
## browser.newPage([options])
|
||||
- `options` <[Object]>
|
||||
- `acceptDownloads` <[boolean]> Whether to automatically download all the attachments. Defaults to `false` where all the downloads are canceled.
|
||||
- `bypassCSP` <[boolean]> Toggles bypassing page's Content-Security-Policy.
|
||||
- `colorScheme` <"light"|"dark"|"no-preference"> Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See [page.emulateMedia(params)](api/class-page.md#pageemulatemediaparams) for more details. Defaults to '`light`'.
|
||||
- `deviceScaleFactor` <[number]> Specify device scale factor (can be thought of as dpr). Defaults to `1`.
|
||||
- `extraHTTPHeaders` <[Object]<[string], [string]>> An object containing additional HTTP headers to be sent with every request. All header values must be strings.
|
||||
- `geolocation` <[Object]>
|
||||
- `latitude` <[number]> Latitude between -90 and 90.
|
||||
- `longitude` <[number]> Longitude between -180 and 180.
|
||||
- `accuracy` <[number]> Non-negative accuracy value. Defaults to `0`.
|
||||
- `hasTouch` <[boolean]> Specifies if viewport supports touch events. Defaults to false.
|
||||
- `httpCredentials` <[Object]> Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).
|
||||
- `username` <[string]>
|
||||
- `password` <[string]>
|
||||
- `ignoreHTTPSErrors` <[boolean]> Whether to ignore HTTPS errors during navigation. Defaults to `false`.
|
||||
- `isMobile` <[boolean]> Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not supported in Firefox.
|
||||
- `javaScriptEnabled` <[boolean]> Whether or not to enable JavaScript in the context. Defaults to `true`.
|
||||
- `locale` <[string]> Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value, `Accept-Language` request header value as well as number and date formatting rules.
|
||||
- `logger` <[Logger]> Logger sink for Playwright logging.
|
||||
- `offline` <[boolean]> Whether to emulate network being offline. Defaults to `false`.
|
||||
- `permissions` <[Array]<[string]>> A list of permissions to grant to all pages in this context. See [browserContext.grantPermissions(permissions[, options])](api/class-browsercontext.md#browsercontextgrantpermissionspermissions-options) for more details.
|
||||
- `proxy` <[Object]> Network proxy settings to use with this context. Note that browser needs to be launched with the global proxy for this option to work. If all contexts override the proxy, global proxy will be never used and can be any string, for example `launch({ proxy: { server: 'per-context' } })`.
|
||||
- `server` <[string]> Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example `http://myproxy.com:3128` or `socks5://myproxy.com:3128`. Short form `myproxy.com:3128` is considered an HTTP proxy.
|
||||
- `bypass` <[string]> Optional coma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`.
|
||||
- `username` <[string]> Optional username to use if HTTP proxy requires authentication.
|
||||
- `password` <[string]> Optional password to use if HTTP proxy requires authentication.
|
||||
- `recordHar` <[Object]> Enables [HAR](http://www.softwareishard.com/blog/har-12-spec) recording for all pages into `recordHar.path` file. If not specified, the HAR is not recorded. Make sure to await [browserContext.close()](api/class-browsercontext.md#browsercontextclose) for the HAR to be saved.
|
||||
- `omitContent` <[boolean]> Optional setting to control whether to omit request content from the HAR. Defaults to `false`.
|
||||
- `path` <[string]> Path on the filesystem to write the HAR file to.
|
||||
- `recordVideo` <[Object]> Enables video recording for all pages into `recordVideo.dir` directory. If not specified videos are not recorded. Make sure to await [browserContext.close()](api/class-browsercontext.md#browsercontextclose) for videos to be saved.
|
||||
- `dir` <[string]> Path to the directory to put videos into.
|
||||
- `size` <[Object]> Optional dimensions of the recorded videos. If not specified the size will be equal to `viewport`. If `viewport` is not configured explicitly the video size defaults to 1280x720. Actual picture of each page will be scaled down if necessary to fit the specified size.
|
||||
- `width` <[number]> Video frame width.
|
||||
- `height` <[number]> Video frame height.
|
||||
- `storageState` <[string]|[Object]> Populates context with given storage state. This method can be used to initialize context with logged-in information obtained via [browserContext.storageState([options])](api/class-browsercontext.md#browsercontextstoragestateoptions). Either a path to the file with saved storage, or an object with the following fields:
|
||||
- `cookies` <[Array]<[Object]>> Optional cookies to set for context
|
||||
- `name` <[string]> **required**
|
||||
- `value` <[string]> **required**
|
||||
- `url` <[string]> Optional either url or domain / path are required
|
||||
- `domain` <[string]> Optional either url or domain / path are required
|
||||
- `path` <[string]> Optional either url or domain / path are required
|
||||
- `expires` <[number]> Optional Unix time in seconds.
|
||||
- `httpOnly` <[boolean]> Optional httpOnly flag
|
||||
- `secure` <[boolean]> Optional secure flag
|
||||
- `sameSite` <"Strict"|"Lax"|"None"> Optional sameSite flag
|
||||
- `origins` <[Array]<[Object]>> Optional localStorage to set for context
|
||||
- `origin` <[string]>
|
||||
- `localStorage` <[Array]<[Object]>>
|
||||
- `name` <[string]>
|
||||
- `value` <[string]>
|
||||
- `timezoneId` <[string]> Changes the timezone of the context. 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.
|
||||
- `userAgent` <[string]> Specific user agent to use in this context.
|
||||
- `videoSize` <[Object]> **NOTE** Use `recordVideo` instead, it takes precedence over `videoSize`. Specifies dimensions of the automatically recorded video. Can only be used if `videosPath` is set. If not specified the size will be equal to `viewport`. If `viewport` is not configured explicitly the video size defaults to 1280x720. Actual picture of the page will be scaled down if necessary to fit specified size.
|
||||
- `width` <[number]> Video frame width.
|
||||
- `height` <[number]> Video frame height.
|
||||
- `videosPath` <[string]> **NOTE** Use `recordVideo` instead, it takes precedence over `videosPath`. Enables video recording for all pages to `videosPath` directory. If not specified, videos are not recorded. Make sure to await [browserContext.close()](api/class-browsercontext.md#browsercontextclose) for videos to be saved.
|
||||
- `viewport` <[null]|[Object]> Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport.
|
||||
- `width` <[number]> page width in pixels.
|
||||
- `height` <[number]> page height in pixels.
|
||||
- returns: <[Promise]<[Page]>>
|
||||
|
||||
Creates a new page in a new browser context. Closing this page will close the context as well.
|
||||
|
||||
This is a convenience API that should only be used for the single-page scenarios and short snippets. Production code and testing frameworks should explicitly create [browser.newContext([options])](api/class-browser.md#browsernewcontextoptions) followed by the [browserContext.newPage()](api/class-browsercontext.md#browsercontextnewpage) to control their exact life times.
|
||||
|
||||
## browser.version()
|
||||
- returns: <[string]>
|
||||
|
||||
Returns the browser version.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,472 +0,0 @@
|
|||
---
|
||||
id: class-browsercontext
|
||||
title: "BrowserContext"
|
||||
---
|
||||
|
||||
* extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
|
||||
|
||||
BrowserContexts provide a way to operate multiple independent browser sessions.
|
||||
|
||||
If a page opens another page, e.g. with a `window.open` call, the popup will belong to the parent page's browser context.
|
||||
|
||||
Playwright allows creation of "incognito" browser contexts with `browser.newContext()` method. "Incognito" browser contexts don't write any browsing data to disk.
|
||||
|
||||
```js
|
||||
// Create a new incognito browser context
|
||||
const context = await browser.newContext();
|
||||
// Create a new page inside context.
|
||||
const page = await context.newPage();
|
||||
await page.goto('https://example.com');
|
||||
// Dispose context once it's no longer needed.
|
||||
await context.close();
|
||||
```
|
||||
|
||||
|
||||
- [browserContext.on('close')](api/class-browsercontext.md#browsercontextonclose)
|
||||
- [browserContext.on('page')](api/class-browsercontext.md#browsercontextonpage)
|
||||
- [browserContext.addCookies(cookies)](api/class-browsercontext.md#browsercontextaddcookiescookies)
|
||||
- [browserContext.addInitScript(script[, arg])](api/class-browsercontext.md#browsercontextaddinitscriptscript-arg)
|
||||
- [browserContext.browser()](api/class-browsercontext.md#browsercontextbrowser)
|
||||
- [browserContext.clearCookies()](api/class-browsercontext.md#browsercontextclearcookies)
|
||||
- [browserContext.clearPermissions()](api/class-browsercontext.md#browsercontextclearpermissions)
|
||||
- [browserContext.close()](api/class-browsercontext.md#browsercontextclose)
|
||||
- [browserContext.cookies([urls])](api/class-browsercontext.md#browsercontextcookiesurls)
|
||||
- [browserContext.exposeBinding(name, callback[, options])](api/class-browsercontext.md#browsercontextexposebindingname-callback-options)
|
||||
- [browserContext.exposeFunction(name, callback)](api/class-browsercontext.md#browsercontextexposefunctionname-callback)
|
||||
- [browserContext.grantPermissions(permissions[, options])](api/class-browsercontext.md#browsercontextgrantpermissionspermissions-options)
|
||||
- [browserContext.newPage()](api/class-browsercontext.md#browsercontextnewpage)
|
||||
- [browserContext.pages()](api/class-browsercontext.md#browsercontextpages)
|
||||
- [browserContext.route(url, handler)](api/class-browsercontext.md#browsercontextrouteurl-handler)
|
||||
- [browserContext.setDefaultNavigationTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaultnavigationtimeouttimeout)
|
||||
- [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout)
|
||||
- [browserContext.setExtraHTTPHeaders(headers)](api/class-browsercontext.md#browsercontextsetextrahttpheadersheaders)
|
||||
- [browserContext.setGeolocation(geolocation)](api/class-browsercontext.md#browsercontextsetgeolocationgeolocation)
|
||||
- [browserContext.setHTTPCredentials(httpCredentials)](api/class-browsercontext.md#browsercontextsethttpcredentialshttpcredentials)
|
||||
- [browserContext.setOffline(offline)](api/class-browsercontext.md#browsercontextsetofflineoffline)
|
||||
- [browserContext.storageState([options])](api/class-browsercontext.md#browsercontextstoragestateoptions)
|
||||
- [browserContext.unroute(url[, handler])](api/class-browsercontext.md#browsercontextunrouteurl-handler)
|
||||
- [browserContext.waitForEvent(event[, optionsOrPredicate])](api/class-browsercontext.md#browsercontextwaitforeventevent-optionsorpredicate)
|
||||
|
||||
## browserContext.on('close')
|
||||
|
||||
Emitted when Browser context gets closed. This might happen because of one of the following:
|
||||
* Browser context is closed.
|
||||
* Browser application is closed or crashed.
|
||||
* The [browser.close()](api/class-browser.md#browserclose) method was called.
|
||||
|
||||
## browserContext.on('page')
|
||||
- type: <[Page]>
|
||||
|
||||
The event is emitted when a new Page is created in the BrowserContext. The page may still be loading. The event will also fire for popup pages. See also [page.on('popup')](api/class-page.md#pageonpopup) to receive events about popups relevant to a specific page.
|
||||
|
||||
The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a popup with `window.open('http://example.com')`, this event will fire when the network request to "http://example.com" is done and its response has started loading in the popup.
|
||||
|
||||
```js
|
||||
const [page] = await Promise.all([
|
||||
context.waitForEvent('page'),
|
||||
page.click('a[target=_blank]'),
|
||||
]);
|
||||
console.log(await page.evaluate('location.href'));
|
||||
```
|
||||
|
||||
> **NOTE** Use [page.waitForLoadState([state, options])](api/class-page.md#pagewaitforloadstatestate-options) to wait until the page gets to a particular state (you should not need it in most cases).
|
||||
|
||||
## browserContext.addCookies(cookies)
|
||||
- `cookies` <[Array]<[Object]>>
|
||||
- `name` <[string]> **required**
|
||||
- `value` <[string]> **required**
|
||||
- `url` <[string]> either url or domain / path are required. Optional.
|
||||
- `domain` <[string]> either url or domain / path are required Optional.
|
||||
- `path` <[string]> either url or domain / path are required Optional.
|
||||
- `expires` <[number]> Unix time in seconds. Optional.
|
||||
- `httpOnly` <[boolean]> Optional.
|
||||
- `secure` <[boolean]> Optional.
|
||||
- `sameSite` <"Strict"|"Lax"|"None"> Optional.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Adds cookies into this browser context. All pages within this context will have these cookies installed. Cookies can be obtained via [browserContext.cookies([urls])](api/class-browsercontext.md#browsercontextcookiesurls).
|
||||
|
||||
```js
|
||||
await browserContext.addCookies([cookieObject1, cookieObject2]);
|
||||
```
|
||||
|
||||
## browserContext.addInitScript(script[, arg])
|
||||
- `script` <[function]|[string]|[Object]> Script to be evaluated in all pages in the browser context.
|
||||
- `path` <[string]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. Optional.
|
||||
- `content` <[string]> Raw script content. Optional.
|
||||
- `arg` <[Serializable]> Optional argument to pass to `script` (only supported when passing a function).
|
||||
- returns: <[Promise]>
|
||||
|
||||
Adds a script which would be evaluated in one of the following scenarios:
|
||||
* Whenever a page is created in the browser context or is navigated.
|
||||
* Whenever a child frame is attached or navigated in any page in the browser context. In this case, the script is evaluated in the context of the newly attached frame.
|
||||
|
||||
The script is evaluated 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`.
|
||||
|
||||
An example of overriding `Math.random` before the page loads:
|
||||
|
||||
```js
|
||||
// preload.js
|
||||
Math.random = () => 42;
|
||||
```
|
||||
|
||||
```js
|
||||
// In your playwright script, assuming the preload.js file is in same directory.
|
||||
await browserContext.addInitScript({
|
||||
path: 'preload.js'
|
||||
});
|
||||
```
|
||||
|
||||
> **NOTE** The order of evaluation of multiple scripts installed via [browserContext.addInitScript(script[, arg])](api/class-browsercontext.md#browsercontextaddinitscriptscript-arg) and [page.addInitScript(script[, arg])](api/class-page.md#pageaddinitscriptscript-arg) is not defined.
|
||||
|
||||
## browserContext.browser()
|
||||
- returns: <[null]|[Browser]>
|
||||
|
||||
Returns the browser instance of the context. If it was launched as a persistent context null gets returned.
|
||||
|
||||
## browserContext.clearCookies()
|
||||
- returns: <[Promise]>
|
||||
|
||||
Clears context cookies.
|
||||
|
||||
## browserContext.clearPermissions()
|
||||
- returns: <[Promise]>
|
||||
|
||||
Clears all permission overrides for the browser context.
|
||||
|
||||
```js
|
||||
const context = await browser.newContext();
|
||||
await context.grantPermissions(['clipboard-read']);
|
||||
// do stuff ..
|
||||
context.clearPermissions();
|
||||
```
|
||||
|
||||
## browserContext.close()
|
||||
- returns: <[Promise]>
|
||||
|
||||
Closes the browser context. All the pages that belong to the browser context will be closed.
|
||||
|
||||
> **NOTE** the default browser context cannot be closed.
|
||||
|
||||
## browserContext.cookies([urls])
|
||||
- `urls` <[string]|[Array]<[string]>> Optional list of URLs.
|
||||
- returns: <[Promise]<[Array]<[Object]>>>
|
||||
- `name` <[string]>
|
||||
- `value` <[string]>
|
||||
- `domain` <[string]>
|
||||
- `path` <[string]>
|
||||
- `expires` <[number]> Unix time in seconds.
|
||||
- `httpOnly` <[boolean]>
|
||||
- `secure` <[boolean]>
|
||||
- `sameSite` <"Strict"|"Lax"|"None">
|
||||
|
||||
If no URLs are specified, this method returns all cookies. If URLs are specified, only cookies that affect those URLs are returned.
|
||||
|
||||
## browserContext.exposeBinding(name, callback[, options])
|
||||
- `name` <[string]> Name of the function on the window object.
|
||||
- `callback` <[function]> Callback function that will be called in the Playwright's context.
|
||||
- `options` <[Object]>
|
||||
- `handle` <[boolean]> Whether to pass the argument as a handle, instead of passing by value. When passing a handle, only one argument is supported. When passing by value, multiple arguments are supported.
|
||||
- returns: <[Promise]>
|
||||
|
||||
The method adds a function called `name` on the `window` object of every frame in every page in the context. When called, the function executes `callback` and returns a [Promise] which resolves to the return value of `callback`. If the `callback` returns a [Promise], it will be awaited.
|
||||
|
||||
The first argument of the `callback` function contains information about the caller: `{ browserContext: BrowserContext, page: Page, frame: Frame }`.
|
||||
|
||||
See [page.exposeBinding(name, callback[, options])](api/class-page.md#pageexposebindingname-callback-options) for page-only version.
|
||||
|
||||
An example of exposing page URL to all frames in all pages in the context:
|
||||
|
||||
```js
|
||||
const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'.
|
||||
|
||||
(async () => {
|
||||
const browser = await webkit.launch({ headless: false });
|
||||
const context = await browser.newContext();
|
||||
await context.exposeBinding('pageURL', ({ page }) => page.url());
|
||||
const page = await context.newPage();
|
||||
await page.setContent(`
|
||||
<script>
|
||||
async function onClick() {
|
||||
document.querySelector('div').textContent = await window.pageURL();
|
||||
}
|
||||
</script>
|
||||
<button onclick="onClick()">Click me</button>
|
||||
<div></div>
|
||||
`);
|
||||
await page.click('button');
|
||||
})();
|
||||
```
|
||||
|
||||
An example of passing an element handle:
|
||||
|
||||
```js
|
||||
await context.exposeBinding('clicked', async (source, element) => {
|
||||
console.log(await element.textContent());
|
||||
}, { handle: true });
|
||||
await page.setContent(`
|
||||
<script>
|
||||
document.addEventListener('click', event => window.clicked(event.target));
|
||||
</script>
|
||||
<div>Click me</div>
|
||||
<div>Or click me</div>
|
||||
`);
|
||||
```
|
||||
|
||||
## browserContext.exposeFunction(name, callback)
|
||||
- `name` <[string]> Name of the function on the window object.
|
||||
- `callback` <[function]> Callback function that will be called in the Playwright's context.
|
||||
- returns: <[Promise]>
|
||||
|
||||
The method adds a function called `name` on the `window` object of every frame in every page in the context. When called, the function executes `callback` and returns a [Promise] which resolves to the return value of `callback`.
|
||||
|
||||
If the `callback` returns a [Promise], it will be awaited.
|
||||
|
||||
See [page.exposeFunction(name, callback)](api/class-page.md#pageexposefunctionname-callback) for page-only version.
|
||||
|
||||
An example of adding an `md5` function to all pages in the context:
|
||||
|
||||
```js
|
||||
const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'.
|
||||
const crypto = require('crypto');
|
||||
|
||||
(async () => {
|
||||
const browser = await webkit.launch({ headless: false });
|
||||
const context = await browser.newContext();
|
||||
await context.exposeFunction('md5', text => crypto.createHash('md5').update(text).digest('hex'));
|
||||
const page = await context.newPage();
|
||||
await page.setContent(`
|
||||
<script>
|
||||
async function onClick() {
|
||||
document.querySelector('div').textContent = await window.md5('PLAYWRIGHT');
|
||||
}
|
||||
</script>
|
||||
<button onclick="onClick()">Click me</button>
|
||||
<div></div>
|
||||
`);
|
||||
await page.click('button');
|
||||
})();
|
||||
```
|
||||
|
||||
## browserContext.grantPermissions(permissions[, options])
|
||||
- `permissions` <[Array]<[string]>> A permission or an array of permissions to grant. Permissions can be one of the following values:
|
||||
* `'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'`
|
||||
- `options` <[Object]>
|
||||
- `origin` <[string]> The [origin] to grant permissions to, e.g. "https://example.com".
|
||||
- returns: <[Promise]>
|
||||
|
||||
Grants specified permissions to the browser context. Only grants corresponding permissions to the given origin if specified.
|
||||
|
||||
## browserContext.newPage()
|
||||
- returns: <[Promise]<[Page]>>
|
||||
|
||||
Creates a new page in the browser context.
|
||||
|
||||
## browserContext.pages()
|
||||
- returns: <[Array]<[Page]>>
|
||||
|
||||
Returns all open pages in the context. Non visible pages, such as `"background_page"`, will not be listed here. You can find them using [chromiumBrowserContext.backgroundPages()](api/class-chromiumbrowsercontext.md#chromiumbrowsercontextbackgroundpages).
|
||||
|
||||
## browserContext.route(url, handler)
|
||||
- `url` <[string]|[RegExp]|[function]\([URL]\):[boolean]> A glob pattern, regex pattern or predicate receiving [URL] to match while routing.
|
||||
- `handler` <[function]\([Route], [Request]\)> handler function to route the request.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Routing provides the capability to modify network requests that are made by any page in the browser context. Once route is enabled, every request matching the url pattern will stall unless it's continued, fulfilled or aborted.
|
||||
|
||||
An example of a naïve handler that aborts all image requests:
|
||||
|
||||
```js
|
||||
const context = await browser.newContext();
|
||||
await context.route('**/*.{png,jpg,jpeg}', route => route.abort());
|
||||
const page = await context.newPage();
|
||||
await page.goto('https://example.com');
|
||||
await browser.close();
|
||||
```
|
||||
|
||||
or the same snippet using a regex pattern instead:
|
||||
|
||||
```js
|
||||
const context = await browser.newContext();
|
||||
await context.route(/(\.png$)|(\.jpg$)/, route => route.abort());
|
||||
const page = await context.newPage();
|
||||
await page.goto('https://example.com');
|
||||
await browser.close();
|
||||
```
|
||||
|
||||
Page routes (set up with [page.route(url, handler)](api/class-page.md#pagerouteurl-handler)) take precedence over browser context routes when request matches both handlers.
|
||||
|
||||
> **NOTE** Enabling routing disables http cache.
|
||||
|
||||
## browserContext.setDefaultNavigationTimeout(timeout)
|
||||
- `timeout` <[number]> Maximum navigation time in milliseconds
|
||||
|
||||
This setting will change the default maximum navigation time for the following methods and related shortcuts:
|
||||
* [page.goBack([options])](api/class-page.md#pagegobackoptions)
|
||||
* [page.goForward([options])](api/class-page.md#pagegoforwardoptions)
|
||||
* [page.goto(url[, options])](api/class-page.md#pagegotourl-options)
|
||||
* [page.reload([options])](api/class-page.md#pagereloadoptions)
|
||||
* [page.setContent(html[, options])](api/class-page.md#pagesetcontenthtml-options)
|
||||
* [page.waitForNavigation([options])](api/class-page.md#pagewaitfornavigationoptions)
|
||||
|
||||
> **NOTE** [page.setDefaultNavigationTimeout(timeout)](api/class-page.md#pagesetdefaultnavigationtimeouttimeout) and [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) take priority over [browserContext.setDefaultNavigationTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaultnavigationtimeouttimeout).
|
||||
|
||||
## browserContext.setDefaultTimeout(timeout)
|
||||
- `timeout` <[number]> Maximum time in milliseconds
|
||||
|
||||
This setting will change the default maximum time for all the methods accepting `timeout` option.
|
||||
|
||||
> **NOTE** [page.setDefaultNavigationTimeout(timeout)](api/class-page.md#pagesetdefaultnavigationtimeouttimeout), [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) and [browserContext.setDefaultNavigationTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaultnavigationtimeouttimeout) take priority over [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout).
|
||||
|
||||
## browserContext.setExtraHTTPHeaders(headers)
|
||||
- `headers` <[Object]<[string], [string]>> An object containing additional HTTP headers to be sent with every request. All header values must be strings.
|
||||
- returns: <[Promise]>
|
||||
|
||||
The extra HTTP headers will be sent with every request initiated by any page in the context. These headers are merged with page-specific extra HTTP headers set with [page.setExtraHTTPHeaders(headers)](api/class-page.md#pagesetextrahttpheadersheaders). If page overrides a particular header, page-specific header value will be used instead of the browser context header value.
|
||||
|
||||
> **NOTE** `browserContext.setExtraHTTPHeaders` does not guarantee the order of headers in the outgoing requests.
|
||||
|
||||
## browserContext.setGeolocation(geolocation)
|
||||
- `geolocation` <[null]|[Object]>
|
||||
- `latitude` <[number]> Latitude between -90 and 90. **required**
|
||||
- `longitude` <[number]> Longitude between -180 and 180. **required**
|
||||
- `accuracy` <[number]> Non-negative accuracy value. Defaults to `0`.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Sets the context's geolocation. Passing `null` or `undefined` emulates position unavailable.
|
||||
|
||||
```js
|
||||
await browserContext.setGeolocation({latitude: 59.95, longitude: 30.31667});
|
||||
```
|
||||
|
||||
> **NOTE** Consider using [browserContext.grantPermissions(permissions[, options])](api/class-browsercontext.md#browsercontextgrantpermissionspermissions-options) to grant permissions for the browser context pages to read its geolocation.
|
||||
|
||||
## browserContext.setHTTPCredentials(httpCredentials)
|
||||
- `httpCredentials` <[null]|[Object]>
|
||||
- `username` <[string]> **required**
|
||||
- `password` <[string]> **required**
|
||||
- returns: <[Promise]>
|
||||
|
||||
Provide credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).
|
||||
|
||||
> **NOTE** Browsers may cache credentials after successful authentication. Passing different credentials or passing `null` to disable authentication will be unreliable. To remove or replace credentials, create a new browser context instead.
|
||||
|
||||
## browserContext.setOffline(offline)
|
||||
- `offline` <[boolean]> Whether to emulate network being offline for the browser context.
|
||||
- returns: <[Promise]>
|
||||
|
||||
## browserContext.storageState([options])
|
||||
- `options` <[Object]>
|
||||
- `path` <[string]> The file path to save the storage state 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, storage state is still returned, but won't be saved to the disk.
|
||||
- returns: <[Promise]<[Object]>>
|
||||
- `cookies` <[Array]<[Object]>>
|
||||
- `name` <[string]>
|
||||
- `value` <[string]>
|
||||
- `domain` <[string]>
|
||||
- `path` <[string]>
|
||||
- `expires` <[number]> Unix time in seconds.
|
||||
- `httpOnly` <[boolean]>
|
||||
- `secure` <[boolean]>
|
||||
- `sameSite` <"Strict"|"Lax"|"None">
|
||||
- `origins` <[Array]<[Object]>>
|
||||
- `origin` <[string]>
|
||||
- `localStorage` <[Array]<[Object]>>
|
||||
- `name` <[string]>
|
||||
- `value` <[string]>
|
||||
|
||||
Returns storage state for this browser context, contains current cookies and local storage snapshot.
|
||||
|
||||
## browserContext.unroute(url[, handler])
|
||||
- `url` <[string]|[RegExp]|[function]\([URL]\):[boolean]> A glob pattern, regex pattern or predicate receiving [URL] used to register a routing with [browserContext.route(url, handler)](api/class-browsercontext.md#browsercontextrouteurl-handler).
|
||||
- `handler` <[function]\([Route], [Request]\)> Optional handler function used to register a routing with [browserContext.route(url, handler)](api/class-browsercontext.md#browsercontextrouteurl-handler).
|
||||
- returns: <[Promise]>
|
||||
|
||||
Removes a route created with [browserContext.route(url, handler)](api/class-browsercontext.md#browsercontextrouteurl-handler). When `handler` is not specified, removes all routes for the `url`.
|
||||
|
||||
## browserContext.waitForEvent(event[, optionsOrPredicate])
|
||||
- `event` <[string]> Event name, same one would pass into `browserContext.on(event)`.
|
||||
- `optionsOrPredicate` <[Function]|[Object]> Either a predicate that receives an event or an options object. Optional.
|
||||
- `predicate` <[Function]> receives the event data and resolves to truthy value when the waiting should resolve.
|
||||
- `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 [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout).
|
||||
- returns: <[Promise]<[Object]>>
|
||||
|
||||
Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy value. Will throw an error if the context closes before the event is fired. Returns the event data value.
|
||||
|
||||
```js
|
||||
const context = await browser.newContext();
|
||||
await context.grantPermissions(['geolocation']);
|
||||
```
|
||||
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,96 +0,0 @@
|
|||
---
|
||||
id: class-browserserver
|
||||
title: "BrowserServer"
|
||||
---
|
||||
|
||||
|
||||
|
||||
- [browserServer.on('close')](api/class-browserserver.md#browserserveronclose)
|
||||
- [browserServer.close()](api/class-browserserver.md#browserserverclose)
|
||||
- [browserServer.kill()](api/class-browserserver.md#browserserverkill)
|
||||
- [browserServer.process()](api/class-browserserver.md#browserserverprocess)
|
||||
- [browserServer.wsEndpoint()](api/class-browserserver.md#browserserverwsendpoint)
|
||||
|
||||
## browserServer.on('close')
|
||||
|
||||
Emitted when the browser server closes.
|
||||
|
||||
## browserServer.close()
|
||||
- returns: <[Promise]>
|
||||
|
||||
Closes the browser gracefully and makes sure the process is terminated.
|
||||
|
||||
## browserServer.kill()
|
||||
- returns: <[Promise]>
|
||||
|
||||
Kills the browser process and waits for the process to exit.
|
||||
|
||||
## browserServer.process()
|
||||
- returns: <[ChildProcess]>
|
||||
|
||||
Spawned browser application process.
|
||||
|
||||
## browserServer.wsEndpoint()
|
||||
- returns: <[string]>
|
||||
|
||||
Browser websocket url.
|
||||
|
||||
Browser websocket endpoint which can be used as an argument to [browserType.connect(params)](api/class-browsertype.md#browsertypeconnectparams) to establish connection to the browser.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,252 +0,0 @@
|
|||
---
|
||||
id: class-browsertype
|
||||
title: "BrowserType"
|
||||
---
|
||||
|
||||
|
||||
BrowserType provides methods to launch a specific browser instance or connect to an existing one. The following is a typical example of using Playwright to drive automation:
|
||||
|
||||
```js
|
||||
const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'.
|
||||
|
||||
(async () => {
|
||||
const browser = await chromium.launch();
|
||||
const page = await browser.newPage();
|
||||
await page.goto('https://example.com');
|
||||
// other actions...
|
||||
await browser.close();
|
||||
})();
|
||||
```
|
||||
|
||||
|
||||
- [browserType.connect(params)](api/class-browsertype.md#browsertypeconnectparams)
|
||||
- [browserType.executablePath()](api/class-browsertype.md#browsertypeexecutablepath)
|
||||
- [browserType.launch([options])](api/class-browsertype.md#browsertypelaunchoptions)
|
||||
- [browserType.launchPersistentContext(userDataDir[, options])](api/class-browsertype.md#browsertypelaunchpersistentcontextuserdatadir-options)
|
||||
- [browserType.launchServer([options])](api/class-browsertype.md#browsertypelaunchserveroptions)
|
||||
- [browserType.name()](api/class-browsertype.md#browsertypename)
|
||||
|
||||
## browserType.connect(params)
|
||||
- `params` <[Object]>
|
||||
- `wsEndpoint` <[string]> A browser websocket endpoint to connect to. **required**
|
||||
- `slowMo` <[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. Defaults to 0.
|
||||
- `logger` <[Logger]> Logger sink for Playwright logging. Optional.
|
||||
- `timeout` <[number]> Maximum time in milliseconds to wait for the connection to be established. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
|
||||
- returns: <[Promise]<[Browser]>>
|
||||
|
||||
This methods attaches Playwright to an existing browser instance.
|
||||
|
||||
## browserType.executablePath()
|
||||
- returns: <[string]>
|
||||
|
||||
A path where Playwright expects to find a bundled browser executable.
|
||||
|
||||
## browserType.launch([options])
|
||||
- `options` <[Object]>
|
||||
- `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/).
|
||||
- `chromiumSandbox` <[boolean]> Enable Chromium sandboxing. Defaults to `false`.
|
||||
- `devtools` <[boolean]> **Chromium-only** Whether to auto-open a Developer Tools panel for each tab. If this option is `true`, the `headless` option will be set `false`.
|
||||
- `downloadsPath` <[string]> If specified, accepted downloads are downloaded into this directory. Otherwise, temporary directory is created and is deleted when browser is closed.
|
||||
- `env` <[Object]<[string], [string]|[number]|[boolean]>> Specify environment variables that will be visible to the browser. Defaults to `process.env`.
|
||||
- `executablePath` <[string]> Path to a browser executable to run instead of the bundled one. If `executablePath` is a relative path, then it is resolved relative to the current working directory. Note that Playwright only works with the bundled Chromium, Firefox or WebKit, use at your own risk.
|
||||
- `firefoxUserPrefs` <[Object]<[string], [string]|[number]|[boolean]>> Firefox user preferences. Learn more about the Firefox user preferences at [`about:config`](https://support.mozilla.org/en-US/kb/about-config-editor-firefox).
|
||||
- `handleSIGHUP` <[boolean]> Close the browser process on SIGHUP. Defaults to `true`.
|
||||
- `handleSIGINT` <[boolean]> Close the browser process on Ctrl-C. Defaults to `true`.
|
||||
- `handleSIGTERM` <[boolean]> Close the browser process on SIGTERM. Defaults to `true`.
|
||||
- `headless` <[boolean]> Whether to run browser in headless mode. More details for [Chromium](https://developers.google.com/web/updates/2017/04/headless-chrome) and [Firefox](https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Headless_mode). Defaults to `true` unless the `devtools` option is `true`.
|
||||
- `ignoreDefaultArgs` <[boolean]|[Array]<[string]>> If `true`, Playwright does not pass its own configurations args and only uses the ones from `args`. If an array is given, then filters out the given default arguments. Dangerous option; use with care. Defaults to `false`.
|
||||
- `logger` <[Logger]> Logger sink for Playwright logging.
|
||||
- `proxy` <[Object]> Network proxy settings.
|
||||
- `server` <[string]> Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example `http://myproxy.com:3128` or `socks5://myproxy.com:3128`. Short form `myproxy.com:3128` is considered an HTTP proxy.
|
||||
- `bypass` <[string]> Optional coma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`.
|
||||
- `username` <[string]> Optional username to use if HTTP proxy requires authentication.
|
||||
- `password` <[string]> Optional password to use if HTTP proxy requires authentication.
|
||||
- `slowMo` <[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on.
|
||||
- `timeout` <[number]> Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
|
||||
- returns: <[Promise]<[Browser]>>
|
||||
|
||||
Returns the browser instance.
|
||||
|
||||
You can use `ignoreDefaultArgs` to filter out `--mute-audio` from default arguments:
|
||||
|
||||
```js
|
||||
const browser = await chromium.launch({ // Or 'firefox' or 'webkit'.
|
||||
ignoreDefaultArgs: ['--mute-audio']
|
||||
});
|
||||
```
|
||||
|
||||
> **Chromium-only** Playwright can also be used to control the Chrome browser, but it works best with the version of Chromium it is bundled with. There is no guarantee it will work with any other version. Use `executablePath` option with extreme caution.
|
||||
>
|
||||
> If Google Chrome (rather than Chromium) is preferred, a [Chrome Canary](https://www.google.com/chrome/browser/canary.html) or [Dev Channel](https://www.chromium.org/getting-involved/dev-channel) build is suggested.
|
||||
>
|
||||
> In [browserType.launch([options])](api/class-browsertype.md#browsertypelaunchoptions) above, any mention of Chromium also applies to Chrome.
|
||||
>
|
||||
> 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.
|
||||
|
||||
## browserType.launchPersistentContext(userDataDir[, options])
|
||||
- `userDataDir` <[string]> Path to a User Data Directory, which stores browser session data like cookies and local storage. More details for [Chromium](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md) and [Firefox](https://developer.mozilla.org/en-US/docs/Mozilla/Command_Line_Options#User_Profile).
|
||||
- `options` <[Object]>
|
||||
- `acceptDownloads` <[boolean]> Whether to automatically download all the attachments. Defaults to `false` where all the downloads are canceled.
|
||||
- `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/).
|
||||
- `bypassCSP` <[boolean]> Toggles bypassing page's Content-Security-Policy.
|
||||
- `chromiumSandbox` <[boolean]> Enable Chromium sandboxing. Defaults to `true`.
|
||||
- `colorScheme` <"light"|"dark"|"no-preference"> Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See [page.emulateMedia(params)](api/class-page.md#pageemulatemediaparams) for more details. Defaults to '`light`'.
|
||||
- `deviceScaleFactor` <[number]> Specify device scale factor (can be thought of as dpr). Defaults to `1`.
|
||||
- `devtools` <[boolean]> **Chromium-only** Whether to auto-open a Developer Tools panel for each tab. If this option is `true`, the `headless` option will be set `false`.
|
||||
- `downloadsPath` <[string]> If specified, accepted downloads are downloaded into this directory. Otherwise, temporary directory is created and is deleted when browser is closed.
|
||||
- `env` <[Object]<[string], [string]|[number]|[boolean]>> Specify environment variables that will be visible to the browser. Defaults to `process.env`.
|
||||
- `executablePath` <[string]> Path to a browser executable to run instead of the bundled one. If `executablePath` is a relative path, then it is resolved relative to the current working directory. **BEWARE**: Playwright is only guaranteed to work with the bundled Chromium, Firefox or WebKit, use at your own risk.
|
||||
- `extraHTTPHeaders` <[Object]<[string], [string]>> An object containing additional HTTP headers to be sent with every request. All header values must be strings.
|
||||
- `geolocation` <[Object]>
|
||||
- `latitude` <[number]> Latitude between -90 and 90.
|
||||
- `longitude` <[number]> Longitude between -180 and 180.
|
||||
- `accuracy` <[number]> Non-negative accuracy value. Defaults to `0`.
|
||||
- `handleSIGHUP` <[boolean]> Close the browser process on SIGHUP. Defaults to `true`.
|
||||
- `handleSIGINT` <[boolean]> Close the browser process on Ctrl-C. Defaults to `true`.
|
||||
- `handleSIGTERM` <[boolean]> Close the browser process on SIGTERM. Defaults to `true`.
|
||||
- `hasTouch` <[boolean]> Specifies if viewport supports touch events. Defaults to false.
|
||||
- `headless` <[boolean]> Whether to run browser in headless mode. More details for [Chromium](https://developers.google.com/web/updates/2017/04/headless-chrome) and [Firefox](https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Headless_mode). Defaults to `true` unless the `devtools` option is `true`.
|
||||
- `httpCredentials` <[Object]> Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).
|
||||
- `username` <[string]>
|
||||
- `password` <[string]>
|
||||
- `ignoreDefaultArgs` <[boolean]|[Array]<[string]>> If `true`, then do not use any of the default arguments. If an array is given, then filter out the given default arguments. Dangerous option; use with care. Defaults to `false`.
|
||||
- `ignoreHTTPSErrors` <[boolean]> Whether to ignore HTTPS errors during navigation. Defaults to `false`.
|
||||
- `isMobile` <[boolean]> Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not supported in Firefox.
|
||||
- `javaScriptEnabled` <[boolean]> Whether or not to enable JavaScript in the context. Defaults to `true`.
|
||||
- `locale` <[string]> Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value, `Accept-Language` request header value as well as number and date formatting rules.
|
||||
- `logger` <[Logger]> Logger sink for Playwright logging.
|
||||
- `offline` <[boolean]> Whether to emulate network being offline. Defaults to `false`.
|
||||
- `permissions` <[Array]<[string]>> A list of permissions to grant to all pages in this context. See [browserContext.grantPermissions(permissions[, options])](api/class-browsercontext.md#browsercontextgrantpermissionspermissions-options) for more details.
|
||||
- `proxy` <[Object]> Network proxy settings.
|
||||
- `server` <[string]> Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example `http://myproxy.com:3128` or `socks5://myproxy.com:3128`. Short form `myproxy.com:3128` is considered an HTTP proxy.
|
||||
- `bypass` <[string]> Optional coma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`.
|
||||
- `username` <[string]> Optional username to use if HTTP proxy requires authentication.
|
||||
- `password` <[string]> Optional password to use if HTTP proxy requires authentication.
|
||||
- `recordHar` <[Object]> Enables [HAR](http://www.softwareishard.com/blog/har-12-spec) recording for all pages into `recordHar.path` file. If not specified, the HAR is not recorded. Make sure to await [browserContext.close()](api/class-browsercontext.md#browsercontextclose) for the HAR to be saved.
|
||||
- `omitContent` <[boolean]> Optional setting to control whether to omit request content from the HAR. Defaults to `false`.
|
||||
- `path` <[string]> Path on the filesystem to write the HAR file to.
|
||||
- `recordVideo` <[Object]> Enables video recording for all pages into `recordVideo.dir` directory. If not specified videos are not recorded. Make sure to await [browserContext.close()](api/class-browsercontext.md#browsercontextclose) for videos to be saved.
|
||||
- `dir` <[string]> Path to the directory to put videos into.
|
||||
- `size` <[Object]> Optional dimensions of the recorded videos. If not specified the size will be equal to `viewport`. If `viewport` is not configured explicitly the video size defaults to 1280x720. Actual picture of each page will be scaled down if necessary to fit the specified size.
|
||||
- `width` <[number]> Video frame width.
|
||||
- `height` <[number]> Video frame height.
|
||||
- `slowMo` <[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. Defaults to 0.
|
||||
- `timeout` <[number]> Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
|
||||
- `timezoneId` <[string]> Changes the timezone of the context. 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.
|
||||
- `userAgent` <[string]> Specific user agent to use in this context.
|
||||
- `videoSize` <[Object]> **NOTE** Use `recordVideo` instead, it takes precedence over `videoSize`. Specifies dimensions of the automatically recorded video. Can only be used if `videosPath` is set. If not specified the size will be equal to `viewport`. If `viewport` is not configured explicitly the video size defaults to 1280x720. Actual picture of the page will be scaled down if necessary to fit specified size.
|
||||
- `width` <[number]> Video frame width.
|
||||
- `height` <[number]> Video frame height.
|
||||
- `videosPath` <[string]> **NOTE** Use `recordVideo` instead, it takes precedence over `videosPath`. Enables video recording for all pages to `videosPath` directory. If not specified, videos are not recorded. Make sure to await [browserContext.close()](api/class-browsercontext.md#browsercontextclose) for videos to be saved.
|
||||
- `viewport` <[null]|[Object]> Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport.
|
||||
- `width` <[number]> page width in pixels.
|
||||
- `height` <[number]> page height in pixels.
|
||||
- returns: <[Promise]<[BrowserContext]>>
|
||||
|
||||
Returns the persistent browser context instance.
|
||||
|
||||
Launches browser that uses persistent storage located at `userDataDir` and returns the only context. Closing this context will automatically close the browser.
|
||||
|
||||
## browserType.launchServer([options])
|
||||
- `options` <[Object]>
|
||||
- `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/).
|
||||
- `chromiumSandbox` <[boolean]> Enable Chromium sandboxing. Defaults to `true`.
|
||||
- `devtools` <[boolean]> **Chromium-only** Whether to auto-open a Developer Tools panel for each tab. If this option is `true`, the `headless` option will be set `false`.
|
||||
- `downloadsPath` <[string]> If specified, accepted downloads are downloaded into this directory. Otherwise, temporary directory is created and is deleted when browser is closed.
|
||||
- `env` <[Object]<[string], [string]|[number]|[boolean]>> Specify environment variables that will be visible to the browser. Defaults to `process.env`.
|
||||
- `executablePath` <[string]> Path to a browser executable to run instead of the bundled one. If `executablePath` is a relative path, then it is resolved relative to the current working directory. **BEWARE**: Playwright is only guaranteed to work with the bundled Chromium, Firefox or WebKit, use at your own risk.
|
||||
- `firefoxUserPrefs` <[Object]<[string], [string]|[number]|[boolean]>> Firefox user preferences. Learn more about the Firefox user preferences at [`about:config`](https://support.mozilla.org/en-US/kb/about-config-editor-firefox).
|
||||
- `handleSIGHUP` <[boolean]> Close the browser process on SIGHUP. Defaults to `true`.
|
||||
- `handleSIGINT` <[boolean]> Close the browser process on Ctrl-C. Defaults to `true`.
|
||||
- `handleSIGTERM` <[boolean]> Close the browser process on SIGTERM. Defaults to `true`.
|
||||
- `headless` <[boolean]> Whether to run browser in headless mode. More details for [Chromium](https://developers.google.com/web/updates/2017/04/headless-chrome) and [Firefox](https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Headless_mode). Defaults to `true` unless the `devtools` option is `true`.
|
||||
- `ignoreDefaultArgs` <[boolean]|[Array]<[string]>> If `true`, then do not use any of the default arguments. If an array is given, then filter out the given default arguments. Dangerous option; use with care. Defaults to `false`.
|
||||
- `logger` <[Logger]> Logger sink for Playwright logging.
|
||||
- `port` <[number]> Port to use for the web socket. Defaults to 0 that picks any available port.
|
||||
- `proxy` <[Object]> Network proxy settings.
|
||||
- `server` <[string]> Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example `http://myproxy.com:3128` or `socks5://myproxy.com:3128`. Short form `myproxy.com:3128` is considered an HTTP proxy.
|
||||
- `bypass` <[string]> Optional coma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`.
|
||||
- `username` <[string]> Optional username to use if HTTP proxy requires authentication.
|
||||
- `password` <[string]> Optional password to use if HTTP proxy requires authentication.
|
||||
- `timeout` <[number]> Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
|
||||
- returns: <[Promise]<[BrowserServer]>>
|
||||
|
||||
Returns the browser app instance.
|
||||
|
||||
Launches browser server that client can connect to. An example of launching a browser executable and connecting to it later:
|
||||
|
||||
```js
|
||||
const { chromium } = require('playwright'); // Or 'webkit' or 'firefox'.
|
||||
|
||||
(async () => {
|
||||
const browserServer = await chromium.launchServer();
|
||||
const wsEndpoint = browserServer.wsEndpoint();
|
||||
// Use web socket endpoint later to establish a connection.
|
||||
const browser = await chromium.connect({ wsEndpoint });
|
||||
// Close browser instance.
|
||||
await browserServer.close();
|
||||
})();
|
||||
```
|
||||
|
||||
## browserType.name()
|
||||
- returns: <[string]>
|
||||
|
||||
Returns browser name. For example: `'chromium'`, `'webkit'` or `'firefox'`.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,97 +0,0 @@
|
|||
---
|
||||
id: class-cdpsession
|
||||
title: "CDPSession"
|
||||
---
|
||||
|
||||
* extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
|
||||
|
||||
The `CDPSession` instances are used to talk raw Chrome Devtools Protocol:
|
||||
* protocol methods can be called with `session.send` method.
|
||||
* protocol events can be subscribed to with `session.on` method.
|
||||
|
||||
Useful links:
|
||||
* Documentation on DevTools Protocol can be found here: [DevTools Protocol Viewer](https://chromedevtools.github.io/devtools-protocol/).
|
||||
* Getting Started with DevTools Protocol: https://github.com/aslushnikov/getting-started-with-cdp/blob/master/README.md
|
||||
|
||||
```js
|
||||
const client = await page.context().newCDPSession(page);
|
||||
await client.send('Animation.enable');
|
||||
client.on('Animation.animationCreated', () => console.log('Animation created!'));
|
||||
const response = await client.send('Animation.getPlaybackRate');
|
||||
console.log('playback rate is ' + response.playbackRate);
|
||||
await client.send('Animation.setPlaybackRate', {
|
||||
playbackRate: response.playbackRate / 2
|
||||
});
|
||||
```
|
||||
|
||||
|
||||
- [cdpSession.detach()](api/class-cdpsession.md#cdpsessiondetach)
|
||||
- [cdpSession.send(method[, params])](api/class-cdpsession.md#cdpsessionsendmethod-params)
|
||||
|
||||
## cdpSession.detach()
|
||||
- returns: <[Promise]>
|
||||
|
||||
Detaches the CDPSession from the target. Once detached, the CDPSession object won't emit any events and can't be used to send messages.
|
||||
|
||||
## cdpSession.send(method[, params])
|
||||
- `method` <[string]> protocol method name
|
||||
- `params` <[Object]> Optional method parameters
|
||||
- returns: <[Promise]<[Object]>>
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,104 +0,0 @@
|
|||
---
|
||||
id: class-chromiumbrowser
|
||||
title: "ChromiumBrowser"
|
||||
---
|
||||
|
||||
* extends: [Browser]
|
||||
|
||||
Chromium-specific features including Tracing, service worker support, etc. You can use [chromiumBrowser.startTracing([page, options])](api/class-chromiumbrowser.md#chromiumbrowserstarttracingpage-options) and [chromiumBrowser.stopTracing()](api/class-chromiumbrowser.md#chromiumbrowserstoptracing) to create a trace file which can be opened in Chrome DevTools or [timeline viewer](https://chromedevtools.github.io/timeline-viewer/).
|
||||
|
||||
```js
|
||||
await browser.startTracing(page, {path: 'trace.json'});
|
||||
await page.goto('https://www.google.com');
|
||||
await browser.stopTracing();
|
||||
```
|
||||
|
||||
|
||||
- [chromiumBrowser.newBrowserCDPSession()](api/class-chromiumbrowser.md#chromiumbrowsernewbrowsercdpsession)
|
||||
- [chromiumBrowser.startTracing([page, options])](api/class-chromiumbrowser.md#chromiumbrowserstarttracingpage-options)
|
||||
- [chromiumBrowser.stopTracing()](api/class-chromiumbrowser.md#chromiumbrowserstoptracing)
|
||||
- [browser.on('disconnected')](api/class-browser.md#browserondisconnected)
|
||||
- [browser.close()](api/class-browser.md#browserclose)
|
||||
- [browser.contexts()](api/class-browser.md#browsercontexts)
|
||||
- [browser.isConnected()](api/class-browser.md#browserisconnected)
|
||||
- [browser.newContext([options])](api/class-browser.md#browsernewcontextoptions)
|
||||
- [browser.newPage([options])](api/class-browser.md#browsernewpageoptions)
|
||||
- [browser.version()](api/class-browser.md#browserversion)
|
||||
|
||||
## chromiumBrowser.newBrowserCDPSession()
|
||||
- returns: <[Promise]<[CDPSession]>>
|
||||
|
||||
Returns the newly created browser session.
|
||||
|
||||
## chromiumBrowser.startTracing([page, options])
|
||||
- `page` <[Page]> Optional, if specified, tracing includes screenshots of the given page.
|
||||
- `options` <[Object]>
|
||||
- `categories` <[Array]<[string]>> specify custom categories to use instead of default.
|
||||
- `path` <[string]> A path to write the trace file to.
|
||||
- `screenshots` <[boolean]> captures screenshots in the trace.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Only one trace can be active at a time per browser.
|
||||
|
||||
## chromiumBrowser.stopTracing()
|
||||
- returns: <[Promise]<[Buffer]>>
|
||||
|
||||
Returns the buffer with trace data.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,129 +0,0 @@
|
|||
---
|
||||
id: class-chromiumbrowsercontext
|
||||
title: "ChromiumBrowserContext"
|
||||
---
|
||||
|
||||
* extends: [BrowserContext]
|
||||
|
||||
Chromium-specific features including background pages, service worker support, etc.
|
||||
|
||||
```js
|
||||
const backgroundPage = await context.waitForEvent('backgroundpage');
|
||||
```
|
||||
|
||||
|
||||
- [chromiumBrowserContext.on('backgroundpage')](api/class-chromiumbrowsercontext.md#chromiumbrowsercontextonbackgroundpage)
|
||||
- [chromiumBrowserContext.on('serviceworker')](api/class-chromiumbrowsercontext.md#chromiumbrowsercontextonserviceworker)
|
||||
- [chromiumBrowserContext.backgroundPages()](api/class-chromiumbrowsercontext.md#chromiumbrowsercontextbackgroundpages)
|
||||
- [chromiumBrowserContext.newCDPSession(page)](api/class-chromiumbrowsercontext.md#chromiumbrowsercontextnewcdpsessionpage)
|
||||
- [chromiumBrowserContext.serviceWorkers()](api/class-chromiumbrowsercontext.md#chromiumbrowsercontextserviceworkers)
|
||||
- [browserContext.on('close')](api/class-browsercontext.md#browsercontextonclose)
|
||||
- [browserContext.on('page')](api/class-browsercontext.md#browsercontextonpage)
|
||||
- [browserContext.addCookies(cookies)](api/class-browsercontext.md#browsercontextaddcookiescookies)
|
||||
- [browserContext.addInitScript(script[, arg])](api/class-browsercontext.md#browsercontextaddinitscriptscript-arg)
|
||||
- [browserContext.browser()](api/class-browsercontext.md#browsercontextbrowser)
|
||||
- [browserContext.clearCookies()](api/class-browsercontext.md#browsercontextclearcookies)
|
||||
- [browserContext.clearPermissions()](api/class-browsercontext.md#browsercontextclearpermissions)
|
||||
- [browserContext.close()](api/class-browsercontext.md#browsercontextclose)
|
||||
- [browserContext.cookies([urls])](api/class-browsercontext.md#browsercontextcookiesurls)
|
||||
- [browserContext.exposeBinding(name, callback[, options])](api/class-browsercontext.md#browsercontextexposebindingname-callback-options)
|
||||
- [browserContext.exposeFunction(name, callback)](api/class-browsercontext.md#browsercontextexposefunctionname-callback)
|
||||
- [browserContext.grantPermissions(permissions[, options])](api/class-browsercontext.md#browsercontextgrantpermissionspermissions-options)
|
||||
- [browserContext.newPage()](api/class-browsercontext.md#browsercontextnewpage)
|
||||
- [browserContext.pages()](api/class-browsercontext.md#browsercontextpages)
|
||||
- [browserContext.route(url, handler)](api/class-browsercontext.md#browsercontextrouteurl-handler)
|
||||
- [browserContext.setDefaultNavigationTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaultnavigationtimeouttimeout)
|
||||
- [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout)
|
||||
- [browserContext.setExtraHTTPHeaders(headers)](api/class-browsercontext.md#browsercontextsetextrahttpheadersheaders)
|
||||
- [browserContext.setGeolocation(geolocation)](api/class-browsercontext.md#browsercontextsetgeolocationgeolocation)
|
||||
- [browserContext.setHTTPCredentials(httpCredentials)](api/class-browsercontext.md#browsercontextsethttpcredentialshttpcredentials)
|
||||
- [browserContext.setOffline(offline)](api/class-browsercontext.md#browsercontextsetofflineoffline)
|
||||
- [browserContext.storageState([options])](api/class-browsercontext.md#browsercontextstoragestateoptions)
|
||||
- [browserContext.unroute(url[, handler])](api/class-browsercontext.md#browsercontextunrouteurl-handler)
|
||||
- [browserContext.waitForEvent(event[, optionsOrPredicate])](api/class-browsercontext.md#browsercontextwaitforeventevent-optionsorpredicate)
|
||||
|
||||
## chromiumBrowserContext.on('backgroundpage')
|
||||
- type: <[Page]>
|
||||
|
||||
Emitted when new background page is created in the context.
|
||||
|
||||
> **NOTE** Only works with persistent context.
|
||||
|
||||
## chromiumBrowserContext.on('serviceworker')
|
||||
- type: <[Worker]>
|
||||
|
||||
Emitted when new service worker is created in the context.
|
||||
|
||||
## chromiumBrowserContext.backgroundPages()
|
||||
- returns: <[Array]<[Page]>>
|
||||
|
||||
All existing background pages in the context.
|
||||
|
||||
## chromiumBrowserContext.newCDPSession(page)
|
||||
- `page` <[Page]> Page to create new session for.
|
||||
- returns: <[Promise]<[CDPSession]>>
|
||||
|
||||
Returns the newly created session.
|
||||
|
||||
## chromiumBrowserContext.serviceWorkers()
|
||||
- returns: <[Array]<[Worker]>>
|
||||
|
||||
All existing service workers in the context.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,139 +0,0 @@
|
|||
---
|
||||
id: class-chromiumcoverage
|
||||
title: "ChromiumCoverage"
|
||||
---
|
||||
|
||||
|
||||
Coverage gathers information about parts of JavaScript and CSS that were used by the page.
|
||||
|
||||
An example of using JavaScript coverage to produce Istambul report for page load:
|
||||
|
||||
```js
|
||||
const { chromium } = require('playwright');
|
||||
const v8toIstanbul = require('v8-to-istanbul');
|
||||
|
||||
(async() => {
|
||||
const browser = await chromium.launch();
|
||||
const page = await browser.newPage();
|
||||
await page.coverage.startJSCoverage();
|
||||
await page.goto('https://chromium.org');
|
||||
const coverage = await page.coverage.stopJSCoverage();
|
||||
for (const entry of coverage) {
|
||||
const converter = new v8toIstanbul('', 0, { source: entry.source });
|
||||
await converter.load();
|
||||
converter.applyCoverage(entry.functions);
|
||||
console.log(JSON.stringify(converter.toIstanbul()));
|
||||
}
|
||||
await browser.close();
|
||||
})();
|
||||
```
|
||||
|
||||
|
||||
- [chromiumCoverage.startCSSCoverage([options])](api/class-chromiumcoverage.md#chromiumcoveragestartcsscoverageoptions)
|
||||
- [chromiumCoverage.startJSCoverage([options])](api/class-chromiumcoverage.md#chromiumcoveragestartjscoverageoptions)
|
||||
- [chromiumCoverage.stopCSSCoverage()](api/class-chromiumcoverage.md#chromiumcoveragestopcsscoverage)
|
||||
- [chromiumCoverage.stopJSCoverage()](api/class-chromiumcoverage.md#chromiumcoveragestopjscoverage)
|
||||
|
||||
## chromiumCoverage.startCSSCoverage([options])
|
||||
- `options` <[Object]>
|
||||
- `resetOnNavigation` <[boolean]> Whether to reset coverage on every navigation. Defaults to `true`.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Returns coverage is started
|
||||
|
||||
## chromiumCoverage.startJSCoverage([options])
|
||||
- `options` <[Object]>
|
||||
- `reportAnonymousScripts` <[boolean]> Whether anonymous scripts generated by the page should be reported. Defaults to `false`.
|
||||
- `resetOnNavigation` <[boolean]> Whether to reset coverage on every navigation. Defaults to `true`.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Returns coverage is started
|
||||
|
||||
> **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 `__playwright_evaluation_script__` as their URL.
|
||||
|
||||
## chromiumCoverage.stopCSSCoverage()
|
||||
- returns: <[Promise]<[Array]<[Object]>>>
|
||||
- `url` <[string]> StyleSheet URL
|
||||
- `text` <[string]> StyleSheet content, if available.
|
||||
- `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
|
||||
|
||||
Returns the array of coverage reports for all stylesheets
|
||||
|
||||
> **NOTE** CSS Coverage doesn't include dynamically injected style tags without sourceURLs.
|
||||
|
||||
## chromiumCoverage.stopJSCoverage()
|
||||
- returns: <[Promise]<[Array]<[Object]>>>
|
||||
- `url` <[string]> Script URL
|
||||
- `scriptId` <[string]> Script ID
|
||||
- `source` <[string]> Script content, if applicable.
|
||||
- `functions` <[Array]<[Object]>> V8-specific coverage format.
|
||||
- `functionName` <[string]>
|
||||
- `isBlockCoverage` <[boolean]>
|
||||
- `ranges` <[Array]<[Object]>>
|
||||
- `count` <[number]>
|
||||
- `startOffset` <[number]>
|
||||
- `endOffset` <[number]>
|
||||
|
||||
Returns the array of coverage reports for all scripts
|
||||
|
||||
> **NOTE** JavaScript Coverage doesn't include anonymous scripts by default. However, scripts with sourceURLs are reported.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,88 +0,0 @@
|
|||
---
|
||||
id: class-consolemessage
|
||||
title: "ConsoleMessage"
|
||||
---
|
||||
|
||||
|
||||
[ConsoleMessage] objects are dispatched by page via the [page.on('console')](api/class-page.md#pageonconsole) event.
|
||||
|
||||
|
||||
- [consoleMessage.args()](api/class-consolemessage.md#consolemessageargs)
|
||||
- [consoleMessage.location()](api/class-consolemessage.md#consolemessagelocation)
|
||||
- [consoleMessage.text()](api/class-consolemessage.md#consolemessagetext)
|
||||
- [consoleMessage.type()](api/class-consolemessage.md#consolemessagetype)
|
||||
|
||||
## consoleMessage.args()
|
||||
- returns: <[Array]<[JSHandle]>>
|
||||
|
||||
## consoleMessage.location()
|
||||
- returns: <[Object]>
|
||||
- `url` <[string]> URL of the resource.
|
||||
- `lineNumber` <[number]> 0-based line number in the resource.
|
||||
- `columnNumber` <[number]> 0-based column number in the resource.
|
||||
|
||||
## consoleMessage.text()
|
||||
- returns: <[string]>
|
||||
|
||||
## consoleMessage.type()
|
||||
- returns: <[string]>
|
||||
|
||||
One of the following values: `'log'`, `'debug'`, `'info'`, `'error'`, `'warning'`, `'dir'`, `'dirxml'`, `'table'`, `'trace'`, `'clear'`, `'startGroup'`, `'startGroupCollapsed'`, `'endGroup'`, `'assert'`, `'profile'`, `'profileEnd'`, `'count'`, `'timeEnd'`.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,115 +0,0 @@
|
|||
---
|
||||
id: class-dialog
|
||||
title: "Dialog"
|
||||
---
|
||||
|
||||
|
||||
[Dialog] objects are dispatched by page via the [page.on('dialog')](api/class-page.md#pageondialog) event.
|
||||
|
||||
An example of using `Dialog` class:
|
||||
|
||||
```js
|
||||
const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'.
|
||||
|
||||
(async () => {
|
||||
const browser = await chromium.launch();
|
||||
const page = await browser.newPage();
|
||||
page.on('dialog', async dialog => {
|
||||
console.log(dialog.message());
|
||||
await dialog.dismiss();
|
||||
await browser.close();
|
||||
});
|
||||
page.evaluate(() => alert('1'));
|
||||
})();
|
||||
```
|
||||
|
||||
|
||||
- [dialog.accept([promptText])](api/class-dialog.md#dialogacceptprompttext)
|
||||
- [dialog.defaultValue()](api/class-dialog.md#dialogdefaultvalue)
|
||||
- [dialog.dismiss()](api/class-dialog.md#dialogdismiss)
|
||||
- [dialog.message()](api/class-dialog.md#dialogmessage)
|
||||
- [dialog.type()](api/class-dialog.md#dialogtype)
|
||||
|
||||
## dialog.accept([promptText])
|
||||
- `promptText` <[string]> A text to enter in prompt. Does not cause any effects if the dialog's `type` is not prompt. Optional.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Returns when the dialog has been accepted.
|
||||
|
||||
## dialog.defaultValue()
|
||||
- returns: <[string]>
|
||||
|
||||
If dialog is prompt, returns default prompt value. Otherwise, returns empty string.
|
||||
|
||||
## dialog.dismiss()
|
||||
- returns: <[Promise]>
|
||||
|
||||
Returns when the dialog has been dismissed.
|
||||
|
||||
## dialog.message()
|
||||
- returns: <[string]>
|
||||
|
||||
A message displayed in the dialog.
|
||||
|
||||
## dialog.type()
|
||||
- returns: <[string]>
|
||||
|
||||
Returns dialog's type, can be one of `alert`, `beforeunload`, `confirm` or `prompt`.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,126 +0,0 @@
|
|||
---
|
||||
id: class-download
|
||||
title: "Download"
|
||||
---
|
||||
|
||||
|
||||
[Download] objects are dispatched by page via the [page.on('download')](api/class-page.md#pageondownload) event.
|
||||
|
||||
All the downloaded files belonging to the browser context are deleted when the browser context is closed. All downloaded files are deleted when the browser closes.
|
||||
|
||||
Download event is emitted once the download starts. Download path becomes available once download completes:
|
||||
|
||||
```js
|
||||
const [ download ] = await Promise.all([
|
||||
page.waitForEvent('download'), // wait for download to start
|
||||
page.click('a')
|
||||
]);
|
||||
// wait for download to complete
|
||||
const path = await download.path();
|
||||
...
|
||||
```
|
||||
|
||||
> **NOTE** Browser context **must** be created with the `acceptDownloads` set to `true` when user needs access to the downloaded content. If `acceptDownloads` is not set or set to `false`, download events are emitted, but the actual download is not performed and user has no access to the downloaded files.
|
||||
|
||||
|
||||
- [download.createReadStream()](api/class-download.md#downloadcreatereadstream)
|
||||
- [download.delete()](api/class-download.md#downloaddelete)
|
||||
- [download.failure()](api/class-download.md#downloadfailure)
|
||||
- [download.path()](api/class-download.md#downloadpath)
|
||||
- [download.saveAs(path)](api/class-download.md#downloadsaveaspath)
|
||||
- [download.suggestedFilename()](api/class-download.md#downloadsuggestedfilename)
|
||||
- [download.url()](api/class-download.md#downloadurl)
|
||||
|
||||
## download.createReadStream()
|
||||
- returns: <[Promise]<[null]|[Readable]>>
|
||||
|
||||
Returns readable stream for current download or `null` if download failed.
|
||||
|
||||
## download.delete()
|
||||
- returns: <[Promise]>
|
||||
|
||||
Deletes the downloaded file.
|
||||
|
||||
## download.failure()
|
||||
- returns: <[Promise]<[null]|[string]>>
|
||||
|
||||
Returns download error if any.
|
||||
|
||||
## download.path()
|
||||
- returns: <[Promise]<[null]|[string]>>
|
||||
|
||||
Returns path to the downloaded file in case of successful download.
|
||||
|
||||
## download.saveAs(path)
|
||||
- `path` <[string]> Path where the download should be saved.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Saves the download to a user-specified path.
|
||||
|
||||
## download.suggestedFilename()
|
||||
- returns: <[string]>
|
||||
|
||||
Returns suggested filename for this download. It is typically computed by the browser from the [`Content-Disposition`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) response header or the `download` attribute. See the spec on [whatwg](https://html.spec.whatwg.org/#downloading-resources). Different browsers can use different logic for computing it.
|
||||
|
||||
## download.url()
|
||||
- returns: <[string]>
|
||||
|
||||
Returns downloaded url.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,563 +0,0 @@
|
|||
---
|
||||
id: class-elementhandle
|
||||
title: "ElementHandle"
|
||||
---
|
||||
|
||||
* extends: [JSHandle]
|
||||
|
||||
ElementHandle represents an in-page DOM element. ElementHandles can be created with the [page.$(selector)](api/class-page.md#pageselector) method.
|
||||
|
||||
```js
|
||||
const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'.
|
||||
|
||||
(async () => {
|
||||
const browser = await chromium.launch();
|
||||
const page = await browser.newPage();
|
||||
await page.goto('https://example.com');
|
||||
const hrefElement = await page.$('a');
|
||||
await hrefElement.click();
|
||||
// ...
|
||||
})();
|
||||
```
|
||||
|
||||
ElementHandle prevents DOM element from garbage collection unless the handle is disposed with [jsHandle.dispose()](api/class-jshandle.md#jshandledispose). ElementHandles are auto-disposed when their origin frame gets navigated.
|
||||
|
||||
ElementHandle instances can be used as an argument in [page.$eval(selector, pageFunction[, arg])](api/class-page.md#pageevalselector-pagefunction-arg) and [page.evaluate(pageFunction[, arg])](api/class-page.md#pageevaluatepagefunction-arg) methods.
|
||||
|
||||
|
||||
- [elementHandle.$(selector)](api/class-elementhandle.md#elementhandleselector)
|
||||
- [elementHandle.$$(selector)](api/class-elementhandle.md#elementhandleselector-1)
|
||||
- [elementHandle.$eval(selector, pageFunction[, arg])](api/class-elementhandle.md#elementhandleevalselector-pagefunction-arg)
|
||||
- [elementHandle.$$eval(selector, pageFunction[, arg])](api/class-elementhandle.md#elementhandleevalselector-pagefunction-arg-1)
|
||||
- [elementHandle.boundingBox()](api/class-elementhandle.md#elementhandleboundingbox)
|
||||
- [elementHandle.check([options])](api/class-elementhandle.md#elementhandlecheckoptions)
|
||||
- [elementHandle.click([options])](api/class-elementhandle.md#elementhandleclickoptions)
|
||||
- [elementHandle.contentFrame()](api/class-elementhandle.md#elementhandlecontentframe)
|
||||
- [elementHandle.dblclick([options])](api/class-elementhandle.md#elementhandledblclickoptions)
|
||||
- [elementHandle.dispatchEvent(type[, eventInit])](api/class-elementhandle.md#elementhandledispatcheventtype-eventinit)
|
||||
- [elementHandle.fill(value[, options])](api/class-elementhandle.md#elementhandlefillvalue-options)
|
||||
- [elementHandle.focus()](api/class-elementhandle.md#elementhandlefocus)
|
||||
- [elementHandle.getAttribute(name)](api/class-elementhandle.md#elementhandlegetattributename)
|
||||
- [elementHandle.hover([options])](api/class-elementhandle.md#elementhandlehoveroptions)
|
||||
- [elementHandle.innerHTML()](api/class-elementhandle.md#elementhandleinnerhtml)
|
||||
- [elementHandle.innerText()](api/class-elementhandle.md#elementhandleinnertext)
|
||||
- [elementHandle.ownerFrame()](api/class-elementhandle.md#elementhandleownerframe)
|
||||
- [elementHandle.press(key[, options])](api/class-elementhandle.md#elementhandlepresskey-options)
|
||||
- [elementHandle.screenshot([options])](api/class-elementhandle.md#elementhandlescreenshotoptions)
|
||||
- [elementHandle.scrollIntoViewIfNeeded([options])](api/class-elementhandle.md#elementhandlescrollintoviewifneededoptions)
|
||||
- [elementHandle.selectOption(values[, options])](api/class-elementhandle.md#elementhandleselectoptionvalues-options)
|
||||
- [elementHandle.selectText([options])](api/class-elementhandle.md#elementhandleselecttextoptions)
|
||||
- [elementHandle.setInputFiles(files[, options])](api/class-elementhandle.md#elementhandlesetinputfilesfiles-options)
|
||||
- [elementHandle.tap([options])](api/class-elementhandle.md#elementhandletapoptions)
|
||||
- [elementHandle.textContent()](api/class-elementhandle.md#elementhandletextcontent)
|
||||
- [elementHandle.type(text[, options])](api/class-elementhandle.md#elementhandletypetext-options)
|
||||
- [elementHandle.uncheck([options])](api/class-elementhandle.md#elementhandleuncheckoptions)
|
||||
- [elementHandle.waitForElementState(state[, options])](api/class-elementhandle.md#elementhandlewaitforelementstatestate-options)
|
||||
- [elementHandle.waitForSelector(selector[, options])](api/class-elementhandle.md#elementhandlewaitforselectorselector-options)
|
||||
- [jsHandle.asElement()](api/class-jshandle.md#jshandleaselement)
|
||||
- [jsHandle.dispose()](api/class-jshandle.md#jshandledispose)
|
||||
- [jsHandle.evaluate(pageFunction[, arg])](api/class-jshandle.md#jshandleevaluatepagefunction-arg)
|
||||
- [jsHandle.evaluateHandle(pageFunction[, arg])](api/class-jshandle.md#jshandleevaluatehandlepagefunction-arg)
|
||||
- [jsHandle.getProperties()](api/class-jshandle.md#jshandlegetproperties)
|
||||
- [jsHandle.getProperty(propertyName)](api/class-jshandle.md#jshandlegetpropertypropertyname)
|
||||
- [jsHandle.jsonValue()](api/class-jshandle.md#jshandlejsonvalue)
|
||||
|
||||
## elementHandle.$(selector)
|
||||
- `selector` <[string]> A selector to query for. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- returns: <[Promise]<[null]|[ElementHandle]>>
|
||||
|
||||
The method finds an element matching the specified selector in the `ElementHandle`'s subtree. See [Working with selectors](./selectors.md#working-with-selectors) for more details. If no elements match the selector, returns `null`.
|
||||
|
||||
## elementHandle.$$(selector)
|
||||
- `selector` <[string]> A selector to query for. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- returns: <[Promise]<[Array]<[ElementHandle]>>>
|
||||
|
||||
The method finds all elements matching the specified selector in the `ElementHandle`s subtree. See [Working with selectors](./selectors.md#working-with-selectors) for more details. If no elements match the selector, returns empty array.
|
||||
|
||||
## elementHandle.$eval(selector, pageFunction[, arg])
|
||||
- `selector` <[string]> A selector to query for. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `pageFunction` <[function]\([Element]\)> Function to be evaluated in browser context
|
||||
- `arg` <[EvaluationArgument]> Optional argument to pass to `pageFunction`
|
||||
- returns: <[Promise]<[Serializable]>>
|
||||
|
||||
Returns the return value of `pageFunction`
|
||||
|
||||
The method finds an element matching the specified selector in the `ElementHandle`s subtree and passes it as a first argument to `pageFunction`. See [Working with selectors](./selectors.md#working-with-selectors) for more details. If no elements match the 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:
|
||||
|
||||
```js
|
||||
const tweetHandle = await page.$('.tweet');
|
||||
expect(await tweetHandle.$eval('.like', node => node.innerText)).toBe('100');
|
||||
expect(await tweetHandle.$eval('.retweets', node => node.innerText)).toBe('10');
|
||||
```
|
||||
|
||||
## elementHandle.$$eval(selector, pageFunction[, arg])
|
||||
- `selector` <[string]> A selector to query for. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `pageFunction` <[function]\([Array]<[Element]>\)> Function to be evaluated in browser context
|
||||
- `arg` <[EvaluationArgument]> Optional argument to pass to `pageFunction`
|
||||
- returns: <[Promise]<[Serializable]>>
|
||||
|
||||
Returns the return value of `pageFunction`
|
||||
|
||||
The method finds all elements matching the specified selector in the `ElementHandle`'s subtree and passes an array of matched elements as a first argument to `pageFunction`. See [Working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
|
||||
If `pageFunction` returns a [Promise], then `frame.$$eval` would wait for the promise to resolve and return its value.
|
||||
|
||||
Examples:
|
||||
|
||||
```html
|
||||
<div class="feed">
|
||||
<div class="tweet">Hello!</div>
|
||||
<div class="tweet">Hi!</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
```js
|
||||
const feedHandle = await page.$('.feed');
|
||||
expect(await feedHandle.$$eval('.tweet', nodes => nodes.map(n => n.innerText))).toEqual(['Hello!', 'Hi!']);
|
||||
```
|
||||
|
||||
## elementHandle.boundingBox()
|
||||
- returns: <[Promise]<[null]|[Object]>>
|
||||
- `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.
|
||||
|
||||
This method returns the bounding box of the element, or `null` if the element is not visible. The bounding box is calculated relative to the main frame viewport - which is usually the same as the browser window.
|
||||
|
||||
Scrolling affects the returned bonding box, similarly to [Element.getBoundingClientRect](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect). That means `x` and/or `y` may be negative.
|
||||
|
||||
Elements from child frames return the bounding box relative to the main frame, unlike the [Element.getBoundingClientRect](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
|
||||
|
||||
Assuming the page is static, it is safe to use bounding box coordinates to perform input. For example, the following snippet should click the center of the element.
|
||||
|
||||
```js
|
||||
const box = await elementHandle.boundingBox();
|
||||
await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);
|
||||
```
|
||||
|
||||
## elementHandle.check([options])
|
||||
- `options` <[Object]>
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
This method checks the element by performing the following steps:
|
||||
1. Ensure that element is a checkbox or a radio input. If not, this method rejects. If the element is already checked, this method returns immediately.
|
||||
1. Wait for [actionability](./actionability.md) checks on the element, unless `force` option is set.
|
||||
1. Scroll the element into view if needed.
|
||||
1. Use [page.mouse](api/class-page.md#pagemouse) to click in the center of the element.
|
||||
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
||||
1. Ensure that the element is now checked. If not, this method rejects.
|
||||
|
||||
If the element is detached from the DOM at any moment during the action, this method rejects.
|
||||
|
||||
When all steps combined have not finished during the specified `timeout`, this method rejects with a [TimeoutError]. Passing zero timeout disables this.
|
||||
|
||||
## elementHandle.click([options])
|
||||
- `options` <[Object]>
|
||||
- `button` <"left"|"right"|"middle"> Defaults to `left`.
|
||||
- `clickCount` <[number]> defaults to 1. See [UIEvent.detail].
|
||||
- `delay` <[number]> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `modifiers` <[Array]<"Alt"|"Control"|"Meta"|"Shift">> Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `position` <[Object]> A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
|
||||
- `x` <[number]>
|
||||
- `y` <[number]>
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
This method clicks the element by performing the following steps:
|
||||
1. Wait for [actionability](./actionability.md) checks on the element, unless `force` option is set.
|
||||
1. Scroll the element into view if needed.
|
||||
1. Use [page.mouse](api/class-page.md#pagemouse) to click in the center of the element, or the specified `position`.
|
||||
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
||||
|
||||
If the element is detached from the DOM at any moment during the action, this method rejects.
|
||||
|
||||
When all steps combined have not finished during the specified `timeout`, this method rejects with a [TimeoutError]. Passing zero timeout disables this.
|
||||
|
||||
## elementHandle.contentFrame()
|
||||
- returns: <[Promise]<[null]|[Frame]>>
|
||||
|
||||
Returns the content frame for element handles referencing iframe nodes, or `null` otherwise
|
||||
|
||||
## elementHandle.dblclick([options])
|
||||
- `options` <[Object]>
|
||||
- `button` <"left"|"right"|"middle"> Defaults to `left`.
|
||||
- `delay` <[number]> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `modifiers` <[Array]<"Alt"|"Control"|"Meta"|"Shift">> Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `position` <[Object]> A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
|
||||
- `x` <[number]>
|
||||
- `y` <[number]>
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
This method double clicks the element by performing the following steps:
|
||||
1. Wait for [actionability](./actionability.md) checks on the element, unless `force` option is set.
|
||||
1. Scroll the element into view if needed.
|
||||
1. Use [page.mouse](api/class-page.md#pagemouse) to double click in the center of the element, or the specified `position`.
|
||||
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. Note that if the first click of the `dblclick()` triggers a navigation event, this method will reject.
|
||||
|
||||
If the element is detached from the DOM at any moment during the action, this method rejects.
|
||||
|
||||
When all steps combined have not finished during the specified `timeout`, this method rejects with a [TimeoutError]. Passing zero timeout disables this.
|
||||
|
||||
> **NOTE** `elementHandle.dblclick()` dispatches two `click` events and a single `dblclick` event.
|
||||
|
||||
## elementHandle.dispatchEvent(type[, eventInit])
|
||||
- `type` <[string]> DOM event type: `"click"`, `"dragstart"`, etc.
|
||||
- `eventInit` <[EvaluationArgument]> Optional event-specific initialization properties.
|
||||
- returns: <[Promise]>
|
||||
|
||||
The snippet below dispatches the `click` event on the element. Regardless of the visibility state of the elment, `click` is dispatched. This is equivalend to calling [element.click()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click).
|
||||
|
||||
```js
|
||||
await elementHandle.dispatchEvent('click');
|
||||
```
|
||||
|
||||
Under the hood, it creates an instance of an event based on the given `type`, initializes it with `eventInit` properties and dispatches it on the element. Events are `composed`, `cancelable` and bubble by default.
|
||||
|
||||
Since `eventInit` is event-specific, please refer to the events documentation for the lists of initial properties:
|
||||
* [DragEvent](https://developer.mozilla.org/en-US/docs/Web/API/DragEvent/DragEvent)
|
||||
* [FocusEvent](https://developer.mozilla.org/en-US/docs/Web/API/FocusEvent/FocusEvent)
|
||||
* [KeyboardEvent](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/KeyboardEvent)
|
||||
* [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/MouseEvent)
|
||||
* [PointerEvent](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/PointerEvent)
|
||||
* [TouchEvent](https://developer.mozilla.org/en-US/docs/Web/API/TouchEvent/TouchEvent)
|
||||
* [Event](https://developer.mozilla.org/en-US/docs/Web/API/Event/Event)
|
||||
|
||||
You can also specify `JSHandle` as the property value if you want live objects to be passed into the event:
|
||||
|
||||
```js
|
||||
// Note you can only create DataTransfer in Chromium and Firefox
|
||||
const dataTransfer = await page.evaluateHandle(() => new DataTransfer());
|
||||
await elementHandle.dispatchEvent('dragstart', { dataTransfer });
|
||||
```
|
||||
|
||||
## elementHandle.fill(value[, options])
|
||||
- `value` <[string]> Value to set for the `<input>`, `<textarea>` or `[contenteditable]` element.
|
||||
- `options` <[Object]>
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
This method waits for [actionability](./actionability.md) checks, focuses the element, fills it and triggers an `input` event after filling. If the element is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an error. Note that you can pass an empty string to clear the input field.
|
||||
|
||||
## elementHandle.focus()
|
||||
- returns: <[Promise]>
|
||||
|
||||
Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element.
|
||||
|
||||
## elementHandle.getAttribute(name)
|
||||
- `name` <[string]> Attribute name to get the value for.
|
||||
- returns: <[Promise]<[null]|[string]>>
|
||||
|
||||
Returns element attribute value.
|
||||
|
||||
## elementHandle.hover([options])
|
||||
- `options` <[Object]>
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `modifiers` <[Array]<"Alt"|"Control"|"Meta"|"Shift">> Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
|
||||
- `position` <[Object]> A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
|
||||
- `x` <[number]>
|
||||
- `y` <[number]>
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
This method hovers over the element by performing the following steps:
|
||||
1. Wait for [actionability](./actionability.md) checks on the element, unless `force` option is set.
|
||||
1. Scroll the element into view if needed.
|
||||
1. Use [page.mouse](api/class-page.md#pagemouse) to hover over the center of the element, or the specified `position`.
|
||||
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
||||
|
||||
If the element is detached from the DOM at any moment during the action, this method rejects.
|
||||
|
||||
When all steps combined have not finished during the specified `timeout`, this method rejects with a [TimeoutError]. Passing zero timeout disables this.
|
||||
|
||||
## elementHandle.innerHTML()
|
||||
- returns: <[Promise]<[string]>>
|
||||
|
||||
Returns the `element.innerHTML`.
|
||||
|
||||
## elementHandle.innerText()
|
||||
- returns: <[Promise]<[string]>>
|
||||
|
||||
Returns the `element.innerText`.
|
||||
|
||||
## elementHandle.ownerFrame()
|
||||
- returns: <[Promise]<[null]|[Frame]>>
|
||||
|
||||
Returns the frame containing the given element.
|
||||
|
||||
## elementHandle.press(key[, options])
|
||||
- `key` <[string]> Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.
|
||||
- `options` <[Object]>
|
||||
- `delay` <[number]> Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Focuses the element, and then uses [keyboard.down(key)](api/class-keyboard.md#keyboarddownkey) and [keyboard.up(key)](api/class-keyboard.md#keyboardupkey).
|
||||
|
||||
`key` can specify the intended [keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) value or a single character to generate the text for. A superset of the `key` values can be found [here](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values). Examples of the keys are:
|
||||
|
||||
`F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`, `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.
|
||||
|
||||
Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`.
|
||||
|
||||
Holding down `Shift` will type the text that corresponds to the `key` in the upper case.
|
||||
|
||||
If `key` is a single character, it is case-sensitive, so the values `a` and `A` will generate different respective texts.
|
||||
|
||||
Shortcuts such as `key: "Control+o"` or `key: "Control+Shift+T"` are supported as well. When speficied with the modifier, modifier is pressed and being held while the subsequent key is being pressed.
|
||||
|
||||
## elementHandle.screenshot([options])
|
||||
- `options` <[Object]>
|
||||
- `omitBackground` <[boolean]> Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images. Defaults to `false`.
|
||||
- `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 the current working directory. If no path is provided, the image won't be saved to the disk.
|
||||
- `quality` <[number]> The quality of the image, between 0-100. Not applicable to `png` images.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- `type` <"png"|"jpeg"> Specify screenshot type, defaults to `png`.
|
||||
- returns: <[Promise]<[Buffer]>>
|
||||
|
||||
Returns the buffer with the captured screenshot.
|
||||
|
||||
This method waits for the [actionability](./actionability.md) checks, then scrolls element into view before taking a screenshot. If the element is detached from DOM, the method throws an error.
|
||||
|
||||
## elementHandle.scrollIntoViewIfNeeded([options])
|
||||
- `options` <[Object]>
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
This method waits for [actionability](./actionability.md) checks, then tries to scroll element into view, unless it is completely visible as defined by [IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)'s ```ratio```.
|
||||
|
||||
Throws when `elementHandle` does not point to an element [connected](https://developer.mozilla.org/en-US/docs/Web/API/Node/isConnected) to a Document or a ShadowRoot.
|
||||
|
||||
## elementHandle.selectOption(values[, options])
|
||||
- `values` <[null]|[string]|[ElementHandle]|[Array]<[string]>|[Object]|[Array]<[ElementHandle]>|[Array]<[Object]>> Options to select. If the `<select>` has the `multiple` attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are equivalent to `{value:'string'}`. Option is considered matching if all specified properties match.
|
||||
- `value` <[string]> Matches by `option.value`. Optional.
|
||||
- `label` <[string]> Matches by `option.label`. Optional.
|
||||
- `index` <[number]> Matches by the index. Optional.
|
||||
- `options` <[Object]>
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]<[Array]<[string]>>>
|
||||
|
||||
Returns the array of option values that have been successfully selected.
|
||||
|
||||
Triggers a `change` and `input` event once all the provided options have been selected. If element is not a `<select>` element, the method throws an error.
|
||||
|
||||
```js
|
||||
// single selection matching the value
|
||||
handle.selectOption('blue');
|
||||
|
||||
// single selection matching both the value and the label
|
||||
handle.selectOption({ label: 'Blue' });
|
||||
|
||||
// multiple selection
|
||||
handle.selectOption('red', 'green', 'blue');
|
||||
|
||||
// multiple selection for blue, red and second option
|
||||
handle.selectOption({ value: 'blue' }, { index: 2 }, 'red');
|
||||
```
|
||||
|
||||
## elementHandle.selectText([options])
|
||||
- `options` <[Object]>
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
This method waits for [actionability](./actionability.md) checks, then focuses the element and selects all its text content.
|
||||
|
||||
## elementHandle.setInputFiles(files[, options])
|
||||
- `files` <[string]|[Array]<[string]>|[Object]|[Array]<[Object]>>
|
||||
- `name` <[string]> [File] name **required**
|
||||
- `mimeType` <[string]> [File] type **required**
|
||||
- `buffer` <[Buffer]> File content **required**
|
||||
- `options` <[Object]>
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
This method expects `elementHandle` to point to an [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
|
||||
|
||||
Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they are resolved relative to the the current working directory. For empty array, clears the selected files.
|
||||
|
||||
## elementHandle.tap([options])
|
||||
- `options` <[Object]>
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `modifiers` <[Array]<"Alt"|"Control"|"Meta"|"Shift">> Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `position` <[Object]> A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
|
||||
- `x` <[number]>
|
||||
- `y` <[number]>
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
This method taps the element by performing the following steps:
|
||||
1. Wait for [actionability](./actionability.md) checks on the element, unless `force` option is set.
|
||||
1. Scroll the element into view if needed.
|
||||
1. Use [page.touchscreen](api/class-page.md#pagetouchscreen) to tap the center of the element, or the specified `position`.
|
||||
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
||||
|
||||
If the element is detached from the DOM at any moment during the action, this method rejects.
|
||||
|
||||
When all steps combined have not finished during the specified `timeout`, this method rejects with a [TimeoutError]. Passing zero timeout disables this.
|
||||
|
||||
> **NOTE** `elementHandle.tap()` requires that the `hasTouch` option of the browser context be set to true.
|
||||
|
||||
## elementHandle.textContent()
|
||||
- returns: <[Promise]<[null]|[string]>>
|
||||
|
||||
Returns the `node.textContent`.
|
||||
|
||||
## elementHandle.type(text[, options])
|
||||
- `text` <[string]> A text to type into a focused element.
|
||||
- `options` <[Object]>
|
||||
- `delay` <[number]> Time to wait between key presses in milliseconds. Defaults to 0.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- 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(key[, options])](api/class-elementhandle.md#elementhandlepresskey-options).
|
||||
|
||||
```js
|
||||
await elementHandle.type('Hello'); // Types instantly
|
||||
await elementHandle.type('World', {delay: 100}); // Types slower, like a user
|
||||
```
|
||||
|
||||
An example of typing into a text field and then submitting the form:
|
||||
|
||||
```js
|
||||
const elementHandle = await page.$('input');
|
||||
await elementHandle.type('some text');
|
||||
await elementHandle.press('Enter');
|
||||
```
|
||||
|
||||
## elementHandle.uncheck([options])
|
||||
- `options` <[Object]>
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
This method checks the element by performing the following steps:
|
||||
1. Ensure that element is a checkbox or a radio input. If not, this method rejects. If the element is already unchecked, this method returns immediately.
|
||||
1. Wait for [actionability](./actionability.md) checks on the element, unless `force` option is set.
|
||||
1. Scroll the element into view if needed.
|
||||
1. Use [page.mouse](api/class-page.md#pagemouse) to click in the center of the element.
|
||||
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
||||
1. Ensure that the element is now unchecked. If not, this method rejects.
|
||||
|
||||
If the element is detached from the DOM at any moment during the action, this method rejects.
|
||||
|
||||
When all steps combined have not finished during the specified `timeout`, this method rejects with a [TimeoutError]. Passing zero timeout disables this.
|
||||
|
||||
## elementHandle.waitForElementState(state[, options])
|
||||
- `state` <"visible"|"hidden"|"stable"|"enabled"|"disabled"> A state to wait for, see below for more details.
|
||||
- `options` <[Object]>
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Returns when the element satisfies the `state`.
|
||||
|
||||
Depending on the `state` parameter, this method waits for one of the [actionability](./actionability.md) checks to pass. This method throws when the element is detached while waiting, unless waiting for the `"hidden"` state.
|
||||
* `"visible"` Wait until the element is [visible](./actionability.md#visible).
|
||||
* `"hidden"` Wait until the element is [not visible](./actionability.md#visible) or [not attached](./actionability.md#attached). Note that waiting for hidden does not throw when the element detaches.
|
||||
* `"stable"` Wait until the element is both [visible](./actionability.md#visible) and [stable](./actionability.md#stable).
|
||||
* `"enabled"` Wait until the element is [enabled](./actionability.md#enabled).
|
||||
* `"disabled"` Wait until the element is [not enabled](./actionability.md#enabled).
|
||||
|
||||
If the element does not satisfy the condition for the `timeout` milliseconds, this method will throw.
|
||||
|
||||
## elementHandle.waitForSelector(selector[, options])
|
||||
- `selector` <[string]> A selector to query for. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `options` <[Object]>
|
||||
- `state` <"attached"|"detached"|"visible"|"hidden"> Defaults to `'visible'`. Can be either:
|
||||
* `'attached'` - wait for element to be present in DOM.
|
||||
* `'detached'` - wait for element to not be present in DOM.
|
||||
* `'visible'` - wait for element to have non-empty bounding box and no `visibility:hidden`. Note that element without any content or with `display:none` has an empty bounding box and is not considered visible.
|
||||
* `'hidden'` - wait for element to be either detached from DOM, or have an empty bounding box or `visibility:hidden`. This is opposite to the `'visible'` option.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]<[null]|[ElementHandle]>>
|
||||
|
||||
Returns element specified by selector when it satisfies `state` option. Returns `null` if waiting for `hidden` or `detached`.
|
||||
|
||||
Wait for the `selector` relative to the element handle to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If at the moment of calling the method `selector` already satisfies the condition, the method will return immediately. If the selector doesn't satisfy the condition for the `timeout` milliseconds, the function will throw.
|
||||
|
||||
```js
|
||||
await page.setContent(`<div><span></span></div>`);
|
||||
const div = await page.$('div');
|
||||
// Waiting for the 'span' selector relative to the div.
|
||||
const span = await div.waitForSelector('span', { state: 'attached' });
|
||||
```
|
||||
|
||||
> **NOTE** This method does not work across navigations, use [page.waitForSelector(selector[, options])](api/class-page.md#pagewaitforselectorselector-options) instead.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,104 +0,0 @@
|
|||
---
|
||||
id: class-filechooser
|
||||
title: "FileChooser"
|
||||
---
|
||||
|
||||
|
||||
[FileChooser] objects are dispatched by the page in the [page.on('filechooser')](api/class-page.md#pageonfilechooser) event.
|
||||
|
||||
```js
|
||||
page.on('filechooser', async (fileChooser) => {
|
||||
await fileChooser.setFiles('/tmp/myfile.pdf');
|
||||
});
|
||||
```
|
||||
|
||||
|
||||
- [fileChooser.element()](api/class-filechooser.md#filechooserelement)
|
||||
- [fileChooser.isMultiple()](api/class-filechooser.md#filechooserismultiple)
|
||||
- [fileChooser.page()](api/class-filechooser.md#filechooserpage)
|
||||
- [fileChooser.setFiles(files[, options])](api/class-filechooser.md#filechoosersetfilesfiles-options)
|
||||
|
||||
## fileChooser.element()
|
||||
- returns: <[ElementHandle]>
|
||||
|
||||
Returns input element associated with this file chooser.
|
||||
|
||||
## fileChooser.isMultiple()
|
||||
- returns: <[boolean]>
|
||||
|
||||
Returns whether this file chooser accepts multiple files.
|
||||
|
||||
## fileChooser.page()
|
||||
- returns: <[Page]>
|
||||
|
||||
Returns page this file chooser belongs to.
|
||||
|
||||
## fileChooser.setFiles(files[, options])
|
||||
- `files` <[string]|[Array]<[string]>|[Object]|[Array]<[Object]>>
|
||||
- `name` <[string]> [File] name **required**
|
||||
- `mimeType` <[string]> [File] type **required**
|
||||
- `buffer` <[Buffer]> File content **required**
|
||||
- `options` <[Object]>
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Sets the value of the file input this chooser is associated with. If some of the `filePaths` are relative paths, then they are resolved relative to the the current working directory. For empty array, clears the selected files.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,75 +0,0 @@
|
|||
---
|
||||
id: class-firefoxbrowser
|
||||
title: "FirefoxBrowser"
|
||||
---
|
||||
|
||||
* extends: [Browser]
|
||||
|
||||
Firefox browser instance does not expose Firefox-specific features.
|
||||
|
||||
|
||||
- [browser.on('disconnected')](api/class-browser.md#browserondisconnected)
|
||||
- [browser.close()](api/class-browser.md#browserclose)
|
||||
- [browser.contexts()](api/class-browser.md#browsercontexts)
|
||||
- [browser.isConnected()](api/class-browser.md#browserisconnected)
|
||||
- [browser.newContext([options])](api/class-browser.md#browsernewcontextoptions)
|
||||
- [browser.newPage([options])](api/class-browser.md#browsernewpageoptions)
|
||||
- [browser.version()](api/class-browser.md#browserversion)
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,785 +0,0 @@
|
|||
---
|
||||
id: class-frame
|
||||
title: "Frame"
|
||||
---
|
||||
|
||||
|
||||
At every point of time, page exposes its current frame tree via the [page.mainFrame()](api/class-page.md#pagemainframe) and [frame.childFrames()](api/class-frame.md#framechildframes) methods.
|
||||
|
||||
[Frame] object's lifecycle is controlled by three events, dispatched on the page object:
|
||||
* [page.on('frameattached')](api/class-page.md#pageonframeattached) - fired when the frame gets attached to the page. A Frame can be attached to the page only once.
|
||||
* [page.on('framenavigated')](api/class-page.md#pageonframenavigated) - fired when the frame commits navigation to a different URL.
|
||||
* [page.on('framedetached')](api/class-page.md#pageonframedetached) - fired when the frame gets detached from the page. A Frame can be detached from the page only once.
|
||||
|
||||
An example of dumping frame tree:
|
||||
|
||||
```js
|
||||
const { firefox } = require('playwright'); // Or 'chromium' or 'webkit'.
|
||||
|
||||
(async () => {
|
||||
const browser = await firefox.launch();
|
||||
const page = await browser.newPage();
|
||||
await page.goto('https://www.google.com/chrome/browser/canary.html');
|
||||
dumpFrameTree(page.mainFrame(), '');
|
||||
await browser.close();
|
||||
|
||||
function dumpFrameTree(frame, indent) {
|
||||
console.log(indent + frame.url());
|
||||
for (const child of frame.childFrames()) {
|
||||
dumpFrameTree(child, indent + ' ');
|
||||
}
|
||||
}
|
||||
})();
|
||||
```
|
||||
|
||||
An example of getting text from an iframe element:
|
||||
|
||||
```js
|
||||
const frame = page.frames().find(frame => frame.name() === 'myframe');
|
||||
const text = await frame.$eval('.selector', element => element.textContent);
|
||||
console.log(text);
|
||||
```
|
||||
|
||||
|
||||
- [frame.$(selector)](api/class-frame.md#frameselector)
|
||||
- [frame.$$(selector)](api/class-frame.md#frameselector-1)
|
||||
- [frame.$eval(selector, pageFunction[, arg])](api/class-frame.md#frameevalselector-pagefunction-arg)
|
||||
- [frame.$$eval(selector, pageFunction[, arg])](api/class-frame.md#frameevalselector-pagefunction-arg-1)
|
||||
- [frame.addScriptTag(params)](api/class-frame.md#frameaddscripttagparams)
|
||||
- [frame.addStyleTag(params)](api/class-frame.md#frameaddstyletagparams)
|
||||
- [frame.check(selector[, options])](api/class-frame.md#framecheckselector-options)
|
||||
- [frame.childFrames()](api/class-frame.md#framechildframes)
|
||||
- [frame.click(selector[, options])](api/class-frame.md#frameclickselector-options)
|
||||
- [frame.content()](api/class-frame.md#framecontent)
|
||||
- [frame.dblclick(selector[, options])](api/class-frame.md#framedblclickselector-options)
|
||||
- [frame.dispatchEvent(selector, type[, eventInit, options])](api/class-frame.md#framedispatcheventselector-type-eventinit-options)
|
||||
- [frame.evaluate(pageFunction[, arg])](api/class-frame.md#frameevaluatepagefunction-arg)
|
||||
- [frame.evaluateHandle(pageFunction[, arg])](api/class-frame.md#frameevaluatehandlepagefunction-arg)
|
||||
- [frame.fill(selector, value[, options])](api/class-frame.md#framefillselector-value-options)
|
||||
- [frame.focus(selector[, options])](api/class-frame.md#framefocusselector-options)
|
||||
- [frame.frameElement()](api/class-frame.md#frameframeelement)
|
||||
- [frame.getAttribute(selector, name[, options])](api/class-frame.md#framegetattributeselector-name-options)
|
||||
- [frame.goto(url[, options])](api/class-frame.md#framegotourl-options)
|
||||
- [frame.hover(selector[, options])](api/class-frame.md#framehoverselector-options)
|
||||
- [frame.innerHTML(selector[, options])](api/class-frame.md#frameinnerhtmlselector-options)
|
||||
- [frame.innerText(selector[, options])](api/class-frame.md#frameinnertextselector-options)
|
||||
- [frame.isDetached()](api/class-frame.md#frameisdetached)
|
||||
- [frame.name()](api/class-frame.md#framename)
|
||||
- [frame.page()](api/class-frame.md#framepage)
|
||||
- [frame.parentFrame()](api/class-frame.md#frameparentframe)
|
||||
- [frame.press(selector, key[, options])](api/class-frame.md#framepressselector-key-options)
|
||||
- [frame.selectOption(selector, values[, options])](api/class-frame.md#frameselectoptionselector-values-options)
|
||||
- [frame.setContent(html[, options])](api/class-frame.md#framesetcontenthtml-options)
|
||||
- [frame.setInputFiles(selector, files[, options])](api/class-frame.md#framesetinputfilesselector-files-options)
|
||||
- [frame.tap(selector[, options])](api/class-frame.md#frametapselector-options)
|
||||
- [frame.textContent(selector[, options])](api/class-frame.md#frametextcontentselector-options)
|
||||
- [frame.title()](api/class-frame.md#frametitle)
|
||||
- [frame.type(selector, text[, options])](api/class-frame.md#frametypeselector-text-options)
|
||||
- [frame.uncheck(selector[, options])](api/class-frame.md#frameuncheckselector-options)
|
||||
- [frame.url()](api/class-frame.md#frameurl)
|
||||
- [frame.waitForFunction(pageFunction[, arg, options])](api/class-frame.md#framewaitforfunctionpagefunction-arg-options)
|
||||
- [frame.waitForLoadState([state, options])](api/class-frame.md#framewaitforloadstatestate-options)
|
||||
- [frame.waitForNavigation([options])](api/class-frame.md#framewaitfornavigationoptions)
|
||||
- [frame.waitForSelector(selector[, options])](api/class-frame.md#framewaitforselectorselector-options)
|
||||
- [frame.waitForTimeout(timeout)](api/class-frame.md#framewaitfortimeouttimeout)
|
||||
|
||||
## frame.$(selector)
|
||||
- `selector` <[string]> A selector to query for. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- returns: <[Promise]<[null]|[ElementHandle]>>
|
||||
|
||||
Returns the ElementHandle pointing to the frame element.
|
||||
|
||||
The method finds an element matching the specified selector within the frame. See [Working with selectors](./selectors.md#working-with-selectors) for more details. If no elements match the selector, returns `null`.
|
||||
|
||||
## frame.$$(selector)
|
||||
- `selector` <[string]> A selector to query for. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- returns: <[Promise]<[Array]<[ElementHandle]>>>
|
||||
|
||||
Returns the ElementHandles pointing to the frame elements.
|
||||
|
||||
The method finds all elements matching the specified selector within the frame. See [Working with selectors](./selectors.md#working-with-selectors) for more details. If no elements match the selector, returns empty array.
|
||||
|
||||
## frame.$eval(selector, pageFunction[, arg])
|
||||
- `selector` <[string]> A selector to query for. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `pageFunction` <[function]\([Element]\)> Function to be evaluated in browser context
|
||||
- `arg` <[EvaluationArgument]> Optional argument to pass to `pageFunction`
|
||||
- returns: <[Promise]<[Serializable]>>
|
||||
|
||||
Returns the return value of `pageFunction`
|
||||
|
||||
The method finds an element matching the specified selector within the frame and passes it as a first argument to `pageFunction`. See [Working with selectors](./selectors.md#working-with-selectors) for more details. If no elements match the 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:
|
||||
|
||||
```js
|
||||
const searchValue = await frame.$eval('#search', el => el.value);
|
||||
const preloadHref = await frame.$eval('link[rel=preload]', el => el.href);
|
||||
const html = await frame.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello');
|
||||
```
|
||||
|
||||
## frame.$$eval(selector, pageFunction[, arg])
|
||||
- `selector` <[string]> A selector to query for. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `pageFunction` <[function]\([Array]<[Element]>\)> Function to be evaluated in browser context
|
||||
- `arg` <[EvaluationArgument]> Optional argument to pass to `pageFunction`
|
||||
- returns: <[Promise]<[Serializable]>>
|
||||
|
||||
Returns the return value of `pageFunction`
|
||||
|
||||
The method finds all elements matching the specified selector within the frame and passes an array of matched elements as a first argument to `pageFunction`. See [Working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
|
||||
If `pageFunction` returns a [Promise], then `frame.$$eval` would wait for the promise to resolve and return its value.
|
||||
|
||||
Examples:
|
||||
|
||||
```js
|
||||
const divsCounts = await frame.$$eval('div', (divs, min) => divs.length >= min, 10);
|
||||
```
|
||||
|
||||
## frame.addScriptTag(params)
|
||||
- `params` <[Object]>
|
||||
- `url` <[string]> URL of a script to be added. Optional.
|
||||
- `path` <[string]> Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative to the current working directory. Optional.
|
||||
- `content` <[string]> Raw JavaScript content to be injected into frame. Optional.
|
||||
- `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. Optional.
|
||||
- returns: <[Promise]<[ElementHandle]>>
|
||||
|
||||
Returns the added tag when the script's onload fires or when the script content was injected into frame.
|
||||
|
||||
Adds a `<script>` tag into the page with the desired url or content.
|
||||
|
||||
## frame.addStyleTag(params)
|
||||
- `params` <[Object]>
|
||||
- `url` <[string]> URL of the `<link>` tag. Optional.
|
||||
- `path` <[string]> Path to the CSS file to be injected into frame. If `path` is a relative path, then it is resolved relative to the current working directory. Optional.
|
||||
- `content` <[string]> Raw CSS content to be injected into frame. Optional.
|
||||
- returns: <[Promise]<[ElementHandle]>>
|
||||
|
||||
Returns the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.
|
||||
|
||||
Adds a `<link rel="stylesheet">` tag into the page with the desired url or a `<style type="text/css">` tag with the content.
|
||||
|
||||
## frame.check(selector[, options])
|
||||
- `selector` <[string]> A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `options` <[Object]>
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
This method checks an element matching `selector` by performing the following steps:
|
||||
1. Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM.
|
||||
1. Ensure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already checked, this method returns immediately.
|
||||
1. Wait for [actionability](./actionability.md) checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried.
|
||||
1. Scroll the element into view if needed.
|
||||
1. Use [page.mouse](api/class-page.md#pagemouse) to click in the center of the element.
|
||||
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
||||
1. Ensure that the element is now checked. If not, this method rejects.
|
||||
|
||||
When all steps combined have not finished during the specified `timeout`, this method rejects with a [TimeoutError]. Passing zero timeout disables this.
|
||||
|
||||
## frame.childFrames()
|
||||
- returns: <[Array]<[Frame]>>
|
||||
|
||||
## frame.click(selector[, options])
|
||||
- `selector` <[string]> A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `options` <[Object]>
|
||||
- `button` <"left"|"right"|"middle"> Defaults to `left`.
|
||||
- `clickCount` <[number]> defaults to 1. See [UIEvent.detail].
|
||||
- `delay` <[number]> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `modifiers` <[Array]<"Alt"|"Control"|"Meta"|"Shift">> Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `position` <[Object]> A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
|
||||
- `x` <[number]>
|
||||
- `y` <[number]>
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
This method clicks an element matching `selector` by performing the following steps:
|
||||
1. Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM.
|
||||
1. Wait for [actionability](./actionability.md) checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried.
|
||||
1. Scroll the element into view if needed.
|
||||
1. Use [page.mouse](api/class-page.md#pagemouse) to click in the center of the element, or the specified `position`.
|
||||
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
||||
|
||||
When all steps combined have not finished during the specified `timeout`, this method rejects with a [TimeoutError]. Passing zero timeout disables this.
|
||||
|
||||
## frame.content()
|
||||
- returns: <[Promise]<[string]>>
|
||||
|
||||
Gets the full HTML contents of the frame, including the doctype.
|
||||
|
||||
## frame.dblclick(selector[, options])
|
||||
- `selector` <[string]> A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `options` <[Object]>
|
||||
- `button` <"left"|"right"|"middle"> Defaults to `left`.
|
||||
- `delay` <[number]> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `modifiers` <[Array]<"Alt"|"Control"|"Meta"|"Shift">> Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `position` <[Object]> A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
|
||||
- `x` <[number]>
|
||||
- `y` <[number]>
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
This method double clicks an element matching `selector` by performing the following steps:
|
||||
1. Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM.
|
||||
1. Wait for [actionability](./actionability.md) checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried.
|
||||
1. Scroll the element into view if needed.
|
||||
1. Use [page.mouse](api/class-page.md#pagemouse) to double click in the center of the element, or the specified `position`.
|
||||
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. Note that if the first click of the `dblclick()` triggers a navigation event, this method will reject.
|
||||
|
||||
When all steps combined have not finished during the specified `timeout`, this method rejects with a [TimeoutError]. Passing zero timeout disables this.
|
||||
|
||||
> **NOTE** `frame.dblclick()` dispatches two `click` events and a single `dblclick` event.
|
||||
|
||||
## frame.dispatchEvent(selector, type[, eventInit, options])
|
||||
- `selector` <[string]> A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `type` <[string]> DOM event type: `"click"`, `"dragstart"`, etc.
|
||||
- `eventInit` <[EvaluationArgument]> Optional event-specific initialization properties.
|
||||
- `options` <[Object]>
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
The snippet below dispatches the `click` event on the element. Regardless of the visibility state of the elment, `click` is dispatched. This is equivalend to calling [element.click()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click).
|
||||
|
||||
```js
|
||||
await frame.dispatchEvent('button#submit', 'click');
|
||||
```
|
||||
|
||||
Under the hood, it creates an instance of an event based on the given `type`, initializes it with `eventInit` properties and dispatches it on the element. Events are `composed`, `cancelable` and bubble by default.
|
||||
|
||||
Since `eventInit` is event-specific, please refer to the events documentation for the lists of initial properties:
|
||||
* [DragEvent](https://developer.mozilla.org/en-US/docs/Web/API/DragEvent/DragEvent)
|
||||
* [FocusEvent](https://developer.mozilla.org/en-US/docs/Web/API/FocusEvent/FocusEvent)
|
||||
* [KeyboardEvent](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/KeyboardEvent)
|
||||
* [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/MouseEvent)
|
||||
* [PointerEvent](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/PointerEvent)
|
||||
* [TouchEvent](https://developer.mozilla.org/en-US/docs/Web/API/TouchEvent/TouchEvent)
|
||||
* [Event](https://developer.mozilla.org/en-US/docs/Web/API/Event/Event)
|
||||
|
||||
You can also specify `JSHandle` as the property value if you want live objects to be passed into the event:
|
||||
|
||||
```js
|
||||
// Note you can only create DataTransfer in Chromium and Firefox
|
||||
const dataTransfer = await frame.evaluateHandle(() => new DataTransfer());
|
||||
await frame.dispatchEvent('#source', 'dragstart', { dataTransfer });
|
||||
```
|
||||
|
||||
## frame.evaluate(pageFunction[, arg])
|
||||
- `pageFunction` <[function]|[string]> Function to be evaluated in browser context
|
||||
- `arg` <[EvaluationArgument]> Optional argument to pass to `pageFunction`
|
||||
- returns: <[Promise]<[Serializable]>>
|
||||
|
||||
Returns the return value of `pageFunction`
|
||||
|
||||
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.
|
||||
|
||||
If the function passed to the `frame.evaluate` returns a non-[Serializable] value, then `frame.evaluate` returns `undefined`. DevTools Protocol also supports transferring some additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals.
|
||||
|
||||
```js
|
||||
const result = await frame.evaluate(([x, y]) => {
|
||||
return Promise.resolve(x * y);
|
||||
}, [7, 8]);
|
||||
console.log(result); // prints "56"
|
||||
```
|
||||
|
||||
A string can also be passed in instead of a function.
|
||||
|
||||
```js
|
||||
console.log(await frame.evaluate('1 + 2')); // prints "3"
|
||||
```
|
||||
|
||||
[ElementHandle] instances can be passed as an argument to the `frame.evaluate`:
|
||||
|
||||
```js
|
||||
const bodyHandle = await frame.$('body');
|
||||
const html = await frame.evaluate(([body, suffix]) => body.innerHTML + suffix, [bodyHandle, 'hello']);
|
||||
await bodyHandle.dispose();
|
||||
```
|
||||
|
||||
## frame.evaluateHandle(pageFunction[, arg])
|
||||
- `pageFunction` <[function]|[string]> Function to be evaluated in the page context
|
||||
- `arg` <[EvaluationArgument]> Optional argument to pass to `pageFunction`
|
||||
- returns: <[Promise]<[JSHandle]>>
|
||||
|
||||
Returns the return value of `pageFunction` as in-page object (JSHandle).
|
||||
|
||||
The only difference between `frame.evaluate` and `frame.evaluateHandle` is that `frame.evaluateHandle` returns in-page object (JSHandle).
|
||||
|
||||
If the function, passed to the `frame.evaluateHandle`, returns a [Promise], then `frame.evaluateHandle` would wait for the promise to resolve and return its value.
|
||||
|
||||
```js
|
||||
const aWindowHandle = await frame.evaluateHandle(() => Promise.resolve(window));
|
||||
aWindowHandle; // Handle for the window object.
|
||||
```
|
||||
|
||||
A string can also be passed in instead of a function.
|
||||
|
||||
```js
|
||||
const aHandle = await frame.evaluateHandle('document'); // Handle for the 'document'.
|
||||
```
|
||||
|
||||
[JSHandle] instances can be passed as an argument to the `frame.evaluateHandle`:
|
||||
|
||||
```js
|
||||
const aHandle = await frame.evaluateHandle(() => document.body);
|
||||
const resultHandle = await frame.evaluateHandle(([body, suffix]) => body.innerHTML + suffix, [aHandle, 'hello']);
|
||||
console.log(await resultHandle.jsonValue());
|
||||
await resultHandle.dispose();
|
||||
```
|
||||
|
||||
## frame.fill(selector, value[, options])
|
||||
- `selector` <[string]> A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `value` <[string]> Value to fill for the `<input>`, `<textarea>` or `[contenteditable]` element.
|
||||
- `options` <[Object]>
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
This method waits for an element matching `selector`, waits for [actionability](./actionability.md) checks, focuses the element, fills it and triggers an `input` event after filling. If the element matching `selector` is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an error. Note that you can pass an empty string to clear the input field.
|
||||
|
||||
To send fine-grained keyboard events, use [frame.type(selector, text[, options])](api/class-frame.md#frametypeselector-text-options).
|
||||
|
||||
## frame.focus(selector[, options])
|
||||
- `selector` <[string]> A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `options` <[Object]>
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
This method fetches an element with `selector` and focuses it. If there's no element matching `selector`, the method waits until a matching element appears in the DOM.
|
||||
|
||||
## frame.frameElement()
|
||||
- returns: <[Promise]<[ElementHandle]>>
|
||||
|
||||
Returns the `frame` or `iframe` element handle which corresponds to this frame.
|
||||
|
||||
This is an inverse of [elementHandle.contentFrame()](api/class-elementhandle.md#elementhandlecontentframe). Note that returned handle actually belongs to the parent frame.
|
||||
|
||||
This method throws an error if the frame has been detached before `frameElement()` returns.
|
||||
|
||||
```js
|
||||
const frameElement = await frame.frameElement();
|
||||
const contentFrame = await frameElement.contentFrame();
|
||||
console.log(frame === contentFrame); // -> true
|
||||
```
|
||||
|
||||
## frame.getAttribute(selector, name[, options])
|
||||
- `selector` <[string]> A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `name` <[string]> Attribute name to get the value for.
|
||||
- `options` <[Object]>
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]<[null]|[string]>>
|
||||
|
||||
Returns element attribute value.
|
||||
|
||||
## frame.goto(url[, options])
|
||||
- `url` <[string]> URL to navigate frame to. The url should include scheme, e.g. `https://`.
|
||||
- `options` <[Object]>
|
||||
- `referer` <[string]> Referer header value. If provided it will take preference over the referer header value set by [page.setExtraHTTPHeaders(headers)](api/class-page.md#pagesetextrahttpheadersheaders).
|
||||
- `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultNavigationTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaultnavigationtimeouttimeout), [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout), [page.setDefaultNavigationTimeout(timeout)](api/class-page.md#pagesetdefaultnavigationtimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- `waitUntil` <"load"|"domcontentloaded"|"networkidle"> When to consider operation succeeded, defaults to `load`. Events can be either:
|
||||
* `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
|
||||
* `'load'` - consider operation to be finished when the `load` event is fired.
|
||||
* `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms.
|
||||
- returns: <[Promise]<[null]|[Response]>>
|
||||
|
||||
Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
|
||||
|
||||
`frame.goto` will throw an error if:
|
||||
* there's an SSL error (e.g. in case of self-signed certificates).
|
||||
* target URL is invalid.
|
||||
* the `timeout` is exceeded during navigation.
|
||||
* the remote server does not respond or is unreachable.
|
||||
* the main resource failed to load.
|
||||
|
||||
`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()](api/class-response.md#responsestatus).
|
||||
|
||||
> **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`.
|
||||
> **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).
|
||||
|
||||
## frame.hover(selector[, options])
|
||||
- `selector` <[string]> A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `options` <[Object]>
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `modifiers` <[Array]<"Alt"|"Control"|"Meta"|"Shift">> Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
|
||||
- `position` <[Object]> A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
|
||||
- `x` <[number]>
|
||||
- `y` <[number]>
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
This method hovers over an element matching `selector` by performing the following steps:
|
||||
1. Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM.
|
||||
1. Wait for [actionability](./actionability.md) checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried.
|
||||
1. Scroll the element into view if needed.
|
||||
1. Use [page.mouse](api/class-page.md#pagemouse) to hover over the center of the element, or the specified `position`.
|
||||
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
||||
|
||||
When all steps combined have not finished during the specified `timeout`, this method rejects with a [TimeoutError]. Passing zero timeout disables this.
|
||||
|
||||
## frame.innerHTML(selector[, options])
|
||||
- `selector` <[string]> A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `options` <[Object]>
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]<[string]>>
|
||||
|
||||
Returns `element.innerHTML`.
|
||||
|
||||
## frame.innerText(selector[, options])
|
||||
- `selector` <[string]> A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `options` <[Object]>
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]<[string]>>
|
||||
|
||||
Returns `element.innerText`.
|
||||
|
||||
## frame.isDetached()
|
||||
- returns: <[boolean]>
|
||||
|
||||
Returns `true` if the frame has been detached, or `false` otherwise.
|
||||
|
||||
## frame.name()
|
||||
- returns: <[string]>
|
||||
|
||||
Returns frame's name attribute as specified in the tag.
|
||||
|
||||
If the name is empty, returns the id attribute instead.
|
||||
|
||||
> **NOTE** This value is calculated once when the frame is created, and will not update if the attribute is changed later.
|
||||
|
||||
## frame.page()
|
||||
- returns: <[Page]>
|
||||
|
||||
Returns the page containing this frame.
|
||||
|
||||
## frame.parentFrame()
|
||||
- returns: <[null]|[Frame]>
|
||||
|
||||
Parent frame, if any. Detached frames and main frames return `null`.
|
||||
|
||||
## frame.press(selector, key[, options])
|
||||
- `selector` <[string]> A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `key` <[string]> Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.
|
||||
- `options` <[Object]>
|
||||
- `delay` <[number]> Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
`key` can specify the intended [keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) value or a single character to generate the text for. A superset of the `key` values can be found [here](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values). Examples of the keys are:
|
||||
|
||||
`F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`, `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.
|
||||
|
||||
Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`.
|
||||
|
||||
Holding down `Shift` will type the text that corresponds to the `key` in the upper case.
|
||||
|
||||
If `key` is a single character, it is case-sensitive, so the values `a` and `A` will generate different respective texts.
|
||||
|
||||
Shortcuts such as `key: "Control+o"` or `key: "Control+Shift+T"` are supported as well. When speficied with the modifier, modifier is pressed and being held while the subsequent key is being pressed.
|
||||
|
||||
## frame.selectOption(selector, values[, options])
|
||||
- `selector` <[string]> A selector to query for. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `values` <[null]|[string]|[ElementHandle]|[Array]<[string]>|[Object]|[Array]<[ElementHandle]>|[Array]<[Object]>> Options to select. If the `<select>` has the `multiple` attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are equivalent to `{value:'string'}`. Option is considered matching if all specified properties match.
|
||||
- `value` <[string]> Matches by `option.value`. Optional.
|
||||
- `label` <[string]> Matches by `option.label`. Optional.
|
||||
- `index` <[number]> Matches by the index. Optional.
|
||||
- `options` <[Object]>
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]<[Array]<[string]>>>
|
||||
|
||||
Returns the 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
|
||||
// single selection matching the value
|
||||
frame.selectOption('select#colors', 'blue');
|
||||
|
||||
// single selection matching both the value and the label
|
||||
frame.selectOption('select#colors', { label: 'Blue' });
|
||||
|
||||
// multiple selection
|
||||
frame.selectOption('select#colors', 'red', 'green', 'blue');
|
||||
```
|
||||
|
||||
## frame.setContent(html[, options])
|
||||
- `html` <[string]> HTML markup to assign to the page.
|
||||
- `options` <[Object]>
|
||||
- `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultNavigationTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaultnavigationtimeouttimeout), [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout), [page.setDefaultNavigationTimeout(timeout)](api/class-page.md#pagesetdefaultnavigationtimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- `waitUntil` <"load"|"domcontentloaded"|"networkidle"> When to consider operation succeeded, defaults to `load`. Events can be either:
|
||||
* `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
|
||||
* `'load'` - consider operation to be finished when the `load` event is fired.
|
||||
* `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms.
|
||||
- returns: <[Promise]>
|
||||
|
||||
## frame.setInputFiles(selector, files[, options])
|
||||
- `selector` <[string]> A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `files` <[string]|[Array]<[string]>|[Object]|[Array]<[Object]>>
|
||||
- `name` <[string]> [File] name **required**
|
||||
- `mimeType` <[string]> [File] type **required**
|
||||
- `buffer` <[Buffer]> File content **required**
|
||||
- `options` <[Object]>
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
This method expects `selector` to point to an [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
|
||||
|
||||
Sets the value of the file input to these file paths or files. If some of the `filePaths` are relative paths, then they are resolved relative to the the current working directory. For empty array, clears the selected files.
|
||||
|
||||
## frame.tap(selector[, options])
|
||||
- `selector` <[string]> A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `options` <[Object]>
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `modifiers` <[Array]<"Alt"|"Control"|"Meta"|"Shift">> Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `position` <[Object]> A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
|
||||
- `x` <[number]>
|
||||
- `y` <[number]>
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
This method taps an element matching `selector` by performing the following steps:
|
||||
1. Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM.
|
||||
1. Wait for [actionability](./actionability.md) checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried.
|
||||
1. Scroll the element into view if needed.
|
||||
1. Use [page.touchscreen](api/class-page.md#pagetouchscreen) to tap the center of the element, or the specified `position`.
|
||||
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
||||
|
||||
When all steps combined have not finished during the specified `timeout`, this method rejects with a [TimeoutError]. Passing zero timeout disables this.
|
||||
|
||||
> **NOTE** `frame.tap()` requires that the `hasTouch` option of the browser context be set to true.
|
||||
|
||||
## frame.textContent(selector[, options])
|
||||
- `selector` <[string]> A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `options` <[Object]>
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]<[null]|[string]>>
|
||||
|
||||
Returns `element.textContent`.
|
||||
|
||||
## frame.title()
|
||||
- returns: <[Promise]<[string]>>
|
||||
|
||||
Returns the page title.
|
||||
|
||||
## frame.type(selector, text[, options])
|
||||
- `selector` <[string]> A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `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.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text. `frame.type` can be used to send fine-grained keyboard events. To fill values in form fields, use [frame.fill(selector, value[, options])](api/class-frame.md#framefillselector-value-options).
|
||||
|
||||
To press a special key, like `Control` or `ArrowDown`, use [keyboard.press(key[, options])](api/class-keyboard.md#keyboardpresskey-options).
|
||||
|
||||
```js
|
||||
await frame.type('#mytextarea', 'Hello'); // Types instantly
|
||||
await frame.type('#mytextarea', 'World', {delay: 100}); // Types slower, like a user
|
||||
```
|
||||
|
||||
## frame.uncheck(selector[, options])
|
||||
- `selector` <[string]> A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `options` <[Object]>
|
||||
- `force` <[boolean]> Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
|
||||
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
This method checks an element matching `selector` by performing the following steps:
|
||||
1. Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM.
|
||||
1. Ensure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already unchecked, this method returns immediately.
|
||||
1. Wait for [actionability](./actionability.md) checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried.
|
||||
1. Scroll the element into view if needed.
|
||||
1. Use [page.mouse](api/class-page.md#pagemouse) to click in the center of the element.
|
||||
1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
|
||||
1. Ensure that the element is now unchecked. If not, this method rejects.
|
||||
|
||||
When all steps combined have not finished during the specified `timeout`, this method rejects with a [TimeoutError]. Passing zero timeout disables this.
|
||||
|
||||
## frame.url()
|
||||
- returns: <[string]>
|
||||
|
||||
Returns frame's url.
|
||||
|
||||
## frame.waitForFunction(pageFunction[, arg, options])
|
||||
- `pageFunction` <[function]|[string]> Function to be evaluated in browser context
|
||||
- `arg` <[EvaluationArgument]> Optional argument to pass to `pageFunction`
|
||||
- `options` <[Object]>
|
||||
- `polling` <[number]|"raf"> If `polling` is `'raf'`, then `pageFunction` is constantly executed in `requestAnimationFrame` callback. If `polling` is a number, then it is treated as an interval in milliseconds at which the function would be executed. Defaults to `raf`.
|
||||
- `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 [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout).
|
||||
- returns: <[Promise]<[JSHandle]>>
|
||||
|
||||
Returns when the `pageFunction` returns a truthy value, returns that value.
|
||||
|
||||
The `waitForFunction` can be used to observe viewport size change:
|
||||
|
||||
```js
|
||||
const { firefox } = require('playwright'); // Or 'chromium' or 'webkit'.
|
||||
|
||||
(async () => {
|
||||
const browser = await firefox.launch();
|
||||
const page = await browser.newPage();
|
||||
const watchDog = page.mainFrame().waitForFunction('window.innerWidth < 100');
|
||||
page.setViewportSize({width: 50, height: 50});
|
||||
await watchDog;
|
||||
await browser.close();
|
||||
})();
|
||||
```
|
||||
|
||||
To pass an argument to the predicate of `frame.waitForFunction` function:
|
||||
|
||||
```js
|
||||
const selector = '.foo';
|
||||
await frame.waitForFunction(selector => !!document.querySelector(selector), selector);
|
||||
```
|
||||
|
||||
## frame.waitForLoadState([state, options])
|
||||
- `state` <"load"|"domcontentloaded"|"networkidle"> Optional load state to wait for, defaults to `load`. If the state has been already reached while loading current document, the method returns immediately. Can be one of:
|
||||
* `'load'` - wait for the `load` event to be fired.
|
||||
* `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired.
|
||||
* `'networkidle'` - wait until there are no network connections for at least `500` ms.
|
||||
- `options` <[Object]>
|
||||
- `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultNavigationTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaultnavigationtimeouttimeout), [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout), [page.setDefaultNavigationTimeout(timeout)](api/class-page.md#pagesetdefaultnavigationtimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Waits for the required load state to be reached.
|
||||
|
||||
This returns when the frame reaches a required load state, `load` by default. The navigation must have been committed when this method is called. If current document has already reached the required state, resolves immediately.
|
||||
|
||||
```js
|
||||
await frame.click('button'); // Click triggers navigation.
|
||||
await frame.waitForLoadState(); // Waits for 'load' state by default.
|
||||
```
|
||||
|
||||
## frame.waitForNavigation([options])
|
||||
- `options` <[Object]>
|
||||
- `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultNavigationTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaultnavigationtimeouttimeout), [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout), [page.setDefaultNavigationTimeout(timeout)](api/class-page.md#pagesetdefaultnavigationtimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- `url` <[string]|[RegExp]|[function]\([URL]\):[boolean]> URL string, URL regex pattern or predicate receiving [URL] to match while waiting for the navigation.
|
||||
- `waitUntil` <"load"|"domcontentloaded"|"networkidle"> When to consider operation succeeded, defaults to `load`. Events can be either:
|
||||
* `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
|
||||
* `'load'` - consider operation to be finished when the `load` event is fired.
|
||||
* `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms.
|
||||
- returns: <[Promise]<[null]|[Response]>>
|
||||
|
||||
Returns 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`.
|
||||
|
||||
This method waits for the frame to navigate to a new URL. It is useful for when you run code which will indirectly cause the frame to navigate. Consider this example:
|
||||
|
||||
```js
|
||||
const [response] = await Promise.all([
|
||||
frame.waitForNavigation(), // Wait for the navigation to finish
|
||||
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.
|
||||
|
||||
## frame.waitForSelector(selector[, options])
|
||||
- `selector` <[string]> A selector to query for. See [working with selectors](./selectors.md#working-with-selectors) for more details.
|
||||
- `options` <[Object]>
|
||||
- `state` <"attached"|"detached"|"visible"|"hidden"> Defaults to `'visible'`. Can be either:
|
||||
* `'attached'` - wait for element to be present in DOM.
|
||||
* `'detached'` - wait for element to not be present in DOM.
|
||||
* `'visible'` - wait for element to have non-empty bounding box and no `visibility:hidden`. Note that element without any content or with `display:none` has an empty bounding box and is not considered visible.
|
||||
* `'hidden'` - wait for element to be either detached from DOM, or have an empty bounding box or `visibility:hidden`. This is opposite to the `'visible'` option.
|
||||
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](api/class-page.md#pagesetdefaulttimeouttimeout) methods.
|
||||
- returns: <[Promise]<[null]|[ElementHandle]>>
|
||||
|
||||
Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or `detached`.
|
||||
|
||||
Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If at the moment of calling the method `selector` already satisfies the condition, the method will return immediately. If the selector doesn't satisfy the condition for the `timeout` milliseconds, the function will throw.
|
||||
|
||||
This method works across navigations:
|
||||
|
||||
```js
|
||||
const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'.
|
||||
|
||||
(async () => {
|
||||
const browser = await webkit.launch();
|
||||
const page = await browser.newPage();
|
||||
let currentURL;
|
||||
page.mainFrame()
|
||||
.waitForSelector('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();
|
||||
})();
|
||||
```
|
||||
|
||||
## frame.waitForTimeout(timeout)
|
||||
- `timeout` <[number]> A timeout to wait for
|
||||
- returns: <[Promise]>
|
||||
|
||||
Waits for the given `timeout` in milliseconds.
|
||||
|
||||
Note that `frame.waitForTimeout()` should only be used for debugging. Tests using the timer in production are going to be flaky. Use signals such as network events, selectors becoming visible and others instead.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,152 +0,0 @@
|
|||
---
|
||||
id: class-jshandle
|
||||
title: "JSHandle"
|
||||
---
|
||||
|
||||
|
||||
JSHandle represents an in-page JavaScript object. JSHandles can be created with the [page.evaluateHandle(pageFunction[, arg])](api/class-page.md#pageevaluatehandlepagefunction-arg) method.
|
||||
|
||||
```js
|
||||
const windowHandle = await page.evaluateHandle(() => window);
|
||||
// ...
|
||||
```
|
||||
|
||||
JSHandle prevents the referenced JavaScript object being garbage collected unless the handle is exposed with [jsHandle.dispose()](api/class-jshandle.md#jshandledispose). JSHandles are auto-disposed when their origin frame gets navigated or the parent context gets destroyed.
|
||||
|
||||
JSHandle instances can be used as an argument in [page.$eval(selector, pageFunction[, arg])](api/class-page.md#pageevalselector-pagefunction-arg), [page.evaluate(pageFunction[, arg])](api/class-page.md#pageevaluatepagefunction-arg) and [page.evaluateHandle(pageFunction[, arg])](api/class-page.md#pageevaluatehandlepagefunction-arg) methods.
|
||||
|
||||
|
||||
- [jsHandle.asElement()](api/class-jshandle.md#jshandleaselement)
|
||||
- [jsHandle.dispose()](api/class-jshandle.md#jshandledispose)
|
||||
- [jsHandle.evaluate(pageFunction[, arg])](api/class-jshandle.md#jshandleevaluatepagefunction-arg)
|
||||
- [jsHandle.evaluateHandle(pageFunction[, arg])](api/class-jshandle.md#jshandleevaluatehandlepagefunction-arg)
|
||||
- [jsHandle.getProperties()](api/class-jshandle.md#jshandlegetproperties)
|
||||
- [jsHandle.getProperty(propertyName)](api/class-jshandle.md#jshandlegetpropertypropertyname)
|
||||
- [jsHandle.jsonValue()](api/class-jshandle.md#jshandlejsonvalue)
|
||||
|
||||
## jsHandle.asElement()
|
||||
- returns: <[null]|[ElementHandle]>
|
||||
|
||||
Returns either `null` or the object handle itself, if the object handle is an instance of [ElementHandle].
|
||||
|
||||
## jsHandle.dispose()
|
||||
- returns: <[Promise]>
|
||||
|
||||
The `jsHandle.dispose` method stops referencing the element handle.
|
||||
|
||||
## jsHandle.evaluate(pageFunction[, arg])
|
||||
- `pageFunction` <[function]> Function to be evaluated in browser context
|
||||
- `arg` <[EvaluationArgument]> Optional argument to pass to `pageFunction`
|
||||
- returns: <[Promise]<[Serializable]>>
|
||||
|
||||
Returns 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:
|
||||
|
||||
```js
|
||||
const tweetHandle = await page.$('.tweet .retweets');
|
||||
expect(await tweetHandle.evaluate((node, suffix) => node.innerText, ' retweets')).toBe('10 retweets');
|
||||
```
|
||||
|
||||
## jsHandle.evaluateHandle(pageFunction[, arg])
|
||||
- `pageFunction` <[function]|[string]> Function to be evaluated
|
||||
- `arg` <[EvaluationArgument]> Optional argument to pass to `pageFunction`
|
||||
- returns: <[Promise]<[JSHandle]>>
|
||||
|
||||
Returns the return value of `pageFunction` as in-page object (JSHandle).
|
||||
|
||||
This method passes this handle as the first argument to `pageFunction`.
|
||||
|
||||
The only difference between `jsHandle.evaluate` and `jsHandle.evaluateHandle` is that `jsHandle.evaluateHandle` returns in-page object (JSHandle).
|
||||
|
||||
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(pageFunction[, arg])](api/class-page.md#pageevaluatehandlepagefunction-arg) for more details.
|
||||
|
||||
## jsHandle.getProperties()
|
||||
- returns: <[Promise]<[Map]<[string], [JSHandle]>>>
|
||||
|
||||
The method returns a map with **own property names** as keys and JSHandle instances for the property values.
|
||||
|
||||
```js
|
||||
const handle = await page.evaluateHandle(() => ({window, document}));
|
||||
const properties = await handle.getProperties();
|
||||
const windowHandle = properties.get('window');
|
||||
const documentHandle = properties.get('document');
|
||||
await handle.dispose();
|
||||
```
|
||||
|
||||
## jsHandle.getProperty(propertyName)
|
||||
- `propertyName` <[string]> property to get
|
||||
- returns: <[Promise]<[JSHandle]>>
|
||||
|
||||
Fetches a single property from the referenced object.
|
||||
|
||||
## jsHandle.jsonValue()
|
||||
- returns: <[Promise]<[Serializable]>>
|
||||
|
||||
Returns a JSON representation of the object. If the object has a `toJSON` function, it **will not be called**.
|
||||
|
||||
> **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.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,195 +0,0 @@
|
|||
---
|
||||
id: class-keyboard
|
||||
title: "Keyboard"
|
||||
---
|
||||
|
||||
|
||||
Keyboard provides an api for managing a virtual keyboard. The high level api is [keyboard.type(text[, options])](api/class-keyboard.md#keyboardtypetext-options), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page.
|
||||
|
||||
For finer control, you can use [keyboard.down(key)](api/class-keyboard.md#keyboarddownkey), [keyboard.up(key)](api/class-keyboard.md#keyboardupkey), and [keyboard.insertText(text)](api/class-keyboard.md#keyboardinserttexttext) to manually fire events as if they were generated from a real keyboard.
|
||||
|
||||
An example of holding down `Shift` in order to select and delete some text:
|
||||
|
||||
```js
|
||||
await page.keyboard.type('Hello World!');
|
||||
await page.keyboard.press('ArrowLeft');
|
||||
|
||||
await page.keyboard.down('Shift');
|
||||
for (let i = 0; i < ' World'.length; i++)
|
||||
await page.keyboard.press('ArrowLeft');
|
||||
await page.keyboard.up('Shift');
|
||||
|
||||
await page.keyboard.press('Backspace');
|
||||
// Result text will end up saying 'Hello!'
|
||||
```
|
||||
|
||||
An example of pressing uppercase `A`
|
||||
|
||||
```js
|
||||
await page.keyboard.press('Shift+KeyA');
|
||||
// or
|
||||
await page.keyboard.press('Shift+A');
|
||||
```
|
||||
|
||||
An example to trigger select-all with the keyboard
|
||||
|
||||
```js
|
||||
// on Windows and Linux
|
||||
await page.keyboard.press('Control+A');
|
||||
// on macOS
|
||||
await page.keyboard.press('Meta+A');
|
||||
```
|
||||
|
||||
|
||||
- [keyboard.down(key)](api/class-keyboard.md#keyboarddownkey)
|
||||
- [keyboard.insertText(text)](api/class-keyboard.md#keyboardinserttexttext)
|
||||
- [keyboard.press(key[, options])](api/class-keyboard.md#keyboardpresskey-options)
|
||||
- [keyboard.type(text[, options])](api/class-keyboard.md#keyboardtypetext-options)
|
||||
- [keyboard.up(key)](api/class-keyboard.md#keyboardupkey)
|
||||
|
||||
## keyboard.down(key)
|
||||
- `key` <[string]> Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Dispatches a `keydown` event.
|
||||
|
||||
`key` can specify the intended [keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) value or a single character to generate the text for. A superset of the `key` values can be found [here](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values). Examples of the keys are:
|
||||
|
||||
`F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`, `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.
|
||||
|
||||
Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`.
|
||||
|
||||
Holding down `Shift` will type the text that corresponds to the `key` in the upper case.
|
||||
|
||||
If `key` is a single character, it is case-sensitive, so the values `a` and `A` will generate different respective texts.
|
||||
|
||||
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(key)](api/class-keyboard.md#keyboardupkey).
|
||||
|
||||
After the key is pressed once, subsequent calls to [keyboard.down(key)](api/class-keyboard.md#keyboarddownkey) will have [repeat](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/repeat) set to true. To release the key, use [keyboard.up(key)](api/class-keyboard.md#keyboardupkey).
|
||||
|
||||
> **NOTE** Modifier keys DO influence `keyboard.down`. Holding down `Shift` will type the text in upper case.
|
||||
|
||||
## keyboard.insertText(text)
|
||||
- `text` <[string]> Sets input to the specified text value.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Dispatches only `input` event, does not emit the `keydown`, `keyup` or `keypress` events.
|
||||
|
||||
```js
|
||||
page.keyboard.insertText('嗨');
|
||||
```
|
||||
|
||||
> **NOTE** Modifier keys DO NOT effect `keyboard.insertText`. Holding down `Shift` will not type the text in upper case.
|
||||
|
||||
## keyboard.press(key[, options])
|
||||
- `key` <[string]> Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.
|
||||
- `options` <[Object]>
|
||||
- `delay` <[number]> Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
|
||||
- returns: <[Promise]>
|
||||
|
||||
`key` can specify the intended [keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) value or a single character to generate the text for. A superset of the `key` values can be found [here](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values). Examples of the keys are:
|
||||
|
||||
`F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`, `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.
|
||||
|
||||
Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`.
|
||||
|
||||
Holding down `Shift` will type the text that corresponds to the `key` in the upper case.
|
||||
|
||||
If `key` is a single character, it is case-sensitive, so the values `a` and `A` will generate different respective texts.
|
||||
|
||||
Shortcuts such as `key: "Control+o"` or `key: "Control+Shift+T"` are supported as well. When speficied with the modifier, modifier is pressed and being held while the subsequent key is being pressed.
|
||||
|
||||
```js
|
||||
const page = await browser.newPage();
|
||||
await page.goto('https://keycode.info');
|
||||
await page.keyboard.press('A');
|
||||
await page.screenshot({ path: 'A.png' });
|
||||
await page.keyboard.press('ArrowLeft');
|
||||
await page.screenshot({ path: 'ArrowLeft.png' });
|
||||
await page.keyboard.press('Shift+O');
|
||||
await page.screenshot({ path: 'O.png' });
|
||||
await browser.close();
|
||||
```
|
||||
|
||||
Shortcut for [keyboard.down(key)](api/class-keyboard.md#keyboarddownkey) and [keyboard.up(key)](api/class-keyboard.md#keyboardupkey).
|
||||
|
||||
## keyboard.type(text[, options])
|
||||
- `text` <[string]> A text to type into a focused element.
|
||||
- `options` <[Object]>
|
||||
- `delay` <[number]> Time to wait between key presses in milliseconds. Defaults to 0.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
|
||||
|
||||
To press a special key, like `Control` or `ArrowDown`, use [keyboard.press(key[, options])](api/class-keyboard.md#keyboardpresskey-options).
|
||||
|
||||
```js
|
||||
await page.keyboard.type('Hello'); // Types instantly
|
||||
await page.keyboard.type('World', {delay: 100}); // Types slower, like a user
|
||||
```
|
||||
|
||||
> **NOTE** Modifier keys DO NOT effect `keyboard.type`. Holding down `Shift` will not type the text in upper case.
|
||||
|
||||
## keyboard.up(key)
|
||||
- `key` <[string]> Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Dispatches a `keyup` event.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,98 +0,0 @@
|
|||
---
|
||||
id: class-logger
|
||||
title: "Logger"
|
||||
---
|
||||
|
||||
|
||||
Playwright generates a lot of logs and they are accessible via the pluggable logger sink.
|
||||
|
||||
```js
|
||||
const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'.
|
||||
|
||||
(async () => {
|
||||
const browser = await chromium.launch({
|
||||
logger: {
|
||||
isEnabled: (name, severity) => name === 'browser',
|
||||
log: (name, severity, message, args) => console.log(`${name} ${message}`)
|
||||
}
|
||||
});
|
||||
...
|
||||
})();
|
||||
```
|
||||
|
||||
|
||||
- [logger.isEnabled(name, severity)](api/class-logger.md#loggerisenabledname-severity)
|
||||
- [logger.log(name, severity, message, args, hints)](api/class-logger.md#loggerlogname-severity-message-args-hints)
|
||||
|
||||
## logger.isEnabled(name, severity)
|
||||
- `name` <[string]> logger name
|
||||
- `severity` <"verbose"|"info"|"warning"|"error">
|
||||
- returns: <[boolean]>
|
||||
|
||||
Determines whether sink is interested in the logger with the given name and severity.
|
||||
|
||||
## logger.log(name, severity, message, args, hints)
|
||||
- `name` <[string]> logger name
|
||||
- `severity` <"verbose"|"info"|"warning"|"error">
|
||||
- `message` <[string]|[Error]> log message format
|
||||
- `args` <[Array]<[Object]>> message arguments
|
||||
- `hints` <[Object]> optional formatting hints
|
||||
- `color` <[string]> Optional preferred logger color.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,131 +0,0 @@
|
|||
---
|
||||
id: class-mouse
|
||||
title: "Mouse"
|
||||
---
|
||||
|
||||
|
||||
The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport.
|
||||
|
||||
Every `page` object has its own Mouse, accessible with [page.mouse](api/class-page.md#pagemouse).
|
||||
|
||||
```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();
|
||||
```
|
||||
|
||||
|
||||
- [mouse.click(x, y[, options])](api/class-mouse.md#mouseclickx-y-options)
|
||||
- [mouse.dblclick(x, y[, options])](api/class-mouse.md#mousedblclickx-y-options)
|
||||
- [mouse.down([options])](api/class-mouse.md#mousedownoptions)
|
||||
- [mouse.move(x, y[, options])](api/class-mouse.md#mousemovex-y-options)
|
||||
- [mouse.up([options])](api/class-mouse.md#mouseupoptions)
|
||||
|
||||
## mouse.click(x, y[, options])
|
||||
- `x` <[number]>
|
||||
- `y` <[number]>
|
||||
- `options` <[Object]>
|
||||
- `button` <"left"|"right"|"middle"> Defaults to `left`.
|
||||
- `clickCount` <[number]> defaults to 1. See [UIEvent.detail].
|
||||
- `delay` <[number]> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Shortcut for [mouse.move(x, y[, options])](api/class-mouse.md#mousemovex-y-options), [mouse.down([options])](api/class-mouse.md#mousedownoptions), [mouse.up([options])](api/class-mouse.md#mouseupoptions).
|
||||
|
||||
## mouse.dblclick(x, y[, options])
|
||||
- `x` <[number]>
|
||||
- `y` <[number]>
|
||||
- `options` <[Object]>
|
||||
- `button` <"left"|"right"|"middle"> Defaults to `left`.
|
||||
- `delay` <[number]> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Shortcut for [mouse.move(x, y[, options])](api/class-mouse.md#mousemovex-y-options), [mouse.down([options])](api/class-mouse.md#mousedownoptions), [mouse.up([options])](api/class-mouse.md#mouseupoptions), [mouse.down([options])](api/class-mouse.md#mousedownoptions) and [mouse.up([options])](api/class-mouse.md#mouseupoptions).
|
||||
|
||||
## mouse.down([options])
|
||||
- `options` <[Object]>
|
||||
- `button` <"left"|"right"|"middle"> Defaults to `left`.
|
||||
- `clickCount` <[number]> defaults to 1. See [UIEvent.detail].
|
||||
- returns: <[Promise]>
|
||||
|
||||
Dispatches a `mousedown` event.
|
||||
|
||||
## mouse.move(x, y[, options])
|
||||
- `x` <[number]>
|
||||
- `y` <[number]>
|
||||
- `options` <[Object]>
|
||||
- `steps` <[number]> defaults to 1. Sends intermediate `mousemove` events.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Dispatches a `mousemove` event.
|
||||
|
||||
## mouse.up([options])
|
||||
- `options` <[Object]>
|
||||
- `button` <"left"|"right"|"middle"> Defaults to `left`.
|
||||
- `clickCount` <[number]> defaults to 1. See [UIEvent.detail].
|
||||
- returns: <[Promise]>
|
||||
|
||||
Dispatches a `mouseup` event.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
File diff suppressed because it is too large
Load diff
|
|
@ -1,148 +0,0 @@
|
|||
---
|
||||
id: class-playwright
|
||||
title: "Playwright"
|
||||
---
|
||||
|
||||
|
||||
Playwright module provides a method to launch a browser instance. The following is a typical example of using Playwright to drive automation:
|
||||
|
||||
```js
|
||||
const { chromium, firefox, webkit } = require('playwright');
|
||||
|
||||
(async () => {
|
||||
const browser = await chromium.launch(); // Or 'firefox' or 'webkit'.
|
||||
const page = await browser.newPage();
|
||||
await page.goto('http://example.com');
|
||||
// other actions...
|
||||
await browser.close();
|
||||
})();
|
||||
```
|
||||
|
||||
By default, the `playwright` NPM package automatically downloads browser executables during installation. The `playwright-core` NPM package can be used to skip automatic downloads.
|
||||
|
||||
|
||||
- [playwright.chromium](api/class-playwright.md#playwrightchromium)
|
||||
- [playwright.devices](api/class-playwright.md#playwrightdevices)
|
||||
- [playwright.errors](api/class-playwright.md#playwrighterrors)
|
||||
- [playwright.firefox](api/class-playwright.md#playwrightfirefox)
|
||||
- [playwright.selectors](api/class-playwright.md#playwrightselectors)
|
||||
- [playwright.webkit](api/class-playwright.md#playwrightwebkit)
|
||||
|
||||
## playwright.chromium
|
||||
- type: <[BrowserType]>
|
||||
|
||||
This object can be used to launch or connect to Chromium, returning instances of [ChromiumBrowser].
|
||||
|
||||
## playwright.devices
|
||||
- type: <[Object]>
|
||||
|
||||
Returns a list of devices to be used with [browser.newContext([options])](api/class-browser.md#browsernewcontextoptions) or [browser.newPage([options])](api/class-browser.md#browsernewpageoptions). Actual list of devices can be found in [src/server/deviceDescriptors.ts](https://github.com/Microsoft/playwright/blob/master/src/server/deviceDescriptors.ts).
|
||||
|
||||
```js
|
||||
const { webkit, devices } = require('playwright');
|
||||
const iPhone = devices['iPhone 6'];
|
||||
|
||||
(async () => {
|
||||
const browser = await webkit.launch();
|
||||
const context = await browser.newContext({
|
||||
...iPhone
|
||||
});
|
||||
const page = await context.newPage();
|
||||
await page.goto('http://example.com');
|
||||
// other actions...
|
||||
await browser.close();
|
||||
})();
|
||||
```
|
||||
|
||||
## playwright.errors
|
||||
- type: <[Object]>
|
||||
- `TimeoutError` <[function]> A class of [TimeoutError].
|
||||
|
||||
Playwright methods might throw errors if they are unable to fulfill a request. For example, [page.waitForSelector(selector[, options])](api/class-page.md#pagewaitforselectorselector-options) might fail if the selector doesn't match any nodes during the given timeframe.
|
||||
|
||||
For certain types of errors Playwright uses specific error classes. These classes are available via [`playwright.errors`](#playwrighterrors).
|
||||
|
||||
An example of handling a timeout error:
|
||||
|
||||
```js
|
||||
try {
|
||||
await page.waitForSelector('.foo');
|
||||
} catch (e) {
|
||||
if (e instanceof playwright.errors.TimeoutError) {
|
||||
// Do something if this is a timeout.
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## playwright.firefox
|
||||
- type: <[BrowserType]>
|
||||
|
||||
This object can be used to launch or connect to Firefox, returning instances of [FirefoxBrowser].
|
||||
|
||||
## playwright.selectors
|
||||
- type: <[Selectors]>
|
||||
|
||||
Selectors can be used to install custom selector engines. See [Working with selectors](./selectors.md#working-with-selectors) for more information.
|
||||
|
||||
## playwright.webkit
|
||||
- type: <[BrowserType]>
|
||||
|
||||
This object can be used to launch or connect to WebKit, returning instances of [WebKitBrowser].
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,210 +0,0 @@
|
|||
---
|
||||
id: class-request
|
||||
title: "Request"
|
||||
---
|
||||
|
||||
|
||||
Whenever the page sends a request for a network resource the following sequence of events are emitted by [Page]:
|
||||
* [page.on('request')](api/class-page.md#pageonrequest) emitted when the request is issued by the page.
|
||||
* [page.on('response')](api/class-page.md#pageonresponse) emitted when/if the response status and headers are received for the request.
|
||||
* [page.on('requestfinished')](api/class-page.md#pageonrequestfinished) emitted when the response body is downloaded and the request is complete.
|
||||
|
||||
If request fails at some point, then instead of `'requestfinished'` event (and possibly instead of 'response' event), the [page.on('requestfailed')](api/class-page.md#pageonrequestfailed) event is emitted.
|
||||
|
||||
> **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will complete with `'requestfinished'` event.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
- [request.failure()](api/class-request.md#requestfailure)
|
||||
- [request.frame()](api/class-request.md#requestframe)
|
||||
- [request.headers()](api/class-request.md#requestheaders)
|
||||
- [request.isNavigationRequest()](api/class-request.md#requestisnavigationrequest)
|
||||
- [request.method()](api/class-request.md#requestmethod)
|
||||
- [request.postData()](api/class-request.md#requestpostdata)
|
||||
- [request.postDataBuffer()](api/class-request.md#requestpostdatabuffer)
|
||||
- [request.postDataJSON()](api/class-request.md#requestpostdatajson)
|
||||
- [request.redirectedFrom()](api/class-request.md#requestredirectedfrom)
|
||||
- [request.redirectedTo()](api/class-request.md#requestredirectedto)
|
||||
- [request.resourceType()](api/class-request.md#requestresourcetype)
|
||||
- [request.response()](api/class-request.md#requestresponse)
|
||||
- [request.timing()](api/class-request.md#requesttiming)
|
||||
- [request.url()](api/class-request.md#requesturl)
|
||||
|
||||
## request.failure()
|
||||
- returns: <[null]|[Object]>
|
||||
- `errorText` <[string]> Human-readable error message, e.g. `'net::ERR_FAILED'`.
|
||||
|
||||
The method returns `null` unless this request has failed, as reported by `requestfailed` event.
|
||||
|
||||
Example of logging of all the failed requests:
|
||||
|
||||
```js
|
||||
page.on('requestfailed', request => {
|
||||
console.log(request.url() + ' ' + request.failure().errorText);
|
||||
});
|
||||
```
|
||||
|
||||
## request.frame()
|
||||
- returns: <[Frame]>
|
||||
|
||||
Returns the [Frame] that initiated this request.
|
||||
|
||||
## request.headers()
|
||||
- returns: <[Object]<[string], [string]>>
|
||||
|
||||
An object with HTTP headers associated with the request. All header names are lower-case.
|
||||
|
||||
## request.isNavigationRequest()
|
||||
- returns: <[boolean]>
|
||||
|
||||
Whether this request is driving frame's navigation.
|
||||
|
||||
## request.method()
|
||||
- returns: <[string]>
|
||||
|
||||
Request's method (GET, POST, etc.)
|
||||
|
||||
## request.postData()
|
||||
- returns: <[null]|[string]>
|
||||
|
||||
Request's post body, if any.
|
||||
|
||||
## request.postDataBuffer()
|
||||
- returns: <[null]|[Buffer]>
|
||||
|
||||
Request's post body in a binary form, if any.
|
||||
|
||||
## request.postDataJSON()
|
||||
- returns: <[null]|[Object]>
|
||||
|
||||
Returns parsed request's body for `form-urlencoded` and JSON as a fallback if any.
|
||||
|
||||
When the response is `application/x-www-form-urlencoded` then a key/value object of the values will be returned. Otherwise it will be parsed as JSON.
|
||||
|
||||
## request.redirectedFrom()
|
||||
- returns: <[null]|[Request]>
|
||||
|
||||
Request that was redirected by the server to this one, if any.
|
||||
|
||||
When the server responds with a redirect, Playwright creates a new [Request] object. The two requests are connected by `redirectedFrom()` and `redirectedTo()` methods. When multiple server redirects has happened, it is possible to construct the whole redirect chain by repeatedly calling `redirectedFrom()`.
|
||||
|
||||
For example, if the website `http://example.com` redirects to `https://example.com`:
|
||||
|
||||
```js
|
||||
const response = await page.goto('http://example.com');
|
||||
console.log(response.request().redirectedFrom().url()); // 'http://example.com'
|
||||
```
|
||||
|
||||
If the website `https://google.com` has no redirects:
|
||||
|
||||
```js
|
||||
const response = await page.goto('https://google.com');
|
||||
console.log(response.request().redirectedFrom()); // null
|
||||
```
|
||||
|
||||
## request.redirectedTo()
|
||||
- returns: <[null]|[Request]>
|
||||
|
||||
New request issued by the browser if the server responded with redirect.
|
||||
|
||||
This method is the opposite of [request.redirectedFrom()](api/class-request.md#requestredirectedfrom):
|
||||
|
||||
```js
|
||||
console.log(request.redirectedFrom().redirectedTo() === request); // true
|
||||
```
|
||||
|
||||
## request.resourceType()
|
||||
- returns: <[string]>
|
||||
|
||||
Contains the request's resource type as it was perceived by the rendering engine. ResourceType will be one of the following: `document`, `stylesheet`, `image`, `media`, `font`, `script`, `texttrack`, `xhr`, `fetch`, `eventsource`, `websocket`, `manifest`, `other`.
|
||||
|
||||
## request.response()
|
||||
- returns: <[Promise]<[null]|[Response]>>
|
||||
|
||||
Returns the matching [Response] object, or `null` if the response was not received due to error.
|
||||
|
||||
## request.timing()
|
||||
- returns: <[Object]>
|
||||
- `startTime` <[number]> Request start time in milliseconds elapsed since January 1, 1970 00:00:00 UTC
|
||||
- `domainLookupStart` <[number]> Time immediately before the browser starts the domain name lookup for the resource. The value is given in milliseconds relative to `startTime`, -1 if not available.
|
||||
- `domainLookupEnd` <[number]> Time immediately after the browser starts the domain name lookup for the resource. The value is given in milliseconds relative to `startTime`, -1 if not available.
|
||||
- `connectStart` <[number]> Time immediately before the user agent starts establishing the connection to the server to retrieve the resource. The value is given in milliseconds relative to `startTime`, -1 if not available.
|
||||
- `secureConnectionStart` <[number]> Time immediately before the browser starts the handshake process to secure the current connection. The value is given in milliseconds relative to `startTime`, -1 if not available.
|
||||
- `connectEnd` <[number]> Time immediately before the user agent starts establishing the connection to the server to retrieve the resource. The value is given in milliseconds relative to `startTime`, -1 if not available.
|
||||
- `requestStart` <[number]> Time immediately before the browser starts requesting the resource from the server, cache, or local resource. The value is given in milliseconds relative to `startTime`, -1 if not available.
|
||||
- `responseStart` <[number]> Time immediately after the browser starts requesting the resource from the server, cache, or local resource. The value is given in milliseconds relative to `startTime`, -1 if not available.
|
||||
- `responseEnd` <[number]> Time immediately after the browser receives the last byte of the resource or immediately before the transport connection is closed, whichever comes first. The value is given in milliseconds relative to `startTime`, -1 if not available.
|
||||
|
||||
Returns resource timing information for given request. Most of the timing values become available upon the response, `responseEnd` becomes available when request finishes. Find more information at [Resource Timing API](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming).
|
||||
|
||||
```js
|
||||
const [request] = await Promise.all([
|
||||
page.waitForEvent('requestfinished'),
|
||||
page.goto(httpsServer.EMPTY_PAGE)
|
||||
]);
|
||||
console.log(request.timing());
|
||||
```
|
||||
|
||||
## request.url()
|
||||
- returns: <[string]>
|
||||
|
||||
URL of the request.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,135 +0,0 @@
|
|||
---
|
||||
id: class-response
|
||||
title: "Response"
|
||||
---
|
||||
|
||||
|
||||
[Response] class represents responses which are received by page.
|
||||
|
||||
|
||||
- [response.body()](api/class-response.md#responsebody)
|
||||
- [response.finished()](api/class-response.md#responsefinished)
|
||||
- [response.frame()](api/class-response.md#responseframe)
|
||||
- [response.headers()](api/class-response.md#responseheaders)
|
||||
- [response.json()](api/class-response.md#responsejson)
|
||||
- [response.ok()](api/class-response.md#responseok)
|
||||
- [response.request()](api/class-response.md#responserequest)
|
||||
- [response.status()](api/class-response.md#responsestatus)
|
||||
- [response.statusText()](api/class-response.md#responsestatustext)
|
||||
- [response.text()](api/class-response.md#responsetext)
|
||||
- [response.url()](api/class-response.md#responseurl)
|
||||
|
||||
## response.body()
|
||||
- returns: <[Promise]<[Buffer]>>
|
||||
|
||||
Returns the buffer with response body.
|
||||
|
||||
## response.finished()
|
||||
- returns: <[Promise]<[null]|[Error]>>
|
||||
|
||||
Waits for this response to finish, returns failure error if request failed.
|
||||
|
||||
## response.frame()
|
||||
- returns: <[Frame]>
|
||||
|
||||
Returns the [Frame] that initiated this response.
|
||||
|
||||
## response.headers()
|
||||
- returns: <[Object]<[string], [string]>>
|
||||
|
||||
Returns the object with HTTP headers associated with the response. All header names are lower-case.
|
||||
|
||||
## response.json()
|
||||
- returns: <[Promise]<[Serializable]>>
|
||||
|
||||
Returns the JSON representation of response body.
|
||||
|
||||
This method will throw if the response body is not parsable via `JSON.parse`.
|
||||
|
||||
## response.ok()
|
||||
- returns: <[boolean]>
|
||||
|
||||
Contains a boolean stating whether the response was successful (status in the range 200-299) or not.
|
||||
|
||||
## response.request()
|
||||
- returns: <[Request]>
|
||||
|
||||
Returns the matching [Request] object.
|
||||
|
||||
## response.status()
|
||||
- returns: <[number]>
|
||||
|
||||
Contains the status code of the response (e.g., 200 for a success).
|
||||
|
||||
## response.statusText()
|
||||
- returns: <[string]>
|
||||
|
||||
Contains the status text of the response (e.g. usually an "OK" for a success).
|
||||
|
||||
## response.text()
|
||||
- returns: <[Promise]<[string]>>
|
||||
|
||||
Returns the text representation of response body.
|
||||
|
||||
## response.url()
|
||||
- returns: <[string]>
|
||||
|
||||
Contains the URL of the response.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,147 +0,0 @@
|
|||
---
|
||||
id: class-route
|
||||
title: "Route"
|
||||
---
|
||||
|
||||
|
||||
Whenever a network route is set up with [page.route(url, handler)](api/class-page.md#pagerouteurl-handler) or [browserContext.route(url, handler)](api/class-browsercontext.md#browsercontextrouteurl-handler), the `Route` object allows to handle the route.
|
||||
|
||||
|
||||
- [route.abort([errorCode])](api/class-route.md#routeaborterrorcode)
|
||||
- [route.continue([overrides])](api/class-route.md#routecontinueoverrides)
|
||||
- [route.fulfill(response)](api/class-route.md#routefulfillresponse)
|
||||
- [route.request()](api/class-route.md#routerequest)
|
||||
|
||||
## route.abort([errorCode])
|
||||
- `errorCode` <[string]> Optional error code. Defaults to `failed`, could be one of the following:
|
||||
* `'aborted'` - An operation was aborted (due to user action)
|
||||
* `'accessdenied'` - Permission to access a resource, other than the network, was denied
|
||||
* `'addressunreachable'` - The IP address is unreachable. This usually means that there is no route to the specified host or network.
|
||||
* `'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).
|
||||
* `'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.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Aborts the route's request.
|
||||
|
||||
## route.continue([overrides])
|
||||
- `overrides` <[Object]> Optional request overrides, can override following properties:
|
||||
- `url` <[string]> If set changes the request URL. New URL must have same protocol as original one.
|
||||
- `method` <[string]> If set changes the request method (e.g. GET or POST)
|
||||
- `postData` <[string]|[Buffer]> If set changes the post data of request
|
||||
- `headers` <[Object]<[string], [string]>> If set changes the request HTTP headers. Header values will be converted to a string.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Continues route's request with optional overrides.
|
||||
|
||||
```js
|
||||
await page.route('**/*', (route, request) => {
|
||||
// Override headers
|
||||
const headers = {
|
||||
...request.headers(),
|
||||
foo: 'bar', // set "foo" header
|
||||
origin: undefined, // remove "origin" header
|
||||
};
|
||||
route.continue({headers});
|
||||
});
|
||||
```
|
||||
|
||||
## route.fulfill(response)
|
||||
- `response` <[Object]> Response that will fulfill this route's request.
|
||||
- `status` <[number]> Response status code, defaults to `200`.
|
||||
- `headers` <[Object]<[string], [string]>> Optional response headers. Header values will be converted to a string.
|
||||
- `contentType` <[string]> If set, equals to setting `Content-Type` response header.
|
||||
- `body` <[string]|[Buffer]> Optional response body.
|
||||
- `path` <[string]> Optional file path to respond with. The content type will be inferred from file extension. If `path` is a relative path, then it is resolved relative to the current working directory.
|
||||
- returns: <[Promise]>
|
||||
|
||||
Fulfills route's request with given response.
|
||||
|
||||
An example of fulfilling all requests with 404 responses:
|
||||
|
||||
```js
|
||||
await page.route('**/*', route => {
|
||||
route.fulfill({
|
||||
status: 404,
|
||||
contentType: 'text/plain',
|
||||
body: 'Not Found!'
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
An example of serving static file:
|
||||
|
||||
```js
|
||||
await page.route('**/xhr_endpoint', route => route.fulfill({ path: 'mock_data.json' }));
|
||||
```
|
||||
|
||||
## route.request()
|
||||
- returns: <[Request]>
|
||||
|
||||
A request to be routed.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,115 +0,0 @@
|
|||
---
|
||||
id: class-selectors
|
||||
title: "Selectors"
|
||||
---
|
||||
|
||||
|
||||
Selectors can be used to install custom selector engines. See [Working with selectors](./selectors.md#working-with-selectors) for more information.
|
||||
|
||||
|
||||
- [selectors.register(name, script[, options])](api/class-selectors.md#selectorsregistername-script-options)
|
||||
|
||||
## selectors.register(name, script[, options])
|
||||
- `name` <[string]> Name that is used in selectors as a prefix, e.g. `{name: 'foo'}` enables `foo=myselectorbody` selectors. May only contain `[a-zA-Z0-9_]` characters.
|
||||
- `script` <[function]|[string]|[Object]> Script that evaluates to a selector engine instance.
|
||||
- `path` <[string]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. Optional.
|
||||
- `content` <[string]> Raw script content. Optional.
|
||||
- `options` <[Object]>
|
||||
- `contentScript` <[boolean]> Whether to run this selector engine in isolated JavaScript environment. This environment has access to the same DOM, but not any JavaScript objects from the frame's scripts. Defaults to `false`. Note that running as a content script is not guaranteed when this engine is used together with other registered engines.
|
||||
- returns: <[Promise]>
|
||||
|
||||
An example of registering selector engine that queries elements based on a tag name:
|
||||
|
||||
```js
|
||||
const { selectors, firefox } = require('playwright'); // Or 'chromium' or 'webkit'.
|
||||
|
||||
(async () => {
|
||||
// Must be a function that evaluates to a selector engine instance.
|
||||
const createTagNameEngine = () => ({
|
||||
// Returns the first element matching given selector in the root's subtree.
|
||||
query(root, selector) {
|
||||
return root.querySelector(selector);
|
||||
},
|
||||
|
||||
// Returns all elements matching given selector in the root's subtree.
|
||||
queryAll(root, selector) {
|
||||
return Array.from(root.querySelectorAll(selector));
|
||||
}
|
||||
});
|
||||
|
||||
// Register the engine. Selectors will be prefixed with "tag=".
|
||||
await selectors.register('tag', createTagNameEngine);
|
||||
|
||||
const browser = await firefox.launch();
|
||||
const page = await browser.newPage();
|
||||
await page.setContent(`<div><button>Click me</button></div>`);
|
||||
|
||||
// Use the selector prefixed with its name.
|
||||
const button = await page.$('tag=button');
|
||||
// Combine it with other selector engines.
|
||||
await page.click('tag=div >> text="Click me"');
|
||||
// Can use it in any methods supporting selectors.
|
||||
const buttonCount = await page.$$eval('tag=button', buttons => buttons.length);
|
||||
|
||||
await browser.close();
|
||||
})();
|
||||
```
|
||||
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,68 +0,0 @@
|
|||
---
|
||||
id: class-timeouterror
|
||||
title: "TimeoutError"
|
||||
---
|
||||
|
||||
* extends: [Error]
|
||||
|
||||
TimeoutError is emitted whenever certain operations are terminated due to timeout, e.g. [page.waitForSelector(selector[, options])](api/class-page.md#pagewaitforselectorselector-options) or [browserType.launch([options])](api/class-browsertype.md#browsertypelaunchoptions).
|
||||
|
||||
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,75 +0,0 @@
|
|||
---
|
||||
id: class-touchscreen
|
||||
title: "Touchscreen"
|
||||
---
|
||||
|
||||
|
||||
The Touchscreen class operates in main-frame CSS pixels relative to the top-left corner of the viewport. Methods on the touchscreen can only be used in browser contexts that have been intialized with `hasTouch` set to true.
|
||||
|
||||
|
||||
- [touchscreen.tap(x, y)](api/class-touchscreen.md#touchscreentapx-y)
|
||||
|
||||
## touchscreen.tap(x, y)
|
||||
- `x` <[number]>
|
||||
- `y` <[number]>
|
||||
- returns: <[Promise]>
|
||||
|
||||
Dispatches a `touchstart` and `touchend` event with a single touch at the position (`x`,`y`).
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,77 +0,0 @@
|
|||
---
|
||||
id: class-video
|
||||
title: "Video"
|
||||
---
|
||||
|
||||
|
||||
When browser context is created with the `videosPath` option, each page has a video object associated with it.
|
||||
|
||||
```js
|
||||
console.log(await page.video().path());
|
||||
```
|
||||
|
||||
|
||||
- [video.path()](api/class-video.md#videopath)
|
||||
|
||||
## video.path()
|
||||
- returns: <[Promise]<[string]>>
|
||||
|
||||
Returns the file system path this video will be recorded to. The video is guaranteed to be written to the filesystem upon closing the browser context.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,75 +0,0 @@
|
|||
---
|
||||
id: class-webkitbrowser
|
||||
title: "WebKitBrowser"
|
||||
---
|
||||
|
||||
* extends: [Browser]
|
||||
|
||||
WebKit browser instance does not expose WebKit-specific features.
|
||||
|
||||
|
||||
- [browser.on('disconnected')](api/class-browser.md#browserondisconnected)
|
||||
- [browser.close()](api/class-browser.md#browserclose)
|
||||
- [browser.contexts()](api/class-browser.md#browsercontexts)
|
||||
- [browser.isConnected()](api/class-browser.md#browserisconnected)
|
||||
- [browser.newContext([options])](api/class-browser.md#browsernewcontextoptions)
|
||||
- [browser.newPage([options])](api/class-browser.md#browsernewpageoptions)
|
||||
- [browser.version()](api/class-browser.md#browserversion)
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,116 +0,0 @@
|
|||
---
|
||||
id: class-websocket
|
||||
title: "WebSocket"
|
||||
---
|
||||
|
||||
|
||||
The [WebSocket] class represents websocket connections in the page.
|
||||
|
||||
|
||||
- [webSocket.on('close')](api/class-websocket.md#websocketonclose)
|
||||
- [webSocket.on('framereceived')](api/class-websocket.md#websocketonframereceived)
|
||||
- [webSocket.on('framesent')](api/class-websocket.md#websocketonframesent)
|
||||
- [webSocket.on('socketerror')](api/class-websocket.md#websocketonsocketerror)
|
||||
- [webSocket.isClosed()](api/class-websocket.md#websocketisclosed)
|
||||
- [webSocket.url()](api/class-websocket.md#websocketurl)
|
||||
- [webSocket.waitForEvent(event[, optionsOrPredicate])](api/class-websocket.md#websocketwaitforeventevent-optionsorpredicate)
|
||||
|
||||
## webSocket.on('close')
|
||||
|
||||
Fired when the websocket closes.
|
||||
|
||||
## webSocket.on('framereceived')
|
||||
- type: <[Object]>
|
||||
- `payload` <[string]|[Buffer]> frame payload
|
||||
|
||||
Fired when the websocket recieves a frame.
|
||||
|
||||
## webSocket.on('framesent')
|
||||
- type: <[Object]>
|
||||
- `payload` <[string]|[Buffer]> frame payload
|
||||
|
||||
Fired when the websocket sends a frame.
|
||||
|
||||
## webSocket.on('socketerror')
|
||||
- type: <[String]>
|
||||
|
||||
Fired when the websocket has an error.
|
||||
|
||||
## webSocket.isClosed()
|
||||
- returns: <[boolean]>
|
||||
|
||||
Indicates that the web socket has been closed.
|
||||
|
||||
## webSocket.url()
|
||||
- returns: <[string]>
|
||||
|
||||
Contains the URL of the WebSocket.
|
||||
|
||||
## webSocket.waitForEvent(event[, optionsOrPredicate])
|
||||
- `event` <[string]> Event name, same one would pass into `webSocket.on(event)`.
|
||||
- `optionsOrPredicate` <[Function]|[Object]> Either a predicate that receives an event or an options object. Optional.
|
||||
- `predicate` <[Function]> receives the event data and resolves to truthy value when the waiting should resolve.
|
||||
- `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 [browserContext.setDefaultTimeout(timeout)](api/class-browsercontext.md#browsercontextsetdefaulttimeouttimeout).
|
||||
- returns: <[Promise]<[Object]>>
|
||||
|
||||
Returns the event data value.
|
||||
|
||||
Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy value. Will throw an error if the webSocket is closed before the event is fired.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,112 +0,0 @@
|
|||
---
|
||||
id: class-worker
|
||||
title: "Worker"
|
||||
---
|
||||
|
||||
|
||||
The Worker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). `worker` event is emitted on the page object to signal a worker creation. `close` event is emitted on the worker object when the worker is gone.
|
||||
|
||||
```js
|
||||
page.on('worker', worker => {
|
||||
console.log('Worker created: ' + worker.url());
|
||||
worker.on('close', worker => console.log('Worker destroyed: ' + worker.url()));
|
||||
});
|
||||
|
||||
console.log('Current workers:');
|
||||
for (const worker of page.workers())
|
||||
console.log(' ' + worker.url());
|
||||
```
|
||||
|
||||
|
||||
- [worker.on('close')](api/class-worker.md#workeronclose)
|
||||
- [worker.evaluate(pageFunction[, arg])](api/class-worker.md#workerevaluatepagefunction-arg)
|
||||
- [worker.evaluateHandle(pageFunction[, arg])](api/class-worker.md#workerevaluatehandlepagefunction-arg)
|
||||
- [worker.url()](api/class-worker.md#workerurl)
|
||||
|
||||
## worker.on('close')
|
||||
- type: <[Worker]>
|
||||
|
||||
Emitted when this dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is terminated.
|
||||
|
||||
## worker.evaluate(pageFunction[, arg])
|
||||
- `pageFunction` <[function]|[string]> Function to be evaluated in the worker context
|
||||
- `arg` <[EvaluationArgument]> Optional argument to pass to `pageFunction`
|
||||
- returns: <[Promise]<[Serializable]>>
|
||||
|
||||
Returns 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.
|
||||
|
||||
If the function passed to the `worker.evaluate` returns a non-[Serializable] value, then `worker.evaluate` returns `undefined`. DevTools Protocol also supports transferring some additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals.
|
||||
|
||||
## worker.evaluateHandle(pageFunction[, arg])
|
||||
- `pageFunction` <[function]|[string]> Function to be evaluated in the page context
|
||||
- `arg` <[EvaluationArgument]> Optional argument to pass to `pageFunction`
|
||||
- returns: <[Promise]<[JSHandle]>>
|
||||
|
||||
Returns the return value of `pageFunction` as in-page object (JSHandle).
|
||||
|
||||
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.
|
||||
|
||||
## worker.url()
|
||||
- returns: <[string]>
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,168 +0,0 @@
|
|||
---
|
||||
id: assertions
|
||||
title: "Assertions"
|
||||
---
|
||||
|
||||
The Playwright API can be used to read element contents and properties for test assertions. These values are fetched from the browser page and asserted in Node.js.
|
||||
|
||||
The examples in this guide use the built-in [`assert` module](https://nodejs.org/api/assert.html), but they can be used with any assertion library (like [Expect](https://www.npmjs.com/package/expect) or [Chai](https://www.npmjs.com/package/chai)). See [Test runners](test-runners.md) for more info.
|
||||
|
||||
- [Common patterns](#common-patterns)
|
||||
- [Element Handles](#element-handles)
|
||||
- [Custom assertions](#custom-assertions)
|
||||
|
||||
## Common patterns
|
||||
|
||||
Playwright provides convenience APIs for common assertion tasks, like finding the text content of an element. These APIs require a [selector](./selectors.md) to locate the element.
|
||||
|
||||
```js
|
||||
// Assert text content
|
||||
const content = await page.textContent('nav:first-child');
|
||||
assert(content === 'home');
|
||||
|
||||
// Assert inner text
|
||||
const text = await page.innerText('.selected');
|
||||
assert(text === 'value');
|
||||
|
||||
// Assert inner HTML
|
||||
const html = await page.innerHTML('div.result');
|
||||
assert(html === '<p>Result</p>')
|
||||
|
||||
// Assert `checked` attribute
|
||||
const checked = await page.getAttribute('input', 'checked');
|
||||
assert(checked);
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [page.textContent(selector[, options])](api/class-page.md#pagetextcontentselector-options)
|
||||
- [page.innerText(selector[, options])](api/class-page.md#pageinnertextselector-options)
|
||||
- [page.innerHTML(selector[, options])](api/class-page.md#pageinnerhtmlselector-options)
|
||||
- [page.getAttribute(selector, name[, options])](api/class-page.md#pagegetattributeselector-name-options)
|
||||
- [frame.textContent(selector[, options])](api/class-frame.md#frametextcontentselector-options)
|
||||
- [frame.innerText(selector[, options])](api/class-frame.md#frameinnertextselector-options)
|
||||
- [frame.innerHTML(selector[, options])](api/class-frame.md#frameinnerhtmlselector-options)
|
||||
- [frame.getAttribute(selector, name[, options])](api/class-frame.md#framegetattributeselector-name-options)
|
||||
|
||||
<br/>
|
||||
|
||||
## Element Handles
|
||||
|
||||
[ElementHandle] objects represent in-page DOM elements. They can be used to assert for multiple properties of the element.
|
||||
|
||||
It is recommended to fetch the `ElementHandle` object with [page.waitForSelector(selector[, options])](api/class-page.md#pagewaitforselectorselector-options) or [frame.waitForSelector(selector[, options])](api/class-frame.md#framewaitforselectorselector-options). These APIs wait for the element to be visible and then return an `ElementHandle`.
|
||||
|
||||
```js
|
||||
// Get the element handle
|
||||
const elementHandle = page.waitForSelector('#box');
|
||||
|
||||
// Assert bounding box for the element
|
||||
const boundingBox = await elementHandle.boundingBox();
|
||||
assert(boundingBox.width === 100);
|
||||
|
||||
// Assert attribute for the element
|
||||
const classNames = await elementHandle.getAttribute('class');
|
||||
assert(classNames.includes('highlighted'));
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [elementHandle.textContent()](api/class-elementhandle.md#elementhandletextcontent)
|
||||
- [elementHandle.innerText()](api/class-elementhandle.md#elementhandleinnertext)
|
||||
- [elementHandle.innerHTML()](api/class-elementhandle.md#elementhandleinnerhtml)
|
||||
- [elementHandle.getAttribute(name)](api/class-elementhandle.md#elementhandlegetattributename)
|
||||
- [elementHandle.boundingBox()](api/class-elementhandle.md#elementhandleboundingbox)
|
||||
|
||||
<br/>
|
||||
|
||||
## Custom assertions
|
||||
|
||||
With Playwright, you can also write custom JavaScript to run in the context of the browser. This is useful in situations where you want to assert for values that are not covered by the convenience APIs above.
|
||||
|
||||
The following APIs do not auto-wait for the element. It is recommended to use [page.waitForSelector(selector[, options])](api/class-page.md#pagewaitforselectorselector-options) or [frame.waitForSelector(selector[, options])](api/class-frame.md#framewaitforselectorselector-options).
|
||||
|
||||
```js
|
||||
// Assert local storage value
|
||||
const userId = page.evaluate(() => window.localStorage.getItem('userId'));
|
||||
assert(userId);
|
||||
|
||||
// Assert value for input element
|
||||
await page.waitForSelector('#search');
|
||||
const value = await page.$eval('#search', el => el.value);
|
||||
assert(value === 'query');
|
||||
|
||||
// Assert computed style
|
||||
const fontSize = await page.$eval('div', el => window.getComputedStyle(el).fontSize);
|
||||
assert(fontSize === '16px');
|
||||
|
||||
// Assert list length
|
||||
const length = await page.$$eval('li.selected', (items) => items.length);
|
||||
assert(length === 3);
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [page.evaluate(pageFunction[, arg])](api/class-page.md#pageevaluatepagefunction-arg)
|
||||
- [page.$eval(selector, pageFunction[, arg])](api/class-page.md#pageevalselector-pagefunction-arg)
|
||||
- [page.$$eval(selector, pageFunction[, arg])](api/class-page.md#pageevalselector-pagefunction-arg-1)
|
||||
- [frame.evaluate(pageFunction[, arg])](api/class-frame.md#frameevaluatepagefunction-arg)
|
||||
- [frame.$eval(selector, pageFunction[, arg])](api/class-frame.md#frameevalselector-pagefunction-arg)
|
||||
- [frame.$$eval(selector, pageFunction[, arg])](api/class-frame.md#frameevalselector-pagefunction-arg-1)
|
||||
- [elementHandle.$eval(selector, pageFunction[, arg])](api/class-elementhandle.md#elementhandleevalselector-pagefunction-arg)
|
||||
- [elementHandle.$$eval(selector, pageFunction[, arg])](api/class-elementhandle.md#elementhandleevalselector-pagefunction-arg-1)
|
||||
- [EvaluationArgument]
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
202
docs/out/auth.md
202
docs/out/auth.md
|
|
@ -1,202 +0,0 @@
|
|||
---
|
||||
id: auth
|
||||
title: "Authentication"
|
||||
---
|
||||
|
||||
Playwright can be used to automate scenarios that require authentication.
|
||||
|
||||
Tests written with Playwright execute in isolated clean-slate environments called [browser contexts](./core-concepts.md#browser-contexts). This isolation model improves reproducibility and prevents cascading test failures. New browser contexts can load existing authentication state. This eliminates the need to login in every context and speeds up test execution.
|
||||
|
||||
> Note: This guide covers cookie/token-based authentication (logging in via the app UI). For [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) use [`browser.newContext`](./network.md#http-authentication).
|
||||
|
||||
- [Automate logging in](#automate-logging-in)
|
||||
- [Reuse authentication state](#reuse-authentication-state)
|
||||
- [Multi-factor authentication](#multi-factor-authentication)
|
||||
|
||||
## Automate logging in
|
||||
|
||||
The Playwright API can automate interaction with a login form. See [Input guide](./input.md) for more details.
|
||||
|
||||
The following example automates login on GitHub. Once these steps are executed, the browser context will be authenticated.
|
||||
|
||||
```js
|
||||
const page = await context.newPage();
|
||||
await page.goto('https://github.com/login');
|
||||
|
||||
// Interact with login form
|
||||
await page.click('text=Login');
|
||||
await page.fill('input[name="login"]', USERNAME);
|
||||
await page.fill('input[name="password"]', PASSWORD);
|
||||
await page.click('text=Submit');
|
||||
// Verify app is logged in
|
||||
```
|
||||
|
||||
These steps can be executed for every browser context. However, redoing login for every test can slow down test execution. To prevent that, we will reuse existing authentication state in new browser contexts.
|
||||
|
||||
## Reuse authentication state
|
||||
|
||||
Web apps use cookie-based or token-based authentication, where authenticated state is stored as [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) or in [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Storage). The Playwright API can be used to retrieve this state from authenticated contexts and then load it into new contexts.
|
||||
|
||||
Cookies and local storage state can be used across different browsers. They depend on your application's authentication model: some apps might require both cookies and local storage.
|
||||
|
||||
The following code snippets retrieve state from an authenticated page/context and load them into a new context.
|
||||
|
||||
### Cookies
|
||||
|
||||
```js
|
||||
// Get cookies and store as an env variable
|
||||
const cookies = await context.cookies();
|
||||
process.env.COOKIES = JSON.stringify(cookies);
|
||||
|
||||
// Set cookies in a new context
|
||||
const deserializedCookies = JSON.parse(process.env.COOKIES)
|
||||
await context.addCookies(deserializedCookies);
|
||||
```
|
||||
|
||||
### Local storage
|
||||
|
||||
Local storage ([`window.localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)) is specific to a particular domain.
|
||||
|
||||
```js
|
||||
// Get local storage and store as env variable
|
||||
const localStorage = await page.evaluate(() => JSON.stringify(window.localStorage));
|
||||
process.env.LOCAL_STORAGE = localStorage;
|
||||
|
||||
// Set local storage in a new context
|
||||
const localStorage = process.env.LOCAL_STORAGE;
|
||||
await context.addInitScript(storage => {
|
||||
if (window.location.hostname === 'example.com') {
|
||||
const entries = JSON.parse(storage);
|
||||
Object.keys(entries).forEach(key => {
|
||||
window.localStorage.setItem(key, entries[key]);
|
||||
});
|
||||
}
|
||||
}, localStorage);
|
||||
```
|
||||
|
||||
### Session storage
|
||||
|
||||
Session storage ([`window.sessionStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage)) is specific to a particular domain.
|
||||
|
||||
```js
|
||||
// Get session storage and store as env variable
|
||||
const sessionStorage = await page.evaluate(() => JSON.stringify(sessionStorage));
|
||||
process.env.SESSION_STORAGE = sessionStorage;
|
||||
|
||||
// Set session storage in a new context
|
||||
const sessionStorage = process.env.SESSION_STORAGE;
|
||||
await context.addInitScript(storage => {
|
||||
if (window.location.hostname === 'example.com') {
|
||||
const entries = JSON.parse(storage);
|
||||
Object.keys(entries).forEach(key => {
|
||||
window.sessionStorage.setItem(key, entries[key]);
|
||||
});
|
||||
}
|
||||
}, sessionStorage);
|
||||
```
|
||||
|
||||
### Lifecycle
|
||||
|
||||
Logging in via the UI and then reusing authentication state can be combined to implement **login once and run multiple scenarios**. The lifecycle looks like:
|
||||
1. Run tests (for example, with `npm run test`).
|
||||
1. Login via UI and retrieve authentication state.
|
||||
* In Jest, this can be executed in [`globalSetup`](https://jestjs.io/docs/en/configuration#globalsetup-string).
|
||||
1. In each test, load authentication state in `beforeEach` or `beforeAll` step.
|
||||
|
||||
This approach will also **work in CI environments**, since it does not rely on any external state.
|
||||
|
||||
### Example
|
||||
|
||||
[This example script](examples/authentication.js) logs in on GitHub.com with Chromium, and then reuses the logged in cookie state in WebKit.
|
||||
|
||||
### API reference
|
||||
- [BrowserContext]
|
||||
- [browserContext.cookies([urls])](api/class-browsercontext.md#browsercontextcookiesurls)
|
||||
- [browserContext.addCookies(cookies)](api/class-browsercontext.md#browsercontextaddcookiescookies)
|
||||
- [page.evaluate(pageFunction[, arg])](api/class-page.md#pageevaluatepagefunction-arg)
|
||||
- [browserContext.addInitScript(script[, arg])](api/class-browsercontext.md#browsercontextaddinitscriptscript-arg)
|
||||
|
||||
## Multi-factor authentication
|
||||
|
||||
Accounts with multi-factor authentication (MFA) cannot be fully automated, and need manual intervention. Persistent authentication can be used to partially automate MFA scenarios.
|
||||
|
||||
### Persistent authentication
|
||||
|
||||
Web browsers use a directory on disk to store user history, cookies, IndexedDB and other local state. This disk location is called the [User data directory](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md).
|
||||
|
||||
Note that persistent authentication is not suited for CI environments since it relies on a disk location. User data directories are specific to browser types and cannot be shared across browser types.
|
||||
|
||||
User data directories can be used with the `launchPersistentContext` API.
|
||||
|
||||
```js
|
||||
const { chromium } = require('playwright');
|
||||
|
||||
const userDataDir = '/path/to/directory';
|
||||
const context = await chromium.launchPersistentContext(userDataDir, { headless: false });
|
||||
// Execute login steps manually in the browser window
|
||||
```
|
||||
|
||||
### Lifecycle
|
||||
1. Create a user data directory on disk 2. Launch a persistent context with the user data directory and login the MFA account. 3. Reuse user data directory to run automation scenarios.
|
||||
|
||||
### API reference
|
||||
- [BrowserContext]
|
||||
- [browserType.launchPersistentContext(userDataDir[, options])](api/class-browsertype.md#browsertypelaunchpersistentcontextuserdatadir-options)
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
304
docs/out/ci.md
304
docs/out/ci.md
|
|
@ -1,304 +0,0 @@
|
|||
---
|
||||
id: ci
|
||||
title: "Continuous Integration"
|
||||
---
|
||||
|
||||
Playwright tests can be executed in CI environments. We have created sample configurations for common CI providers.
|
||||
|
||||
- [Introduction](#introduction)
|
||||
- [CI configurations](#ci-configurations)
|
||||
- [Caching browsers](#caching-browsers)
|
||||
- [Debugging browser launches](#debugging-browser-launches)
|
||||
- [Running headful](#running-headful)
|
||||
|
||||
## Introduction
|
||||
|
||||
3 steps to get your tests running on CI:
|
||||
1. **Ensure CI agent can run browsers**: Use [our Docker image](./docker.md) in Linux agents. Windows and macOS agents do not require any additional dependencies.
|
||||
1. **Install Playwright**: In most projects, this would be done with `npm ci` (or `npm install`). Playwright would install the relevant browsers automatically.
|
||||
1. **Run your tests**: Use `npm test` or equivalent to execute your tests.
|
||||
|
||||
## CI configurations
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
The [Playwright GitHub Action](https://github.com/microsoft/playwright-github-action) can be used to run Playwright tests on GitHub Actions.
|
||||
|
||||
```yml
|
||||
steps:
|
||||
- uses: microsoft/playwright-github-action@v1
|
||||
- name: Run your tests
|
||||
run: npm test
|
||||
```
|
||||
|
||||
We run [our tests](/.github/workflows/tests.yml) on GitHub Actions, across a matrix of 3 platforms (Windows, Linux, macOS) and 3 browsers (Chromium, Firefox, WebKit).
|
||||
|
||||
### Docker
|
||||
|
||||
We have a [pre-built Docker image](./docker.md) which can either be used directly, or as a reference to update your existing Docker definitions.
|
||||
|
||||
Suggested configuration
|
||||
1. By default, Docker runs a container with a `/dev/shm` shared memory space 64MB. This is [typically too small](https://github.com/c0b/chrome-in-docker/issues/1) for Chromium and will cause Chromium to crash when rendering large pages. To fix, run the container with `docker run --shm-size=1gb` to increase the size of `/dev/shm`. Since Chromium 65, this is no longer necessary. Instead, launch the browser with the `--disable-dev-shm-usage` flag:
|
||||
|
||||
```js
|
||||
const browser = await playwright.chromium.launch({
|
||||
args: ['--disable-dev-shm-usage']
|
||||
});
|
||||
```
|
||||
|
||||
This will write shared memory files into `/tmp` instead of `/dev/shm`. See [crbug.com/736452](https://bugs.chromium.org/p/chromium/issues/detail?id=736452) for more details.
|
||||
1. Using `--ipc=host` is also recommended when using Chromium—without it Chromium can run out of memory and crash. Learn more about this option in [Docker docs](https://docs.docker.com/engine/reference/run/#ipc-settings---ipc).
|
||||
1. Seeing other weird errors when launching Chromium? Try running your container with `docker run --cap-add=SYS_ADMIN` when developing locally.
|
||||
1. [dumb-init](https://github.com/Yelp/dumb-init) is worth checking out if you're experiencing a lot of zombies Chromium processes sticking around. There's special treatment for processes with PID=1, which makes it hard to terminate Chromium properly in some cases (e.g. in Docker).
|
||||
|
||||
### Azure Pipelines
|
||||
|
||||
For Windows or macOS agents, no additional configuration required, just install Playwright and run your tests.
|
||||
|
||||
For Linux agents, you can use [our Docker container](./docker.md) with Azure Pipelines support for [running containerized jobs](https://docs.microsoft.com/en-us/azure/devops/pipelines/process/container-phases?view=azure-devops). Alternatively, you can refer to the [Dockerfile](./docker.md) to see additional dependencies that need to be installed on a Ubuntu agent.
|
||||
|
||||
```yml
|
||||
pool:
|
||||
vmImage: 'ubuntu-18.04'
|
||||
|
||||
container: mcr.microsoft.com/playwright:bionic
|
||||
|
||||
steps:
|
||||
- script: npm install
|
||||
- script: npm run test
|
||||
```
|
||||
|
||||
### Travis CI
|
||||
|
||||
We run our tests on Travis CI over a Linux agent (Ubuntu 18.04).
|
||||
|
||||
Suggested configuration
|
||||
1. [User namespace cloning](http://man7.org/linux/man-pages/man7/user_namespaces.7.html) should be enabled to support proper sandboxing
|
||||
1. [xvfb](https://en.wikipedia.org/wiki/Xvfb) should be launched in order to run Chromium in non-headless mode (e.g. to test Chrome Extensions)
|
||||
1. If your project does not have `package-lock.json`, Travis would be auto-caching `node_modules` directory. If you run `npm install` (instead of `npm ci`), it is possible that the browser binaries are not downloaded. Fix this with [these steps](#exception-node_modules-are-cached) outlined below.
|
||||
|
||||
To sum up, your `.travis.yml` might look like this:
|
||||
|
||||
```yml
|
||||
language: node_js
|
||||
dist: bionic
|
||||
addons:
|
||||
apt:
|
||||
packages:
|
||||
# These are required to run webkit
|
||||
- libwoff1
|
||||
- libopus0
|
||||
- libwebp6
|
||||
- libwebpdemux2
|
||||
- libenchant1c2a
|
||||
- libgudev-1.0-0
|
||||
- libsecret-1-0
|
||||
- libhyphen0
|
||||
- libgdk-pixbuf2.0-0
|
||||
- libegl1
|
||||
- libgles2
|
||||
- libevent-2.1-6
|
||||
- libnotify4
|
||||
- libxslt1.1
|
||||
- libvpx5
|
||||
# gstreamer and plugins to support video playback in WebKit.
|
||||
- gstreamer1.0-gl
|
||||
- gstreamer1.0-plugins-base
|
||||
- gstreamer1.0-plugins-good
|
||||
- gstreamer1.0-plugins-bad
|
||||
# This is required to run chromium
|
||||
- libgbm1
|
||||
# this is needed for running headful tests
|
||||
- xvfb
|
||||
|
||||
# allow headful tests
|
||||
before_install:
|
||||
# Enable user namespace cloning
|
||||
- "sysctl kernel.unprivileged_userns_clone=1"
|
||||
# Launch XVFB
|
||||
- "export DISPLAY=:99.0"
|
||||
- "sh -e /etc/init.d/xvfb start"
|
||||
```
|
||||
|
||||
### CircleCI
|
||||
|
||||
We run our tests on CircleCI, with our [pre-built Docker image](./docker.md). Running Playwright smoothly on CircleCI requires the following steps:
|
||||
1. Use the pre-built [Docker image](./docker.md) in your config like so:
|
||||
|
||||
```yaml
|
||||
docker:
|
||||
- image: mcr.microsoft.com/playwright:bionic
|
||||
environment:
|
||||
NODE_ENV: development # Needed if playwright is in `devDependencies`
|
||||
```
|
||||
|
||||
1. If you’re using Playwright through Jest, then you may encounter an error spawning child processes:
|
||||
|
||||
```
|
||||
[00:00.0] jest args: --e2e --spec --max-workers=36
|
||||
Error: spawn ENOMEM
|
||||
at ChildProcess.spawn (internal/child_process.js:394:11)
|
||||
```
|
||||
|
||||
This is likely caused by Jest autodetecting the number of processes on the entire machine (`36`) rather than the number allowed to your container (`2`). To fix this, set `jest --maxWorkers=2` in your test command.
|
||||
|
||||
### Jenkins
|
||||
|
||||
Jenkins supports Docker agents for pipelines. Use the [Playwright Docker image](./docker.md) to run tests on Jenkins.
|
||||
|
||||
```groovy
|
||||
pipeline {
|
||||
agent { docker { image 'mcr.microsoft.com/playwright:bionic' } }
|
||||
stages {
|
||||
stage('e2e-tests') {
|
||||
steps {
|
||||
sh 'npm install'
|
||||
sh 'npm run test'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Bitbucket Pipelines
|
||||
|
||||
Bitbucket Pipelines can use public [Docker images as build environments](https://confluence.atlassian.com/bitbucket/use-docker-images-as-build-environments-792298897.html). To run Playwright tests on Bitbucket, use our public Docker image ([see Dockerfile](./docker.md)).
|
||||
|
||||
```yml
|
||||
image: mcr.microsoft.com/playwright:bionic
|
||||
```
|
||||
|
||||
While the Docker image supports sandboxing for Chromium, it does not work in the Bitbucket Pipelines environment. To launch Chromium on Bitbucket Pipelines, use the `chromiumSandbox: false` launch argument.
|
||||
|
||||
```js
|
||||
const { chromium } = require('playwright');
|
||||
const browser = await chromium.launch({ chromiumSandbox: false });
|
||||
```
|
||||
|
||||
### GitLab CI
|
||||
|
||||
To run Playwright tests on GitLab, use our public Docker image ([see Dockerfile](./docker.md)).
|
||||
|
||||
```yml
|
||||
stages:
|
||||
- test
|
||||
|
||||
tests:
|
||||
stage: test
|
||||
image: mcr.microsoft.com/playwright:bionic
|
||||
script:
|
||||
- npm install # This should install playwright
|
||||
- npm run test
|
||||
```
|
||||
|
||||
## Caching browsers
|
||||
|
||||
By default, Playwright downloads browser binaries when the Playwright NPM package is installed. The NPM packages have a `postinstall` hook that downloads the browser binaries. This behavior can be [customized with environment variables](./installation.md).
|
||||
|
||||
Caching browsers on CI is **strictly optional**: The `postinstall` hooks should execute and download the browser binaries on every run.
|
||||
|
||||
#### Exception: `node_modules` are cached
|
||||
|
||||
Most CI providers cache the [npm-cache](https://docs.npmjs.com/cli-commands/cache.html) directory (located at `$HOME/.npm`). If your CI pipelines caches the `node_modules` directory and you run `npm install` (instead of `npm ci`), the default configuration
|
||||
|
||||
**will not work**. This is because the `npm install` step will find the Playwright NPM package on disk and not execute the `postinstall` step.
|
||||
|
||||
> Travis CI automatically caches `node_modules` if your repo does not have a `package-lock.json` file.
|
||||
|
||||
This behavior can be fixed with one of the following approaches:
|
||||
1. Move to caching `$HOME/.npm` or the npm-cache directory. (This is the default behavior in most CI providers.)
|
||||
1. Set `PLAYWRIGHT_BROWSERS_PATH=0` as the environment variable before running `npm install`. This will download the browser binaries in the `node_modules` directory and cache them with the package code. See [installation docs](./installation.md).
|
||||
1. Use `npm ci` (instead of `npm install`) which forces a clean install: by removing the existing `node_modules` directory. See [npm docs](https://docs.npmjs.com/cli/ci.html).
|
||||
1. Cache the browser binaries, with the steps below.
|
||||
|
||||
#### Directories to cache
|
||||
|
||||
With the default behavior, Playwright downloads the browser binaries in the following directories:
|
||||
- `%USERPROFILE%\AppData\Local\ms-playwright` on Windows
|
||||
- `~/Library/Caches/ms-playwright` on MacOS
|
||||
- `~/.cache/ms-playwright` on Linux
|
||||
|
||||
To cache the browser downloads between CI runs, cache this location in your CI configuration, against a hash of the Playwright version.
|
||||
|
||||
## Debugging browser launches
|
||||
|
||||
Playwright supports the `DEBUG` environment variable to output debug logs during execution. Setting it to `pw:browser*` is helpful while debugging `Error: Failed to launch browser` errors.
|
||||
|
||||
```
|
||||
DEBUG=pw:browser* npm run test
|
||||
```
|
||||
|
||||
## Running headful
|
||||
|
||||
By default, Playwright launches browsers in headless mode. This can be changed by passing a flag when the browser is launched.
|
||||
|
||||
```js
|
||||
// Works across chromium, firefox and webkit
|
||||
const { chromium } = require('playwright');
|
||||
const browser = await chromium.launch({ headless: false });
|
||||
```
|
||||
|
||||
On Linux agents, headful execution requires [Xvfb](https://en.wikipedia.org/wiki/Xvfb) to be installed. Our [Docker image](./docker.md) and GitHub Action have Xvfb pre-installed. To run browsers in headful mode with Xvfb, add `xvfb-run` before the Node.js command.
|
||||
|
||||
```
|
||||
xvfb-run node index.js
|
||||
```
|
||||
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
233
docs/out/cli.md
233
docs/out/cli.md
|
|
@ -1,233 +0,0 @@
|
|||
---
|
||||
id: cli
|
||||
title: "Command Line Interface"
|
||||
---
|
||||
|
||||
Playwright comes with the command line tools that run via `npx` or as a part of the `npm` scripts.
|
||||
|
||||
- [Usage](#usage)
|
||||
- [Generate code](#generate-code)
|
||||
- [Open pages](#open-pages)
|
||||
- [Inspect selectors](#inspect-selectors)
|
||||
- [Take screenshot](#take-screenshot)
|
||||
- [Generate PDF](#generate-pdf)
|
||||
- [Known limitations](#known-limitations)
|
||||
|
||||
## Usage
|
||||
|
||||
```sh
|
||||
$ npx playwright --help
|
||||
```
|
||||
|
||||
Running from `package.json` script
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"help": "playwright --help"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Generate code
|
||||
|
||||
```sh
|
||||
$ npx playwright codegen wikipedia.org
|
||||
```
|
||||
|
||||
Run `codegen` and perform actions in the browser. Playwright CLI will generate JavaScript code for the user interactions. `codegen` will attempt to generate resilient text-based selectors.
|
||||
|
||||
<img src="https://user-images.githubusercontent.com/284612/92536033-7e7ebe00-f1ed-11ea-9e1a-7cbd912e3391.gif"></img>
|
||||
|
||||
### Preserve authenticated state
|
||||
|
||||
Run `codegen` with `--save-storage` to save [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) and [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) at the end. This is useful to separately record authentication step and reuse it later.
|
||||
|
||||
```sh
|
||||
$ npx playwright --save-storage=auth.json codegen
|
||||
# Perform authentication and exit.
|
||||
# auth.json will contain the storage state.
|
||||
```
|
||||
|
||||
Run with `--load-storage` to consume previously loaded storage. This way, all [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) and [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) will be restored, bringing most web apps to the authenticated state.
|
||||
|
||||
```sh
|
||||
$ npx playwright --load-storage=auth.json open my.web.app
|
||||
$ npx playwright --load-storage=auth.json codegen my.web.app
|
||||
# Perform actions in authenticated state.
|
||||
```
|
||||
|
||||
## Open pages
|
||||
|
||||
With `open`, you can use Playwright bundled browsers to browse web pages. Playwright provides cross-platform WebKit builds that can be used to reproduce Safari rendering across Windows, Linux and macOS.
|
||||
|
||||
```sh
|
||||
# Open page in Chromium
|
||||
npx playwright open example.com
|
||||
```
|
||||
|
||||
```sh
|
||||
# Open page in WebKit
|
||||
npx playwright wk example.com
|
||||
```
|
||||
|
||||
### Emulate devices
|
||||
|
||||
`open` can emulate mobile and tablet devices ([see all devices](https://github.com/microsoft/playwright/blob/master/src/server/deviceDescriptors.ts)).
|
||||
|
||||
```sh
|
||||
# Emulate iPhone 11.
|
||||
npx playwright --device="iPhone 11" open wikipedia.org
|
||||
```
|
||||
|
||||
### Emulate color scheme and viewport size
|
||||
|
||||
```sh
|
||||
# Emulate screen size and color scheme.
|
||||
npx playwright --viewport-size=800,600 --color-scheme=dark open twitter.com
|
||||
```
|
||||
|
||||
### Emulate geolocation, language and timezone
|
||||
|
||||
```sh
|
||||
# Emulate timezone, language & location
|
||||
# Once page opens, click the "my location" button to see geolocation in action
|
||||
npx playwright --timezone="Europe/Rome" --geolocation="41.890221,12.492348" --lang="it-IT" open maps.google.com
|
||||
```
|
||||
|
||||
## Inspect selectors
|
||||
|
||||
During `open` or `codegen`, you can use following API inside the developer tools console of any browser.
|
||||
|
||||
<img src="https://user-images.githubusercontent.com/284612/92536317-37dd9380-f1ee-11ea-875d-daf1b206dd56.png"></img>
|
||||
|
||||
#### playwright.$(selector)
|
||||
|
||||
Query Playwright selector, using the actual Playwright query engine, for example:
|
||||
|
||||
```js
|
||||
> playwright.$('.auth-form >> text=Log in');
|
||||
|
||||
<button>Log in</button>
|
||||
```
|
||||
|
||||
#### playwright.$$(selector)
|
||||
|
||||
Same as `playwright.$`, but returns all matching elements.
|
||||
|
||||
```js
|
||||
> playwright.$$('li >> text=John')
|
||||
|
||||
> [<li>, <li>, <li>, <li>]
|
||||
```
|
||||
|
||||
#### playwright.inspect(selector)
|
||||
|
||||
Reveal element in the Elements panel (if DevTools of the respective browser supports it).
|
||||
|
||||
```js
|
||||
> playwright.inspect('text=Log in')
|
||||
```
|
||||
|
||||
#### playwright.selector(element)
|
||||
|
||||
Generates selector for the given element.
|
||||
|
||||
```js
|
||||
> playwright.selector($0)
|
||||
|
||||
"div[id="glow-ingress-block"] >> text=/.*Hello.*/"
|
||||
```
|
||||
|
||||
## Take screenshot
|
||||
|
||||
```sh
|
||||
# See command help
|
||||
$ npx playwright screenshot --help
|
||||
```
|
||||
|
||||
```sh
|
||||
# Wait 3 seconds before capturing a screenshot after page loads ('load' event fires)
|
||||
npx playwright \
|
||||
--device="iPhone 11" \
|
||||
--color-scheme=dark \
|
||||
screenshot \
|
||||
--wait-for-timeout=3000 \
|
||||
twitter.com twitter-iphone.png
|
||||
```
|
||||
|
||||
```sh
|
||||
# Capture a full page screenshot
|
||||
npx playwright screenshot --full-page en.wikipedia.org wiki-full.png
|
||||
```
|
||||
|
||||
## Generate PDF
|
||||
|
||||
PDF generation only works in Headless Chromium.
|
||||
|
||||
```sh
|
||||
# See command help
|
||||
$ npx playwright pdf https://en.wikipedia.org/wiki/PDF wiki.pdf
|
||||
```
|
||||
|
||||
## Known limitations
|
||||
|
||||
Opening WebKit Web Inspector will disconnect Playwright from the browser. In such cases, code generation will stop.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,436 +0,0 @@
|
|||
---
|
||||
id: core-concepts
|
||||
title: "Core concepts"
|
||||
---
|
||||
|
||||
Playwright provides a set of APIs to automate Chromium, Firefox and WebKit browsers. By using the Playwright API, you can write JavaScript code to create new browser pages, navigate to URLs and then interact with elements on a page.
|
||||
|
||||
Along with a test runner Playwright can be used to automate user interactions to validate and test web applications. The Playwright API enables this through the following primitives.
|
||||
|
||||
- [Browser](#browser)
|
||||
- [Browser contexts](#browser-contexts)
|
||||
- [Pages and frames](#pages-and-frames)
|
||||
- [Selectors](#selectors)
|
||||
- [Auto-waiting](#auto-waiting)
|
||||
- [Execution contexts: Node.js and Browser](#execution-contexts-nodejs-and-browser)
|
||||
- [Evaluation Argument](#evaluation-argument)
|
||||
- [Object & Element handles](#object--element-handles)
|
||||
|
||||
<br/>
|
||||
|
||||
## Browser
|
||||
|
||||
A [Browser] refers to an instance of Chromium, Firefox or WebKit. Playwright scripts generally start with launching a browser instance and end with closing the browser. Browser instances can be launched in headless (without a GUI) or headful mode.
|
||||
|
||||
```js
|
||||
const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'.
|
||||
|
||||
const browser = await chromium.launch({ headless: false });
|
||||
await browser.close();
|
||||
```
|
||||
|
||||
Launching a browser instance can be expensive, and Playwright is designed to maximize what a single instance can do through multiple browser contexts.
|
||||
|
||||
#### API reference
|
||||
- [Browser]
|
||||
|
||||
<br/>
|
||||
|
||||
## Browser contexts
|
||||
|
||||
A [BrowserContext] is an isolated incognito-alike session within a browser instance. Browser contexts are fast and cheap to create. Browser contexts can be used to parallelize isolated test executions.
|
||||
|
||||
```js
|
||||
const browser = await chromium.launch();
|
||||
const context = await browser.newContext();
|
||||
```
|
||||
|
||||
Browser contexts can also be used to emulate multi-page scenarios involving mobile devices, permissions, locale and color scheme.
|
||||
|
||||
```js
|
||||
const { devices } = require('playwright');
|
||||
const iPhone = devices['iPhone 11 Pro'];
|
||||
|
||||
const context = await browser.newContext({
|
||||
...iPhone,
|
||||
permissions: ['geolocation'],
|
||||
geolocation: { latitude: 52.52, longitude: 13.39},
|
||||
colorScheme: 'dark',
|
||||
locale: 'de-DE'
|
||||
});
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [BrowserContext]
|
||||
- [browser.newContext([options])](api/class-browser.md#browsernewcontextoptions)
|
||||
|
||||
<br/>
|
||||
|
||||
## Pages and frames
|
||||
|
||||
A Browser context can have multiple pages. A [Page] refers to a single tab or a popup window within a browser context. It should be used to navigate to URLs and interact with the page content.
|
||||
|
||||
```js
|
||||
// Create a page.
|
||||
const page = await context.newPage();
|
||||
|
||||
// Navigate explicitly, similar to entering a URL in the browser.
|
||||
await page.goto('http://example.com');
|
||||
// Fill an input.
|
||||
await page.fill('#search', 'query');
|
||||
|
||||
// Navigate implicitly by clicking a link.
|
||||
await page.click('#submit');
|
||||
// Expect a new url.
|
||||
console.log(page.url());
|
||||
|
||||
// Page can navigate from the script - this will be picked up by Playwright.
|
||||
window.location.href = 'https://example.com';
|
||||
```
|
||||
|
||||
> Read more on [page navigation and loading](./navigations.md).
|
||||
|
||||
A page can have one or more [Frame] objects attached to it. Each page has a main frame and page-level interactions (like `click`) are assumed to operate in the main frame.
|
||||
|
||||
A page can have additional frames attached with the `iframe` HTML tag. These frames can be accessed for interactions inside the frame.
|
||||
|
||||
```js
|
||||
// Get frame using the frame's name attribute
|
||||
const frame = page.frame('frame-login');
|
||||
|
||||
// Get frame using frame's URL
|
||||
const frame = page.frame({ url: /.*domain.*/ });
|
||||
|
||||
// Get frame using any other selector
|
||||
const frameElementHandle = await page.$('.frame-class');
|
||||
const frame = await frameElementHandle.contentFrame();
|
||||
|
||||
// Interact with the frame
|
||||
await frame.fill('#username-input', 'John');
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [Page]
|
||||
- [Frame]
|
||||
- [page.frame(frameSelector)](api/class-page.md#pageframeframeselector)
|
||||
|
||||
<br/>
|
||||
|
||||
## Selectors
|
||||
|
||||
Playwright can search for elements using CSS selectors, XPath selectors, HTML attributes like `id`, `data-test-id` and even text content.
|
||||
|
||||
You can explicitly specify the selector engine you are using or let Playwright detect it.
|
||||
|
||||
All selector engines except for XPath pierce shadow DOM by default. If you want to enforce regular DOM selection, you can use the `*:light` versions of the selectors. You don't typically need to though.
|
||||
|
||||
Learn more about selectors and selector engines [here](./selectors.md).
|
||||
|
||||
Some examples below:
|
||||
|
||||
```js
|
||||
// Using data-test-id= selector engine
|
||||
await page.click('data-test-id=foo');
|
||||
```
|
||||
|
||||
```js
|
||||
// CSS and XPath selector engines are automatically detected
|
||||
await page.click('div');
|
||||
await page.click('//html/body/div');
|
||||
```
|
||||
|
||||
```js
|
||||
// Find node by text substring
|
||||
await page.click('text=Hello w');
|
||||
```
|
||||
|
||||
```js
|
||||
// Explicit CSS and XPath notation
|
||||
await page.click('css=div');
|
||||
await page.click('xpath=//html/body/div');
|
||||
```
|
||||
|
||||
```js
|
||||
// Only search light DOM, outside WebComponent shadow DOM:
|
||||
await page.click('css:light=div');
|
||||
```
|
||||
|
||||
Selectors using the same or different engines can be combined using the `>>` separator. For example,
|
||||
|
||||
```js
|
||||
// Click an element with text 'Sign Up' inside of a #free-month-promo.
|
||||
await page.click('#free-month-promo >> text=Sign Up');
|
||||
```
|
||||
|
||||
```js
|
||||
// Capture textContent of a section that contains an element with text 'Selectors'.
|
||||
const sectionText = await page.$eval('*css=section >> text=Selectors', e => e.textContent);
|
||||
```
|
||||
|
||||
<br/>
|
||||
|
||||
## Auto-waiting
|
||||
|
||||
Actions like `click` and `fill` auto-wait for the element to be visible and [actionable](./actionability.md). For example, click will:
|
||||
- wait for an element with the given selector to appear in the DOM
|
||||
- wait for it to become visible: have non-empty bounding box and no `visibility:hidden`
|
||||
- wait for it to stop moving: for example, wait until css transition finishes
|
||||
- scroll the element into view
|
||||
- wait for it to receive pointer events at the action point: for example, wait until element becomes non-obscured by other elements
|
||||
- retry if the element is detached during any of the above checks
|
||||
|
||||
```js
|
||||
// Playwright waits for #search element to be in the DOM
|
||||
await page.fill('#search', 'query');
|
||||
```
|
||||
|
||||
```js
|
||||
// Playwright waits for element to stop animating
|
||||
// and accept clicks.
|
||||
await page.click('#search');
|
||||
```
|
||||
|
||||
You can explicitly wait for an element to appear in the DOM or to become visible:
|
||||
|
||||
```js
|
||||
// Wait for #search to appear in the DOM.
|
||||
await page.waitForSelector('#search', { state: 'attached' });
|
||||
// Wait for #promo to become visible, for example with `visibility:visible`.
|
||||
await page.waitForSelector('#promo');
|
||||
```
|
||||
|
||||
... or to become hidden or detached
|
||||
|
||||
```js
|
||||
// Wait for #details to become hidden, for example with `display:none`.
|
||||
await page.waitForSelector('#details', { state: 'hidden' });
|
||||
// Wait for #promo to be removed from the DOM.
|
||||
await page.waitForSelector('#promo', { state: 'detached' });
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [page.click(selector[, options])](api/class-page.md#pageclickselector-options)
|
||||
- [page.fill(selector, value[, options])](api/class-page.md#pagefillselector-value-options)
|
||||
- [page.waitForSelector(selector[, options])](api/class-page.md#pagewaitforselectorselector-options)
|
||||
|
||||
<br/>
|
||||
|
||||
## Execution contexts: Node.js and Browser
|
||||
|
||||
Playwright scripts run in your Node.js environment. Your page scripts run in the browser page environment. Those environments don't intersect, they are running in different virtual machines in different processes and even potentially on different computers.
|
||||
|
||||
The [page.evaluate(pageFunction[, arg])](api/class-page.md#pageevaluatepagefunction-arg) API can run a JavaScript function in the context of the web page and bring results back to the Node.js environment. Browser globals like `window` and `document` can be used in `evaluate`.
|
||||
|
||||
```js
|
||||
const href = await page.evaluate(() => document.location.href);
|
||||
```
|
||||
|
||||
If the result is a Promise or if the function is asynchronous evaluate will automatically wait until it's resolved:
|
||||
|
||||
```js
|
||||
const status = await page.evaluate(async () => {
|
||||
const response = await fetch(location.href);
|
||||
return response.status;
|
||||
});
|
||||
```
|
||||
|
||||
## Evaluation Argument
|
||||
|
||||
Playwright evaluation methods like [page.evaluate(pageFunction[, arg])](api/class-page.md#pageevaluatepagefunction-arg) take a single optional argument. This argument can be a mix of [Serializable] values and [JSHandle] or [ElementHandle] instances. Handles are automatically converted to the value they represent.
|
||||
|
||||
```js
|
||||
// A primitive value.
|
||||
await page.evaluate(num => num, 42);
|
||||
|
||||
// An array.
|
||||
await page.evaluate(array => array.length, [1, 2, 3]);
|
||||
|
||||
// An object.
|
||||
await page.evaluate(object => object.foo, { foo: 'bar' });
|
||||
|
||||
// A single handle.
|
||||
const button = await page.$('button');
|
||||
await page.evaluate(button => button.textContent, button);
|
||||
|
||||
// Alternative notation using elementHandle.evaluate.
|
||||
await button.evaluate((button, from) => button.textContent.substring(from), 5);
|
||||
|
||||
// Object with multiple handles.
|
||||
const button1 = await page.$('.button1');
|
||||
const button2 = await page.$('.button2');
|
||||
await page.evaluate(
|
||||
o => o.button1.textContent + o.button2.textContent,
|
||||
{ button1, button2 });
|
||||
|
||||
// Object destructuring works. Note that property names must match
|
||||
// between the destructured object and the argument.
|
||||
// Also note the required parenthesis.
|
||||
await page.evaluate(
|
||||
({ button1, button2 }) => button1.textContent + button2.textContent,
|
||||
{ button1, button2 });
|
||||
|
||||
// Array works as well. Arbitrary names can be used for destructuring.
|
||||
// Note the required parenthesis.
|
||||
await page.evaluate(
|
||||
([b1, b2]) => b1.textContent + b2.textContent,
|
||||
[button1, button2]);
|
||||
|
||||
// Any non-cyclic mix of serializables and handles works.
|
||||
await page.evaluate(
|
||||
x => x.button1.textContent + x.list[0].textContent + String(x.foo),
|
||||
{ button1, list: [button2], foo: null });
|
||||
```
|
||||
|
||||
Right:
|
||||
|
||||
```js
|
||||
const data = { text: 'some data', value: 1 };
|
||||
// Pass |data| as a parameter.
|
||||
const result = await page.evaluate(data => {
|
||||
window.myApp.use(data);
|
||||
}, data);
|
||||
```
|
||||
|
||||
Wrong:
|
||||
|
||||
```js
|
||||
const data = { text: 'some data', value: 1 };
|
||||
const result = await page.evaluate(() => {
|
||||
// There is no |data| in the web page.
|
||||
window.myApp.use(data);
|
||||
});
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [page.evaluate(pageFunction[, arg])](api/class-page.md#pageevaluatepagefunction-arg)
|
||||
- [frame.evaluate(pageFunction[, arg])](api/class-frame.md#frameevaluatepagefunction-arg)
|
||||
- [EvaluationArgument]
|
||||
|
||||
<br/>
|
||||
|
||||
## Object & Element handles
|
||||
|
||||
Playwright can create Node-side handles to the page DOM elements or any other objects inside the page. These handles live in the Node.js process, whereas the actual objects reside in browser.
|
||||
|
||||
There are two types of handles:
|
||||
- [JSHandle] to reference any JavaScript objects in the page
|
||||
- [ElementHandle] to reference DOM elements in the page
|
||||
|
||||
Note that since any DOM element in the page is also a JavaScript object, Playwright's [ElementHandle] extends [JSHandle].
|
||||
|
||||
### Handles Lifecycle
|
||||
- Handles can be acquired using the page methods [page.evaluateHandle(pageFunction[, arg])](api/class-page.md#pageevaluatehandlepagefunction-arg), [page.$(selector)](api/class-page.md#pageselector) or [page.$$(selector)](api/class-page.md#pageselector-1) or their frame counterparts [frame.evaluateHandle(pageFunction[, arg])](api/class-frame.md#frameevaluatehandlepagefunction-arg), [frame.$(selector)](api/class-frame.md#frameselector) or [frame.$$(selector)](api/class-frame.md#frameselector-1).
|
||||
- Once created, handles will retain object from [garbage collection](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Memory_Management).
|
||||
- Handles will be **automatically disposed** once the page or frame they belong to navigates or closes.
|
||||
- Handles can be **manually disposed** using [jsHandle.dispose()](api/class-jshandle.md#jshandledispose) method.
|
||||
|
||||
### Example: ElementHandle
|
||||
|
||||
```js
|
||||
// The first parameter of the elementHandle.evaluate callback is the element handle points to.
|
||||
const ulElementHandle = await page.$('ul');
|
||||
await ulElementHandle.evaluate(ulElement => getComputedStyle(ulElement).getPropertyValue('display'));
|
||||
```
|
||||
|
||||
Handles can also be passed as arguments to [page.evaluate(pageFunction[, arg])](api/class-page.md#pageevaluatepagefunction-arg) function:
|
||||
|
||||
```js
|
||||
// In the page API, you can pass handle as a parameter.
|
||||
const ulElementHandle = await page.$('ul');
|
||||
await page.evaluate(uiElement => getComputedStyle(uiElement).getPropertyValue('display'), uiElement);
|
||||
```
|
||||
|
||||
### Example: JSHandle
|
||||
|
||||
```js
|
||||
// Create a new array in the page, write a reference to it in
|
||||
// window.myArray and get a handle to it.
|
||||
const myArrayHandle = await page.evaluateHandle(() => {
|
||||
window.myArray = [1];
|
||||
return myArray;
|
||||
});
|
||||
|
||||
// Get current length of the array using the handle.
|
||||
const length = await page.evaluate(
|
||||
(arg) => arg.myArray.length,
|
||||
{ myArray: myArrayHandle }
|
||||
);
|
||||
|
||||
// Add one more element to the array using the handle
|
||||
await page.evaluate((arg) => arg.myArray.push(arg.newElement), {
|
||||
myArray: myArrayHandle,
|
||||
newElement: 2
|
||||
});
|
||||
|
||||
// Get current length of the array using window.myArray reference.
|
||||
const newLength = await page.evaluate(() => window.myArray.length);
|
||||
|
||||
// Release the object when it's no longer needed.
|
||||
await myArrayHandle.dispose();
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [JSHandle]
|
||||
- [ElementHandle]
|
||||
- [page.evaluateHandle(pageFunction[, arg])](api/class-page.md#pageevaluatehandlepagefunction-arg)
|
||||
- [page.$(selector)](api/class-page.md#pageselector)
|
||||
- [page.$$(selector)](api/class-page.md#pageselector-1)
|
||||
- [jsHandle.evaluate(pageFunction[, arg])](api/class-jshandle.md#jshandleevaluatepagefunction-arg)
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,168 +0,0 @@
|
|||
---
|
||||
id: debug
|
||||
title: "Debugging tools"
|
||||
---
|
||||
|
||||
Playwright scripts work with existing debugging tools, like Node.js debuggers and browser developer tools. Playwright also introduces new debugging features for browser automation.
|
||||
|
||||
- [Run in headful mode](#run-in-headful-mode)
|
||||
- [Visual Studio Code debugger](#visual-studio-code-debugger)
|
||||
- [Browser Developer Tools](#browser-developer-tools)
|
||||
- [Run in Debug Mode](#run-in-debug-mode)
|
||||
- [Verbose API logs](#verbose-api-logs)
|
||||
|
||||
## Run in headful mode
|
||||
|
||||
Playwright runs browsers in headless mode by default. To change this behavior, use `headless: false` as a launch option. You can also use the `slowMo` option to slow down execution and follow along while debugging.
|
||||
|
||||
```js
|
||||
await chromium.launch({ headless: false, slowMo: 100 }); // or firefox, webkit
|
||||
```
|
||||
|
||||
## Visual Studio Code debugger
|
||||
|
||||
The VS Code debugger can be used to pause and resume execution of Playwright scripts with breakpoints. The debugger can be configured in two ways.
|
||||
|
||||
### Use launch config
|
||||
|
||||
Setup [`launch.json` configuration](https://code.visualstudio.com/docs/nodejs/nodejs-debugging) for your Node.js project. Once configured launch the scripts with F5 and use breakpoints.
|
||||
|
||||
### Use the new JavaScript debugger
|
||||
|
||||
VS Code 1.46+ introduces the new JavaScript debugger behind a feature flag. The new debugger does not require a `launch.json` configuration. To use this:
|
||||
1. Enable the preview debugger
|
||||
* Open JSON settings and add `"debug.javascript.usePreview": true`
|
||||
* Open settings UI and enable the `Debug › JavaScript: Use Preview` setting
|
||||
1. Set a breakpoint in VS Code
|
||||
* Use the `debugger` keyword or set a breakpoint in the VS Code UI
|
||||
1. Run your Node.js script from the terminal
|
||||
|
||||
## Browser Developer Tools
|
||||
|
||||
You can use browser developer tools in Chromium, Firefox and WebKit while running a Playwright script. Developer tools help to:
|
||||
* Inspect the DOM tree and **find element selectors**
|
||||
* **See console logs** during execution (or learn how to [read logs via API](./verification.md#console-logs))
|
||||
* Check **network activity** and other developer tools features
|
||||
|
||||
<a href="https://user-images.githubusercontent.com/284612/77234134-5f21a500-6b69-11ea-92ec-1c146e1333ec.png"><img src="https://user-images.githubusercontent.com/284612/77234134-5f21a500-6b69-11ea-92ec-1c146e1333ec.png" width="500" alt="Chromium Developer Tools"></img></a>
|
||||
|
||||
> **For WebKit**: Note that launching WebKit Inspector during the execution will prevent the Playwright script from executing any further.
|
||||
|
||||
### API for Chromium
|
||||
|
||||
In Chromium, you can also open developer tools through a launch option.
|
||||
|
||||
```js
|
||||
await chromium.launch({ devtools: true });
|
||||
```
|
||||
|
||||
## Run in Debug Mode
|
||||
|
||||
Set the `PWDEBUG` environment variable to run your scripts in debug mode. This configures the browser for debugging.
|
||||
|
||||
```sh
|
||||
# Linux/macOS
|
||||
$ PWDEBUG=1 npm run test
|
||||
|
||||
# Windows
|
||||
$ set PWDEBUG=1
|
||||
$ npm run test
|
||||
```
|
||||
|
||||
### Defaults
|
||||
|
||||
With PWDEBUG, the following defaults are configured for you:
|
||||
* **Run in headful**: With PWDEBUG, browsers always launch in headful mode
|
||||
* **Disables timeout**: PWDEBUG sets timeout to 0 (= no timeout)
|
||||
* **Preserve DevTools preferences**: When used with `devtools: true`, PWDEBUG preserves the docked/undocked state of Chrome DevTools
|
||||
|
||||
### Debugging Selectors
|
||||
|
||||
PWDEBUG configures a `playwright` object in the browser to highlight [Playwright selectors](./selectors.md). This can be used to verify text or composite selectors. To use this:
|
||||
1. Setup a breakpoint to pause the execution
|
||||
1. Open the console panel in browser developer tools
|
||||
1. Use the `playwright` API
|
||||
* `playwright.$(selector)`: Highlight the first occurrence of the selector. This reflects how `page.$` would see the page.
|
||||
* `playwright.$$(selector)`: Highlight all occurrences of the selector. This reflects how `page.$$` would see the page.
|
||||
* `playwright.inspect(selector)`: Inspect the selector in the Elements panel.
|
||||
* `playwright.clear()`: Clear existing highlights.
|
||||
|
||||
<a href="https://user-images.githubusercontent.com/284612/86857345-299abc00-c073-11ea-9e31-02923a9f0d4b.png"><img src="https://user-images.githubusercontent.com/284612/86857345-299abc00-c073-11ea-9e31-02923a9f0d4b.png" width="500" alt="Highlight selectors"></img></a>
|
||||
|
||||
### Evaluate Source Maps
|
||||
|
||||
PWDEBUG also enables source maps for [`page.evaluate` executions](core-concepts.md#evaluation). This improves the debugging experience for JavaScript executions in the page context.
|
||||
|
||||
<a href="https://user-images.githubusercontent.com/284612/86857568-a6c63100-c073-11ea-82a4-bfd531a4ec87.png"><img src="https://user-images.githubusercontent.com/284612/86857568-a6c63100-c073-11ea-82a4-bfd531a4ec87.png" width="500" alt="Highlight selectors"></img></a>
|
||||
|
||||
## Verbose API logs
|
||||
|
||||
Playwright supports verbose logging with the `DEBUG` environment variable.
|
||||
|
||||
```sh
|
||||
# Linux/macOS
|
||||
$ DEBUG=pw:api npm run test
|
||||
|
||||
# Windows
|
||||
$ set DEBUG=pw:api
|
||||
$ npm run test
|
||||
```
|
||||
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,169 +0,0 @@
|
|||
---
|
||||
id: docker
|
||||
title: "Docker"
|
||||
---
|
||||
|
||||
[Dockerfile.bionic](https://github.com/microsoft/playwright/blob/master/utils/docker/Dockerfile.bionic) and [Dockerfile.focal](https://github.com/microsoft/playwright/blob/master/utils/docker/Dockerfile.focal) can be used to run Playwright scripts in Docker environments. These images includes all the dependencies needed to run browsers in a Docker container, including browsers.
|
||||
|
||||
- [Usage](#usage)
|
||||
- [Image tags](#image-tags)
|
||||
- [Development](#development)
|
||||
- [Base images](#base-images)
|
||||
|
||||
## Usage
|
||||
|
||||
[](https://hub.docker.com/_/microsoft-playwright)
|
||||
|
||||
This image is published on [Docker Hub](https://hub.docker.com/_/microsoft-playwright).
|
||||
|
||||
### Pull the image
|
||||
|
||||
```
|
||||
$ docker pull mcr.microsoft.com/playwright:bionic
|
||||
```
|
||||
|
||||
### Run the image
|
||||
|
||||
By default, the Docker image will use the `root` user to run the browsers. This will disable the Chromium sandbox which is not available with root. If you run trusted code (e.g. End-to-end tests) and want to avoid the hassle of managing separate user then the root user may be fine. For web scraping or crawling, we recommend to create a separate user inside the Docker container and use the seccomp profile.
|
||||
|
||||
#### End-to-end tests
|
||||
|
||||
On trusted websites, you can avoid creating a separate user and use root for it since you trust the code which will run on the browsers.
|
||||
|
||||
```
|
||||
docker run -it --rm --ipc=host mcr.microsoft.com/playwright:bionic /bin/bash
|
||||
```
|
||||
|
||||
#### Crawling and scraping
|
||||
|
||||
On untrusted websites, it's recommended to use a separate user for launching the browsers in combination with the seccomp profile. Inside the container or if you are using the Docker image as a base image you have to use `adduser` for it.
|
||||
|
||||
```
|
||||
$ docker run -it --rm --ipc=host --user pwuser --security-opt seccomp=seccomp_profile.json mcr.microsoft.com/playwright:bionic /bin/bash
|
||||
```
|
||||
|
||||
[`seccomp_profile.json`](https://github.com/microsoft/playwright/blob/master/utils/docker/seccomp_profile.json) is needed to run Chromium with sandbox. This is a [default Docker seccomp profile](https://github.com/docker/engine/blob/d0d99b04cf6e00ed3fc27e81fc3d94e7eda70af3/profiles/seccomp/default.json) with extra user namespace cloning permissions:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"comment": "Allow create user namespaces",
|
||||
"names": [
|
||||
"clone",
|
||||
"setns",
|
||||
"unshare"
|
||||
],
|
||||
"action": "SCMP_ACT_ALLOW",
|
||||
"args": [],
|
||||
"includes": {},
|
||||
"excludes": {}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
> **NOTE**: Using `--ipc=host` is recommended when using Chrome ([Docker docs](https://docs.docker.com/engine/reference/run/#ipc-settings---ipc)). Chrome can run out of memory without this flag.
|
||||
|
||||
### Using on CI
|
||||
|
||||
See our [Continuous Integration guides](./ci.md) for sample configs.
|
||||
|
||||
## Image tags
|
||||
|
||||
See [all available image tags](https://mcr.microsoft.com/v2/playwright/tags/list).
|
||||
|
||||
## Development
|
||||
|
||||
### Build the image
|
||||
|
||||
Use [`//utils/docker/build.sh`](https://github.com/microsoft/playwright/blob/master/utils/docker/build.sh) to build the image.
|
||||
|
||||
```
|
||||
$ ./utils/docker/build.sh bionic playwright:localbuild-bionic
|
||||
```
|
||||
|
||||
The image will be tagged as `playwright:localbuild-bionic` and could be run as:
|
||||
|
||||
```
|
||||
$ docker run --rm -it playwright:localbuild /bin/bash
|
||||
```
|
||||
|
||||
### Push
|
||||
|
||||
Docker images are published automatically by GitHub Actions. We currently publish the following images:
|
||||
- `mcr.microsoft.com/playwright:next` - tip-of-tree image version.
|
||||
- `mcr.microsoft.com/playwright:bionic` - last Playwright release docker image.
|
||||
- `mcr.microsoft.com/playwright:sha-XXXXXXX` - docker image for every commit that changed docker files or browsers, marked with a [short sha](https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection#Short-SHA-1) (first 7 digits of the SHA commit).
|
||||
|
||||
Status of push to MCR can be [verified here](https://mcrflow-status-ui.azurewebsites.net/) (internal link).
|
||||
|
||||
## Base images
|
||||
|
||||
### Ubuntu 20
|
||||
|
||||
`mcr.microsoft.com/playwright:focal` is based on Ubuntu 20.04 LTS (Focal Fossa).
|
||||
|
||||
### Ubuntu 18
|
||||
|
||||
`mcr.microsoft.com/playwright:bionic` is based on Ubuntu 18.04 LTS (Bionic Beaver).
|
||||
|
||||
### Alpine
|
||||
|
||||
Browser builds for Firefox and WebKit are built for the [glibc](https://en.wikipedia.org/wiki/GNU_C_Library) library. Alpine Linux and other distributions that are based on the [musl](https://en.wikipedia.org/wiki/Musl) standard library are not supported.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,242 +0,0 @@
|
|||
---
|
||||
id: emulation
|
||||
title: "Device and environment emulation"
|
||||
---
|
||||
|
||||
Playwright allows overriding various parameters of the device where the browser is running:
|
||||
- viewport size, device scale factor, touch support
|
||||
- locale, timezone
|
||||
- color scheme
|
||||
- geolocation
|
||||
|
||||
Most of these parameters are configured during the browser context construction, but some of them such as viewport size can be changed for individual pages.
|
||||
|
||||
- [Devices](#devices)
|
||||
- [User agent](#user-agent)
|
||||
- [Viewport](#viewport)
|
||||
- [Locale & timezone](#locale--timezone)
|
||||
- [Permissions](#permissions)
|
||||
- [Geolocation](#geolocation)
|
||||
- [Color scheme and media](#color-scheme-and-media)
|
||||
|
||||
<br/>
|
||||
|
||||
## Devices
|
||||
|
||||
Playwright comes with a registry of device parameters for selected mobile devices. It can be used to simulate browser behavior on a mobile device:
|
||||
|
||||
```js
|
||||
const { chromium, devices } = require('playwright');
|
||||
const browser = await chromium.launch();
|
||||
|
||||
const pixel2 = devices['Pixel 2'];
|
||||
const context = await browser.newContext({
|
||||
...pixel2,
|
||||
});
|
||||
```
|
||||
|
||||
All pages created in the context above will share the same device parameters.
|
||||
|
||||
#### API reference
|
||||
- [playwright.devices](api/class-playwright.md#playwrightdevices)
|
||||
- [browser.newContext([options])](api/class-browser.md#browsernewcontextoptions)
|
||||
|
||||
<br/>
|
||||
|
||||
## User agent
|
||||
|
||||
All pages created in the context above will share the user agent specified:
|
||||
|
||||
```js
|
||||
const context = await browser.newContext({
|
||||
userAgent: 'My user agent'
|
||||
});
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [browser.newContext([options])](api/class-browser.md#browsernewcontextoptions)
|
||||
|
||||
<br/>
|
||||
|
||||
## Viewport
|
||||
|
||||
Create a context with custom viewport size:
|
||||
|
||||
```js
|
||||
// Create context with given viewport
|
||||
const context = await browser.newContext({
|
||||
viewport: { width: 1280, height: 1024 }
|
||||
});
|
||||
|
||||
// Resize viewport for individual page
|
||||
await page.setViewportSize({ width: 1600, height: 1200 });
|
||||
|
||||
// Emulate high-DPI
|
||||
const context = await browser.newContext({
|
||||
viewport: { width: 2560, height: 1440 },
|
||||
deviceScaleFactor: 2,
|
||||
});
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [browser.newContext([options])](api/class-browser.md#browsernewcontextoptions)
|
||||
- [page.setViewportSize(viewportSize)](api/class-page.md#pagesetviewportsizeviewportsize)
|
||||
|
||||
<br/>
|
||||
|
||||
## Locale & timezone
|
||||
|
||||
```js
|
||||
// Emulate locale and time
|
||||
const context = await browser.newContext({
|
||||
locale: 'de-DE',
|
||||
timezoneId: 'Europe/Berlin',
|
||||
});
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [browser.newContext([options])](api/class-browser.md#browsernewcontextoptions)
|
||||
|
||||
<br/>
|
||||
|
||||
## Permissions
|
||||
|
||||
Allow all pages in the context to show system notifications:
|
||||
|
||||
```js
|
||||
const context = await browser.newContext({
|
||||
permissions: ['notifications'],
|
||||
});
|
||||
```
|
||||
|
||||
Grant all pages in the existing context access to current location:
|
||||
|
||||
```js
|
||||
await context.grantPermissions(['geolocation']);
|
||||
```
|
||||
|
||||
Grant notifications access from a specific domain:
|
||||
|
||||
```js
|
||||
await context.grantPermissions(['notifications'], {origin: 'https://skype.com'} );
|
||||
```
|
||||
|
||||
Revoke all permissions:
|
||||
|
||||
```js
|
||||
await context.clearPermissions();
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [browser.newContext([options])](api/class-browser.md#browsernewcontextoptions)
|
||||
- [browserContext.grantPermissions(permissions[, options])](api/class-browsercontext.md#browsercontextgrantpermissionspermissions-options)
|
||||
- [browserContext.clearPermissions()](api/class-browsercontext.md#browsercontextclearpermissions)
|
||||
|
||||
<br/>
|
||||
|
||||
## Geolocation
|
||||
|
||||
Create a context with `"geolocation"` permissions granted:
|
||||
|
||||
```js
|
||||
const context = await browser.newContext({
|
||||
geolocation: { longitude: 48.858455, latitude: 2.294474 },
|
||||
permissions: ['geolocation']
|
||||
});
|
||||
```
|
||||
|
||||
```js
|
||||
await context.setGeolocation({ longitude: 29.979097, latitude: 31.134256 });
|
||||
```
|
||||
|
||||
**Note** you can only change geolocation for all pages in the context.
|
||||
|
||||
#### API reference
|
||||
- [browser.newContext([options])](api/class-browser.md#browsernewcontextoptions)
|
||||
- [browserContext.setGeolocation(geolocation)](api/class-browsercontext.md#browsercontextsetgeolocationgeolocation)
|
||||
|
||||
<br/>
|
||||
|
||||
## Color scheme and media
|
||||
|
||||
Create a context with dark or light mode. Pages created in this context will follow this color scheme preference.
|
||||
|
||||
```js
|
||||
// Create context with dark mode
|
||||
const context = await browser.newContext({
|
||||
colorScheme: 'dark' // or 'light'
|
||||
});
|
||||
|
||||
// Create page with dark mode
|
||||
const page = await browser.newPage({
|
||||
colorScheme: 'dark' // or 'light'
|
||||
});
|
||||
|
||||
// Change color scheme for the page
|
||||
await page.emulateMedia({ colorScheme: 'dark' });
|
||||
|
||||
// Change media for page
|
||||
await page.emulateMedia({ media: 'print' });
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [browser.newContext([options])](api/class-browser.md#browsernewcontextoptions)
|
||||
- [page.emulateMedia(params)](api/class-page.md#pageemulatemediaparams)
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,105 +0,0 @@
|
|||
---
|
||||
id: extensibility
|
||||
title: "Extensibility"
|
||||
---
|
||||
|
||||
- [Custom selector engines](#custom-selector-engines)
|
||||
|
||||
## Custom selector engines
|
||||
|
||||
Playwright supports custom selector engines, registered with [selectors.register(name, script[, options])](api/class-selectors.md#selectorsregistername-script-options).
|
||||
|
||||
Selector engine should have the following properties:
|
||||
- `create` function to create a relative selector from `root` (root is either a `Document`, `ShadowRoot` or `Element`) to a `target` element.
|
||||
- `query` function to query first element matching `selector` relative to the `root`.
|
||||
- `queryAll` function to query all elements matching `selector` relative to the `root`.
|
||||
|
||||
By default the engine is run directly in the frame's JavaScript context and, for example, can call an application-defined function. To isolate the engine from any JavaScript in the frame, but leave access to the DOM, register the engine with `{contentScript: true}` option. Content script engine is safer because it is protected from any tampering with the global objects, for example altering `Node.prototype` methods. All built-in selector engines run as content scripts. Note that running as a content script is not guaranteed when the engine is used together with other custom engines.
|
||||
|
||||
An example of registering selector engine that queries elements based on a tag name:
|
||||
|
||||
```js
|
||||
// Must be a function that evaluates to a selector engine instance.
|
||||
const createTagNameEngine = () => ({
|
||||
// Returns the first element matching given selector in the root's subtree.
|
||||
query(root, selector) {
|
||||
return root.querySelector(selector);
|
||||
},
|
||||
|
||||
// Returns all elements matching given selector in the root's subtree.
|
||||
queryAll(root, selector) {
|
||||
return Array.from(root.querySelectorAll(selector));
|
||||
}
|
||||
});
|
||||
|
||||
// Register the engine. Selectors will be prefixed with "tag=".
|
||||
await selectors.register('tag', createTagNameEngine);
|
||||
|
||||
// Now we can use 'tag=' selectors.
|
||||
const button = await page.$('tag=button');
|
||||
|
||||
// We can combine it with other selector engines using `>>` combinator.
|
||||
await page.click('tag=div >> span >> "Click me"');
|
||||
|
||||
// We can use it in any methods supporting selectors.
|
||||
const buttonCount = await page.$$eval('tag=button', buttons => buttons.length);
|
||||
```
|
||||
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,329 +0,0 @@
|
|||
---
|
||||
id: input
|
||||
title: "Input"
|
||||
---
|
||||
|
||||
- [Text input](#text-input)
|
||||
- [Checkboxes and radio buttons](#checkboxes-and-radio-buttons)
|
||||
- [Select options](#select-options)
|
||||
- [Mouse click](#mouse-click)
|
||||
- [Type characters](#type-characters)
|
||||
- [Keys and shortcuts](#keys-and-shortcuts)
|
||||
- [Upload files](#upload-files)
|
||||
- [Focus element](#focus-element)
|
||||
|
||||
## Text input
|
||||
|
||||
This is the easiest way to fill out the form fields. It focuses the element and triggers an `input` event with the entered text. It works for `<input>`, `<textarea>`, `[contenteditable]` and `<label>` associated with an input or textarea.
|
||||
|
||||
```js
|
||||
// Text input
|
||||
await page.fill('#name', 'Peter');
|
||||
|
||||
// Date input
|
||||
await page.fill('#date', '2020-02-02');
|
||||
|
||||
// Time input
|
||||
await page.fill('#time', '13-15');
|
||||
|
||||
// Local datetime input
|
||||
await page.fill('#local', '2020-03-02T05:15');
|
||||
|
||||
// Input through label
|
||||
await page.fill('text=First Name', 'Peter');
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [page.fill(selector, value[, options])](api/class-page.md#pagefillselector-value-options)
|
||||
- [frame.fill(selector, value[, options])](api/class-frame.md#framefillselector-value-options)
|
||||
- [elementHandle.fill(value[, options])](api/class-elementhandle.md#elementhandlefillvalue-options)
|
||||
|
||||
<br/>
|
||||
|
||||
## Checkboxes and radio buttons
|
||||
|
||||
This is the easiest way to check and uncheck a checkbox or a radio button. This method can be used with `input[type=checkbox]`, `input[type=radio]`, `[role=checkbox]` or `label` associated with checkbox or radio button.
|
||||
|
||||
```js
|
||||
// Check the checkbox
|
||||
await page.check('#agree');
|
||||
|
||||
// Uncheck by input <label>.
|
||||
await page.uncheck('#subscribe-label');
|
||||
|
||||
// Select the radio button
|
||||
await page.check('text=XL');
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [page.check(selector[, options])](api/class-page.md#pagecheckselector-options)
|
||||
- [page.uncheck(selector[, options])](api/class-page.md#pageuncheckselector-options)
|
||||
- [frame.check(selector[, options])](api/class-frame.md#framecheckselector-options)
|
||||
- [frame.uncheck(selector[, options])](api/class-frame.md#frameuncheckselector-options)
|
||||
- [elementHandle.check([options])](api/class-elementhandle.md#elementhandlecheckoptions)
|
||||
- [elementHandle.uncheck([options])](api/class-elementhandle.md#elementhandleuncheckoptions)
|
||||
|
||||
<br/>
|
||||
|
||||
## Select options
|
||||
|
||||
Selects one or multiple options in the `<select>` element. You can specify option `value`, `label` or `elementHandle` to select. Multiple options can be selected.
|
||||
|
||||
```js
|
||||
// Single selection matching the value
|
||||
await page.selectOption('select#colors', 'blue');
|
||||
|
||||
// Single selection matching the label
|
||||
await page.selectOption('select#colors', { label: 'Blue' });
|
||||
|
||||
// Multiple selected items
|
||||
await page.selectOption('select#colors', ['red', 'green', 'blue']);
|
||||
|
||||
// Select the option via element handle
|
||||
const option = await page.$('#best-option');
|
||||
await page.selectOption('select#colors', option);
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [page.selectOption(selector, values[, options])](api/class-page.md#pageselectoptionselector-values-options)
|
||||
- [frame.selectOption(selector, values[, options])](api/class-frame.md#frameselectoptionselector-values-options)
|
||||
- [elementHandle.selectOption(values[, options])](api/class-elementhandle.md#elementhandleselectoptionvalues-options)
|
||||
|
||||
<br/>
|
||||
|
||||
## Mouse click
|
||||
|
||||
Performs a simple human click.
|
||||
|
||||
```js
|
||||
// Generic click
|
||||
await page.click('button#submit');
|
||||
|
||||
// Double click
|
||||
await page.dblclick('#item');
|
||||
|
||||
// Right click
|
||||
await page.click('#item', { button: 'right' });
|
||||
|
||||
// Shift + click
|
||||
await page.click('#item', { modifiers: ['Shift'] });
|
||||
|
||||
// Hover over element
|
||||
await page.hover('#item');
|
||||
|
||||
// Click the top left corner
|
||||
await page.click('#item', { position: { x: 0, y: 0} });
|
||||
```
|
||||
|
||||
Under the hood, this and other pointer-related methods:
|
||||
- wait for element with given selector to be in DOM
|
||||
- wait for it to become displayed, i.e. not empty, no `display:none`, no `visibility:hidden`
|
||||
- wait for it to stop moving, for example, until css transition finishes
|
||||
- scroll the element into view
|
||||
- wait for it to receive pointer events at the action point, for example, waits until element becomes non-obscured by other elements
|
||||
- retry if the element is detached during any of the above checks
|
||||
|
||||
#### Forcing the click
|
||||
|
||||
Sometimes, apps use non-trivial logic where hovering the element overlays it with another element that intercepts the click. This behavior is indistinguishable from a bug where element gets covered and the click is dispatched elsewhere. If you know this is taking place, you can bypass the [actionability](./actionability.md) checks and force the click:
|
||||
|
||||
```js
|
||||
await page.click('button#submit', { force: true });
|
||||
```
|
||||
|
||||
#### Programmatic click
|
||||
|
||||
If you are not interested in testing your app under the real conditions and want to simulate the click by any means possible, you can trigger the [`HTMLElement.click()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click) behavior via simply dispatching a click event on the element:
|
||||
|
||||
```js
|
||||
await page.dispatchEvent('button#submit', 'click');
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [page.click(selector[, options])](api/class-page.md#pageclickselector-options)
|
||||
- [frame.click(selector[, options])](api/class-frame.md#frameclickselector-options)
|
||||
- [elementHandle.click([options])](api/class-elementhandle.md#elementhandleclickoptions)
|
||||
- [page.dblclick(selector[, options])](api/class-page.md#pagedblclickselector-options)
|
||||
- [frame.dblclick(selector[, options])](api/class-frame.md#framedblclickselector-options)
|
||||
- [elementHandle.dblclick([options])](api/class-elementhandle.md#elementhandledblclickoptions)
|
||||
- [page.hover(selector[, options])](api/class-page.md#pagehoverselector-options)
|
||||
- [frame.hover(selector[, options])](api/class-frame.md#framehoverselector-options)
|
||||
- [elementHandle.hover([options])](api/class-elementhandle.md#elementhandlehoveroptions)
|
||||
- [page.dispatchEvent(selector, type[, eventInit, options])](api/class-page.md#pagedispatcheventselector-type-eventinit-options)
|
||||
- [frame.dispatchEvent(selector, type[, eventInit, options])](api/class-frame.md#framedispatcheventselector-type-eventinit-options)
|
||||
- [elementHandle.dispatchEvent(type[, eventInit])](api/class-elementhandle.md#elementhandledispatcheventtype-eventinit)
|
||||
|
||||
<br/>
|
||||
|
||||
## Type characters
|
||||
|
||||
Type into the field character by character, as if it was a user with a real keyboard.
|
||||
|
||||
```js
|
||||
// Type character by character
|
||||
await page.type('#area', 'Hello World!');
|
||||
```
|
||||
|
||||
This method will emit all the necessary keyboard events, with all the `keydown`, `keyup`, `keypress` events in place. You can even specify the optional `delay` between the key presses to simulate real user behavior.
|
||||
|
||||
> **NOTE** that most of the time, [`page.fill`](#text-input) will just work. You only need to type characters if there is special keyboard handling on the page.
|
||||
|
||||
#### API reference
|
||||
- [page.type(selector, text[, options])](api/class-page.md#pagetypeselector-text-options)
|
||||
- [frame.type(selector, text[, options])](api/class-frame.md#frametypeselector-text-options)
|
||||
- [elementHandle.type(text[, options])](api/class-elementhandle.md#elementhandletypetext-options)
|
||||
- [keyboard.type(text[, options])](api/class-keyboard.md#keyboardtypetext-options)
|
||||
|
||||
<br/>
|
||||
|
||||
## Keys and shortcuts
|
||||
|
||||
```js
|
||||
// Hit Enter
|
||||
await page.press('#submit', 'Enter');
|
||||
|
||||
// Dispatch Control+Right
|
||||
await page.press('#name', 'Control+ArrowRight');
|
||||
|
||||
// Press $ sign on keyboard
|
||||
await page.press('#value', '$');
|
||||
```
|
||||
|
||||
This method focuses the selected element and produces a single keystroke. It accepts the logical key names that are emitted in the [keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) property of the keyboard events:
|
||||
|
||||
```
|
||||
Backquote, Minus, Equal, Backslash, Backspace, Tab, Delete, Escape,
|
||||
ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrowRight,
|
||||
ArrowUp, F1 - F12, Digit0 - Digit9, KeyA - KeyZ, etc.
|
||||
```
|
||||
|
||||
- You can alternatively specify a single character you'd like to produce such as `"a"` or `"#"`.
|
||||
- Following modification shortcuts are also supported: `Shift, Control, Alt, Meta`.
|
||||
|
||||
Simple version produces a single character. This character is case-sensitive, so `"a"` and `"A"` will produce different results.
|
||||
|
||||
```js
|
||||
// <input id=name>
|
||||
await page.press('#name', 'Shift+A');
|
||||
|
||||
// <input id=name>
|
||||
await page.press('#name', 'Shift+ArrowLeft');
|
||||
```
|
||||
|
||||
Shortcuts such as `"Control+o"` or `"Control+Shift+T"` are supported as well. When specified with the modifier, modifier is pressed and being held while the subsequent key is being pressed.
|
||||
|
||||
Note that you still need to specify the capital `A` in `Shift-A` to produce the capital character. `Shift-a` produces a lower-case one as if you had the `CapsLock` toggled.
|
||||
|
||||
#### API reference
|
||||
- [page.press(selector, key[, options])](api/class-page.md#pagepressselector-key-options)
|
||||
- [frame.press(selector, key[, options])](api/class-frame.md#framepressselector-key-options)
|
||||
- [elementHandle.press(key[, options])](api/class-elementhandle.md#elementhandlepresskey-options)
|
||||
- [keyboard.press(key[, options])](api/class-keyboard.md#keyboardpresskey-options)
|
||||
|
||||
<br/>
|
||||
|
||||
## Upload files
|
||||
|
||||
```js
|
||||
// Select one file
|
||||
await page.setInputFiles('input#upload', 'myfile.pdf');
|
||||
|
||||
// Select multiple files
|
||||
await page.setInputFiles('input#upload', ['file1.txt', 'file2.txt']);
|
||||
|
||||
// Remove all the selected files
|
||||
await page.setInputFiles('input#upload', []);
|
||||
|
||||
// Upload buffer from memory
|
||||
await page.setInputFiles('input#upload', {
|
||||
name: 'file.txt',
|
||||
mimeType: 'text/plain',
|
||||
buffer: Buffer.from('this is test')
|
||||
});
|
||||
```
|
||||
|
||||
You can select input files for upload using the `page.setInputFiles` method. It expects first argument to point to an [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) with the type `"file"`. Multiple files can be passed in the array. If some of the file paths are relative, they are resolved relative to the [current working directory](https://nodejs.org/api/process.html#process_process_cwd). Empty array clears the selected files.
|
||||
|
||||
#### Example
|
||||
|
||||
[This script](https://github.com/microsoft/playwright/blob/master/utils/docs/examples/upload.js) uploads a file to an `input` element that accepts file uploads.
|
||||
|
||||
#### API reference
|
||||
- [page.setInputFiles(selector, files[, options])](api/class-page.md#pagesetinputfilesselector-files-options)
|
||||
- [frame.setInputFiles(selector, files[, options])](api/class-frame.md#framesetinputfilesselector-files-options)
|
||||
- [elementHandle.setInputFiles(files[, options])](api/class-elementhandle.md#elementhandlesetinputfilesfiles-options)
|
||||
|
||||
<br/>
|
||||
|
||||
## Focus element
|
||||
|
||||
For the dynamic pages that handle focus events, you can focus the given element.
|
||||
|
||||
```js
|
||||
await page.focus('input#name');
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [page.focus(selector[, options])](api/class-page.md#pagefocusselector-options)
|
||||
- [frame.focus(selector[, options])](api/class-frame.md#framefocusselector-options)
|
||||
- [elementHandle.focus()](api/class-elementhandle.md#elementhandlefocus)
|
||||
|
||||
<br/>
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,191 +0,0 @@
|
|||
---
|
||||
id: installation
|
||||
title: "Advanced installation"
|
||||
---
|
||||
|
||||
- [Managing browser binaries](#managing-browser-binaries)
|
||||
- [Download from artifact repository](#download-from-artifact-repository)
|
||||
- [Skip browser downloads](#skip-browser-downloads)
|
||||
- [Download single browser binary](#download-single-browser-binary)
|
||||
|
||||
## Managing browser binaries
|
||||
|
||||
Each version of Playwright needs specific versions of browser binaries to operate. By default Playwright downloads Chromium, WebKit and Firefox browsers into the OS-specific cache folders:
|
||||
- `%USERPROFILE%\AppData\Local\ms-playwright` on Windows
|
||||
- `~/Library/Caches/ms-playwright` on MacOS
|
||||
- `~/.cache/ms-playwright` on Linux
|
||||
|
||||
```sh
|
||||
npm i -D playwright
|
||||
```
|
||||
|
||||
These browsers will take few hundreds of megabytes of the disk space when installed:
|
||||
|
||||
```sh
|
||||
du -hs ./Library/Caches/ms-playwright/*
|
||||
281M chromium-XXXXXX
|
||||
187M firefox-XXXX
|
||||
180M webkit-XXXX
|
||||
```
|
||||
|
||||
You can override default behavior using environment variables. When installing Playwright, ask it to download browsers into a specific location:
|
||||
|
||||
```sh
|
||||
# Linux/macOS
|
||||
$ PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npm i -D playwright
|
||||
|
||||
# Windows
|
||||
$ set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
|
||||
$ npm i -D playwright
|
||||
```
|
||||
|
||||
When running Playwright scripts, ask it to search for browsers in a shared location:
|
||||
|
||||
```sh
|
||||
# Linux/macOS
|
||||
$ PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers node playwright-script.js
|
||||
|
||||
# Windows
|
||||
$ set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
|
||||
$ node playwright-script.js
|
||||
```
|
||||
|
||||
Or you can opt into the hermetic install and place binaries under the `node_modules/` folder:
|
||||
|
||||
```sh
|
||||
# Linux/macOS
|
||||
$ PLAYWRIGHT_BROWSERS_PATH=0 npm i -D playwright
|
||||
|
||||
# Windows
|
||||
$ set PLAYWRIGHT_BROWSERS_PATH=0
|
||||
$ npm i -D playwright
|
||||
```
|
||||
|
||||
Playwright keeps track of packages that need those browsers and will garbage collect them as you update Playwright to the newer versions.
|
||||
|
||||
> **NOTE** Developers can opt-in in this mode via exporting `PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers` in their `.bashrc`.
|
||||
|
||||
## Download from artifact repository
|
||||
|
||||
By default, Playwright downloads browsers from Microsoft and Google public CDNs.
|
||||
|
||||
Sometimes companies maintain an internal artifact repository to host browser binaries. In this case, Playwright can be configured to download from a custom location using the `PLAYWRIGHT_DOWNLOAD_HOST` env variable.
|
||||
|
||||
```sh
|
||||
# Linux/macOS
|
||||
$ PLAYWRIGHT_DOWNLOAD_HOST=192.168.1.78 npm i -D playwright
|
||||
|
||||
# Windows
|
||||
$ set PLAYWRIGHT_DOWNLOAD_HOST=192.168.1.78
|
||||
$ npm i -D playwright
|
||||
```
|
||||
|
||||
It is also possible to use a per-browser download hosts using `PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST`, `PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST` and `PLAYWRIGHT_WEBKIT_DOWNLOAD_HOST` env variables that take precedence over `PLAYWRIGHT_DOWNLOAD_HOST`.
|
||||
|
||||
```sh
|
||||
# Linux/macOS
|
||||
$ PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=192.168.1.1 PLAYWRIGHT_DOWNLOAD_HOST=192.168.1.78 npm i -D playwright
|
||||
```
|
||||
|
||||
## Skip browser downloads
|
||||
|
||||
In certain cases, it is desired to avoid browser downloads altogether because browser binaries are managed separately.
|
||||
|
||||
This can be done by setting `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` variable before installation.
|
||||
|
||||
```sh
|
||||
# Linux/macOS
|
||||
$ PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm i -D playwright
|
||||
|
||||
# Windows
|
||||
$ set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
|
||||
$ npm i -D playwright
|
||||
```
|
||||
|
||||
## Download single browser binary
|
||||
|
||||
Playwright ships three packages that bundle only a single browser:
|
||||
- [`playwright-chromium`](https://www.npmjs.com/package/playwright-chromium)
|
||||
- [`playwright-webkit`](https://www.npmjs.com/package/playwright-webkit)
|
||||
- [`playwright-firefox`](https://www.npmjs.com/package/playwright-firefox)
|
||||
|
||||
> **NOTE** All configuration environment variables also apply to these packages.
|
||||
|
||||
Using these packages is as easy as using a regular Playwright:
|
||||
|
||||
Install a specific package
|
||||
|
||||
```sh
|
||||
$ npm i -D playwright-webkit
|
||||
```
|
||||
|
||||
Require package
|
||||
|
||||
```js
|
||||
// Notice a proper package name in require
|
||||
const { webkit } = require('playwright-webkit');
|
||||
|
||||
(async () => {
|
||||
const browser = await webkit.launch();
|
||||
// ...
|
||||
})();
|
||||
```
|
||||
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,169 +0,0 @@
|
|||
---
|
||||
id: intro
|
||||
title: "Getting Started"
|
||||
---
|
||||
|
||||
- [Installation](#installation)
|
||||
- [Usage](#usage)
|
||||
- [First script](#first-script)
|
||||
- [Record scripts](#record-scripts)
|
||||
- [TypeScript support](#typescript-support)
|
||||
- [System requirements](#system-requirements)
|
||||
|
||||
## Installation
|
||||
|
||||
Use npm or Yarn to install Playwright in your Node.js project. See [system requirements](#system-requirements).
|
||||
|
||||
```sh
|
||||
npm i -D playwright
|
||||
```
|
||||
|
||||
This single command downloads the Playwright NPM package and browser binaries for Chromium, Firefox and WebKit. To modify this behavior see [installation parameters](./installation.md).
|
||||
|
||||
## Usage
|
||||
|
||||
Once installed, you can `require` Playwright in a Node.js script, and launch any of the 3 browsers (`chromium`, `firefox` and `webkit`).
|
||||
|
||||
```js
|
||||
const { chromium } = require('playwright');
|
||||
|
||||
(async () => {
|
||||
const browser = await chromium.launch();
|
||||
// Create pages, interact with UI elements, assert values
|
||||
await browser.close();
|
||||
})();
|
||||
```
|
||||
|
||||
Playwright APIs are asynchronous and return Promise objects. Our code examples use [the async/await pattern](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Async_await) to ease readability. The code is wrapped in an unnamed async arrow function which is invoking itself.
|
||||
|
||||
```js
|
||||
(async () => { // Start of async arrow function
|
||||
// Function code
|
||||
// ...
|
||||
})(); // End of the function and () to invoke itself
|
||||
```
|
||||
|
||||
## First script
|
||||
|
||||
In our first script, we will navigate to `whatsmyuseragent.org` and take a screenshot in WebKit.
|
||||
|
||||
```js
|
||||
const { webkit } = require('playwright');
|
||||
|
||||
(async () => {
|
||||
const browser = await webkit.launch();
|
||||
const page = await browser.newPage();
|
||||
await page.goto('http://whatsmyuseragent.org/');
|
||||
await page.screenshot({ path: `example.png` });
|
||||
await browser.close();
|
||||
})();
|
||||
```
|
||||
|
||||
By default, Playwright runs the browsers in headless mode. To see the browser UI, pass the `headless: false` flag while launching the browser. You can also use `slowMo` to slow down execution.
|
||||
|
||||
```js
|
||||
firefox.launch({ headless: false, slowMo: 50 });
|
||||
```
|
||||
|
||||
## Record scripts
|
||||
|
||||
[Playwright CLI](./cli.md) can be used to record user interactions and generate JavaScript code.
|
||||
|
||||
```sh
|
||||
npx playwright codegen wikipedia.org
|
||||
```
|
||||
|
||||
## TypeScript support
|
||||
|
||||
Playwright includes built-in support for TypeScript. Type definitions will be imported automatically. It is recommended to use type-checking to improve the IDE experience.
|
||||
|
||||
### In JavaScript
|
||||
|
||||
Add the following to the top of your JavaScript file to get type-checking in VS Code or WebStorm.
|
||||
|
||||
```js
|
||||
//@ts-check
|
||||
// ...
|
||||
```
|
||||
|
||||
Alternatively, you can use JSDoc to set types for variables.
|
||||
|
||||
```js
|
||||
/** @type {import('playwright').Page} */
|
||||
let page;
|
||||
```
|
||||
|
||||
### In TypeScript
|
||||
|
||||
TypeScript support will work out-of-the-box. Types can also be imported explicitly.
|
||||
|
||||
```ts
|
||||
let page: import('playwright').Page;
|
||||
```
|
||||
|
||||
## System requirements
|
||||
|
||||
Playwright requires Node.js version 10.17 or above. The browser binaries for Chromium, Firefox and WebKit work across the 3 platforms (Windows, macOS, Linux):
|
||||
* **Windows**: Works with Windows and Windows Subsystem for Linux (WSL).
|
||||
* **macOS**: Requires 10.14 or above.
|
||||
* **Linux**: Depending on your Linux distribution, you might need to install additional dependencies to run the browsers.
|
||||
* Firefox requires Ubuntu 18.04+
|
||||
* For Ubuntu 18.04, the additional dependencies are defined in [our Docker image](https://github.com/microsoft/playwright/blob/master/utils/docker/Dockerfile.bionic), which is based on Ubuntu.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,114 +0,0 @@
|
|||
---
|
||||
id: languages
|
||||
title: "Supported languages"
|
||||
---
|
||||
|
||||
The Playwright API is available in multiple languages.
|
||||
|
||||
- [JavaScript and TypeScript](#javascript-and-typescript)
|
||||
- [Python](#python)
|
||||
- [C#](#c)
|
||||
- [Go](#go)
|
||||
|
||||
## JavaScript and TypeScript
|
||||
|
||||
Playwright for JavaScript and TypeScript is generally available.
|
||||
|
||||
```
|
||||
npm i -D playwright
|
||||
```
|
||||
|
||||
* [Playwright on NPM](https://www.npmjs.com/package/playwright)
|
||||
* [GitHub repo](https://github.com/microsoft/playwright)
|
||||
|
||||
## Python
|
||||
|
||||
Playwright for Python is available in preview.
|
||||
|
||||
```
|
||||
pip install playwright
|
||||
```
|
||||
|
||||
* [Playwright on PyPI](https://pypi.org/project/playwright/)
|
||||
* [GitHub repo](https://github.com/microsoft/playwright-python)
|
||||
* [Pytest integration](https://github.com/microsoft/playwright-pytest)
|
||||
|
||||
## C#
|
||||
|
||||
Playwright for C# is available in preview.
|
||||
|
||||
```
|
||||
dotnet add package PlaywrightSharp
|
||||
```
|
||||
|
||||
* [Playwright on NuGet](https://www.nuget.org/packages/PlaywrightSharp/)
|
||||
* [GitHub repo](https://github.com/microsoft/playwright-sharp)
|
||||
|
||||
## Go
|
||||
|
||||
Playwright for Go is available in preview.
|
||||
|
||||
```
|
||||
go get github.com/mxschmitt/playwright-go
|
||||
```
|
||||
|
||||
* [GitHub repo](https://github.com/mxschmitt/playwright-go)
|
||||
* [Documentation](https://pkg.go.dev/github.com/mxschmitt/playwright-go?tab=doc)
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,102 +0,0 @@
|
|||
---
|
||||
id: mobile
|
||||
title: "Experimental support for Chrome for Android"
|
||||
---
|
||||
|
||||
- [Requirements](#requirements)
|
||||
- [How to run](#how-to-run)
|
||||
- [Known limitations](#known-limitations)
|
||||
|
||||
You can try Playwright against Chrome for Android today. This support is experimental. Support for devices is tracked in the issue [#1122](https://github.com/microsoft/playwright/issues/1122).
|
||||
|
||||
## Requirements
|
||||
- [Playwright 1.6](https://www.npmjs.com/package/playwright) or newer
|
||||
- [ADB daemon](https://developer.android.com/studio/command-line/adb) running and authenticated with your device.
|
||||
- [`Chrome 87`](https://play.google.com/store/apps/details?id=com.android.chrome) or newer installed on the device
|
||||
- "Enable command line on non-rooted devices" enabled in `chrome://flags`.
|
||||
|
||||
> Playwright will be looking for ADB daemon on the default port `5037`. It will use the first device available. Typically running `adb devices` is all you need to do.
|
||||
|
||||
## How to run
|
||||
|
||||
```js
|
||||
const { _clank } = require('playwright');
|
||||
|
||||
(async () => {
|
||||
const context = await _clank.launchPersistentContext('', {
|
||||
viewport: null
|
||||
});
|
||||
const [page] = context.pages();
|
||||
await page.goto('https://webkit.org/');
|
||||
console.log(await page.evaluate(() => window.location.href));
|
||||
await page.screenshot({ path: 'example.png' });
|
||||
await context.close();
|
||||
})();
|
||||
```
|
||||
|
||||
> [Clank](https://chromium.googlesource.com/chromium/src/+/master/docs/memory/android_dev_tips.md) is a code name for Chrome for Android.
|
||||
|
||||
## Known limitations
|
||||
- Raw USB operation is not yet supported, so you need ADB.
|
||||
- Only `launchPersistentContext` works, launching ephemeral contexts is not supported.
|
||||
- Passing `viewport: null` is necessary to make sure resolution is not emulated.
|
||||
- Device needs to be awake to produce screenshots. Enabling "Stay awake" developer mode will help.
|
||||
- We didn't run all the tests against the device, so not everything works.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,169 +0,0 @@
|
|||
---
|
||||
id: multi-pages
|
||||
title: "Multi-page scenarios"
|
||||
---
|
||||
|
||||
Playwright can automate scenarios that span multiple browser contexts or multiple tabs in a browser window.
|
||||
|
||||
- [Multiple contexts](#multiple-contexts)
|
||||
- [Multiple pages](#multiple-pages)
|
||||
- [Handling new pages](#handling-new-pages)
|
||||
- [Handling popups](#handling-popups)
|
||||
|
||||
## Multiple contexts
|
||||
|
||||
[Browser contexts](core-concepts.md#browser-contexts) are isolated environments on a single browser instance. Playwright can create multiple browser contexts within a single scenario. This is useful when you want to test for multi-user functionality, like chat.
|
||||
|
||||
```js
|
||||
const { chromium } = require('playwright');
|
||||
|
||||
// Create a Chromium browser instance
|
||||
const browser = await chromium.launch();
|
||||
|
||||
// Create two isolated browser contexts
|
||||
const userContext = await browser.newContext();
|
||||
const adminContext = await browser.newContext();
|
||||
|
||||
// Load user and admin cookies
|
||||
await userContext.addCookies(userCookies);
|
||||
await adminContext.addCookies(adminCookies);
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [BrowserContext]
|
||||
- [browser.newContext([options])](api/class-browser.md#browsernewcontextoptions)
|
||||
- [browserContext.addCookies(cookies)](api/class-browsercontext.md#browsercontextaddcookiescookies)
|
||||
|
||||
## Multiple pages
|
||||
|
||||
Each browser context can host multiple pages (tabs).
|
||||
* Each page behaves like a focused, active page. Bringing the page to front is not required.
|
||||
* Pages inside a context respect context-level emulation, like viewport sizes, custom network routes or browser locale.
|
||||
|
||||
```js
|
||||
// Create two pages
|
||||
const pageOne = await context.newPage();
|
||||
const pageTwo = await context.newPage();
|
||||
|
||||
// Get pages of a brower context
|
||||
const allPages = context.pages();
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [Page]
|
||||
- [browserContext.newPage()](api/class-browsercontext.md#browsercontextnewpage)
|
||||
- [browserContext.pages()](api/class-browsercontext.md#browsercontextpages)
|
||||
|
||||
## Handling new pages
|
||||
|
||||
The `page` event on browser contexts can be used to get new pages that are created in the context. This can be used to handle new pages opened by `target="_blank"` links.
|
||||
|
||||
```js
|
||||
// Get page after a specific action (e.g. clicking a link)
|
||||
const [newPage] = await Promise.all([
|
||||
context.waitForEvent('page'),
|
||||
page.click('a[target="_blank"]') // Opens a new tab
|
||||
])
|
||||
await newPage.waitForLoadState();
|
||||
console.log(await newPage.title());
|
||||
```
|
||||
|
||||
If the action that triggers the new page is unknown, the following pattern can be used.
|
||||
|
||||
```js
|
||||
// Get all new pages (including popups) in the context
|
||||
context.on('page', async page => {
|
||||
await page.waitForLoadState();
|
||||
await page.title();
|
||||
})
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [browserContext.on('page')](api/class-browsercontext.md#browsercontextonpage)
|
||||
|
||||
## Handling popups
|
||||
|
||||
If the page opens a pop-up, you can get a reference to it by listening to the `popup` event on the page.
|
||||
|
||||
This event is emitted in addition to the `browserContext.on('page')` event, but only for popups relevant to this page.
|
||||
|
||||
```js
|
||||
// Get popup after a specific action (e.g., click)
|
||||
const [popup] = await Promise.all([
|
||||
page.waitForEvent('popup'),
|
||||
page.click('#open')
|
||||
]);
|
||||
await popup.waitForLoadState();
|
||||
await popup.title();
|
||||
```
|
||||
|
||||
If the action that triggers the popup is unknown, the following pattern can be used.
|
||||
|
||||
```js
|
||||
// Get all popups when they open
|
||||
page.on('popup', async popup => {
|
||||
await popup.waitForLoadState();
|
||||
await popup.title();
|
||||
})
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [page.on('popup')](api/class-page.md#pageonpopup)
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,230 +0,0 @@
|
|||
---
|
||||
id: navigations
|
||||
title: "Navigations"
|
||||
---
|
||||
|
||||
Playwright can navigate to URLs and handle navigations caused by page interactions. This guide covers common scenarios to wait for page navigations and loading to complete.
|
||||
|
||||
- [Navigation lifecycle](#navigation-lifecycle)
|
||||
- [Scenarios initiated by browser UI](#scenarios-initiated-by-browser-ui)
|
||||
- [Scenarios initiated by page interaction](#scenarios-initiated-by-page-interaction)
|
||||
- [Advanced patterns](#advanced-patterns)
|
||||
|
||||
## Navigation lifecycle
|
||||
|
||||
Playwright splits the process of showing a new document in a page into **navigation** and **loading**.
|
||||
|
||||
**Navigations** can be initiated by changing the page URL or by interacting with the page (e.g., clicking a link). Navigation ends when response headers have been parsed and session history is updated. The navigation intent may be canceled, for example, on hitting an unresolved DNS address or transformed into a file download. Only after the navigation succeeds, page starts **loading** the document.
|
||||
|
||||
**Loading** covers getting the remaining response body over the network, parsing, executing the scripts and firing load events:
|
||||
- [page.url()](api/class-page.md#pageurl) is set to the new url
|
||||
- document content is loaded over network and parsed
|
||||
- [page.on('domcontentloaded')](api/class-page.md#pageondomcontentloaded) event is fired
|
||||
- page executes some scripts and loads resources like stylesheets and images
|
||||
- [page.on('load')](api/class-page.md#pageonload) event is fired
|
||||
- page executes dynamically loaded scripts
|
||||
- `networkidle` is fired when no new network requests are made for 500 ms
|
||||
|
||||
## Scenarios initiated by browser UI
|
||||
|
||||
Navigations can be initiated by changing the URL bar, reloading the page or going back or forward in session history.
|
||||
|
||||
### Auto-wait
|
||||
|
||||
Navigating to a URL auto-waits for the page to fire the `load` event. If the page does a client-side redirect before `load`, `page.goto` will auto-wait for the redirected page to fire the `load` event.
|
||||
|
||||
```js
|
||||
// Navigate the page
|
||||
await page.goto('https://example.com');
|
||||
```
|
||||
|
||||
### Custom wait
|
||||
|
||||
Override the default behavior to wait until a specific event, like `networkidle`.
|
||||
|
||||
```js
|
||||
// Navigate and wait until network is idle
|
||||
await page.goto('https://example.com', { waitUntil: 'networkidle' });
|
||||
```
|
||||
|
||||
### Wait for element
|
||||
|
||||
In lazy-loaded pages, it can be useful to wait until an element is visible with [page.waitForSelector(selector[, options])](api/class-page.md#pagewaitforselectorselector-options). Alternatively, page interactions like [page.click(selector[, options])](api/class-page.md#pageclickselector-options) auto-wait for elements.
|
||||
|
||||
```js
|
||||
// Navigate and wait for element
|
||||
await page.goto('https://example.com');
|
||||
await page.waitForSelector('text=Example Domain');
|
||||
|
||||
// Navigate and click element
|
||||
// Click will auto-wait for the element
|
||||
await page.goto('https://example.com');
|
||||
await page.click('text=Example Domain');
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [page.goto(url[, options])](api/class-page.md#pagegotourl-options)
|
||||
- [page.reload([options])](api/class-page.md#pagereloadoptions)
|
||||
- [page.goBack([options])](api/class-page.md#pagegobackoptions)
|
||||
- [page.goForward([options])](api/class-page.md#pagegoforwardoptions)
|
||||
|
||||
## Scenarios initiated by page interaction
|
||||
|
||||
In the scenarios below, `page.click` initiates a navigation and then waits for the navigation to complete.
|
||||
|
||||
### Auto-wait
|
||||
|
||||
By default, `page.click` will wait for the navigation step to complete. This can be combined with a page interaction on the navigated page which would auto-wait for an element.
|
||||
|
||||
```js
|
||||
// Click will auto-wait for navigation to complete
|
||||
await page.click('text=Login');
|
||||
// Fill will auto-wait for element on navigated page
|
||||
await page.fill('#username', 'John Doe');
|
||||
```
|
||||
|
||||
### Custom wait
|
||||
|
||||
`page.click` can be combined with [page.waitForLoadState([state, options])](api/class-page.md#pagewaitforloadstatestate-options) to wait for a loading event.
|
||||
|
||||
```js
|
||||
await page.click('button'); // Click triggers navigation
|
||||
await page.waitForLoadState('networkidle'); // This resolves after 'networkidle'
|
||||
```
|
||||
|
||||
### Wait for element
|
||||
|
||||
In lazy-loaded pages, it can be useful to wait until an element is visible with [page.waitForSelector(selector[, options])](api/class-page.md#pagewaitforselectorselector-options). Alternatively, page interactions like [page.click(selector[, options])](api/class-page.md#pageclickselector-options) auto-wait for elements.
|
||||
|
||||
```js
|
||||
// Click triggers navigation
|
||||
await page.click('text=Login');
|
||||
// Click will auto-wait for the element
|
||||
await page.waitForSelector('#username', 'John Doe');
|
||||
|
||||
// Click triggers navigation
|
||||
await page.click('text=Login');
|
||||
// Fill will auto-wait for element
|
||||
await page.fill('#username', 'John Doe');
|
||||
```
|
||||
|
||||
### Asynchronous navigation
|
||||
|
||||
Clicking an element could trigger asychronous processing before initiating the navigation. In these cases, it is recommended to explicitly call [page.waitForNavigation([options])](api/class-page.md#pagewaitfornavigationoptions). For example:
|
||||
* Navigation is triggered from a `setTimeout`
|
||||
* Page waits for network requests before navigation
|
||||
|
||||
```js
|
||||
await Promise.all([
|
||||
page.click('a'), // Triggers a navigation after a timeout
|
||||
page.waitForNavigation(), // Waits for the next navigation
|
||||
]);
|
||||
```
|
||||
|
||||
The `Promise.all` pattern prevents a race condition between `page.click` and `page.waitForNavigation` when navigation happens quickly.
|
||||
|
||||
### Multiple navigations
|
||||
|
||||
Clicking an element could trigger multiple navigations. In these cases, it is recommended to explicitly [page.waitForNavigation([options])](api/class-page.md#pagewaitfornavigationoptions) to a specific url. For example:
|
||||
* Client-side redirects issued after the `load` event
|
||||
* Multiple pushes to history state
|
||||
|
||||
```js
|
||||
await Promise.all([
|
||||
page.waitForNavigation({ url: '**/login' }),
|
||||
page.click('a'), // Triggers a navigation with a script redirect
|
||||
]);
|
||||
```
|
||||
|
||||
The `Promise.all` pattern prevents a race condition between `page.click` and `page.waitForNavigation` when navigation happens quickly.
|
||||
|
||||
### Loading a popup
|
||||
|
||||
When popup is opened, explicitly calling [page.waitForLoadState([state, options])](api/class-page.md#pagewaitforloadstatestate-options) ensures that popup is loaded to the desired state.
|
||||
|
||||
```js
|
||||
const [ popup ] = await Promise.all([
|
||||
page.waitForEvent('popup'),
|
||||
page.click('a[target="_blank"]'), // Opens popup
|
||||
]);
|
||||
await popup.waitForLoadState('load');
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [page.click(selector[, options])](api/class-page.md#pageclickselector-options)
|
||||
- [page.waitForLoadState([state, options])](api/class-page.md#pagewaitforloadstatestate-options)
|
||||
- [page.waitForSelector(selector[, options])](api/class-page.md#pagewaitforselectorselector-options)
|
||||
- [page.waitForNavigation([options])](api/class-page.md#pagewaitfornavigationoptions)
|
||||
- [page.waitForFunction(pageFunction[, arg, options])](api/class-page.md#pagewaitforfunctionpagefunction-arg-options)
|
||||
|
||||
## Advanced patterns
|
||||
|
||||
For pages that have complicated loading patterns, [page.waitForFunction(pageFunction[, arg, options])](api/class-page.md#pagewaitforfunctionpagefunction-arg-options) is a powerful and extensible approach to define a custom wait criteria.
|
||||
|
||||
```js
|
||||
await page.goto('http://example.com');
|
||||
await page.waitForFunction(() => window.amILoadedYet());
|
||||
// Ready to take a screenshot, according to the page itself.
|
||||
await page.screenshot();
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [page.waitForFunction(pageFunction[, arg, options])](api/class-page.md#pagewaitforfunctionpagefunction-arg-options)
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,247 +0,0 @@
|
|||
---
|
||||
id: network
|
||||
title: "Network"
|
||||
---
|
||||
|
||||
Playwright provides APIs to **monitor** and **modify** network traffic, both HTTP and HTTPS. Any requests that page does, including [XHRs](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) and [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) requests, can be tracked, modified and handled.
|
||||
|
||||
- [HTTP Authentication](#http-authentication)
|
||||
- [Handle file downloads](#handle-file-downloads)
|
||||
- [Network events](#network-events)
|
||||
- [Handle requests](#handle-requests)
|
||||
- [Modify requests](#modify-requests)
|
||||
- [Abort requests](#abort-requests)
|
||||
|
||||
<br/>
|
||||
|
||||
## HTTP Authentication
|
||||
|
||||
```js
|
||||
const context = await browser.newContext({
|
||||
httpCredentials: {
|
||||
username: 'bill',
|
||||
password: 'pa55w0rd',
|
||||
},
|
||||
});
|
||||
const page = await context.newPage();
|
||||
await page.goto('https://example.com');
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [browser.newContext([options])](api/class-browser.md#browsernewcontextoptions)
|
||||
|
||||
<br/>
|
||||
|
||||
## Handle file downloads
|
||||
|
||||
```js
|
||||
const [ download ] = await Promise.all([
|
||||
page.waitForEvent('download'), // <-- start waiting for the download
|
||||
page.click('button#delayed-download') // <-- perform the action that directly or indirectly initiates it.
|
||||
]);
|
||||
const path = await download.path();
|
||||
```
|
||||
|
||||
For every attachment downloaded by the page, [page.on('download')](api/class-page.md#pageondownload) event is emitted. If you create a browser context with the `acceptDownloads: true`, all these attachments are going to be downloaded into a temporary folder. You can obtain the download url, file system path and payload stream using the [Download] object from the event.
|
||||
|
||||
#### Variations
|
||||
|
||||
If you have no idea what initiates the download, you can still handle the event:
|
||||
|
||||
```js
|
||||
page.on('download', download => download.path().then(console.log));
|
||||
```
|
||||
|
||||
Note that handling the event forks the control flow and makes script harder to follow. Your scenario might end while you are downloading a file since your main control flow is not awaiting for this operation to resolve.
|
||||
|
||||
#### API reference
|
||||
- [Download]
|
||||
- [page.on('download')](api/class-page.md#pageondownload)
|
||||
- [page.waitForEvent(event[, optionsOrPredicate])](api/class-page.md#pagewaitforeventevent-optionsorpredicate)
|
||||
|
||||
<br/>
|
||||
|
||||
## Network events
|
||||
|
||||
You can monitor all the requests and responses:
|
||||
|
||||
```js
|
||||
const { chromium, webkit, firefox } = require('playwright');
|
||||
|
||||
(async () => {
|
||||
const browser = await chromium.launch();
|
||||
const page = await browser.newPage();
|
||||
|
||||
// Subscribe to 'request' and 'response' events.
|
||||
page.on('request', request =>
|
||||
console.log('>>', request.method(), request.url()));
|
||||
page.on('response', response =>
|
||||
console.log('<<', response.status(), response.url()));
|
||||
await page.goto('https://example.com');
|
||||
|
||||
await browser.close();
|
||||
})();
|
||||
```
|
||||
|
||||
Or wait for a network response after the button click:
|
||||
|
||||
```js
|
||||
// Use a glob URL pattern
|
||||
const [response] = await Promise.all([
|
||||
page.waitForResponse('**/api/fetch_data'),
|
||||
page.click('button#update'),
|
||||
]);
|
||||
```
|
||||
|
||||
#### Variations
|
||||
|
||||
```js
|
||||
// Use a RegExp
|
||||
const [response] = await Promise.all([
|
||||
page.waitForResponse(/\.jpeg$/),
|
||||
page.click('button#update'),
|
||||
]);
|
||||
|
||||
// Use a predicate taking a Response object
|
||||
const [response] = await Promise.all([
|
||||
page.waitForResponse(response => response.url().includes(token)),
|
||||
page.click('button#update'),
|
||||
]);
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [Request]
|
||||
- [Response]
|
||||
- [page.on('request')](api/class-page.md#pageonrequest)
|
||||
- [page.on('response')](api/class-page.md#pageonresponse)
|
||||
- [page.waitForRequest(urlOrPredicate[, options])](api/class-page.md#pagewaitforrequesturlorpredicate-options)
|
||||
- [page.waitForResponse(urlOrPredicate[, options])](api/class-page.md#pagewaitforresponseurlorpredicate-options)
|
||||
|
||||
<br/>
|
||||
|
||||
## Handle requests
|
||||
|
||||
```js
|
||||
await page.route('**/api/fetch_data', route => route.fulfill({
|
||||
status: 200,
|
||||
body: testData,
|
||||
}));
|
||||
await page.goto('https://example.com');
|
||||
```
|
||||
|
||||
You can mock API endpoints via handling the network quests in your Playwright script.
|
||||
|
||||
#### Variations
|
||||
|
||||
```js
|
||||
// Set up route on the entire browser context.
|
||||
// It will apply to popup windows and opened links.
|
||||
|
||||
await browserContext.route('**/api/login', route => route.fulfill({
|
||||
status: 200,
|
||||
body: 'accept',
|
||||
}));
|
||||
await page.goto('https://example.com');
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [browserContext.route(url, handler)](api/class-browsercontext.md#browsercontextrouteurl-handler)
|
||||
- [browserContext.unroute(url[, handler])](api/class-browsercontext.md#browsercontextunrouteurl-handler)
|
||||
- [page.route(url, handler)](api/class-page.md#pagerouteurl-handler)
|
||||
- [page.unroute(url[, handler])](api/class-page.md#pageunrouteurl-handler)
|
||||
- [Route]
|
||||
|
||||
<br/>
|
||||
|
||||
## Modify requests
|
||||
|
||||
```js
|
||||
// Delete header
|
||||
await page.route('**/*', route => {
|
||||
const headers = route.request().headers();
|
||||
delete headers['X-Secret'];
|
||||
route.continue({headers});
|
||||
});
|
||||
|
||||
// Continue requests as POST.
|
||||
await page.route('**/*', route => route.continue({method: 'POST'}));
|
||||
```
|
||||
|
||||
You can continue requests with modifications. Example above removes an HTTP header from the outgoing requests.
|
||||
|
||||
## Abort requests
|
||||
|
||||
```js
|
||||
await page.route('**/*.{png,jpg,jpeg}', route => route.abort());
|
||||
|
||||
// Abort based on the request type
|
||||
await page.route('**/*', route => {
|
||||
return route.request().resourceType() === 'image' ?
|
||||
route.abort() : route.continue();
|
||||
});
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [page.route(url, handler)](api/class-page.md#pagerouteurl-handler)
|
||||
- [browserContext.route(url, handler)](api/class-browsercontext.md#browsercontextrouteurl-handler)
|
||||
- [route.abort([errorCode])](api/class-route.md#routeaborterrorcode)
|
||||
|
||||
<br/>
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
112
docs/out/pom.md
112
docs/out/pom.md
|
|
@ -1,112 +0,0 @@
|
|||
---
|
||||
id: pom
|
||||
title: "Page Object Models"
|
||||
---
|
||||
|
||||
Large test suites can be structured to optimize ease of authoring and maintenance. Page object models are one such approach to structure your test suite.
|
||||
|
||||
- [Introduction](#introduction)
|
||||
- [Implementation](#implementation)
|
||||
|
||||
## Introduction
|
||||
|
||||
A page object represents a part of your web application. An e-commerce web application might have a home page, a listings page and a checkout page. Each of them can be represented by page object models.
|
||||
|
||||
Page objects **simplify authoring**. They create a higher-level API which suits your application.
|
||||
|
||||
Page objects **simplify maintenance**. They capture element selectors in one place and create reusable code to avoid repetition.
|
||||
|
||||
## Implementation
|
||||
|
||||
Page object models wrap over a Playwright [Page].
|
||||
|
||||
```js
|
||||
// models/Search.js
|
||||
class SearchPage {
|
||||
constructor(page) {
|
||||
this.page = page;
|
||||
}
|
||||
async navigate() {
|
||||
await this.page.goto('https://bing.com');
|
||||
}
|
||||
async search(text) {
|
||||
await this.page.fill('[aria-label="Enter your search term"]', text);
|
||||
await this.page.keyboard.press('Enter');
|
||||
}
|
||||
}
|
||||
module.exports = { SearchPage };
|
||||
```
|
||||
|
||||
Page objects can then be used inside a test.
|
||||
|
||||
```js
|
||||
// search.spec.js
|
||||
const { SearchPage } = require('./models/Search');
|
||||
|
||||
// In the test
|
||||
const page = await browser.newPage();
|
||||
const searchPage = new SearchPage(page);
|
||||
await searchPage.navigate();
|
||||
await searchPage.search('search query');
|
||||
```
|
||||
|
||||
### API reference
|
||||
- [Page]
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,410 +0,0 @@
|
|||
---
|
||||
id: selectors
|
||||
title: "Element selectors"
|
||||
---
|
||||
|
||||
Selectors query elements on the web page for interactions, like [page.click(selector[, options])](api/class-page.md#pageclickselector-options), and to obtain `ElementHandle` through [page.$(selector)](api/class-page.md#pageselector). Built-in selectors auto-pierce [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM).
|
||||
|
||||
- [Working with selectors](#working-with-selectors)
|
||||
- [Syntax](#syntax)
|
||||
- [Best practices](#best-practices)
|
||||
- [Examples](#examples)
|
||||
- [Selector engines](#selector-engines)
|
||||
|
||||
## Working with selectors
|
||||
|
||||
Selector describes an element in the page. It can be used to obtain `ElementHandle` (see [page.$(selector)](api/class-page.md#pageselector) for example) or shortcut element operations to avoid intermediate handle (see [page.click(selector[, options])](api/class-page.md#pageclickselector-options) for example).
|
||||
|
||||
Selector has the following format: `engine=body [>> engine=body]*`. Here `engine` is one of the supported [selector engines](./selectors.md) (e.g. `css` or `xpath`), and `body` is a selector body in the format of the particular engine. When multiple `engine=body` clauses are present (separated by `>>`), next one is queried relative to the previous one's result.
|
||||
|
||||
Playwright also supports the following CSS extensions:
|
||||
* `:text("string")` - Matches elements that contain specific text node. Learn more about [text selector](./selectors.md#css-extension-text).
|
||||
* `:visible` - Matches only visible elements. Learn more about [visible selector](./selectors.md#css-extension-visible).
|
||||
* `:light(selector)` - Matches in the light DOM only as opposite to piercing open shadow roots. Learn more about [shadow piercing](./selectors.md#shadow-piercing).
|
||||
|
||||
<!--
|
||||
* `:right-of(selector)`, `:left-of(selector)`, `:above(selector)`, `:below(selector)`, `:near(selector)`, `:within(selector)` - Match elements based on their relative position to another element. Learn more about [proximity selectors](./selectors.md#css-extension-proximity).
|
||||
|
||||
-->
|
||||
|
||||
For convenience, selectors in the wrong format are heuristically converted to the right format:
|
||||
- selector starting with `//` or `..` is assumed to be `xpath=selector`;
|
||||
- selector starting and ending with a quote (either `"` or `'`) is assumed to be `text=selector`;
|
||||
- otherwise selector is assumed to be `css=selector`.
|
||||
|
||||
```js
|
||||
// queries 'div' css selector
|
||||
const handle = await page.$('css=div');
|
||||
|
||||
// queries '//html/body/div' xpath selector
|
||||
const handle = await page.$('xpath=//html/body/div');
|
||||
|
||||
// queries '"foo"' text selector
|
||||
const handle = await page.$('text="foo"');
|
||||
|
||||
// queries 'span' css selector inside the result of '//html/body/div' xpath selector
|
||||
const handle = await page.$('xpath=//html/body/div >> css=span');
|
||||
|
||||
// converted to 'css=div'
|
||||
const handle = await page.$('div');
|
||||
|
||||
// converted to 'xpath=//html/body/div'
|
||||
const handle = await page.$('//html/body/div');
|
||||
|
||||
// converted to 'text="foo"'
|
||||
const handle = await page.$('"foo"');
|
||||
|
||||
// queries '../span' xpath selector starting with the result of 'div' css selector
|
||||
const handle = await page.$('div >> ../span');
|
||||
|
||||
// queries 'span' css selector inside the div handle
|
||||
const handle = await divHandle.$('css=span');
|
||||
```
|
||||
|
||||
### Working with Chrome Extensions
|
||||
|
||||
Playwright can be used for testing Chrome Extensions.
|
||||
|
||||
> **NOTE** Extensions in Chrome / Chromium currently only work in non-headless mode.
|
||||
|
||||
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`:
|
||||
|
||||
```js
|
||||
const { chromium } = require('playwright');
|
||||
|
||||
(async () => {
|
||||
const pathToExtension = require('path').join(__dirname, 'my-extension');
|
||||
const userDataDir = '/tmp/test-user-data-dir';
|
||||
const browserContext = await chromium.launchPersistentContext(userDataDir,{
|
||||
headless: false,
|
||||
args: [
|
||||
`--disable-extensions-except=${pathToExtension}`,
|
||||
`--load-extension=${pathToExtension}`
|
||||
]
|
||||
});
|
||||
const backgroundPage = browserContext.backgroundPages()[0];
|
||||
// Test the background page as you would any other page.
|
||||
await browserContext.close();
|
||||
})();
|
||||
```
|
||||
|
||||
## Syntax
|
||||
|
||||
Selectors are defined by selector engine name and selector body, `engine=body`.
|
||||
* `engine` refers to one of the [supported engines](#selector-engines)
|
||||
* Built-in selector engines: [css], [text], [xpath] and [id selectors][id]
|
||||
* Learn more about [custom selector engines](./extensibility.md)
|
||||
* `body` refers to the query string for the respective engine
|
||||
* For `text`, body is the text content
|
||||
* For `css`, body is a [css selector](https://developer.mozilla.org/en/docs/Web/CSS/CSS_Selectors)
|
||||
|
||||
Body format is assumed to ignore leading and trailing white spaces, so that extra whitespace can be added for readability.
|
||||
|
||||
### Short-forms
|
||||
|
||||
For convenience, common selectors have short-forms:
|
||||
- Selector starting with `//` or `..` is assumed to be `xpath=selector`
|
||||
- Example: `page.click('//html')` is converted to `page.click('xpath=//html')`.
|
||||
- Selector starting and ending with a quote (either `"` or `'`) is assumed to be `text=selector`
|
||||
- Example: `page.click('"foo"')` is converted to `page.click('text="foo"')`.
|
||||
- Otherwise, selector is assumed to be `css=selector`
|
||||
- Example: `page.click('div')` is converted to `page.click('css=div')`.
|
||||
|
||||
### Chaining selectors
|
||||
|
||||
Selectors defined as `engine=body` or in short-form can be combined with the `>>` token, e.g. `selector1 >> selector2 >> selectors3`. When selectors are chained, next one is queried relative to the previous one's result.
|
||||
|
||||
For example,
|
||||
|
||||
```
|
||||
css=article >> css=.bar > .baz >> css=span[attr=value]
|
||||
```
|
||||
|
||||
```js
|
||||
document
|
||||
.querySelector('article')
|
||||
.querySelector('.bar > .baz')
|
||||
.querySelector('span[attr=value]')
|
||||
```
|
||||
|
||||
If a selector needs to include `>>` in the body, it should be escaped inside a string to not be confused with chaining separator, e.g. `text="some >> text"`.
|
||||
|
||||
### Intermediate matches
|
||||
|
||||
By default, chained selectors resolve to an element queried by the last selector. A selector can be prefixed with `*` to capture elements that are queried by an intermediate selector.
|
||||
|
||||
For example, `css=article >> text=Hello` captures the element with the text `Hello`, and `*css=article >> text=Hello` (note the `*`) captures the `article` element that contains some element with the text `Hello`.
|
||||
|
||||
## Best practices
|
||||
|
||||
The choice of selectors determines the resiliency of automation scripts. To reduce the maintenance burden, we recommend prioritizing user-facing attributes and explicit contracts.
|
||||
|
||||
### Prioritize user-facing attributes
|
||||
|
||||
Attributes like text content, input placeholder, accessibility roles and labels are user-facing attributes that change rarely. These attributes are not impacted by DOM structure changes.
|
||||
|
||||
The following examples use the built-in [text] and [css] selector engines.
|
||||
|
||||
```js
|
||||
// queries "Login" text selector
|
||||
await page.click('text="Login"');
|
||||
await page.click('"Login"'); // short-form
|
||||
|
||||
// queries "Search GitHub" placeholder attribute
|
||||
await page.fill('css=[placeholder="Search GitHub"]');
|
||||
await page.fill('[placeholder="Search GitHub"]'); // short-form
|
||||
|
||||
// queries "Close" accessibility label
|
||||
await page.click('css=[aria-label="Close"]');
|
||||
await page.click('[aria-label="Close"]'); // short-form
|
||||
|
||||
// combine role and text queries
|
||||
await page.click('css=nav >> text=Login');
|
||||
```
|
||||
|
||||
### Define explicit contract
|
||||
|
||||
When user-facing attributes change frequently, it is recommended to use explicit test ids, like `data-test-id`. These `data-*` attributes are supported by the [css] and [id selectors][id].
|
||||
|
||||
```html
|
||||
<button data-test-id="directions">Itinéraire</button>
|
||||
```
|
||||
|
||||
```js
|
||||
// queries data-test-id attribute with css
|
||||
await page.click('css=[data-test-id=directions]');
|
||||
await page.click('[data-test-id=directions]'); // short-form
|
||||
|
||||
// queries data-test-id with id
|
||||
await page.click('data-test-id=directions');
|
||||
```
|
||||
|
||||
### Avoid selectors tied to implementation
|
||||
|
||||
[xpath] and [css] can be tied to the DOM structure or implementation. These selectors can break when the DOM structure changes.
|
||||
|
||||
```js
|
||||
// avoid long css or xpath chains
|
||||
await page.click('#tsf > div:nth-child(2) > div.A8SBwf > div.RNNXgb > div > div.a4bIc > input');
|
||||
await page.click('//*[@id="tsf"]/div[2]/div[1]/div[1]/div/div[2]/input');
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
```js
|
||||
// queries 'div' css selector
|
||||
const handle = await page.$('css=div');
|
||||
|
||||
// queries '//html/body/div' xpath selector
|
||||
const handle = await page.$('xpath=//html/body/div');
|
||||
|
||||
// queries '"foo"' text selector
|
||||
const handle = await page.$('text="foo"');
|
||||
|
||||
// queries 'span' css selector inside the result of '//html/body/div' xpath selector
|
||||
const handle = await page.$('xpath=//html/body/div >> css=span');
|
||||
|
||||
// converted to 'css=div'
|
||||
const handle = await page.$('div');
|
||||
|
||||
// converted to 'xpath=//html/body/div'
|
||||
const handle = await page.$('//html/body/div');
|
||||
|
||||
// converted to 'text="foo"'
|
||||
const handle = await page.$('"foo"');
|
||||
|
||||
// queries 'span' css selector inside the div handle
|
||||
const handle = await divHandle.$('css=span');
|
||||
```
|
||||
|
||||
## Selector engines
|
||||
|
||||
### css and css:light
|
||||
|
||||
`css` is a default engine - any malformed selector not starting with `//` nor starting and ending with a quote is assumed to be a css selector. For example, Playwright converts `page.$('span > button')` to `page.$('css=span > button')`.
|
||||
|
||||
Playwright augments standard CSS selectors in two ways, see below for more details:
|
||||
* `css` engine pierces open shadow DOM by default.
|
||||
* Playwright adds a few custom pseudo-classes like `:visible`.
|
||||
|
||||
#### Shadow piercing
|
||||
|
||||
`css:light` engine is equivalent to [`Document.querySelector`](https://developer.mozilla.org/en/docs/Web/API/Document/querySelector) and behaves according to the CSS spec. However, it does not pierce shadow roots, which may be inconvenient when working with [Shadow DOM and Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM). For that reason, `css` engine pierces shadow roots. More specifically, any [Descendant combinator](https://developer.mozilla.org/en-US/docs/Web/CSS/Descendant_combinator) or [Child combinator](https://developer.mozilla.org/en-US/docs/Web/CSS/Child_combinator) pierces an arbitrary number of open shadow roots, including the implicit descendant combinator at the start of the selector.
|
||||
|
||||
`css` engine first searches for elements in the light dom in the iteration order, and then recursively inside open shadow roots in the iteration order. It does not search inside closed shadow roots or iframes.
|
||||
|
||||
```html
|
||||
<article>
|
||||
<div>In the light dom</div>
|
||||
<div slot='myslot'>In the light dom, but goes into the shadow slot</div>
|
||||
<open mode shadow root>
|
||||
<div class='in-the-shadow'>
|
||||
<span class='content'>
|
||||
In the shadow dom
|
||||
<open mode shadow root>
|
||||
<li id='target'>Deep in the shadow</li>
|
||||
</open mode shadow root>
|
||||
</span>
|
||||
</div>
|
||||
<slot name='myslot'></slot>
|
||||
</open mode shadow root>
|
||||
</article>
|
||||
```
|
||||
|
||||
Note that `<open mode shadow root>` is not an html element, but rather a shadow root created with `element.attachShadow({mode: 'open'})`.
|
||||
- Both `"css=article div"` and `"css:light=article div"` match the first `<div>In the light dom</div>`.
|
||||
- Both `"css=article > div"` and `"css:light=article > div"` match two `div` elements that are direct children of the `article`.
|
||||
- `"css=article .in-the-shadow"` matches the `<div class='in-the-shadow'>`, piercing the shadow root, while `"css:light=article .in-the-shadow"` does not match anything.
|
||||
- `"css:light=article div > span"` does not match anything, because both light-dom `div` elements do not contain a `span`.
|
||||
- `"css=article div > span"` matches the `<span class='content'>`, piercing the shadow root.
|
||||
- `"css=article > .in-the-shadow"` does not match anything, because `<div class='in-the-shadow'>` is not a direct child of `article`
|
||||
- `"css:light=article > .in-the-shadow"` does not match anything.
|
||||
- `"css=article li#target"` matches the `<li id='target'>Deep in the shadow</li>`, piercing two shadow roots.
|
||||
|
||||
#### CSS extension: visible
|
||||
|
||||
The `:visible` pseudo-class matches elements that are visible as defined in the [actionability](./actionability.md#visible) guide. For example, `input` matches all the inputs on the page, while `input:visible` matches only visible inputs. This is useful to distinguish elements that are very similar but differ in visibility.
|
||||
|
||||
```js
|
||||
// Clicks the first button.
|
||||
await page.click('button');
|
||||
// Clicks the first visible button. If there are some invisible buttons, this click will just ignore them.
|
||||
await page.click('button:visible');
|
||||
```
|
||||
|
||||
Use `:visible` with caution, because it has two major drawbacks:
|
||||
* When elements change their visibility dynamically, `:visible` will give upredictable results based on the timing.
|
||||
* `:visible` forces a layout and may lead to querying being slow, especially when used with `page.waitForSelector(selector[, options])` method.
|
||||
|
||||
#### CSS extension: text
|
||||
|
||||
The `:text` pseudo-class matches elements that have a text node child with specific text. It is similar to the [text engine](#text-and-textlight). There are a few variations that support different arguments:
|
||||
* `:text("substring")` - Matches when element's text contains "substring" somewhere. Matching is case-insensitive. Matching also normalizes whitespace, for example it turns multiple spaces into one, trusn line breaks into spaces and ignores leading and trailing whitespace.
|
||||
* `:text-is("string")` - Matches when element's text equals the "string". Matching is case-insensitive and normalizes whitespace.
|
||||
* `button:text("Sign in")` - Text selector may be combined with regular CSS.
|
||||
* `:text-matches("[+-]?\\d+")` - Matches text against a regular expression. Note that special characters like back-slash `\`, quotes `"`, square brackets `[]` and more should be escaped. Learn more about [regular expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp).
|
||||
* `:text-matches("value", "i")` - Matches text against a regular expression with specified flags.
|
||||
|
||||
```js
|
||||
// Click a button with text "Sign in".
|
||||
await page.click('button:text("Sign in")');
|
||||
```
|
||||
|
||||
#### CSS extension: light
|
||||
|
||||
`css` engine [pierces shadow](#shadow-piercing) by default. It is possible to disable this behavior by wrapping a selector in `:light` pseudo-class: `:light(section > button.class)` matches in light DOM only.
|
||||
|
||||
```js
|
||||
await page.click(':light(.article > .header)');
|
||||
```
|
||||
|
||||
<!--
|
||||
|
||||
#### CSS extension: proximity
|
||||
|
||||
Playwright provides a few proximity selectors based on the page layout. These can be combined with regular CSS for better results, for example `input:right-of(:text("Password"))` matches an input field that is to the right of text "Password".
|
||||
|
||||
Note that Playwright uses some heuristics to determine whether one element should be considered to the left/right/above/below/near/within another. Therefore, using proximity selectors may produce unpredictable results. For example, selector could stop matching when element moves by one pixel.
|
||||
* `:right-of(css > selector)` - Matches elements that are to the right of any element matching the inner selector.
|
||||
* `:left-of(css > selector)` - Matches elements that are to the left of any element matching the inner selector.
|
||||
* `:above(css > selector)` - Matches elements that are above any of the elements matching the inner selector.
|
||||
* `:below(css > selector)` - Matches elements that are below any of the elements matching the inner selector.
|
||||
* `:near(css > selector)` - Matches elements that are near any of the elements matching the inner selector.
|
||||
* `:within(css > selector)` - Matches elements that are within any of the elements matching the inner selector.
|
||||
|
||||
```js
|
||||
// Fill an input to the right of "Username".
|
||||
await page.fill('input:right-of(:text("Username"))');
|
||||
|
||||
// Click a button near the promo card.
|
||||
await page.click('button:near(.promo-card)');
|
||||
```
|
||||
|
||||
-->
|
||||
|
||||
### xpath
|
||||
|
||||
XPath engine is equivalent to [`Document.evaluate`](https://developer.mozilla.org/en/docs/Web/API/Document/evaluate). Example: `xpath=//html/body`.
|
||||
|
||||
Malformed selector starting with `//` or `..` is assumed to be an xpath selector. For example, Playwright converts `page.$('//html/body')` to `page.$('xpath=//html/body')`.
|
||||
|
||||
Note that `xpath` does not pierce shadow roots.
|
||||
|
||||
### text and text:light
|
||||
|
||||
Text engine finds an element that contains a text node with the passed text. For example, `page.click('text=Login')` clicks on a login button, and `page.waitForSelector('"lazy loaded text")` waits for the `"lazy loaded text"` to appear in the page.
|
||||
- By default, the match is case-insensitive, ignores leading/trailing whitespace and searches for a substring. This means `text= Login` matches `<button>Button loGIN (click me)</button>`.
|
||||
- Text body can be escaped with single or double quotes for precise matching, insisting on exact match, including specified whitespace and case. This means `text="Login "` will only match `<button>Login </button>` with exactly one space after "Login". Quoted text follows the usual escaping rules, e.g. use `\"` to escape double quote in a double-quoted string: `text="foo\"bar"`.
|
||||
- Text body can also be a JavaScript-like regex wrapped in `/` symbols. This means `text=/^\\s*Login$/i` will match `<button> loGIN</button>` with any number of spaces before "Login" and no spaces after.
|
||||
- Input elements of the type `button` and `submit` are rendered with their value as text, and text engine finds them. For example, `text=Login` matches `<input type=button value="Login">`.
|
||||
|
||||
Malformed selector starting and ending with a quote (either `"` or `'`) is assumed to be a text selector. For example, Playwright converts `page.click('"Login"')` to `page.click('text="Login"')`.
|
||||
|
||||
`text` engine open pierces shadow roots similarly to `css`, while `text:light` does not. Text engine first searches for elements in the light dom in the iteration order, and then recursively inside open shadow roots in the iteration order. It does not search inside closed shadow roots or iframes.
|
||||
|
||||
### id, data-testid, data-test-id, data-test and their :light counterparts
|
||||
|
||||
Attribute engines are selecting based on the corresponding attribute value. For example: `data-test-id=foo` is equivalent to `css=[data-test-id="foo"]`, and `id:light=foo` is equivalent to `css:light=[id="foo"]`.
|
||||
|
||||
[css]: #css-and-csslight
|
||||
[text]: #text-and-textlight
|
||||
[xpath]: #xpath
|
||||
[id]: #id-data-testid-data-test-id-data-test-and-their-light-counterparts
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,113 +0,0 @@
|
|||
---
|
||||
id: showcase
|
||||
title: "Community Showcase"
|
||||
---
|
||||
|
||||
## Users
|
||||
* [VS Code](https://github.com/microsoft/vscode): Playwright is used to run cross-browser tests on their web builds
|
||||
* [TypeScript](https://github.com/microsoft/TypeScript): Playwright is used test typescript.js across browsers
|
||||
* [Elastic APM JS agent](https://github.com/elastic/apm-agent-rum-js): Playwright is used to run benchmark tests across browsers
|
||||
* [Blockstack](https://github.com/blockstack/ux): Playwright is used to run cross-browser UI tests
|
||||
* [Instakittens React admin](https://github.com/fredericbonnet/instakittens-react-admin): Playwright is used to run end-to-end test scenarios written with Cucumber
|
||||
* [xterm.js](https://github.com/xtermjs/xterm.js): Playwright is used to run cross-browser integration tests
|
||||
* [Accessibility Insights for Web](https://github.com/microsoft/accessibility-insights-web): Playwright is used with Jest and axe-core to run end-to-end functional and accessibility tests of a WebExtension-based browser extension
|
||||
|
||||
## Tools
|
||||
* [CodeceptJS](https://github.com/Codeception/CodeceptJS): Write scenario-driven Playwright tests with synchronous code
|
||||
* [dom-to-playwright](https://github.com/Xiphe/dom-to-playwright) to copy a JSDOM snapshot into a Playwright page.
|
||||
* [expected-condition-playwright](https://github.com/elaichenkov/expected-condition-playwright): Supplies a set of common expected conditions that can wait for certain states and conditions
|
||||
* [Headless Testing](https://headlesstesting.com/support/start/playwright.html): Run Playwright tests on browsers in the cloud
|
||||
* [Lumberjack](https://github.com/JakePartusch/lumberjack): Automated accessibility scanner to run checks on your entire website
|
||||
* [mockiavelli](https://github.com/HLTech/mockiavelli) Request mocking library for Playwright to test SPA in isolation from backend APIs.
|
||||
* [Moon](https://github.com/aerokube/moon): Run Playwright tests in parallel in Kubernetes cluster (free up to 4 parallel sessions)
|
||||
* [playwright-test](https://github.com/hugomrdias/playwright-test) Run unit tests and benchmarks in browsers with Node's seamless experience.
|
||||
* [playwright-video](https://github.com/qawolf/playwright-video): Capture a video while executing a Playwright script
|
||||
* [QA Wolf](https://github.com/qawolf/qawolf): Record and create Playwright tests and then run them in CI
|
||||
* [Root Cause OSS](https://github.com/testimio/root-cause): Capture screenshots on every step and display in a viewer with logs for easy troubleshooting.
|
||||
* [test-real-styles](https://github.com/Xiphe/test-real-styles): Utility to test real styling of virtual DOM elements in a browser
|
||||
* [Testim Playground](https://www.testim.io/playground/): Record Playwright UI tests as code
|
||||
* [Try Playwright](https://try.playwright.tech/): Interactive playground for Playwright to run examples directly from your browser
|
||||
* [Applitools](https://applitools.com): Add AI-powered visual assertions and run your Playwright tests on all browser, device, and viewport combinations in parallel, without requiring any setup.
|
||||
|
||||
## Frameworks
|
||||
* [jest-playwright](https://github.com/mmarkelov/jest-playwright): Jest preset to run Playwright tests with Jest
|
||||
* [query-selector-shadow-dom](https://github.com/Georgegriff/query-selector-shadow-dom): Custom selector engine to pierce shadow DOM roots
|
||||
* [Playwright Sharp](https://github.com/kblok/playwright-sharp): Work in progress port of Playwright to .NET
|
||||
* [playwright-fluent](https://github.com/hdorgeval/playwright-fluent): Fluent API around Playwright
|
||||
* [robotframework-browser](https://robotframework-browser.org/) Robotframework library that uses Playwright to achieve good development ergonomics.
|
||||
|
||||
## Examples
|
||||
* [e2e Boilerplates](https://github.com/e2e-boilerplate?utf8=%E2%9C%93&q=playwright): Project boilerplates for using Playwright with TypeScript, Cucumber, Jest, and other libraries
|
||||
* [react-app-playwright](https://github.com/KyleADay/react-app-playwright): Using Playwright with a create-react-app project
|
||||
* [playwright-react-typescript-jest-example](https://github.com/azemetre/playwright-react-typescript-jest-example): Using Playwright + Jest with a custom webpack configuration for React + Typescript project
|
||||
* [playwright-mocha](https://github.com/roggerfe/playwright-mocha): Using Playwright with Mocha and Chai
|
||||
* [playwright-cljs](https://github.com/apeckham/playwright-cljs): Playwright examples in ClojureScript
|
||||
* [playwright-azure-functions](https://github.com/arjun27/playwright-azure-functions): Playwright setup on Azure Functions
|
||||
* [playwright-aws-lambda](https://github.com/austinkelleher/playwright-aws-lambda): Playwright setup on AWS Lambda
|
||||
* [playwright-jest-circus-allure](https://github.com/d-shch/playwright-jest-circus-allure): Example how to use allure-report and jest-circus with playwright
|
||||
* [Heroku Playwright Example](https://github.com/mxschmitt/heroku-playwright-example): Example using Playwright on Heroku
|
||||
|
||||
## Guides
|
||||
* [theheadless.dev](https://theheadless.dev): Practical guides and runnable examples on Playwright (and Puppeteer)
|
||||
|
||||
## Contributing
|
||||
|
||||
Did we miss something in this list? Send us a PR!
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,165 +0,0 @@
|
|||
---
|
||||
id: test-runners
|
||||
title: "Test Runners"
|
||||
---
|
||||
|
||||
With a few lines of code, you can hook up Playwright to your favorite JavaScript test runner.
|
||||
|
||||
- [Jest / Jasmine](#jest--jasmine)
|
||||
- [AVA](#ava)
|
||||
- [Mocha](#mocha)
|
||||
- [Multiple Browsers](#multiple-browsers)
|
||||
|
||||
## Jest / Jasmine
|
||||
|
||||
For Jest, [jest-playwright](https://github.com/playwright-community/jest-playwright) can be used. However for a light-weight solution, requiring playwright directly works fine. Jest shares it's syntax with Jasmine, so this applies to Jasmine as well.
|
||||
|
||||
```js
|
||||
const {chromium} = require('playwright');
|
||||
const expect = require('expect');
|
||||
let browser;
|
||||
let page;
|
||||
beforeAll(async () => {
|
||||
browser = await chromium.launch();
|
||||
});
|
||||
afterAll(async () => {
|
||||
await browser.close();
|
||||
});
|
||||
beforeEach(async () => {
|
||||
page = await browser.newPage();
|
||||
});
|
||||
afterEach(async () => {
|
||||
await page.close();
|
||||
});
|
||||
|
||||
it('should work', async () => {
|
||||
await page.goto('https://www.example.com/');
|
||||
expect(await page.title()).toBe('Example Domain');
|
||||
});
|
||||
```
|
||||
|
||||
## AVA
|
||||
|
||||
Tests run concurrently in AVA, so a single page variable cannot be shared between tests. Instead, create new pages with a macro function.
|
||||
|
||||
```js
|
||||
const {chromium} = require('playwright');
|
||||
const test = require('ava').default;
|
||||
const browserPromise = chromium.launch();
|
||||
|
||||
async function pageMacro(t, callback) {
|
||||
const browser = await browserPromise;
|
||||
const page = await browser.newPage();
|
||||
try {
|
||||
await callback(t, page);
|
||||
} finally {
|
||||
await page.close();
|
||||
}
|
||||
}
|
||||
|
||||
test('should work', pageMacro, async (t, page) => {
|
||||
await page.goto('https://www.example.com/');
|
||||
t.is(await page.title(), 'Example Domain');
|
||||
});
|
||||
```
|
||||
|
||||
## Mocha
|
||||
|
||||
Mocha looks very similar to the Jest/Jasmine setup, and functions in the same way.
|
||||
|
||||
```js
|
||||
const {chromium} = require('playwright');
|
||||
const assert = require('assert');
|
||||
let browser;
|
||||
before(async() => {
|
||||
browser = await chromium.launch();
|
||||
});
|
||||
after(async () => {
|
||||
await browser.close();
|
||||
});
|
||||
let page;
|
||||
beforeEach(async() => {
|
||||
page = await browser.newPage();
|
||||
});
|
||||
afterEach(async () => {
|
||||
await page.close();
|
||||
});
|
||||
|
||||
it('should work', async () => {
|
||||
await page.goto('https://www.example.com/');
|
||||
assert.equal(await page.title(), 'Example Domain');
|
||||
});
|
||||
```
|
||||
|
||||
## Multiple Browsers
|
||||
|
||||
These simple examples can be extended to support multiple browsers using an environment variable.
|
||||
|
||||
```js
|
||||
const {chromium, webkit, firefox} = require('playwright');
|
||||
const browserName = process.env.BROWSER || 'webkit';
|
||||
let browser;
|
||||
beforeAll(async() => {
|
||||
browser = await {chromium, webkit, firefox}[browserName].launch();
|
||||
});
|
||||
```
|
||||
|
||||
Then set `BROWSER=firefox` to run your tests with firefox, or any other browser.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,95 +0,0 @@
|
|||
---
|
||||
id: troubleshooting
|
||||
title: "Troubleshooting"
|
||||
---
|
||||
|
||||
- [Browser dependencies](#browser-dependencies)
|
||||
- [Code transpilation issues](#code-transpilation-issues)
|
||||
- [Node.js requirements](#nodejs-requirements)
|
||||
- [Please file an issue](#please-file-an-issue)
|
||||
|
||||
## Browser dependencies
|
||||
|
||||
Playwright does self-inspection every time it runs to make sure the browsers can be launched successfully. If there are missing dependencies, playwright will print instructions to acquire them.
|
||||
|
||||
We also provide [Ubuntu 18.04 dockerfile](https://github.com/microsoft/playwright/blob/master/utils/docker/Dockerfile.bionic) and [Ubuntu 20.04 dockerfile](https://github.com/microsoft/playwright/blob/master/utils/docker/Dockerfile.focal) with the list of Debian dependencies.
|
||||
|
||||
## Code transpilation issues
|
||||
|
||||
If you are using a JavaScript transpiler like babel or TypeScript, calling `evaluate()` with an async function might not work. This is because while `playwright` uses `Function.prototype.toString()` to serialize functions while transpilers could be changing the output code in such a way it's incompatible with `playwright`.
|
||||
|
||||
Some workarounds to this problem would be to instruct the transpiler not to mess up with the code, for example, configure TypeScript to use latest ECMAScript version (`"target": "es2018"`). Another workaround could be using string templates instead of functions:
|
||||
|
||||
```js
|
||||
await page.evaluate(`(async() => {
|
||||
console.log('1');
|
||||
})()`);
|
||||
```
|
||||
|
||||
## Node.js requirements
|
||||
|
||||
### ReferenceError: URL is not defined
|
||||
|
||||
Playwright requires Node.js 10 or higher. Node.js 8 is not supported, and will cause you to receive this error.
|
||||
|
||||
# Please file an issue
|
||||
|
||||
Playwright is a new project, and we are watching the issues very closely. As we solve common issues, this document will grow to include the common answers.
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,210 +0,0 @@
|
|||
---
|
||||
id: verification
|
||||
title: "Verification"
|
||||
---
|
||||
|
||||
- [Videos](#videos)
|
||||
- [Screenshots](#screenshots)
|
||||
- [Console logs](#console-logs)
|
||||
- [Page errors](#page-errors)
|
||||
- [Page events](#page-events)
|
||||
|
||||
## Videos
|
||||
|
||||
Playwright can record videos for all pages in a [browser context](core-concepts.md#browser-contexts). Videos are saved upon context closure, so make sure to await `browserContext.close()`.
|
||||
|
||||
```js
|
||||
// With browser.newContext()
|
||||
const context = await browser.newContext({ recordVideo: { dir: 'videos/' } });
|
||||
// Make sure to await close, so that videos are saved.
|
||||
await context.close();
|
||||
|
||||
// With browser.newPage()
|
||||
const page = await browser.newPage({ recordVideo: { dir: 'videos/' } });
|
||||
// Make sure to await close, so that videos are saved.
|
||||
await page.close();
|
||||
|
||||
// [Optional] Specify video size; defaults to viewport size
|
||||
const context = await browser.newContext({
|
||||
recordVideo: {
|
||||
dir: 'videos/',
|
||||
size: { width: 800, height: 600 },
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [BrowserContext]
|
||||
- [browser.newContext([options])](api/class-browser.md#browsernewcontextoptions)
|
||||
- [browser.newPage([options])](api/class-browser.md#browsernewpageoptions)
|
||||
- [browserContext.close()](api/class-browsercontext.md#browsercontextclose)
|
||||
|
||||
## Screenshots
|
||||
|
||||
```js
|
||||
// Save to file
|
||||
await page.screenshot({ path: 'screenshot.png' });
|
||||
|
||||
// Capture full page
|
||||
await page.screenshot({ path: 'screenshot.png', fullPage: true });
|
||||
|
||||
// Capture into buffer
|
||||
const buffer = await page.screenshot();
|
||||
console.log(buffer.toString('base64'));
|
||||
|
||||
// Capture given element
|
||||
const elementHandle = await page.$('.header');
|
||||
await elementHandle.screenshot({ path: 'screenshot.png' });
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [page.screenshot([options])](api/class-page.md#pagescreenshotoptions)
|
||||
- [elementHandle.screenshot([options])](api/class-elementhandle.md#elementhandlescreenshotoptions)
|
||||
|
||||
<br/>
|
||||
|
||||
## Console logs
|
||||
|
||||
Console messages logged in the page can be brought into the Node.js context.
|
||||
|
||||
```js
|
||||
// Listen for all console logs
|
||||
page.on('console', msg => console.log(msg.text()))
|
||||
|
||||
// Listen for all console events and handle errors
|
||||
page.on('console', msg => {
|
||||
if (msg.type() === 'error')
|
||||
console.log(`Error text: "${msg.text()}"`);
|
||||
});
|
||||
|
||||
// Get the next console log
|
||||
const [msg] = await Promise.all([
|
||||
page.waitForEvent('console'),
|
||||
// Issue console.log inside the page
|
||||
page.evaluate(() => {
|
||||
console.log('hello', 42, { foo: 'bar' });
|
||||
}),
|
||||
]);
|
||||
|
||||
// Deconstruct console log arguments
|
||||
await msg.args[0].jsonValue() // hello
|
||||
await msg.args[1].jsonValue() // 42
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [ConsoleMessage]
|
||||
- [Page]
|
||||
- [page.on('console')](api/class-page.md#pageonconsole)
|
||||
|
||||
<br/>
|
||||
|
||||
## Page errors
|
||||
|
||||
Listen for uncaught exceptions in the page with the `pagerror` event.
|
||||
|
||||
```js
|
||||
// Log all uncaught errors to the terminal
|
||||
page.on('pageerror', exception => {
|
||||
console.log(`Uncaught exception: "${exception}"`);
|
||||
});
|
||||
|
||||
// Navigate to a page with an exception.
|
||||
await page.goto('data:text/html,<script>throw new Error("Test")</script>');
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [Page]
|
||||
- [page.on('pageerror')](api/class-page.md#pageonpageerror)
|
||||
|
||||
<br/>
|
||||
|
||||
## Page events
|
||||
|
||||
#### `"requestfailed"`
|
||||
|
||||
```js
|
||||
page.on('requestfailed', request => {
|
||||
console.log(request.url() + ' ' + request.failure().errorText);
|
||||
});
|
||||
```
|
||||
|
||||
#### `"dialog"` - handle alert, confirm, prompt
|
||||
|
||||
```js
|
||||
page.on('dialog', dialog => {
|
||||
dialog.accept();
|
||||
});
|
||||
```
|
||||
|
||||
#### `"popup"` - handle popup windows
|
||||
|
||||
```js
|
||||
const [popup] = await Promise.all([
|
||||
page.waitForEvent('popup'),
|
||||
page.click('#open')
|
||||
]);
|
||||
```
|
||||
|
||||
#### API reference
|
||||
- [Page]
|
||||
- [page.on('requestfailed')](api/class-page.md#pageonrequestfailed)
|
||||
- [page.on('dialog')](api/class-page.md#pageondialog)
|
||||
- [page.on('popup')](api/class-page.md#pageonpopup)
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,100 +0,0 @@
|
|||
---
|
||||
id: why-playwright
|
||||
title: "Why Playwright?"
|
||||
---
|
||||
|
||||
Playwright enables fast, reliable and capable automation across all modern browsers. This guide covers those key differentiators to help you decide on the right tool for your automated tests.
|
||||
|
||||
- [Support for all browsers](#support-for-all-browsers)
|
||||
- [Fast and reliable execution](#fast-and-reliable-execution)
|
||||
- [Powerful automation capabilities](#powerful-automation-capabilities)
|
||||
- [Integrates with your workflow](#integrates-with-your-workflow)
|
||||
- [Limitations](#limitations)
|
||||
|
||||
## Support for all browsers
|
||||
* **Test on Chromium, Firefox and WebKit**. Playwright has full API coverage for all modern browsers, including Google Chrome and Microsoft Edge (with [Chromium](https://www.chromium.org/)), Apple Safari (with [WebKit](https://webkit.org/)) and Mozilla Firefox.
|
||||
* **Cross-platform WebKit testing**. With Playwright, test how your app behaves in Apple Safari with WebKit builds for Windows, Linux and macOS. Test locally and on CI.
|
||||
* **Test for mobile**. Use [device emulation](./emulation.md) to test your responsive web apps in mobile web browsers.
|
||||
* **Headless and headful**. Playwright supports headless (without browser UI) and headful (with browser UI) modes for all browsers and all platforms. Headful is great for debugging, and headless is faster and suited for CI/cloud executions.
|
||||
|
||||
## Fast and reliable execution
|
||||
* **Auto-wait APIs**. Playwright interactions [auto-wait for elements](./actionability.md) to be ready. This improves reliability and simplifies test authoring.
|
||||
* **Timeout-free automation**. Playwright receives browser signals, like network requests, page navigations and page load events to eliminate the need for sleep timeouts that cause flakiness.
|
||||
* **Lean parallelization with browser contexts**. Reuse a single browser instance for multiple parallelized, isolated execution environments with [browser contexts](core-concepts.md).
|
||||
* **Resilient element selectors**. Playwright can rely on user-facing strings, like text content and accessibility labels to [select elements](./selectors.md). These strings are more resilient than selectors tightly-coupled to the DOM structure.
|
||||
|
||||
## Powerful automation capabilities
|
||||
* **Multiple domains, pages and frames**. Playwright is an out-of-process automation driver that is not limited by the scope of in-page JavaScript execution and can automate scenarios with [multiple pages](multi-pages.md).
|
||||
* **Powerful network control**. Playwright introduces context-wide [network interception](./network.md) to stub and mock network requests.
|
||||
* **Modern web features**. Playwright supports web components through [shadow-piercing selectors](./selectors.md), [geolocation, permissions](./emulation.md), web workers and other modern web APIs.
|
||||
* **Capabilities to cover all scenarios**. Support for [file downloads](./network.md) and [uploads](./input.md), out-of-process iframes, native [input events](./input.md), and even [dark mode](./emulation.md).
|
||||
|
||||
## Integrates with your workflow
|
||||
* **One-line installation**. Running `npm i playwright` auto-downloads browser dependencies for your team to be onboarded quickly.
|
||||
* **TypeScript support**. Playwright ships with built-in types for auto-completion and other benefits.
|
||||
* **Debugging tools**. Playwright works with the [editor debugger and browser developer tools](./debug.md) to pause execution and inspect the web page.
|
||||
* **Language bindings**. Playwright is also available in [Python](https://github.com/microsoft/playwright-python) and [C#](https://github.com/microsoft/playwright-sharp). Learn about [supported languages](./languages.md).
|
||||
* **Deploy tests to CI**. First-party [Docker image](./docker.md) and [GitHub Actions](https://github.com/microsoft/playwright-github-action) to deploy tests to [your preferred CI/CD provider](./ci.md).
|
||||
|
||||
## Limitations
|
||||
* **Legacy Edge and IE11 support**. Playwright does not support legacy Microsoft Edge or IE11 ([deprecation notice](https://techcommunity.microsoft.com/t5/microsoft-365-blog/microsoft-365-apps-say-farewell-to-internet-explorer-11-and/ba-p/1591666)). The new Microsoft Edge (on Chromium) is supported.
|
||||
* **Java language bindings**: The Playwright API cannot be used in Java or Ruby today. This is a temporary limitation as Playwright is built to support bindings for any language.
|
||||
* **Test on real mobile devices**: Playwright uses desktop browsers to emulate mobile devices. If you are interested in running on real mobile devices, please [upvote this issue](https://github.com/microsoft/playwright/issues/1122).
|
||||
|
||||
[Playwright]: api/class-playwright.md "Playwright"
|
||||
[Browser]: api/class-browser.md "Browser"
|
||||
[BrowserContext]: api/class-browsercontext.md "BrowserContext"
|
||||
[Page]: api/class-page.md "Page"
|
||||
[Frame]: api/class-frame.md "Frame"
|
||||
[ElementHandle]: api/class-elementhandle.md "ElementHandle"
|
||||
[JSHandle]: api/class-jshandle.md "JSHandle"
|
||||
[ConsoleMessage]: api/class-consolemessage.md "ConsoleMessage"
|
||||
[Dialog]: api/class-dialog.md "Dialog"
|
||||
[Download]: api/class-download.md "Download"
|
||||
[Video]: api/class-video.md "Video"
|
||||
[FileChooser]: api/class-filechooser.md "FileChooser"
|
||||
[Keyboard]: api/class-keyboard.md "Keyboard"
|
||||
[Mouse]: api/class-mouse.md "Mouse"
|
||||
[Touchscreen]: api/class-touchscreen.md "Touchscreen"
|
||||
[Request]: api/class-request.md "Request"
|
||||
[Response]: api/class-response.md "Response"
|
||||
[Selectors]: api/class-selectors.md "Selectors"
|
||||
[Route]: api/class-route.md "Route"
|
||||
[WebSocket]: api/class-websocket.md "WebSocket"
|
||||
[TimeoutError]: api/class-timeouterror.md "TimeoutError"
|
||||
[Accessibility]: api/class-accessibility.md "Accessibility"
|
||||
[Worker]: api/class-worker.md "Worker"
|
||||
[BrowserServer]: api/class-browserserver.md "BrowserServer"
|
||||
[BrowserType]: api/class-browsertype.md "BrowserType"
|
||||
[Logger]: api/class-logger.md "Logger"
|
||||
[ChromiumBrowser]: api/class-chromiumbrowser.md "ChromiumBrowser"
|
||||
[ChromiumBrowserContext]: api/class-chromiumbrowsercontext.md "ChromiumBrowserContext"
|
||||
[ChromiumCoverage]: api/class-chromiumcoverage.md "ChromiumCoverage"
|
||||
[CDPSession]: api/class-cdpsession.md "CDPSession"
|
||||
[FirefoxBrowser]: api/class-firefoxbrowser.md "FirefoxBrowser"
|
||||
[WebKitBrowser]: api/class-webkitbrowser.md "WebKitBrowser"
|
||||
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array"
|
||||
[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer"
|
||||
[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess"
|
||||
[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element"
|
||||
[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error"
|
||||
[Evaluation Argument]: ./core-concepts.md#evaluationargument "Evaluation Argument"
|
||||
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map"
|
||||
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object"
|
||||
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp"
|
||||
[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable"
|
||||
[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail"
|
||||
[URL]: https://nodejs.org/api/url.html "URL"
|
||||
[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout"
|
||||
[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
|
||||
[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"
|
||||
[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null"
|
||||
[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"
|
||||
[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"
|
||||
[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable"
|
||||
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string"
|
||||
[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath"
|
||||
|
|
@ -1,53 +0,0 @@
|
|||
---
|
||||
id: README
|
||||
title: "Documentation"
|
||||
---
|
||||
|
||||
### Capabilities
|
||||
|
||||
Playwright is a library to automate [Chromium](https://www.chromium.org/Home), [Firefox](https://www.mozilla.org/en-US/firefox/new/) and [WebKit](https://webkit.org/) with a single API. Playwright is built to enable cross-browser web automation that is **ever-green**, **capable**, **reliable** and **fast**.
|
||||
|
||||
* Ever-green browser engines
|
||||
* Headless execution
|
||||
* Scenarios that span multiple pages, domains and iframes
|
||||
* Auto-wait for elements to be ready before executing actions (like click, fill)
|
||||
* Reliable signals instead of timeouts (like network response, popup, navigation)
|
||||
* Intercept network activity for stubbing and mocking network requests
|
||||
* Emulate mobile devices, geolocation, permissions
|
||||
* Support for web components via shadow-piercing selectors
|
||||
* Native input events for mouse and keyboard
|
||||
* Upload and download files
|
||||
|
||||
### Table of contents
|
||||
|
||||
1. Introduction
|
||||
- [Why Playwright?](./why-playwright.md)
|
||||
- [Get started](./intro.md)
|
||||
- [Core concepts](./core-concepts.md)
|
||||
- [Debugging](./debug.md)
|
||||
- [Supported languages](./languages.md)
|
||||
1. Guides
|
||||
- [Selectors](./selectors.md)
|
||||
- [Input](./input.md)
|
||||
- [Emulation](./emulation.md)
|
||||
- [Network](./network.md)
|
||||
- [Assertions](./assertions.md)
|
||||
- [Verification](./verification.md)
|
||||
- [Navigations](./navigations.md)
|
||||
- [Multi-page scenarios](./multi-pages.md)
|
||||
1. Tutorials
|
||||
- [Authentication](./auth.md)
|
||||
- [Page object models](./pom.md)
|
||||
1. Integrations
|
||||
- [Test runners](./test-runners.md)
|
||||
- [Docker](./docker.md)
|
||||
- [Continuous integration](./ci.md)
|
||||
1. Reference
|
||||
- [API Reference](./api/class-playwright.md)
|
||||
- [Actionability](./actionability.md)
|
||||
- [Advanced installation](./installation.md)
|
||||
- [Extensibility](./extensibility.md)
|
||||
1. Get help
|
||||
- [Slack community](https://join.slack.com/t/playwright/shared_invite/enQtOTEyMTUxMzgxMjIwLThjMDUxZmIyNTRiMTJjNjIyMzdmZDA3MTQxZWUwZTFjZjQwNGYxZGM5MzRmNzZlMWI5ZWUyOTkzMjE5Njg1NDg)
|
||||
- [Stack Overflow](https://stackoverflow.com/tags/playwright)
|
||||
- [GitHub](https://github.com/microsoft/playwright/issues)
|
||||
|
|
@ -5,19 +5,34 @@ title: "Actionability"
|
|||
|
||||
Playwright does a range of actionability checks on the elements before performing certain actions. These checks ensure that action behaves as expected, for example Playwright does not click on a disabled button.
|
||||
|
||||
Playwright waits until all the relevant actionability checks pass before performing an action. This means that action will fail with `TimeoutError` if checks do not pass within the specified `timeout`.
|
||||
Playwright waits until all the relevant actionability checks pass before performing an action. This means that action will fail with the `TimeoutError` if checks do not pass within the specified `timeout`.
|
||||
|
||||
Some actions like `page.click()` support `{force: true}` option that disable non-essential actionability checks, for example passing `force` to `click()` method will not check that the target element actually receives click events.
|
||||
Some actions like [`method: Page.click`] support `force` option that disables non-essential actionability checks, for example passing truthy `force` to [`method: Page.click`] method will not check that the target element actually receives click events.
|
||||
|
||||
| Actions | Performed checks |
|
||||
| ------ | ------- |
|
||||
| `check()`<br></br>`click()`<br></br>`dblclick()`<br></br>`tap()`<br></br>`uncheck()` | [Visible]<br></br>[Stable]<br></br>[Enabled]<br></br>[Receiving Events]<br></br>[Attached] |
|
||||
| `hover()` | [Visible]<br></br>[Stable]<br></br>[Receiving Events]<br></br>[Attached] |
|
||||
| `fill()` | [Visible]<br></br>[Enabled]<br></br>[Editable]<br></br>[Attached] |
|
||||
| `dispatchEvent()`<br></br>`focus()`<br></br>`press()`<br></br>`setInputFiles()`<br></br>`selectOption()`<br></br>`type()` | [Attached] |
|
||||
| `scrollIntoViewIfNeeded()`<br></br>`screenshot()` | [Visible]<br></br>[Stable]<br></br>[Attached] |
|
||||
| `selectText()` | [Visible]<br></br>[Attached] |
|
||||
| `getAttribute()`<br></br>`innerText()`<br></br>`innerHTML()`<br></br>`textContent()` | [Attached] |
|
||||
| Action | [Attached] | [Visible] | [Stable] | [Receiving Events] | [Enabled] | [Editable] |
|
||||
| :- | :-: | :-: | :-: | :-: | :-: | :-: |
|
||||
| [`method: ElementHandle.check`] | Yes | Yes | Yes | Yes | Yes | - |
|
||||
| [`method: ElementHandle.click`] | Yes | Yes | Yes | Yes | Yes | - |
|
||||
| [`method: ElementHandle.dblclick`] | Yes | Yes | Yes | Yes | Yes | - |
|
||||
| [`method: ElementHandle.tap`] | Yes | Yes | Yes | Yes | Yes | - |
|
||||
| [`method: ElementHandle.uncheck`] | Yes | Yes | Yes | Yes | Yes | - |
|
||||
| [`method: ElementHandle.hover`] | Yes | Yes | Yes | Yes | - | - |
|
||||
| [`method: ElementHandle.scrollIntoViewIfNeeded`] | Yes | Yes | Yes | - | - | - |
|
||||
| [`method: ElementHandle.screenshot`] | Yes | Yes | Yes | - | - | - |
|
||||
| [`method: ElementHandle.fill`] | Yes | Yes | - | - | Yes | Yes |
|
||||
| [`method: ElementHandle.selectText`] | Yes | Yes | - | - | - | - |
|
||||
| [`method: ElementHandle.getAttribute`] | Yes | - | - | - | - | - |
|
||||
| [`method: ElementHandle.dispatchEvent`] | Yes | - | - | - | - | - |
|
||||
| [`method: ElementHandle.focus`] | Yes | - | - | - | - | - |
|
||||
| [`method: ElementHandle.innerText`] | Yes | - | - | - | - | - |
|
||||
| [`method: ElementHandle.innerHTML`] | Yes | - | - | - | - | - |
|
||||
| [`method: ElementHandle.press`] | Yes | - | - | - | - | - |
|
||||
| [`method: ElementHandle.setInputFiles`] | Yes | - | - | - | - | - |
|
||||
| [`method: ElementHandle.selectOption`] | Yes | - | - | - | - | - |
|
||||
| [`method: ElementHandle.textContent`] | Yes | - | - | - | - | - |
|
||||
| [`method: ElementHandle.type`] | Yes | - | - | - | - | - |
|
||||
|
||||
<br/>
|
||||
|
||||
### Visible
|
||||
|
||||
|
|
@ -43,11 +58,11 @@ Element is considered receiving pointer events when it is the hit target of the
|
|||
|
||||
Element is considered attached when it is [connected](https://developer.mozilla.org/en-US/docs/Web/API/Node/isConnected) to a Document or a ShadowRoot.
|
||||
|
||||
Attached check differs between selector-based and handle-based actions, like `page.click(selector, options)` as opposite to `elementHandle.click(options)`:
|
||||
Attached check differs between selector-based and handle-based actions, like [`method: Page.click`] as opposite to [`method: ElementHandle.click`]:
|
||||
- For selector-based actions, Playwright first waits for an element matching `selector` to be attached to the DOM, and then checks that element is still attached before performing the action. If element was detached, the action is retried from the start.
|
||||
- For handle-based actions, Playwright throws if the element is not attached.
|
||||
|
||||
For example, consider a scenario where Playwright will click `Sign Up` button regardless of when the `page.click()` call was made:
|
||||
For example, consider a scenario where Playwright will click `Sign Up` button regardless of when the [`method: Page.click`] call was made:
|
||||
- page is checking that user name is unique and `Sign Up` button is disabled;
|
||||
- after checking with the server, the disabled `Sign Up` button is replaced with another one that is now enabled.
|
||||
|
||||
|
|
|
|||
|
|
@ -6,8 +6,6 @@ title: "Assertions"
|
|||
The Playwright API can be used to read element contents and properties for test assertions. These values are fetched from the browser page and asserted in
|
||||
Node.js.
|
||||
|
||||
The examples in this guide use the built-in [`assert` module](https://nodejs.org/api/assert.html), but they can be used with any assertion library (like [Expect](https://www.npmjs.com/package/expect) or [Chai](https://www.npmjs.com/package/chai)). See [Test runners](test-runners.md) for more info.
|
||||
|
||||
<!-- TOC -->
|
||||
|
||||
## Common patterns
|
||||
|
|
@ -17,6 +15,9 @@ text content of an element. These APIs require a [selector](./selectors.md) to l
|
|||
the element.
|
||||
|
||||
```js
|
||||
// This example uses the Node.js's built-in `assert` module,
|
||||
// but any assertion library (Expect, Chai, etc.) will work.
|
||||
|
||||
// Assert text content
|
||||
const content = await page.textContent('nav:first-child');
|
||||
assert(content === 'home');
|
||||
|
|
@ -52,7 +53,7 @@ assert(checked);
|
|||
[ElementHandle] objects represent in-page DOM
|
||||
elements. They can be used to assert for multiple properties of the element.
|
||||
|
||||
It is recommended to fetch the `ElementHandle` object with
|
||||
It is recommended to fetch the [ElementHandle] object with
|
||||
[`method: Page.waitForSelector`] or [`method: Frame.waitForSelector`]. These
|
||||
APIs wait for the element to be visible and then return an `ElementHandle`.
|
||||
|
||||
|
|
|
|||
|
|
@ -12,8 +12,7 @@ contexts can load existing authentication state. This eliminates the need to
|
|||
login in every context and speeds up test execution.
|
||||
|
||||
> Note: This guide covers cookie/token-based authentication (logging in via the
|
||||
app UI). For [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication)
|
||||
use [`browser.newContext`](./network.md#http-authentication).
|
||||
app UI). For [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) use [`method: Browser.newContext`].
|
||||
|
||||
<!-- TOC -->
|
||||
|
||||
|
|
@ -125,8 +124,8 @@ on any external state.
|
|||
|
||||
### Example
|
||||
|
||||
[This example script](examples/authentication.js) logs in on GitHub.com with
|
||||
Chromium, and then reuses the logged in cookie state in WebKit.
|
||||
[This example script](https://github.com/microsoft/playwright/blob/master/docs/examples/authentication.js) logs in
|
||||
on GitHub.com with Chromium, and then reuses the logged in cookie state in WebKit.
|
||||
|
||||
### API reference
|
||||
- [BrowserContext]
|
||||
|
|
@ -148,7 +147,7 @@ Note that persistent authentication is not suited for CI environments since it
|
|||
relies on a disk location. User data directories are specific to browser types
|
||||
and cannot be shared across browser types.
|
||||
|
||||
User data directories can be used with the `launchPersistentContext` API.
|
||||
User data directories can be used with the [`method: BrowserType.launchPersistentContext`] API.
|
||||
|
||||
```js
|
||||
const { chromium } = require('playwright');
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ steps:
|
|||
run: npm test
|
||||
```
|
||||
|
||||
We run [our tests](/.github/workflows/tests.yml) on GitHub Actions, across a matrix of 3 platforms (Windows, Linux, macOS) and 3 browsers (Chromium, Firefox, WebKit).
|
||||
We run [our tests](https://github.com/microsoft/playwright/blob/master/.github/workflows/tests.yml) on GitHub Actions, across a matrix of 3 platforms (Windows, Linux, macOS) and 3 browsers (Chromium, Firefox, WebKit).
|
||||
|
||||
### Docker
|
||||
|
||||
|
|
|
|||
|
|
@ -182,7 +182,8 @@ const sectionText = await page.$eval('*css=section >> text=Selectors', e => e.te
|
|||
|
||||
## Auto-waiting
|
||||
|
||||
Actions like `click` and `fill` auto-wait for the element to be visible and [actionable](./actionability.md). For example, click will:
|
||||
Actions like [`method: Page.click`] and [`method: Page.fill`] auto-wait for the element to be visible
|
||||
and [actionable](./actionability.md). For example, click will:
|
||||
- wait for an element with the given selector to appear in the DOM
|
||||
- wait for it to become visible: have non-empty bounding box and no `visibility:hidden`
|
||||
- wait for it to stop moving: for example, wait until css transition finishes
|
||||
|
|
|
|||
|
|
@ -166,7 +166,7 @@ await page.type('#area', 'Hello World!');
|
|||
|
||||
This method will emit all the necessary keyboard events, with all the `keydown`, `keyup`, `keypress` events in place. You can even specify the optional `delay` between the key presses to simulate real user behavior.
|
||||
|
||||
> **NOTE** that most of the time, [`page.fill`](#text-input) will just work. You only need to type characters if there is special keyboard handling on the page.
|
||||
> **NOTE** that most of the time, [`method: Page.fill`] will just work. You only need to type characters if there is special keyboard handling on the page.
|
||||
|
||||
#### API reference
|
||||
|
||||
|
|
@ -247,7 +247,7 @@ await page.setInputFiles('input#upload', {
|
|||
});
|
||||
```
|
||||
|
||||
You can select input files for upload using the `page.setInputFiles` method. It expects first argument to point to an [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) with the type `"file"`. Multiple files can be passed in the array. If some of the file paths are relative, they are resolved relative to the [current working directory](https://nodejs.org/api/process.html#process_process_cwd). Empty array clears the selected files.
|
||||
You can select input files for upload using the [`method: Page.setInputFiles`] method. It expects first argument to point to an [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) with the type `"file"`. Multiple files can be passed in the array. If some of the file paths are relative, they are resolved relative to the [current working directory](https://nodejs.org/api/process.html#process_process_cwd). Empty array clears the selected files.
|
||||
|
||||
#### Example
|
||||
|
||||
|
|
|
|||
|
|
@ -96,11 +96,11 @@ Body format is assumed to ignore leading and trailing white spaces, so that extr
|
|||
### Short-forms
|
||||
For convenience, common selectors have short-forms:
|
||||
- Selector starting with `//` or `..` is assumed to be `xpath=selector`
|
||||
- Example: `page.click('//html')` is converted to `page.click('xpath=//html')`.
|
||||
- Example: `'//html'` is converted to `'xpath=//html'`.
|
||||
- Selector starting and ending with a quote (either `"` or `'`) is assumed to be `text=selector`
|
||||
- Example: `page.click('"foo"')` is converted to `page.click('text="foo"')`.
|
||||
- Example: `'"foo"'` is converted to `'text="foo"'`.
|
||||
- Otherwise, selector is assumed to be `css=selector`
|
||||
- Example: `page.click('div')` is converted to `page.click('css=div')`.
|
||||
- Example: `'div'` is converted to `'css=div'`.
|
||||
|
||||
### Chaining selectors
|
||||
Selectors defined as `engine=body` or in short-form can be combined with the `>>` token, e.g. `selector1 >> selector2 >> selectors3`. When selectors are chained, next one is queried relative to the previous one's result.
|
||||
|
|
@ -206,7 +206,7 @@ const handle = await divHandle.$('css=span');
|
|||
## Selector engines
|
||||
### css and css:light
|
||||
|
||||
`css` is a default engine - any malformed selector not starting with `//` nor starting and ending with a quote is assumed to be a css selector. For example, Playwright converts `page.$('span > button')` to `page.$('css=span > button')`.
|
||||
`css` is a default engine - any malformed selector not starting with `//` nor starting and ending with a quote is assumed to be a css selector. For example, Playwright converts `'span > button'` to `'css=span > button'`.
|
||||
|
||||
Playwright augments standard CSS selectors in two ways, see below for more details:
|
||||
* `css` engine pierces open shadow DOM by default.
|
||||
|
|
@ -312,7 +312,7 @@ await page.click('button:near(.promo-card)');
|
|||
|
||||
XPath engine is equivalent to [`Document.evaluate`](https://developer.mozilla.org/en/docs/Web/API/Document/evaluate). Example: `xpath=//html/body`.
|
||||
|
||||
Malformed selector starting with `//` or `..` is assumed to be an xpath selector. For example, Playwright converts `page.$('//html/body')` to `page.$('xpath=//html/body')`.
|
||||
Malformed selector starting with `//` or `..` is assumed to be an xpath selector. For example, Playwright converts `'//html/body'` to `'xpath=//html/body'`.
|
||||
|
||||
Note that `xpath` does not pierce shadow roots.
|
||||
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ title: "Verification"
|
|||
|
||||
## Videos
|
||||
|
||||
Playwright can record videos for all pages in a [browser context](core-concepts.md#browser-contexts). Videos are saved upon context closure, so make sure to await `browserContext.close()`.
|
||||
Playwright can record videos for all pages in a [browser context](core-concepts.md#browser-contexts). Videos are saved upon context closure, so make sure to await [`method: BrowserContext.close`].
|
||||
|
||||
```js
|
||||
// With browser.newContext()
|
||||
|
|
|
|||
|
|
@ -20,9 +20,7 @@
|
|||
const playwright = require('../../');
|
||||
const fs = require('fs');
|
||||
const path = require('path');
|
||||
const md = require('../markdown');
|
||||
const { MDOutline } = require('./MDBuilder');
|
||||
const Documentation = require('./Documentation');
|
||||
const missingDocs = require('./missingDocs');
|
||||
|
||||
/** @typedef {import('./Documentation').Type} Type */
|
||||
|
|
@ -41,98 +39,8 @@ run().catch(e => {
|
|||
|
||||
async function run() {
|
||||
const outline = new MDOutline(path.join(PROJECT_DIR, 'docs', 'src', 'api-body.md'), path.join(PROJECT_DIR, 'docs', 'src', 'api-params.md'));
|
||||
outline.setLinkRenderer(item => {
|
||||
const { clazz, member, param, option } = item;
|
||||
if (param)
|
||||
return `\`${param}\``;
|
||||
if (option)
|
||||
return `\`${option}\``;
|
||||
if (clazz)
|
||||
return `[${clazz.name}]`;
|
||||
return createMemberLink(member);
|
||||
});
|
||||
|
||||
let generatedLinksSuffix;
|
||||
{
|
||||
const links = fs.readFileSync(path.join(PROJECT_DIR, 'docs', 'src', 'links.md')).toString();
|
||||
const localLinks = [];
|
||||
for (const clazz of outline.classesArray)
|
||||
localLinks.push(`[${clazz.name}]: api/class-${clazz.name.toLowerCase()}.md "${clazz.name}"`);
|
||||
generatedLinksSuffix = '\n' + localLinks.join('\n') + '\n' + links;
|
||||
}
|
||||
|
||||
// Produce api.md
|
||||
{
|
||||
for (const clazz of outline.classesArray) {
|
||||
/** @type {MarkdownNode[]} */
|
||||
const result = [];
|
||||
result.push({
|
||||
type: 'text',
|
||||
text: `---
|
||||
id: class-${clazz.name.toLowerCase()}
|
||||
title: "${clazz.name}"
|
||||
---
|
||||
`});
|
||||
result.push(...(clazz.spec || []).map(c => md.clone(c)));
|
||||
result.push({
|
||||
type: 'text',
|
||||
text: ''
|
||||
});
|
||||
result.push(...generateClassToc(clazz));
|
||||
if (clazz.extends && clazz.extends !== 'EventEmitter' && clazz.extends !== 'Error') {
|
||||
const superClass = outline.documentation.classes.get(clazz.extends);
|
||||
result.push(...generateClassToc(superClass));
|
||||
}
|
||||
|
||||
for (const member of clazz.membersArray) {
|
||||
// Iterate members
|
||||
/** @type {MarkdownNode} */
|
||||
const memberNode = { type: 'h2', children: [] };
|
||||
if (member.kind === 'event') {
|
||||
memberNode.text = `${clazz.varName}.on('${member.name}')`;
|
||||
} else if (member.kind === 'property') {
|
||||
memberNode.text = `${clazz.varName}.${member.name}`;
|
||||
} else if (member.kind === 'method') {
|
||||
// Patch method signatures
|
||||
memberNode.text = `${clazz.varName}.${member.name}(${member.signature})`;
|
||||
for (const arg of member.argsArray)
|
||||
memberNode.children.push(renderProperty(`\`${arg.name}\``, arg.type, arg.spec));
|
||||
}
|
||||
|
||||
// Append type
|
||||
if (member.type && member.type.name !== 'void') {
|
||||
let name;
|
||||
switch (member.kind) {
|
||||
case 'event': name = 'type:'; break;
|
||||
case 'property': name = 'type:'; break;
|
||||
case 'method': name = 'returns:'; break;
|
||||
}
|
||||
memberNode.children.push(renderProperty(name, member.type));
|
||||
}
|
||||
|
||||
// Append member doc
|
||||
memberNode.children.push(...(member.spec || []).map(c => md.clone(c)));
|
||||
result.push(memberNode);
|
||||
}
|
||||
writeAssumeNoop(path.join(PROJECT_DIR, 'docs', 'out', 'api', `class-${clazz.name.toLowerCase()}.md`), [md.render(result), generatedLinksSuffix].join('\n'), dirtyFiles);
|
||||
}
|
||||
}
|
||||
|
||||
// Produce other docs
|
||||
{
|
||||
for (const name of fs.readdirSync(path.join(PROJECT_DIR, 'docs', 'src'))) {
|
||||
if (name === 'links.md' || name.startsWith('api-'))
|
||||
continue;
|
||||
const content = fs.readFileSync(path.join(PROJECT_DIR, 'docs', 'src', name)).toString();
|
||||
const nodes = md.parse(content);
|
||||
outline.renderLinksInText(nodes);
|
||||
for (const node of nodes) {
|
||||
if (node.text === '<!-- TOC -->')
|
||||
node.text = md.generateToc(nodes);
|
||||
}
|
||||
writeAssumeNoop(path.join(PROJECT_DIR, 'docs', 'out', name), [md.render(nodes), generatedLinksSuffix].join('\n'), dirtyFiles);
|
||||
}
|
||||
}
|
||||
// This validates member links.
|
||||
outline.setLinkRenderer(() => undefined);
|
||||
|
||||
// Patch README.md
|
||||
{
|
||||
|
|
@ -205,104 +113,3 @@ async function getBrowserVersions() {
|
|||
await Promise.all(browsers.map(browser => browser.close()));
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* @param {string} file
|
||||
* @param {string} text
|
||||
*/
|
||||
function createLink(file, text) {
|
||||
const key = file + '#' + text;
|
||||
if (links.has(key))
|
||||
return links.get(key);
|
||||
const baseLink = file + '#' + text.toLowerCase().split(',').map(c => c.replace(/[^a-z]/g, '')).join('-');
|
||||
let link = baseLink;
|
||||
let index = 0;
|
||||
while (rLinks.has(link))
|
||||
link = baseLink + '-' + (++index);
|
||||
const result = `[${text}](${link})`;
|
||||
links.set(key, result);
|
||||
rLinks.set(link, text);
|
||||
return result;
|
||||
};
|
||||
|
||||
/**
|
||||
* @param {Documentation.Member} member
|
||||
* @return {string}
|
||||
*/
|
||||
function createMemberLink(member) {
|
||||
const file = `api/class-${member.clazz.name.toLowerCase()}.md`;
|
||||
if (member.kind === 'property')
|
||||
return createLink(file, `${member.clazz.varName}.${member.name}`);
|
||||
|
||||
if (member.kind === 'event')
|
||||
return createLink(file, `${member.clazz.varName}.on('${member.name}')`);
|
||||
|
||||
if (member.kind === 'method')
|
||||
return createLink(file, `${member.clazz.varName}.${member.name}(${member.signature})`);
|
||||
}
|
||||
|
||||
/**
|
||||
* @param {Documentation.Class} clazz
|
||||
* @return {MarkdownNode[]}
|
||||
*/
|
||||
function generateClassToc(clazz) {
|
||||
/** @type {MarkdownNode[]} */
|
||||
const result = [];
|
||||
for (const member of clazz.membersArray) {
|
||||
result.push({
|
||||
type: 'li',
|
||||
liType: 'default',
|
||||
text: createMemberLink(member)
|
||||
});
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* @param {string} name
|
||||
* @param {Type} type
|
||||
* @param {MarkdownNode[]} [spec]
|
||||
*/
|
||||
function renderProperty(name, type, spec) {
|
||||
let comment = '';
|
||||
if (spec && spec.length)
|
||||
comment = spec[0].text;
|
||||
let children;
|
||||
const properties = type.deepProperties();
|
||||
if (properties && properties.length)
|
||||
children = properties.map(p => renderProperty(`\`${p.name}\``, p.type, p.spec))
|
||||
else if (spec && spec.length > 1)
|
||||
children = spec.slice(1).map(s => md.clone(s));
|
||||
|
||||
let typeText = renderType(type);
|
||||
if (typeText === '[Promise]<[void]>')
|
||||
typeText = '[Promise]';
|
||||
|
||||
/** @type {MarkdownNode} */
|
||||
const result = {
|
||||
type: 'li',
|
||||
liType: 'default',
|
||||
text: `${name} <${typeText}>${comment ? ' ' + comment : ''}`,
|
||||
children
|
||||
};
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* @param {Documentation.Type} type
|
||||
*/
|
||||
function renderType(type) {
|
||||
if (type.union)
|
||||
return type.union.map(l => renderType(l)).join('|');
|
||||
if (type.templates)
|
||||
return `[${type.name}]<${type.templates.map(l => renderType(l)).join(', ')}>`;
|
||||
if (type.args)
|
||||
return `[function]\\(${type.args.map(l => renderType(l)).join(', ')}\\)${type.returnType ? ':' + renderType(type.returnType) : ''}`;
|
||||
if (type.name.startsWith('"'))
|
||||
return type.name;
|
||||
if (type.name === 'int' || type.name === 'float')
|
||||
return '[number]';
|
||||
if (type.name === 'path')
|
||||
return '[string]';
|
||||
return `[${type.name}]`;
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue