api: update videos api, hide tracing (#4015)

Author: dgozman

docs/api.md

@@ -220,12 +220,10 @@ Indicates that the browser is connected.
     - `password` <[string]>
   - `colorScheme` <"light"|"dark"|"no-preference"> Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See [page.emulateMedia(options)](#pageemulatemediaoptions) for more details. Defaults to '`light`'.
   - `logger` <[Logger]> Logger sink for Playwright logging.
-  - `relativeArtifactsPath` <[string]> Specifies a folder for artifacts like downloads, videos and traces, relative to `artifactsPath` from [`browserType.launch`](#browsertypelaunchoptions). Defaults to `.`.
-  - `recordVideos` <[boolean]> Enables video recording for all pages to the `relativeArtifactsPath` folder.
-  - `videoSize` <[Object]> Specifies dimensions of the automatically recorded video. Can only be used if `recordVideos` is true. 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.
+  - `videosPath` <[string]> Enables video recording for all pages to `videosPath` folder. If not specified, videos are not recorded.
+  - `videoSize` <[Object]> 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.
-  - `recordTrace` <[boolean]> Enables trace recording to the `relativeArtifactsPath` folder.
 - returns: <[Promise]<[BrowserContext]>>
 
 Creates a new browser context. It won't share cookies/cache with other browser contexts.
@@ -268,12 +266,10 @@ Creates a new browser context. It won't share cookies/cache with other browser c
     - `password` <[string]>
   - `colorScheme` <"light"|"dark"|"no-preference"> Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See [page.emulateMedia(options)](#pageemulatemediaoptions) for more details. Defaults to '`light`'.
   - `logger` <[Logger]> Logger sink for Playwright logging.
-  - `relativeArtifactsPath` <[string]> Specifies a folder for artifacts like downloads, videos and traces, relative to `artifactsPath` from [`browserType.launch`](#browsertypelaunchoptions). Defaults to `.`.
-  - `recordVideos` <[boolean]> Enables video recording for all pages to the `relativeArtifactsPath` folder.
-  - `videoSize` <[Object]> Specifies dimensions of the automatically recorded video. Can only be used if `recordVideos` is true. 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.
+  - `videosPath` <[string]> Enables video recording for all pages to `videosPath` folder. If not specified, videos are not recorded.
+  - `videoSize` <[Object]> 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.
-  - `recordTrace` <[boolean]> Enables trace recording to the `relativeArtifactsPath` folder.
 - returns: <[Promise]<[Page]>>
 
 Creates a new page in a new browser context. Closing this page will close the context as well.
@@ -4174,7 +4170,6 @@ This methods attaches Playwright to an existing browser instance.
     - `username` <[string]> Optional username to use if HTTP proxy requires authentication.
     - `password` <[string]> Optional password to use if HTTP proxy requires authentication.
   - `downloadsPath` <[string]> If specified, accepted downloads are downloaded into this folder. Otherwise, temporary folder is created and is deleted when browser is closed.
-  - `artifactsPath` <[string]> Specifies a folder for various artifacts like downloads, videos and traces. If not specified, artifacts are not collected.
   - `chromiumSandbox` <[boolean]> Enable Chromium sandboxing. Defaults to `true`.
   - `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).
   - `handleSIGINT` <[boolean]> Close the browser process on Ctrl-C. Defaults to `true`.
@@ -4217,7 +4212,6 @@ const browser = await chromium.launch({  // Or 'firefox' or 'webkit'.
     - `password` <[string]> Optional password to use if HTTP proxy requires authentication.
   - `acceptDownloads` <[boolean]> Whether to automatically download all the attachments. Defaults to `false` where all the downloads are canceled.
   - `downloadsPath` <[string]> If specified, accepted downloads are downloaded into this folder. Otherwise, temporary folder is created and is deleted when browser is closed.
-  - `artifactsPath` <[string]> Specifies a folder for various artifacts like downloads, videos and traces. If not specified, artifacts are not collected.
   - `chromiumSandbox` <[boolean]> Enable Chromium sandboxing. 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`.
@@ -4250,12 +4244,10 @@ const browser = await chromium.launch({  // Or 'firefox' or 'webkit'.
     - `username` <[string]>
     - `password` <[string]>
   - `colorScheme` <"light"|"dark"|"no-preference"> Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See [page.emulateMedia(options)](#pageemulatemediaoptions) for more details. Defaults to '`light`'.
-  - `relativeArtifactsPath` <[string]> Specifies a folder for artifacts like downloads, videos and traces, relative to `artifactsPath`. Defaults to `.`.
-  - `recordVideos` <[boolean]> Enables video recording for all pages to the `relativeArtifactsPath` folder.
-  - `videoSize` <[Object]> Specifies dimensions of the automatically recorded video. Can only be used if `recordVideos` is true. 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.
+  - `videosPath` <[string]> Enables video recording for all pages to `videosPath` folder. If not specified, videos are not recorded.
+  - `videoSize` <[Object]> 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.
-  - `recordTrace` <[boolean]> Enables trace recording to the `relativeArtifactsPath` folder.
 - returns: <[Promise]<[BrowserContext]>> Promise that resolves to 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.
@@ -4273,7 +4265,6 @@ Launches browser that uses persistent storage located at `userDataDir` and retur
     - `username` <[string]> Optional username to use if HTTP proxy requires authentication.
     - `password` <[string]> Optional password to use if HTTP proxy requires authentication.
   - `downloadsPath` <[string]> If specified, accepted downloads are downloaded into this folder. Otherwise, temporary folder is created and is deleted when browser is closed.
-  - `artifactsPath` <[string]> Specifies a folder for various artifacts like downloads, videos and traces. If not specified, artifacts are not collected.
   - `chromiumSandbox` <[boolean]> Enable Chromium sandboxing. Defaults to `true`.
   - `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).
   - `handleSIGINT` <[boolean]> Close the browser process on Ctrl-C. Defaults to `true`.

packages/installation-tests/screencast.js

@@ -27,17 +27,14 @@ if (process.argv[3] === 'all')
   success = ['chromium', 'firefox', 'webkit'];
 
 const playwright = require(requireName);
-const path = require('path');
 const fs = require('fs');
 
 (async () => {
   for (const browserType of success) {
     try {
-      const browser = await playwright[browserType].launch({
-        artifactsPath: __dirname,
-      });
+      const browser = await playwright[browserType].launch({});
       const context = await browser.newContext({
-        recordVideos: true,
+        videosPath: __dirname,
         videoSize: {width: 320, height: 240},
       });
       await context.newPage();

src/client/browser.ts

@@ -47,6 +47,10 @@ export class Browser extends ChannelOwner<channels.BrowserChannel, channels.Brow
   async newContext(options: BrowserContextOptions = {}): Promise<BrowserContext> {
     const logger = options.logger;
     return this._wrapApiCall('browser.newContext', async () => {
+      if (this._isRemote && options.videosPath)
+        throw new Error(`"videosPath" is not supported in connected browser`);
+      if (this._isRemote && options._tracePath)
+        throw new Error(`"_tracePath" is not supported in connected browser`);
       if (options.extraHTTPHeaders)
         validateHeaders(options.extraHTTPHeaders);
       const contextOptions: channels.BrowserNewContextParams = {

src/client/types.ts

@@ -82,7 +82,6 @@ export type LaunchServerOptions = {
     password?: string
   },
   downloadsPath?: string,
-  artifactsPath?: string,
   chromiumSandbox?: boolean,
   port?: number,
   logger?: Logger,

src/protocol/channels.ts

@@ -168,7 +168,6 @@ export type BrowserTypeLaunchParams = {
     password?: string,
   },
   downloadsPath?: string,
-  artifactsPath?: string,
   firefoxUserPrefs?: any,
   chromiumSandbox?: boolean,
   slowMo?: number,
@@ -195,7 +194,6 @@ export type BrowserTypeLaunchOptions = {
     password?: string,
   },
   downloadsPath?: string,
-  artifactsPath?: string,
   firefoxUserPrefs?: any,
   chromiumSandbox?: boolean,
   slowMo?: number,
@@ -226,7 +224,6 @@ export type BrowserTypeLaunchPersistentContextParams = {
     password?: string,
   },
   downloadsPath?: string,
-  artifactsPath?: string,
   chromiumSandbox?: boolean,
   slowMo?: number,
   noDefaultViewport?: boolean,
@@ -260,8 +257,13 @@ export type BrowserTypeLaunchPersistentContextParams = {
   hasTouch?: boolean,
   colorScheme?: 'light' | 'dark' | 'no-preference',
   acceptDownloads?: boolean,
-  relativeArtifactsPath?: string,
-  recordTrace?: boolean,
+  _traceResourcesPath?: string,
+  _tracePath?: string,
+  videosPath?: string,
+  videoSize?: {
+    width: number,
+    height: number,
+  },
 };
 export type BrowserTypeLaunchPersistentContextOptions = {
   executablePath?: string,
@@ -285,7 +287,6 @@ export type BrowserTypeLaunchPersistentContextOptions = {
     password?: string,
   },
   downloadsPath?: string,
-  artifactsPath?: string,
   chromiumSandbox?: boolean,
   slowMo?: number,
   noDefaultViewport?: boolean,
@@ -319,8 +320,13 @@ export type BrowserTypeLaunchPersistentContextOptions = {
   hasTouch?: boolean,
   colorScheme?: 'light' | 'dark' | 'no-preference',
   acceptDownloads?: boolean,
-  relativeArtifactsPath?: string,
-  recordTrace?: boolean,
+  _traceResourcesPath?: string,
+  _tracePath?: string,
+  videosPath?: string,
+  videoSize?: {
+    width: number,
+    height: number,
+  },
 };
 export type BrowserTypeLaunchPersistentContextResult = {
   context: BrowserContextChannel,
@@ -375,9 +381,9 @@ export type BrowserNewContextParams = {
   hasTouch?: boolean,
   colorScheme?: 'dark' | 'light' | 'no-preference',
   acceptDownloads?: boolean,
-  relativeArtifactsPath?: string,
-  recordTrace?: boolean,
-  recordVideos?: boolean,
+  _traceResourcesPath?: string,
+  _tracePath?: string,
+  videosPath?: string,
   videoSize?: {
     width: number,
     height: number,
@@ -415,9 +421,9 @@ export type BrowserNewContextOptions = {
   hasTouch?: boolean,
   colorScheme?: 'dark' | 'light' | 'no-preference',
   acceptDownloads?: boolean,
-  relativeArtifactsPath?: string,
-  recordTrace?: boolean,
-  recordVideos?: boolean,
+  _traceResourcesPath?: string,
+  _tracePath?: string,
+  videosPath?: string,
   videoSize?: {
     width: number,
     height: number,

src/protocol/protocol.yml

@@ -220,7 +220,6 @@ BrowserType:
             username: string?
             password: string?
         downloadsPath: string?
-        artifactsPath: string?
         firefoxUserPrefs: json?
         chromiumSandbox: boolean?
         slowMo: number?
@@ -259,7 +258,6 @@ BrowserType:
             username: string?
             password: string?
         downloadsPath: string?
-        artifactsPath: string?
         chromiumSandbox: boolean?
         slowMo: number?
         noDefaultViewport: boolean?
@@ -306,8 +304,14 @@ BrowserType:
           - dark
           - no-preference
         acceptDownloads: boolean?
-        relativeArtifactsPath: string?
-        recordTrace: boolean?
+        _traceResourcesPath: string?
+        _tracePath: string?
+        videosPath: string?
+        videoSize:
+          type: object?
+          properties:
+            width: number
+            height: number
       returns:
         context: BrowserContext
 
@@ -369,9 +373,9 @@ Browser:
           - light
           - no-preference
         acceptDownloads: boolean?
-        relativeArtifactsPath: string?
-        recordTrace: boolean?
-        recordVideos: boolean?
+        _traceResourcesPath: string?
+        _tracePath: string?
+        videosPath: string?
         videoSize:
           type: object?
           properties:

src/protocol/validator.ts

@@ -121,7 +121,6 @@ export function createScheme(tChannel: (name: string) => Validator): Scheme {
       password: tOptional(tString),
     })),
     downloadsPath: tOptional(tString),
-    artifactsPath: tOptional(tString),
     firefoxUserPrefs: tOptional(tAny),
     chromiumSandbox: tOptional(tBoolean),
     slowMo: tOptional(tNumber),
@@ -149,7 +148,6 @@ export function createScheme(tChannel: (name: string) => Validator): Scheme {
       password: tOptional(tString),
     })),
     downloadsPath: tOptional(tString),
-    artifactsPath: tOptional(tString),
     chromiumSandbox: tOptional(tBoolean),
     slowMo: tOptional(tNumber),
     noDefaultViewport: tOptional(tBoolean),
@@ -183,8 +181,13 @@ export function createScheme(tChannel: (name: string) => Validator): Scheme {
     hasTouch: tOptional(tBoolean),
     colorScheme: tOptional(tEnum(['light', 'dark', 'no-preference'])),
     acceptDownloads: tOptional(tBoolean),
-    relativeArtifactsPath: tOptional(tString),
-    recordTrace: tOptional(tBoolean),
+    _traceResourcesPath: tOptional(tString),
+    _tracePath: tOptional(tString),
+    videosPath: tOptional(tString),
+    videoSize: tOptional(tObject({
+      width: tNumber,
+      height: tNumber,
+    })),
   });
   scheme.BrowserCloseParams = tOptional(tObject({}));
   scheme.BrowserNewContextParams = tObject({
@@ -219,9 +222,9 @@ export function createScheme(tChannel: (name: string) => Validator): Scheme {
     hasTouch: tOptional(tBoolean),
     colorScheme: tOptional(tEnum(['dark', 'light', 'no-preference'])),
     acceptDownloads: tOptional(tBoolean),
-    relativeArtifactsPath: tOptional(tString),
-    recordTrace: tOptional(tBoolean),
-    recordVideos: tOptional(tBoolean),
+    _traceResourcesPath: tOptional(tString),
+    _tracePath: tOptional(tString),
+    videosPath: tOptional(tString),
     videoSize: tOptional(tObject({
       width: tNumber,
       height: tNumber,

src/server/browser.ts

@@ -31,7 +31,6 @@ export interface BrowserProcess {
 
 export type BrowserOptions = types.UIOptions & {
   name: string,
-  artifactsPath?: string,
   downloadsPath?: string,
   headful?: boolean,
   persistent?: types.BrowserContextOptions,  // Undefined means no persistent context.

src/server/browserContext.ts

@@ -94,19 +94,13 @@ export abstract class BrowserContext extends EventEmitter {
   readonly _browserContextId: string | undefined;
   private _selectors?: Selectors;
   readonly _actionListeners = new Set<ActionListener>();
-  readonly _artifactsPath?: string;
 
   constructor(browser: Browser, options: types.BrowserContextOptions, browserContextId: string | undefined) {
     super();
     this._browser = browser;
     this._options = options;
     this._browserContextId = browserContextId;
     this._isPersistentContext = !browserContextId;
-    if (browser._options.artifactsPath) {
-      this._artifactsPath = browser._options.artifactsPath;
-      if (options.relativeArtifactsPath)
-        this._artifactsPath = path.join(this._artifactsPath, options.relativeArtifactsPath);
-    }
     this._closePromise = new Promise(fulfill => this._closePromiseFulfill = fulfill);
   }
 
@@ -123,9 +117,9 @@ export abstract class BrowserContext extends EventEmitter {
       await listener.onContextCreated(this);
   }
 
-  async _ensureArtifactsPath() {
-    if (this._artifactsPath)
-      await mkdirIfNeeded(path.join(this._artifactsPath, 'dummy'));
+  async _ensureVideosPath() {
+    if (this._options.videosPath)
+      await mkdirIfNeeded(path.join(this._options.videosPath, 'dummy'));
   }
 
   _browserClosed() {
@@ -299,10 +293,8 @@ export function validateBrowserContextOptions(options: types.BrowserContextOptio
   if (!options.viewport && !options.noDefaultViewport)
     options.viewport = { width: 1280, height: 720 };
   verifyGeolocation(options.geolocation);
-  if (options.recordTrace && !browserOptions.artifactsPath)
-    throw new Error(`"recordTrace" option requires "artifactsPath" to be specified`);
-  if (options.recordVideos && !browserOptions.artifactsPath)
-    throw new Error(`"recordVideos" option requires "artifactsPath" to be specified`);
+  if (options.videoSize && !options.videosPath)
+    throw new Error(`"videoSize" option requires "videosPath" to be specified`);
 }
 
 export function verifyGeolocation(geolocation?: types.Geolocation) {

src/server/browserType.ts

@@ -92,7 +92,6 @@ export abstract class BrowserType {
       slowMo: options.slowMo,
       persistent,
       headful: !options.headless,
-      artifactsPath: options.artifactsPath,
       downloadsPath,
       browserProcess,
       proxy: options.proxy,
@@ -132,7 +131,7 @@ export abstract class BrowserType {
       }
       return dir;
     };
-    // TODO: use artifactsPath for downloads.
+    // TODO: add downloadsPath to newContext().
     const downloadsPath = await ensurePath(DOWNLOADS_FOLDER, options.downloadsPath);
 
     if (!userDataDir) {