diff --git a/docs/api.md b/docs/api.md index c51867ef0d..b04416b3b2 100644 --- a/docs/api.md +++ b/docs/api.md @@ -24,13 +24,10 @@ - [class: Accessibility](#class-accessibility) - [class: Coverage](#class-coverage) - [class: Worker](#class-worker) -- [class: ChromiumPlaywright](#class-chromiumplaywright) - [class: ChromiumBrowser](#class-chromiumbrowser) - [class: ChromiumSession](#class-chromiumsession) - [class: ChromiumTarget](#class-chromiumtarget) -- [class: FirefoxPlaywright](#class-firefoxplaywright) - [class: FirefoxBrowser](#class-firefoxbrowser) -- [class: WebKitPlaywright](#class-webkitplaywright) - [class: WebKitBrowser](#class-webkitbrowser) - [Working with selectors](#working-with-selectors) - [Working with Chrome Extensions](#working-with-chrome-extensions) @@ -53,21 +50,43 @@ const playwright = require('playwright').chromium; // Or 'firefox' or 'webkit'. })(); ``` -See [chromiumPlaywright.launch([options])](#chromiumplaywrightlaunchoptions), [firefoxPlaywright.launch([options])](#firefoxplaywrightlaunchoptions) or [webkitPlaywright.launch([options])](#webkitplaywrightlaunchoptions) for browser-specific launch methods. - Playwright automatically downloads browser executables during installation, see [Downloaded browsers](#downloaded-browsers) for more information. +- [playwright.connect(options)](#playwrightconnectoptions) +- [playwright.defaultArgs([options])](#playwrightdefaultargsoptions) - [playwright.devices](#playwrightdevices) - [playwright.errors](#playwrighterrors) - [playwright.executablePath()](#playwrightexecutablepath) +- [playwright.launch([options])](#playwrightlaunchoptions) +- [playwright.launchBrowserApp([options])](#playwrightlaunchbrowserappoptions) +#### playwright.connect(options) +- `options` <[Object]> + - `browserWSEndpoint` A browser websocket endpoint to connect to. + - `slowMo` <[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. + - `browserURL` **Chromium-only** A browser url to connect to, in format `http://${host}:${port}`. Use interchangeably with `browserWSEndpoint` to let Playwright fetch it from [metadata endpoint](https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target). + - `transport` <[ConnectionTransport]> **Experimental** Specify a custom transport object for Playwright to use. +- returns: <[Promise]<[Browser]>> + +This methods attaches Playwright to an existing browser instance. + +#### playwright.defaultArgs([options]) +- `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields: + - `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`. + - `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/). + - `userDataDir` <[string]> Path to a [User Data Directory](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md). + - `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`. +- returns: <[Array]<[string]>> + +The default flags that browser will be launched with. + #### playwright.devices - returns: <[Object]> Returns a list of devices to be used with [`page.emulate(options)`](#pageemulateoptions). Actual list of -devices can be found in [lib/deviceDescriptors.js](https://github.com/Microsoft/playwright/blob/master/src/deviceDescriptors.ts). +devices can be found in [src/deviceDescriptors.ts](https://github.com/Microsoft/playwright/blob/master/src/deviceDescriptors.ts). ```js const playwright = require('playwright').firefox; // Or 'chromium' or 'webkit'. @@ -93,7 +112,7 @@ Playwright methods might throw errors if they are unable to fulfill a request. F 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) +These classes are available via [`playwright.errors`](#playwrighterrors). An example of handling a timeout error: ```js @@ -107,7 +126,59 @@ try { ``` #### playwright.executablePath() -- returns: <[string]> A path where Playwright expects to find bundled browser. +- returns: <[string]> A path where Playwright expects to find a bundled browser. + +#### playwright.launch([options]) +- `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields: + - `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`. + - `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 [current working directory](https://nodejs.org/api/process.html#process_process_cwd). **BEWARE**: Playwright is only [guaranteed to work](https://github.com/Microsoft/playwright/#q-why-doesnt-playwright-vxxx-work-with-chromium-vyyy) with the bundled Chromium, Firefox or WebKit, use at your own risk. + - `slowMo` <[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. + - `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/). + - `ignoreDefaultArgs` <[boolean]|[Array]<[string]>> If `true`, then do not use [`playwright.defaultArgs()`](#playwrightdefaultargsoptions). If an array is given, then filter out the given default arguments. Dangerous option; use with care. Defaults to `false`. + - `handleSIGINT` <[boolean]> Close the browser process on Ctrl-C. Defaults to `true`. + - `handleSIGTERM` <[boolean]> Close the browser process on SIGTERM. Defaults to `true`. + - `handleSIGHUP` <[boolean]> Close the browser process on SIGHUP. Defaults to `true`. + - `timeout` <[number]> Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. + - `dumpio` <[boolean]> Whether to pipe the browser process stdout and stderr into `process.stdout` and `process.stderr`. Defaults to `false`. + - `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). + - `env` <[Object]> Specify environment variables that will be visible to the browser. Defaults to `process.env`. + - `webSocket` <[boolean]> Connects to the browser over a WebSocket instead of a pipe. 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`. +- returns: <[Promise]<[Browser]>> Promise which resolves to browser instance. + + +You can use `ignoreDefaultArgs` to filter out `--mute-audio` from default arguments: +```js +const browser = await playwright.launch({ + 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 [playwright.launch([options])](#playwrightlaunchoptions) 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. + +#### playwright.launchBrowserApp([options]) +- `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields: + - `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`. + - `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 [current working directory](https://nodejs.org/api/process.html#process_process_cwd). **BEWARE**: Playwright is only [guaranteed to work](https://github.com/Microsoft/playwright/#q-why-doesnt-playwright-vxxx-work-with-chromium-vyyy) with the bundled Chromium, Firefox or WebKit, use at your own risk. + - `slowMo` <[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. + - `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/). + - `ignoreDefaultArgs` <[boolean]|[Array]<[string]>> If `true`, then do not use [`playwright.defaultArgs()`](#playwrightdefaultargsoptions). If an array is given, then filter out the given default arguments. Dangerous option; use with care. Defaults to `false`. + - `handleSIGINT` <[boolean]> Close the browser process on Ctrl-C. Defaults to `true`. + - `handleSIGTERM` <[boolean]> Close the browser process on SIGTERM. Defaults to `true`. + - `handleSIGHUP` <[boolean]> Close the browser process on SIGHUP. Defaults to `true`. + - `timeout` <[number]> Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. + - `dumpio` <[boolean]> Whether to pipe the browser process stdout and stderr into `process.stdout` and `process.stderr`. Defaults to `false`. + - `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). + - `env` <[Object]> Specify environment variables that will be visible to the browser. Defaults to `process.env`. + - `webSocket` <[boolean]> Connects to the browser over a WebSocket instead of a pipe. 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`. +- returns: <[Promise]<[BrowserApp]>> Promise which resolves to the browser app instance. ### class: Browser @@ -140,6 +211,9 @@ const playwright = require('playwright').webkit; // Or 'chromium' or 'firefox'. await browserApp.close(); })(); ``` + +See [ChromiumBrowser], [FirefoxBrowser] and [WebKitBrowser] for browser-specific features. Note that [playwright.connect(options)](#playwrightconnectoptions) and [playwright.launch(options)](#playwrightlaunchoptions) always return a specific browser instance, based on the browser being connected to or launched. + - [event: 'disconnected'](#event-disconnected) - [browser.browserContexts()](#browserbrowsercontexts) @@ -233,15 +307,15 @@ Closes the browser gracefully and makes sure the process is terminated. - `slowMo` <[number]> - `transport` <[ConnectionTransport]> **Experimental** A custom transport object which should be used to connect. -This options object can be passed to [chromiumPlaywright.connect(options)](#chromiumplaywrightconnectoptions), [firefoxPlaywright.connect(options)](#firefoxplaywrightconnectoptions) or [webkitPlaywright.connect(options)](#webkitplaywrightconnectoptions) to establish connection to the browser. +This options object can be passed to [playwright.connect(options)](#playwrightconnectoptions) to establish connection to the browser. #### browserApp.process() -- returns: Spawned browser server process. +- returns: Spawned browser application process. #### browserApp.wsEndpoint() - returns: Browser websocket url. -Browser websocket endpoint which can be used as an argument to [chromiumPlaywright.connect(options)](#chromiumplaywrightconnectoptions), [firefoxPlaywright.connect(options)](#firefoxplaywrightconnectoptions) or [webkitPlaywright.connect(options)](#webkitplaywrightconnectoptions) to establish connection to the browser. +Browser websocket endpoint which can be used as an argument to [playwright.connect(options)] to establish connection to the browser. ### class: BrowserContext @@ -3279,89 +3353,6 @@ If the function passed to the `worker.evaluateHandle` returns a [Promise], then #### worker.url() - returns: <[string]> -### class: ChromiumPlaywright - -* extends: [Playwright] - - -- [chromiumPlaywright.connect(options)](#chromiumplaywrightconnectoptions) -- [chromiumPlaywright.defaultArgs([options])](#chromiumplaywrightdefaultargsoptions) -- [chromiumPlaywright.launch([options])](#chromiumplaywrightlaunchoptions) -- [chromiumPlaywright.launchBrowserApp([options])](#chromiumplaywrightlaunchbrowserappoptions) - - -#### chromiumPlaywright.connect(options) -- `options` <[Object]> - - `browserWSEndpoint` a browser websocket endpoint to connect to. - - `browserURL` a browser url to connect to, in format `http://${host}:${port}`. Use interchangeably with `browserWSEndpoint` to let Playwright fetch it from [metadata endpoint](https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target). - - `slowMo` <[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. - - `transport` <[ConnectionTransport]> **Experimental** Specify a custom transport object for Playwright to use. -- returns: <[Promise]<[ChromiumBrowser]>> - -This methods attaches Playwright to an existing Chromium instance. - -#### chromiumPlaywright.defaultArgs([options]) -- `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields: - - `headless` <[boolean]> Whether to run Chromium in [headless mode](https://developers.google.com/web/updates/2017/04/headless-chrome). Defaults to `true` unless the `devtools` option is `true`. - - `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/). - - `userDataDir` <[string]> Path to a [User Data Directory](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md). - - `devtools` <[boolean]> Whether to auto-open a DevTools panel for each tab. If this option is `true`, the `headless` option will be set `false`. -- returns: <[Array]<[string]>> - -The default flags that Chromium will be launched with. - -#### chromiumPlaywright.launch([options]) -- `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields: - - `headless` <[boolean]> Whether to run Chromium in [headless mode](https://developers.google.com/web/updates/2017/04/headless-chrome). Defaults to `true` unless the `devtools` option is `true`. - - `executablePath` <[string]> Path to a Chromium or Chrome executable to run instead of the bundled Chromium. If `executablePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). **BEWARE**: Playwright is only [guaranteed to work](https://github.com/Microsoft/playwright/#q-why-doesnt-playwright-vxxx-work-with-chromium-vyyy) with the bundled Chromium, use at your own risk. - - `slowMo` <[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. - - `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/). - - `ignoreDefaultArgs` <[boolean]|[Array]<[string]>> If `true`, then do not use [`chromiumPlaywright.defaultArgs()`](#chromiumplaywrightdefaultargsoptions). If an array is given, then filter out the given default arguments. Dangerous option; use with care. Defaults to `false`. - - `handleSIGINT` <[boolean]> Close the browser process on Ctrl-C. Defaults to `true`. - - `handleSIGTERM` <[boolean]> Close the browser process on SIGTERM. Defaults to `true`. - - `handleSIGHUP` <[boolean]> Close the browser process on SIGHUP. Defaults to `true`. - - `timeout` <[number]> Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. - - `dumpio` <[boolean]> Whether to pipe the browser process stdout and stderr into `process.stdout` and `process.stderr`. Defaults to `false`. - - `userDataDir` <[string]> Path to a [User Data Directory](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md). - - `env` <[Object]> Specify environment variables that will be visible to the browser. Defaults to `process.env`. - - `devtools` <[boolean]> Whether to auto-open a DevTools panel for each tab. If this option is `true`, the `headless` option will be set `false`. - - `webSocket` <[boolean]> Connects to the browser over a WebSocket instead of a pipe. Defaults to `false`. -- returns: <[Promise]<[ChromiumBrowser]>> Promise which resolves to browser instance. - - -You can use `ignoreDefaultArgs` to filter out `--mute-audio` from default arguments: -```js -const browser = await playwright.launch({ - ignoreDefaultArgs: ['--mute-audio'] -}); -``` - -> **NOTE** 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 [chromiumPlaywright.launch([options])](#chromiumplaywrightlaunchoptions) 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. - -#### chromiumPlaywright.launchBrowserApp([options]) -- `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields: - - `headless` <[boolean]> Whether to run Chromium in [headless mode](https://developers.google.com/web/updates/2017/04/headless-chrome). Defaults to `true` unless the `devtools` option is `true`. - - `executablePath` <[string]> Path to a Chromium or Chrome executable to run instead of the bundled Chromium. If `executablePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). **BEWARE**: Playwright is only [guaranteed to work](https://github.com/Microsoft/playwright/#q-why-doesnt-playwright-vxxx-work-with-chromium-vyyy) with the bundled Chromium, use at your own risk. - - `slowMo` <[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. - - `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/). - - `ignoreDefaultArgs` <[boolean]|[Array]<[string]>> If `true`, then do not use [`chromiumPlaywright.defaultArgs()`](#chromiumplaywrightdefaultargsoptions). If an array is given, then filter out the given default arguments. Dangerous option; use with care. Defaults to `false`. - - `handleSIGINT` <[boolean]> Close the browser process on Ctrl-C. Defaults to `true`. - - `handleSIGTERM` <[boolean]> Close the browser process on SIGTERM. Defaults to `true`. - - `handleSIGHUP` <[boolean]> Close the browser process on SIGHUP. Defaults to `true`. - - `timeout` <[number]> Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. - - `dumpio` <[boolean]> Whether to pipe the browser process stdout and stderr into `process.stdout` and `process.stderr`. Defaults to `false`. - - `userDataDir` <[string]> Path to a [User Data Directory](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md). - - `env` <[Object]> Specify environment variables that will be visible to the browser. Defaults to `process.env`. - - `devtools` <[boolean]> Whether to auto-open a DevTools panel for each tab. If this option is `true`, the `headless` option will be set `false`. - - `webSocket` <[boolean]> Connects to the browser over a WebSocket instead of a pipe. Defaults to `false`. -- returns: <[Promise]<[BrowserApp]>> Promise which resolves to browser server instance. - ### class: ChromiumBrowser * extends: [Browser] @@ -3539,155 +3530,12 @@ Identifies what kind of target this is. Can be `"page"`, [`"background_page"`](h #### chromiumTarget.url() - returns: <[string]> -### class: FirefoxPlaywright - -* extends: [Playwright] - - -- [firefoxPlaywright.connect(options)](#firefoxplaywrightconnectoptions) -- [firefoxPlaywright.defaultArgs([options])](#firefoxplaywrightdefaultargsoptions) -- [firefoxPlaywright.launch([options])](#firefoxplaywrightlaunchoptions) -- [firefoxPlaywright.launchBrowserApp([options])](#firefoxplaywrightlaunchbrowserappoptions) - - -#### firefoxPlaywright.connect(options) -- `options` <[Object]> - - `browserWSEndpoint` a browser websocket endpoint to connect to. - - `slowMo` <[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. - - `transport` <[ConnectionTransport]> **Experimental** Specify a custom transport object for Playwright to use. -- returns: <[Promise]<[FirefoxBrowser]>> - -This methods attaches Playwright to an existing Firefox instance. - -#### firefoxPlaywright.defaultArgs([options]) -- `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields: - - `headless` <[boolean]> Whether to run Firefox in [headless mode](https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Headless_mode). Defaults to `true`. - - `args` <[Array]<[string]>> Additional arguments to pass to the browser instance. The list of Firefox flags can be found [here](https://developer.mozilla.org/en-US/docs/Mozilla/Command_Line_Options). - - `userDataDir` <[string]> Path to a [User Data Directory](https://developer.mozilla.org/en-US/docs/Mozilla/Command_Line_Options#User_Profile). -- returns: <[Array]<[string]>> - -The default flags that Firefox will be launched with. - -#### firefoxPlaywright.launch([options]) -- `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields: - - `headless` <[boolean]> Whether to run Firefox in [headless mode](https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Headless_mode). Defaults to `true`. - - `executablePath` <[string]> Path to a Firefox executable to run instead of the bundled Firefox. If `executablePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). **BEWARE**: Playwright is only guaranteed to work with the bundled Firefox, use at your own risk. - - `slowMo` <[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. - - `args` <[Array]<[string]>> Additional arguments to pass to the browser instance. The list of Firefox flags can be found [here](https://developer.mozilla.org/en-US/docs/Mozilla/Command_Line_Options). - - `ignoreDefaultArgs` <[boolean]|[Array]<[string]>> If `true`, then do not use [`firefoxPlaywright.defaultArgs()`](#firefoxplaywrightdefaultargsoptions). If an array is given, then filter out the given default arguments. Dangerous option; use with care. Defaults to `false`. - - `handleSIGINT` <[boolean]> Close the browser process on Ctrl-C. Defaults to `true`. - - `handleSIGTERM` <[boolean]> Close the browser process on SIGTERM. Defaults to `true`. - - `handleSIGHUP` <[boolean]> Close the browser process on SIGHUP. Defaults to `true`. - - `timeout` <[number]> Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. - - `dumpio` <[boolean]> Whether to pipe the browser process stdout and stderr into `process.stdout` and `process.stderr`. Defaults to `false`. - - `userDataDir` <[string]> Path to a [User Data Directory](https://developer.mozilla.org/en-US/docs/Mozilla/Command_Line_Options#User_Profile). - - `env` <[Object]> Specify environment variables that will be visible to the browser. Defaults to `process.env`. - - `webSocket` <[boolean]> Connects to the browser over a WebSocket instead of a pipe. Defaults to `false`. -- returns: <[Promise]<[FirefoxBrowser]>> Promise which resolves to browser instance. - - -You can use `ignoreDefaultArgs` to filter out `--mute-audio` from default arguments: -```js -const browser = await playwright.launch({ - ignoreDefaultArgs: ['--mute-audio'] -}); -``` - -#### firefoxPlaywright.launchBrowserApp([options]) -- `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields: - - `headless` <[boolean]> Whether to run Firefox in [headless mode](https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Headless_mode). Defaults to `true`. - - `executablePath` <[string]> Path to a Firefox executable to run instead of the bundled Firefox. If `executablePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). **BEWARE**: Playwright is only guaranteed to work with the bundled Firefox, use at your own risk. - - `slowMo` <[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. - - `args` <[Array]<[string]>> Additional arguments to pass to the browser instance. The list of Firefox flags can be found [here](https://developer.mozilla.org/en-US/docs/Mozilla/Command_Line_Options). - - `ignoreDefaultArgs` <[boolean]|[Array]<[string]>> If `true`, then do not use [`firefoxPlaywright.defaultArgs()`](#firefoxplaywrightdefaultargsoptions). If an array is given, then filter out the given default arguments. Dangerous option; use with care. Defaults to `false`. - - `handleSIGINT` <[boolean]> Close the browser process on Ctrl-C. Defaults to `true`. - - `handleSIGTERM` <[boolean]> Close the browser process on SIGTERM. Defaults to `true`. - - `handleSIGHUP` <[boolean]> Close the browser process on SIGHUP. Defaults to `true`. - - `timeout` <[number]> Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. - - `dumpio` <[boolean]> Whether to pipe the browser process stdout and stderr into `process.stdout` and `process.stderr`. Defaults to `false`. - - `userDataDir` <[string]> Path to a [User Data Directory](https://developer.mozilla.org/en-US/docs/Mozilla/Command_Line_Options#User_Profile). - - `env` <[Object]> Specify environment variables that will be visible to the browser. Defaults to `process.env`. - - `webSocket` <[boolean]> Connects to the browser over a WebSocket instead of a pipe. Defaults to `false`. -- returns: <[Promise]<[BrowserApp]>> Promise which resolves to browser server instance. - ### class: FirefoxBrowser * extends: [Browser] Firefox browser instance does not expose Firefox-specific features. - -### class: WebKitPlaywright - -* extends: [Playwright] - - -- [webkitPlaywright.connect(options)](#webkitplaywrightconnectoptions) -- [webkitPlaywright.defaultArgs([options])](#webkitplaywrightdefaultargsoptions) -- [webkitPlaywright.launch([options])](#webkitplaywrightlaunchoptions) -- [webkitPlaywright.launchBrowserApp([options])](#webkitplaywrightlaunchbrowserappoptions) - - -#### webkitPlaywright.connect(options) -- `options` <[Object]> - - `browserWSEndpoint` a browser websocket endpoint to connect to. - - `slowMo` <[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. - - `transport` <[ConnectionTransport]> **Experimental** Specify a custom transport object for Playwright to use. -- returns: <[Promise]<[WebKitBrowser]>> - -This methods attaches Playwright to an existing WebKit instance. - -#### webkitPlaywright.defaultArgs([options]) -- `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields: - - `headless` <[boolean]> Whether to run WebKit in headless mode. Defaults to `true`. - - `userDataDir` <[string]> Path to a User Data Directory, which stores browser session data like cookies and local storage. - - `args` <[Array]<[string]>> Additional arguments to pass to the browser instance. -- returns: <[Array]<[string]>> - -The default flags that WebKit will be launched with. - -#### webkitPlaywright.launch([options]) -- `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields: - - `headless` <[boolean]> Whether to run WebKit in headless mode. Defaults to `true`. - - `executablePath` <[string]> Path to a WebKit executable to run instead of the bundled WebKit. If `executablePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). **BEWARE**: Playwright is only guaranteed to work with the bundled WebKit, use at your own risk. - - `slowMo` <[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. - - `userDataDir` <[string]> Path to a User Data Directory, which stores browser session data like cookies and local storage. - - `args` <[Array]<[string]>> Additional arguments to pass to the browser instance. - - `ignoreDefaultArgs` <[boolean]|[Array]<[string]>> If `true`, then do not use [`webKitPlaywright.defaultArgs()`](#webkitplaywrightdefaultargsoptions). If an array is given, then filter out the given default arguments. Dangerous option; use with care. Defaults to `false`. - - `handleSIGINT` <[boolean]> Close the browser process on Ctrl-C. Defaults to `true`. - - `handleSIGTERM` <[boolean]> Close the browser process on SIGTERM. Defaults to `true`. - - `handleSIGHUP` <[boolean]> Close the browser process on SIGHUP. Defaults to `true`. - - `timeout` <[number]> Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. - - `dumpio` <[boolean]> Whether to pipe the browser process stdout and stderr into `process.stdout` and `process.stderr`. Defaults to `false`. - - `env` <[Object]> Specify environment variables that will be visible to the browser. Defaults to `process.env`. - - `webSocket` <[boolean]> Connects to the browser over a WebSocket instead of a pipe. Defaults to `false`. -- returns: <[Promise]<[WebKitBrowser]>> Promise which resolves to browser instance. - - -You can use `ignoreDefaultArgs` to filter out `--mute-audio` from default arguments: -```js -const browser = await playwright.launch({ - ignoreDefaultArgs: ['--mute-audio'] -}); -``` - -#### webkitPlaywright.launchBrowserApp([options]) -- `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields: - - `headless` <[boolean]> Whether to run WebKit in headless mode. Defaults to `true`. - - `executablePath` <[string]> Path to a WebKit executable to run instead of the bundled WebKit. If `executablePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). **BEWARE**: Playwright is only guaranteed to work with the bundled WebKit, use at your own risk. - - `slowMo` <[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. - - `userDataDir` <[string]> Path to a User Data Directory, which stores browser session data like cookies and local storage. - - `args` <[Array]<[string]>> Additional arguments to pass to the browser instance. - - `ignoreDefaultArgs` <[boolean]|[Array]<[string]>> If `true`, then do not use [`webKitPlaywright.defaultArgs()`](#webkitplaywrightdefaultargsoptions). If an array is given, then filter out the given default arguments. Dangerous option; use with care. Defaults to `false`. - - `handleSIGINT` <[boolean]> Close the browser process on Ctrl-C. Defaults to `true`. - - `handleSIGTERM` <[boolean]> Close the browser process on SIGTERM. Defaults to `true`. - - `handleSIGHUP` <[boolean]> Close the browser process on SIGHUP. Defaults to `true`. - - `timeout` <[number]> Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. - - `dumpio` <[boolean]> Whether to pipe the browser process stdout and stderr into `process.stdout` and `process.stderr`. Defaults to `false`. - - `env` <[Object]> Specify environment variables that will be visible to the browser. Defaults to `process.env`. - - `webSocket` <[boolean]> Connects to the browser over a WebSocket instead of a pipe. Defaults to `false`. -- returns: <[Promise]<[BrowserApp]>> Promise which resolves to browser server instance. - ### class: WebKitBrowser * extends: [Browser] @@ -3781,7 +3629,6 @@ During installation Playwright downloads browser executables, according to revis [Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer" [ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess" [ChromiumBrowser]: #class-chromiumbrowser "ChromiumBrowser" -[ChromiumPlaywright]: #class-chromiumplaywright "ChromiumPlaywright" [ChromiumSession]: #class-chromiumsession "ChromiumSession" [ChromiumTarget]: #class-chromiumtarget "ChromiumTarget" [ConnectionTransport]: ../lib/WebSocketTransport.js "ConnectionTransport" @@ -3794,7 +3641,6 @@ During installation Playwright downloads browser executables, according to revis [File]: #class-file "https://developer.mozilla.org/en-US/docs/Web/API/File" [FileChooser]: #class-filechooser "FileChooser" [FirefoxBrowser]: #class-firefoxbrowser "FirefoxBrowser" -[FirefoxPlaywright]: #class-firefoxplaywright "FirefoxPlaywright" [Frame]: #class-frame "Frame" [JSHandle]: #class-jshandle "JSHandle" [Keyboard]: #class-keyboard "Keyboard" @@ -3815,7 +3661,6 @@ During installation Playwright downloads browser executables, according to revis [USKeyboardLayout]: ../lib/USKeyboardLayout.js "USKeyboardLayout" [UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time" [WebKitBrowser]: #class-webkitbrowser "WebKitBrowser" -[WebKitPlaywright]: #class-webkitplaywright "WebKitPlaywright" [WebSocket]: #class-websocket "WebSocket" [Worker]: #class-worker "Worker" [boolean]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type "Boolean" diff --git a/docs/web.md b/docs/web.md index 42ddb52989..19d926e35b 100644 --- a/docs/web.md +++ b/docs/web.md @@ -4,10 +4,7 @@ Playwright contains a version bundled for web browsers under `playwright/web.js` installs playwright under `window.playwrightweb`. You can use it in the web page to drive another browser instance. -API consists of a single `connect` function, similar to -[chromiumPlaywright.connect(options)](api.md#chromiumplaywrightconnectoptions), -[firefoxPlaywright.connect(options)](api.md#firefoxplaywrightconnectoptions) and -[webkitPlaywright.connect(options)](api.md#webkitplaywrightconnectoptions). +API consists of a single `connect` function, similar to [playwright.connect(options)](api.md#playwrightconnectoptions). ```html diff --git a/index.d.ts b/index.d.ts index 98e5823929..dabb017171 100644 --- a/index.d.ts +++ b/index.d.ts @@ -15,7 +15,7 @@ */ export * from './lib/api'; -export const chromium: import('./lib/api').ChromiumPlaywright; -export const firefox: import('./lib/api').FirefoxPlaywright; -export const webkit: import('./lib/api').WebKitPlaywright; +export const chromium: import('./lib/server/crPlaywright').CRPlaywright; +export const firefox: import('./lib/server/ffPlaywright').FFPlaywright; +export const webkit: import('./lib/server/wkPlaywright').WKPlaywright; export type PlaywrightWeb = typeof import('./lib/web'); diff --git a/index.js b/index.js index 569b1281a2..677ad987b5 100644 --- a/index.js +++ b/index.js @@ -18,6 +18,9 @@ const { helper } = require('./lib/helper'); const api = require('./lib/api'); const packageJson = require('./package.json'); const { DeviceDescriptors } = require('./lib/deviceDescriptors'); +const CRPlaywright = require('./lib/server/crPlaywright').CRPlaywright; +const FFPlaywright = require('./lib/server/ffPlaywright').FFPlaywright; +const WKPlaywright = require('./lib/server/wkPlaywright').WKPlaywright; for (const className in api) { if (typeof api[className] === 'function') @@ -25,8 +28,8 @@ for (const className in api) { } module.exports = { - chromium: new api.ChromiumPlaywright(__dirname, packageJson.playwright.chromium_revision), - firefox: new api.FirefoxPlaywright(__dirname, packageJson.playwright.firefox_revision), - webkit: new api.WebKitPlaywright(__dirname, packageJson.playwright.webkit_revision), - devices: DeviceDescriptors + chromium: new CRPlaywright(__dirname, packageJson.playwright.chromium_revision), + firefox: new FFPlaywright(__dirname, packageJson.playwright.firefox_revision), + webkit: new WKPlaywright(__dirname, packageJson.playwright.webkit_revision), + devices: DeviceDescriptors, }; diff --git a/src/api.ts b/src/api.ts index 134a1f3c82..f253cec0c9 100644 --- a/src/api.ts +++ b/src/api.ts @@ -37,6 +37,3 @@ export { WKBrowser as WebKitBrowser } from './webkit/wkBrowser'; export { Playwright } from './server/playwright'; export { BrowserApp } from './server/browserApp'; -export { CRPlaywright as ChromiumPlaywright } from './server/crPlaywright'; -export { FFPlaywright as FirefoxPlaywright } from './server/ffPlaywright'; -export { WKPlaywright as WebKitPlaywright } from './server/wkPlaywright'; diff --git a/src/server/crPlaywright.ts b/src/server/crPlaywright.ts index 4c10b511aa..835caa56e3 100644 --- a/src/server/crPlaywright.ts +++ b/src/server/crPlaywright.ts @@ -29,33 +29,10 @@ import { TimeoutError } from '../errors'; import { launchProcess, waitForLine } from '../server/processLauncher'; import { kBrowserCloseMessageId } from '../chromium/crConnection'; import { PipeTransport } from './pipeTransport'; -import { Playwright } from './playwright'; +import { Playwright, LaunchOptions, BrowserArgOptions } from './playwright'; import { createTransport, ConnectOptions } from '../browser'; import { BrowserApp } from './browserApp'; -export type SlowMoOptions = { - slowMo?: number, -}; - -export type ChromiumArgOptions = { - headless?: boolean, - args?: string[], - userDataDir?: string, - devtools?: boolean, -}; - -export type LaunchOptions = ChromiumArgOptions & SlowMoOptions & { - executablePath?: string, - ignoreDefaultArgs?: boolean | string[], - handleSIGINT?: boolean, - handleSIGTERM?: boolean, - handleSIGHUP?: boolean, - timeout?: number, - dumpio?: boolean, - env?: {[key: string]: string} | undefined, - webSocket?: boolean, -}; - export class CRPlaywright implements Playwright { private _projectRoot: string; readonly _revision: string; @@ -184,7 +161,7 @@ export class CRPlaywright implements Playwright { return { TimeoutError }; } - defaultArgs(options: ChromiumArgOptions = {}): string[] { + defaultArgs(options: BrowserArgOptions = {}): string[] { const { devtools = false, headless = !devtools, diff --git a/src/server/ffPlaywright.ts b/src/server/ffPlaywright.ts index d08626a9fa..ab48d06fca 100644 --- a/src/server/ffPlaywright.ts +++ b/src/server/ffPlaywright.ts @@ -28,32 +28,10 @@ import * as path from 'path'; import * as util from 'util'; import { TimeoutError } from '../errors'; import { assert } from '../helper'; -import { Playwright } from './playwright'; +import { Playwright, LaunchOptions, BrowserArgOptions } from './playwright'; import { createTransport, ConnectOptions } from '../browser'; import { BrowserApp } from './browserApp'; -export type SlowMoOptions = { - slowMo?: number, -}; - -export type FirefoxArgOptions = { - headless?: boolean, - args?: string[], - userDataDir?: string, -}; - -export type LaunchOptions = FirefoxArgOptions & SlowMoOptions & { - executablePath?: string, - ignoreDefaultArgs?: boolean | string[], - handleSIGINT?: boolean, - handleSIGTERM?: boolean, - handleSIGHUP?: boolean, - timeout?: number, - dumpio?: boolean, - env?: {[key: string]: string} | undefined, - webSocket?: boolean, -}; - export class FFPlaywright implements Playwright { private _projectRoot: string; readonly _revision: string; @@ -151,7 +129,9 @@ export class FFPlaywright implements Playwright { return new BrowserApp(launchedProcess, gracefullyClose, connectOptions); } - async connect(options: ConnectOptions): Promise { + async connect(options: ConnectOptions & { browserURL?: string }): Promise { + if (options.browserURL) + throw new Error('Option "browserURL" is not supported by Firefox'); if (options.transport && options.transport.onmessage) throw new Error('Transport is already in use'); return FFBrowser.connect(options); @@ -169,13 +149,15 @@ export class FFPlaywright implements Playwright { return { TimeoutError }; } - // TODO: rename userDataDir to profile? - defaultArgs(options: FirefoxArgOptions = {}): string[] { + defaultArgs(options: BrowserArgOptions = {}): string[] { const { - headless = true, + devtools = false, + headless = !devtools, args = [], userDataDir = null, } = options; + if (devtools) + throw new Error('Option "devtools" is not supported by Firefox'); const firefoxArguments = [...DEFAULT_ARGS]; if (userDataDir) firefoxArguments.push('-profile', userDataDir); diff --git a/src/server/playwright.ts b/src/server/playwright.ts index eb02005efc..3b273fb810 100644 --- a/src/server/playwright.ts +++ b/src/server/playwright.ts @@ -16,9 +16,35 @@ import * as types from '../types'; import { TimeoutError } from '../errors'; +import { Browser, ConnectOptions } from '../browser'; +import { BrowserApp } from './browserApp'; + +export type BrowserArgOptions = { + headless?: boolean, + args?: string[], + userDataDir?: string, + devtools?: boolean, +}; + +export type LaunchOptions = BrowserArgOptions & { + executablePath?: string, + ignoreDefaultArgs?: boolean | string[], + handleSIGINT?: boolean, + handleSIGTERM?: boolean, + handleSIGHUP?: boolean, + timeout?: number, + dumpio?: boolean, + env?: {[key: string]: string} | undefined, + webSocket?: boolean, + slowMo?: number, // TODO: we probably don't want this in launchBrowserApp. +}; export interface Playwright { executablePath(): string; + launchBrowserApp(options?: LaunchOptions): Promise; + launch(options?: LaunchOptions): Promise; + defaultArgs(options?: BrowserArgOptions): string[]; + connect(options: ConnectOptions & { browserURL?: string }): Promise; devices: types.Devices; errors: { TimeoutError: typeof TimeoutError }; } diff --git a/src/server/wkPlaywright.ts b/src/server/wkPlaywright.ts index 7abc5f03ad..d68aa2644d 100644 --- a/src/server/wkPlaywright.ts +++ b/src/server/wkPlaywright.ts @@ -30,35 +30,13 @@ import * as util from 'util'; import * as os from 'os'; import { assert } from '../helper'; import { kBrowserCloseMessageId } from '../webkit/wkConnection'; -import { Playwright } from './playwright'; +import { Playwright, BrowserArgOptions, LaunchOptions } from './playwright'; import { ConnectionTransport } from '../transport'; import * as ws from 'ws'; import * as uuidv4 from 'uuid/v4'; import { ConnectOptions } from '../browser'; import { BrowserApp } from './browserApp'; -export type SlowMoOptions = { - slowMo?: number, -}; - -export type WebKitArgOptions = { - headless?: boolean, - args?: string[], - userDataDir?: string, -}; - -export type LaunchOptions = WebKitArgOptions & SlowMoOptions & { - executablePath?: string, - ignoreDefaultArgs?: boolean | string[], - handleSIGINT?: boolean, - handleSIGTERM?: boolean, - handleSIGHUP?: boolean, - timeout?: number, - dumpio?: boolean, - env?: {[key: string]: string} | undefined, - webSocket?: boolean, -}; - export class WKPlaywright implements Playwright { private _projectRoot: string; readonly _revision: string; @@ -151,7 +129,9 @@ export class WKPlaywright implements Playwright { return new BrowserApp(launchedProcess, gracefullyClose, connectOptions); } - async connect(options: ConnectOptions): Promise { + async connect(options: ConnectOptions & { browserURL?: string }): Promise { + if (options.browserURL) + throw new Error('Option "browserURL" is not supported by Firefox'); if (options.transport && options.transport.onmessage) throw new Error('Transport is already in use'); return WKBrowser.connect(options); @@ -169,12 +149,15 @@ export class WKPlaywright implements Playwright { return { TimeoutError }; } - defaultArgs(options: WebKitArgOptions = {}): string[] { + defaultArgs(options: BrowserArgOptions = {}): string[] { const { - headless = true, + devtools = false, + headless = !devtools, args = [], userDataDir = null } = options; + if (devtools) + throw new Error('Option "devtools" is not supported by WebKit'); const webkitArguments = ['--inspector-pipe']; if (userDataDir) webkitArguments.push(`--user-data-dir=${userDataDir}`);