From 1a39843df57a2565ed007439e91daacefb9d71ad Mon Sep 17 00:00:00 2001 From: Pavel Feldman Date: Wed, 12 May 2021 16:16:36 -0700 Subject: [PATCH] docs: follow up on adding trace dir, unify launch options (#6545) --- docs/src/api/class-browsertype.md | 265 ++---------------------------- docs/src/api/class-tracing.md | 53 +++++- docs/src/api/params.md | 113 +++++++++++++ src/cli/cli.ts | 1 - types/types.d.ts | 45 ++++- 5 files changed, 209 insertions(+), 268 deletions(-) diff --git a/docs/src/api/class-browsertype.md b/docs/src/api/class-browsertype.md index 157952ef72..f8b892ab2b 100644 --- a/docs/src/api/class-browsertype.md +++ b/docs/src/api/class-browsertype.md @@ -205,102 +205,12 @@ option with extreme caution. [This article](https://chromium.googlesource.com/chromium/src/+/lkgr/docs/chromium_browser_vs_google_chrome.md) describes some differences for Linux users. -### option: BrowserType.launch.headless -- `headless` <[boolean]> +### option: BrowserType.launch.-inline- = %%-shared-browser-options-list-%% +### option: BrowserType.launch.firefoxUserPrefs = %%-js-python-browser-option-firefoxuserprefs-%% +### option: BrowserType.launch.firefoxUserPrefs2 = %%-csharp-java-browser-option-firefoxuserprefs-%% +### option: BrowserType.launch.logger = %%-browser-option-logger-%% +### option: BrowserType.launch.slowMo = %%-browser-option-slowmo-%% -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 -[`option: devtools`] option is `true`. - -### option: BrowserType.launch.channel -- `channel` <[BrowserChannel]<"chrome"|"chrome-beta"|"chrome-dev"|"chrome-canary"|"msedge"|"msedge-beta"|"msedge-dev"|"msedge-canary"|"firefox-stable">> - -Browser distribution channel. Read more about using [Google Chrome and Microsoft Edge](./browsers.md#google-chrome--microsoft-edge). - -### option: BrowserType.launch.executablePath -- `executablePath` <[path]> - -Path to a browser executable to run instead of the bundled one. If [`option: 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. - -### option: BrowserType.launch.args -- `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/). - -### option: BrowserType.launch.ignoreDefaultArgs = %%-browser-option-ignoredefaultargs-%% - -### option: BrowserType.launch.proxy = %%-browser-option-proxy-%% - -### option: BrowserType.launch.downloadsPath -- `downloadsPath` <[path]> - -If specified, accepted downloads are downloaded into this directory. Otherwise, temporary directory is created and is -deleted when browser is closed. - -### option: BrowserType.launch.chromiumSandbox -- `chromiumSandbox` <[boolean]> - -Enable Chromium sandboxing. Defaults to `false`. - -### option: BrowserType.launch.firefoxUserPrefs -* langs: js, python -- `firefoxUserPrefs` <[Object]<[string], [string]|[float]|[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). - -### option: BrowserType.launch.firefoxUserPrefs -* langs: csharp, java -- `firefoxUserPrefs` <[Object]<[string], [any]>> - -Firefox user preferences. Learn more about the Firefox user preferences at -[`about:config`](https://support.mozilla.org/en-US/kb/about-config-editor-firefox). - -### option: BrowserType.launch.handleSIGINT -- `handleSIGINT` <[boolean]> - -Close the browser process on Ctrl-C. Defaults to `true`. - -### option: BrowserType.launch.handleSIGTERM -- `handleSIGTERM` <[boolean]> - -Close the browser process on SIGTERM. Defaults to `true`. - -### option: BrowserType.launch.handleSIGHUP -- `handleSIGHUP` <[boolean]> - -Close the browser process on SIGHUP. Defaults to `true`. - -### option: BrowserType.launch.logger -* langs: js -- `logger` <[Logger]> - -Logger sink for Playwright logging. - -### option: BrowserType.launch.timeout -- `timeout` <[float]> - -Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to -disable timeout. - -### option: BrowserType.launch.env = %%-csharp-java-browser-option-env-%% - -### option: BrowserType.launch.env = %%-js-python-browser-option-env-%% - -### option: BrowserType.launch.devtools -- `devtools` <[boolean]> - -**Chromium-only** Whether to auto-open a Developer Tools panel for each tab. If this option is `true`, the -[`option: headless`] option will be set `false`. - -### option: BrowserType.launch.slowMo -- `slowMo` <[float]> - -Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. ## async method: BrowserType.launchPersistentContext - returns: <[BrowserContext]> @@ -318,85 +228,9 @@ Path to a User Data Directory, which stores browser session data like cookies an [Firefox](https://developer.mozilla.org/en-US/docs/Mozilla/Command_Line_Options#User_Profile). Note that Chromium's user data directory is the **parent** directory of the "Profile Path" seen at `chrome://version`. -### option: BrowserType.launchPersistentContext.headless -- `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 -[`option: devtools`] option is `true`. - -### option: BrowserType.launchPersistentContext.channel -- `channel` <[BrowserChannel]<"chrome"|"chrome-beta"|"chrome-dev"|"chrome-canary"|"msedge"|"msedge-beta"|"msedge-dev"|"msedge-canary"|"firefox-stable">> - -Browser distribution channel. Read more about using [Google Chrome and Microsoft Edge](./browsers.md#google-chrome--microsoft-edge). - -### option: BrowserType.launchPersistentContext.executablePath -- `executablePath` <[path]> - -Path to a browser executable to run instead of the bundled one. If [`option: 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. - -### option: BrowserType.launchPersistentContext.args -- `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/). - -### option: BrowserType.launchPersistentContext.ignoreDefaultArgs = %%-browser-option-ignoredefaultargs-%% - -### option: BrowserType.launchPersistentContext.proxy = %%-browser-option-proxy-%% - -### option: BrowserType.launchPersistentContext.downloadsPath -- `downloadsPath` <[path]> - -If specified, accepted downloads are downloaded into this directory. Otherwise, temporary directory is created and is -deleted when browser is closed. - -### option: BrowserType.launchPersistentContext.chromiumSandbox -- `chromiumSandbox` <[boolean]> - -Enable Chromium sandboxing. Defaults to `true`. - -### option: BrowserType.launchPersistentContext.handleSIGINT -- `handleSIGINT` <[boolean]> - -Close the browser process on Ctrl-C. Defaults to `true`. - -### option: BrowserType.launchPersistentContext.handleSIGTERM -- `handleSIGTERM` <[boolean]> - -Close the browser process on SIGTERM. Defaults to `true`. - -### option: BrowserType.launchPersistentContext.handleSIGHUP -- `handleSIGHUP` <[boolean]> - -Close the browser process on SIGHUP. Defaults to `true`. - -### option: BrowserType.launchPersistentContext.timeout -- `timeout` <[float]> - -Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to -disable timeout. - -### option: BrowserType.launchPersistentContext.env = %%-csharp-java-browser-option-env-%% - -### option: BrowserType.launchPersistentContext.env = %%-js-python-browser-option-env-%% - -### option: BrowserType.launchPersistentContext.devtools -- `devtools` <[boolean]> - -**Chromium-only** Whether to auto-open a Developer Tools panel for each tab. If this option is `true`, the -[`option: headless`] option will be set `false`. - -### option: BrowserType.launchPersistentContext.slowMo -- `slowMo` <[float]> - -Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. -Defaults to 0. - +### option: BrowserType.launchPersistentContext.-inline- = %%-shared-browser-options-list-%% ### option: BrowserType.launchPersistentContext.-inline- = %%-shared-context-params-list-%% +### option: BrowserType.launchPersistentContext.slowMo = %%-browser-option-slowmo-%% ## async method: BrowserType.launchServer * langs: js @@ -420,93 +254,16 @@ const { chromium } = require('playwright'); // Or 'webkit' or 'firefox'. })(); ``` -### option: BrowserType.launchServer.headless -- `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 -[`option: devtools`] option is `true`. +### option: BrowserType.launchServer.-inline- = %%-shared-browser-options-list-%% +### option: BrowserType.launchServer.firefoxUserPrefs = %%-js-python-browser-option-firefoxuserprefs-%% +### option: BrowserType.launchServer.firefoxUserPrefs2 = %%-csharp-java-browser-option-firefoxuserprefs-%% +### option: BrowserType.launchServer.logger = %%-browser-option-logger-%% ### option: BrowserType.launchServer.port - `port` <[int]> Port to use for the web socket. Defaults to 0 that picks any available port. -### option: BrowserType.launchServer.channel -- `channel` <[BrowserChannel]<"chrome"|"chrome-beta"|"chrome-dev"|"chrome-canary"|"msedge"|"msedge-beta"|"msedge-dev"|"msedge-canary"|"firefox-stable">> - -Browser distribution channel. Read more about using [Google Chrome and Microsoft Edge](./browsers.md#google-chrome--microsoft-edge). - -### option: BrowserType.launchServer.executablePath -- `executablePath` <[path]> - -Path to a browser executable to run instead of the bundled one. If [`option: 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. - -### option: BrowserType.launchServer.args -- `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/). - -### option: BrowserType.launchServer.ignoreDefaultArgs = %%-browser-option-ignoredefaultargs-%% - -### option: BrowserType.launchServer.proxy = %%-browser-option-proxy-%% - -### option: BrowserType.launchServer.downloadsPath -- `downloadsPath` <[path]> - -If specified, accepted downloads are downloaded into this directory. Otherwise, temporary directory is created and is -deleted when browser is closed. - -### option: BrowserType.launchServer.chromiumSandbox -- `chromiumSandbox` <[boolean]> - -Enable Chromium sandboxing. Defaults to `true`. - -### option: BrowserType.launchServer.firefoxUserPrefs -- `firefoxUserPrefs` <[Object]<[string], [string]|[float]|[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). - -### option: BrowserType.launchServer.handleSIGINT -- `handleSIGINT` <[boolean]> - -Close the browser process on Ctrl-C. Defaults to `true`. - -### option: BrowserType.launchServer.handleSIGTERM -- `handleSIGTERM` <[boolean]> - -Close the browser process on SIGTERM. Defaults to `true`. - -### option: BrowserType.launchServer.handleSIGHUP -- `handleSIGHUP` <[boolean]> - -Close the browser process on SIGHUP. Defaults to `true`. - -### option: BrowserType.launchServer.logger -* langs: js -- `logger` <[Logger]> - -Logger sink for Playwright logging. - -### option: BrowserType.launchServer.timeout -- `timeout` <[float]> - -Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to -disable timeout. - -### option: BrowserType.launchServer.env = %%-js-python-browser-option-env-%% - -### option: BrowserType.launchServer.devtools -- `devtools` <[boolean]> - -**Chromium-only** Whether to auto-open a Developer Tools panel for each tab. If this option is `true`, the -[`option: headless`] option will be set `false`. - ## method: BrowserType.name - returns: <[string]> diff --git a/docs/src/api/class-tracing.md b/docs/src/api/class-tracing.md index 49a20ae8a6..dd8aebd598 100644 --- a/docs/src/api/class-tracing.md +++ b/docs/src/api/class-tracing.md @@ -1,7 +1,50 @@ # class: Tracing -Tracing object for collecting test traces that can be opened using -Playwright CLI. +API for collecting and saving Playwright traces. Playwright traces can be opened using the [CLI]('./cli.md') after +Playwright script runs. + +Start with specifying the folder traces will be stored in: + +```js +const browser = await chromium.launch({ traceDir: 'traces' }); +const context = await browser.newContext(); +await context.tracing.start({ name: 'trace', screenshots: true, snapshots: true }); +const page = await context.newPage(); +await page.goto('https://playwright.dev'); +await context.tracing.stop(); +await context.tracing.export('trace.zip'); +``` + +```java +Browser browser = chromium.launch(new BrowserType.LaunchOptions().setTraceDir("trace")); +BrowserContext context = browser.newContext(); +context.tracing.start(page, new Tracing.StartOptions() + .setName("trace") + .setScreenshots(true) + .setSnapshots(true); +Page page = context.newPage(); +page.goto("https://playwright.dev"); +context.tracing.stop(); +context.tracing.export(Paths.get("trace.zip"))) +``` + +```python async +browser = await chromium.launch(traceDir='traces') +context = await browser.new_context() +await context.tracing.start(name="trace", screenshots=True, snapshots=True) +await page.goto("https://playwright.dev") +await context.tracing.stop() +await context.tracing.export("trace.zip") +``` + +```python sync +browser = chromium.launch(traceDir='traces') +context = browser.new_context() +context.tracing.start(name="trace", screenshots=True, snapshots=True) +page.goto("https://playwright.dev") +context.tracing.stop() +context.tracing.export("trace.zip") +``` ## async method: Tracing.export @@ -37,14 +80,14 @@ context.tracing.export(Paths.get("trace.zip"))) ``` ```python async -await context.tracing.start(name="trace" screenshots=True snapshots=True) +await context.tracing.start(name="trace", screenshots=True, snapshots=True) await page.goto("https://playwright.dev") await context.tracing.stop() await context.tracing.export("trace.zip") ``` ```python sync -context.tracing.start(name="trace" screenshots=True snapshots=True) +context.tracing.start(name="trace", screenshots=True, snapshots=True) page.goto("https://playwright.dev") context.tracing.stop() context.tracing.export("trace.zip") @@ -54,7 +97,7 @@ context.tracing.export("trace.zip") - `name` <[string]> If specified, the trace is going to be saved into the file with the -given name. +given name inside the [`option: traceDir`] folder specified in [`method: BrowserType.launch`]. ### option: Tracing.start.screenshots - `screenshots` <[boolean]> diff --git a/docs/src/api/params.md b/docs/src/api/params.md index f518d7bbd0..e50721e38c 100644 --- a/docs/src/api/params.md +++ b/docs/src/api/params.md @@ -599,3 +599,116 @@ is considered matching if all specified properties match. - %%-context-option-recordvideo-%% - %%-context-option-recordvideo-dir-%% - %%-context-option-recordvideo-size-%% + +## browser-option-args +- `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/). + +## browser-option-channel +- `channel` <[BrowserChannel]<"chrome"|"chrome-beta"|"chrome-dev"|"chrome-canary"|"msedge"|"msedge-beta"|"msedge-dev"|"msedge-canary"|"firefox-stable">> + +Browser distribution channel. Read more about using [Google Chrome and Microsoft Edge](./browsers.md#google-chrome--microsoft-edge). + +## browser-option-chromiumsandbox +- `chromiumSandbox` <[boolean]> + +Enable Chromium sandboxing. Defaults to `true`. + + +## browser-option-downloadspath +- `downloadsPath` <[path]> + +If specified, accepted downloads are downloaded into this directory. Otherwise, temporary directory is created and is +deleted when browser is closed. + +## browser-option-executablepath +- `executablePath` <[path]> + +Path to a browser executable to run instead of the bundled one. If [`option: 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. + +## browser-option-handlesigint +- `handleSIGINT` <[boolean]> + +Close the browser process on Ctrl-C. Defaults to `true`. + +## browser-option-handlesigterm +- `handleSIGTERM` <[boolean]> + +Close the browser process on SIGTERM. Defaults to `true`. + +## browser-option-handlesighup +- `handleSIGHUP` <[boolean]> + +Close the browser process on SIGHUP. Defaults to `true`. + +## browser-option-headless +- `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 +[`option: devtools`] option is `true`. + +## js-python-browser-option-firefoxuserprefs +* langs: js, python +- `firefoxUserPrefs` <[Object]<[string], [string]|[float]|[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). + +## csharp-java-browser-option-firefoxuserprefs +* langs: csharp, java +- `firefoxUserPrefs` <[Object]<[string], [any]>> + +Firefox user preferences. Learn more about the Firefox user preferences at +[`about:config`](https://support.mozilla.org/en-US/kb/about-config-editor-firefox). + +## browser-option-logger +* langs: js +- `logger` <[Logger]> + +Logger sink for Playwright logging. + +## browser-option-timeout +- `timeout` <[float]> + +Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to +disable timeout. + +## browser-option-tracedir +- `traceDir` <[path]> + +If specified, traces are saved into this directory. + +## browser-option-devtools +- `devtools` <[boolean]> + +**Chromium-only** Whether to auto-open a Developer Tools panel for each tab. If this option is `true`, the +[`option: headless`] option will be set `false`. + +## browser-option-slowmo +- `slowMo` <[float]> + +Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. + +## shared-browser-options-list +- %%-browser-option-args-%% +- %%-browser-option-channel-%% +- %%-browser-option-chromiumsandbox-%% +- %%-browser-option-devtools-%% +- %%-browser-option-downloadspath-%% +- %%-csharp-java-browser-option-env-%% +- %%-js-python-browser-option-env-%% +- %%-browser-option-executablepath-%% +- %%-browser-option-handlesigint-%% +- %%-browser-option-handlesigterm-%% +- %%-browser-option-handlesighup-%% +- %%-browser-option-headless-%% +- %%-browser-option-ignoredefaultargs-%% +- %%-browser-option-proxy-%% +- %%-browser-option-timeout-%% +- %%-browser-option-tracedir-%% diff --git a/src/cli/cli.ts b/src/cli/cli.ts index 4e78ee6ae1..f789561f3c 100755 --- a/src/cli/cli.ts +++ b/src/cli/cli.ts @@ -175,7 +175,6 @@ program console.log(''); console.log('Examples:'); console.log(''); - console.log(' $ show-trace --resources=resources trace/file.trace'); console.log(' $ show-trace trace/directory'); }); diff --git a/types/types.d.ts b/types/types.d.ts index a6348bae66..c274a9e4cd 100644 --- a/types/types.d.ts +++ b/types/types.d.ts @@ -6832,8 +6832,8 @@ export interface BrowserType { /** * 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. + * resolved relative to the current working directory. Note that Playwright only works with the bundled Chromium, Firefox + * or WebKit, use at your own risk. */ executablePath?: string; @@ -7032,7 +7032,6 @@ export interface BrowserType { /** * Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. - * Defaults to 0. */ slowMo?: number; @@ -7049,6 +7048,11 @@ export interface BrowserType { */ timezoneId?: string; + /** + * If specified, traces are saved into this directory. + */ + traceDir?: string; + /** * Specific user agent to use in this context. */ @@ -7150,8 +7154,8 @@ export interface BrowserType { /** * 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. + * resolved relative to the current working directory. Note that Playwright only works with the bundled Chromium, Firefox + * or WebKit, use at your own risk. */ executablePath?: string; @@ -7231,6 +7235,11 @@ export interface BrowserType { * disable timeout. */ timeout?: number; + + /** + * If specified, traces are saved into this directory. + */ + traceDir?: string; }): Promise; /** @@ -10267,7 +10276,21 @@ export interface Touchscreen { } /** - * Tracing object for collecting test traces that can be opened using Playwright CLI. + * API for collecting and saving Playwright traces. Playwright traces can be opened using the [CLI]('./cli.md') after + * Playwright script runs. + * + * Start with specifying the folder traces will be stored in: + * + * ```js + * const browser = await chromium.launch({ traceDir: 'traces' }); + * const context = await browser.newContext(); + * await context.tracing.start({ name: 'trace', screenshots: true, snapshots: true }); + * const page = await context.newPage(); + * await page.goto('https://playwright.dev'); + * await context.tracing.stop(); + * await context.tracing.export('trace.zip'); + * ``` + * */ export interface Tracing { /** @@ -10291,7 +10314,8 @@ export interface Tracing { */ start(options?: { /** - * If specified, the trace is going to be saved into the file with the given name. + * If specified, the trace is going to be saved into the file with the given name inside the `traceDir` folder specified in + * [browserType.launch([options])](https://playwright.dev/docs/api/class-browsertype#browsertypelaunchoptions). */ name?: string; @@ -10882,7 +10906,7 @@ export interface LaunchOptions { channel?: "chrome"|"chrome-beta"|"chrome-dev"|"chrome-canary"|"msedge"|"msedge-beta"|"msedge-dev"|"msedge-canary"|"firefox-stable"; /** - * Enable Chromium sandboxing. Defaults to `false`. + * Enable Chromium sandboxing. Defaults to `true`. */ chromiumSandbox?: boolean; @@ -10986,6 +11010,11 @@ export interface LaunchOptions { * disable timeout. */ timeout?: number; + + /** + * If specified, traces are saved into this directory. + */ + traceDir?: string; } export interface ConnectOverCDPOptions {