chore: add pageSnapshot option

docs/src/test-api/class-testoptions.md

@@ -507,6 +507,27 @@ export default defineConfig({
 
 Learn more about [automatic screenshots](../test-use-options.md#recording-options).
 
+## property: TestOptions.pageSnapshot
+* since: v1.10
+- type: <[PageSnapshotMode]<"off"|"on"|"only-on-failure">>
+
+Whether to automatically capture a ARIA snapshot of the page after each test. Defaults to `'only-on-failure'`.
+* `'off'`: Do not capture page snapshots.
+* `'on'`: Capture page snapshot after each test.
+* `'only-on-failure'`: Capture page snapshot after each test failure.
+
+**Usage**
+
+```js title="playwright.config.ts"
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    pageSnapshot: 'on',
+  },
+});
+```
+
 ## property: TestOptions.storageState = %%-js-python-context-option-storage-state-%%
 * since: v1.10
 

packages/playwright/src/index.ts

@@ -19,7 +19,7 @@ import * as path from 'path';
 import type { APIRequestContext, BrowserContext, Browser, BrowserContextOptions, LaunchOptions, Page, Tracing, Video } from 'playwright-core';
 import * as playwrightLibrary from 'playwright-core';
 import { createGuid, debugMode, addInternalStackPrefix, isString, asLocator, jsonStringifyForceASCII, zones } from 'playwright-core/lib/utils';
-import type { Fixtures, PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions, ScreenshotMode, TestInfo, TestType, VideoMode } from '../types/test';
+import type { Fixtures, PageSnapshotMode, PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions, ScreenshotMode, TestInfo, TestType, VideoMode } from '../types/test';
 import type { TestInfoImpl, TestStepInternal } from './worker/testInfo';
 import { rootTestType } from './common/testType';
 import type { ContextReuseMode } from './common/config';
@@ -454,7 +454,7 @@ const playwrightFixtures: Fixtures<TestFixtures, WorkerFixtures> = ({
 
 type ScreenshotOption = PlaywrightWorkerOptions['screenshot'] | undefined;
 type Playwright = PlaywrightWorkerArgs['playwright'];
-type PageSnapshotOption = 'off' | 'on' | 'only-on-failure';
+type PageSnapshotOption = PlaywrightWorkerOptions['pageSnapshot'] | undefined;
 
 function normalizeVideoMode(video: VideoMode | 'retry-with-video' | { mode: VideoMode } | undefined): VideoMode {
   if (!video)
@@ -533,7 +533,7 @@ class SnapshotRecorder {
 
   constructor(
     private _artifactsRecorder: ArtifactsRecorder,
-    private _mode: ScreenshotMode | PageSnapshotOption,
+    private _mode: ScreenshotMode | PageSnapshotMode,
     private _name: string,
     private _contentType: string,
     private _extension: string,
@@ -640,7 +640,7 @@ class ArtifactsRecorder {
       await page.screenshot({ ...screenshotOptions, timeout: 5000, path, caret: 'initial' });
     });
 
-    this._pageSnapshotRecorder = new SnapshotRecorder(this, pageSnapshot, 'pageSnapshot', 'text/plain', '.ariasnapshot', async (page, path) => {
+    this._pageSnapshotRecorder = new SnapshotRecorder(this, pageSnapshot ?? 'only-on-failure', 'pageSnapshot', 'text/plain', '.ariasnapshot', async (page, path) => {
       const ariaSnapshot = await page.locator('body').ariaSnapshot();
       await fs.promises.writeFile(path, ariaSnapshot);
     });

packages/playwright/src/runner/testServer.ts

@@ -309,9 +309,9 @@ export class TestServerDispatcher implements TestServerInterface {
         ...(params.trace === 'off' ? { trace: 'off' } : {}),
         ...(params.video === 'on' || params.video === 'off' ? { video: params.video } : {}),
         ...(params.headed !== undefined ? { headless: !params.headed } : {}),
+        ...(params.pageSnapshot ? { pageSnapshot: params.pageSnapshot } : undefined),
         _optionContextReuseMode: params.reuseContext ? 'when-possible' : undefined,
         _optionConnectOptions: params.connectWsEndpoint ? { wsEndpoint: params.connectWsEndpoint } : undefined,
-        _pageSnapshot: params.pageSnapshot,
       },
       ...(params.updateSnapshots ? { updateSnapshots: params.updateSnapshots } : {}),
       ...(params.updateSourceMethod ? { updateSourceMethod: params.updateSourceMethod } : {}),

packages/playwright/types/test.d.ts

@@ -6187,6 +6187,27 @@ export interface PlaywrightWorkerOptions {
    * Learn more about [automatic screenshots](https://playwright.dev/docs/test-use-options#recording-options).
    */
   screenshot: ScreenshotMode | { mode: ScreenshotMode } & Pick<PageScreenshotOptions, 'fullPage' | 'omitBackground'>;
+  /**
+   * Whether to automatically capture a ARIA snapshot of the page after each test. Defaults to `'only-on-failure'`.
+   * - `'off'`: Do not capture page snapshots.
+   * - `'on'`: Capture page snapshot after each test.
+   * - `'only-on-failure'`: Capture page snapshot after each test failure.
+   *
+   * **Usage**
+   *
+   * ```js
+   * // playwright.config.ts
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     pageSnapshot: 'on',
+   *   },
+   * });
+   * ```
+   *
+   */
+  pageSnapshot: PageSnapshotMode;
   /**
    * Whether to record trace for each test. Defaults to `'off'`.
    * - `'off'`: Do not record trace.
@@ -6246,6 +6267,7 @@ export interface PlaywrightWorkerOptions {
 }
 
 export type ScreenshotMode = 'off' | 'on' | 'only-on-failure' | 'on-first-failure';
+export type PageSnapshotMode = 'off' | 'on' | 'only-on-failure';
 export type TraceMode = 'off' | 'on' | 'retain-on-failure' | 'on-first-retry' | 'on-all-retries' | 'retain-on-first-failure';
 export type VideoMode = 'off' | 'on' | 'retain-on-failure' | 'on-first-retry';
 

tests/playwright-test/playwright.artifacts.spec.ts

@@ -421,11 +421,11 @@ test('should take screenshot when page is closed in afterEach', async ({ runInli
   expect(fs.existsSync(testInfo.outputPath('test-results', 'a-fails', 'test-failed-1.png'))).toBeTruthy();
 });
 
-test('should work with _pageSnapshot: on', async ({ runInlineTest }, testInfo) => {
+test('should work with pageSnapshot: on', async ({ runInlineTest }, testInfo) => {
   const result = await runInlineTest({
     ...testFiles,
     'playwright.config.ts': `
-      module.exports = { use: { _pageSnapshot: 'on' } };
+      module.exports = { use: { pageSnapshot: 'on' } };
     `,
   }, { workers: 1 });
 
@@ -461,11 +461,11 @@ test('should work with _pageSnapshot: on', async ({ runInlineTest }, testInfo) =
   ]);
 });
 
-test('should work with _pageSnapshot: only-on-failure', async ({ runInlineTest }, testInfo) => {
+test('should work with pageSnapshot: only-on-failure', async ({ runInlineTest }, testInfo) => {
   const result = await runInlineTest({
     ...testFiles,
     'playwright.config.ts': `
-      module.exports = { use: { _pageSnapshot: 'only-on-failure' } };
+      module.exports = { use: { pageSnapshot: 'only-on-failure' } };
     `,
   }, { workers: 1 });
 

utils/generate_types/overrides-test.d.ts

@@ -234,11 +234,13 @@ export interface PlaywrightWorkerOptions {
   launchOptions: Omit<LaunchOptions, 'tracesDir'>;
   connectOptions: ConnectOptions | undefined;
   screenshot: ScreenshotMode | { mode: ScreenshotMode } & Pick<PageScreenshotOptions, 'fullPage' | 'omitBackground'>;
+  pageSnapshot: PageSnapshotMode;
   trace: TraceMode | /** deprecated */ 'retry-with-trace' | { mode: TraceMode, snapshots?: boolean, screenshots?: boolean, sources?: boolean, attachments?: boolean };
   video: VideoMode | /** deprecated */ 'retry-with-video' | { mode: VideoMode, size?: ViewportSize };
 }
 
 export type ScreenshotMode = 'off' | 'on' | 'only-on-failure' | 'on-first-failure';
+export type PageSnapshotMode = 'off' | 'on' | 'only-on-failure';
 export type TraceMode = 'off' | 'on' | 'retain-on-failure' | 'on-first-retry' | 'on-all-retries' | 'retain-on-first-failure';
 export type VideoMode = 'off' | 'on' | 'retain-on-failure' | 'on-first-retry';