feat(roll): roll to ToT Playwright (roll/next-30-01-25)

nodejs/docs/api/class-locatorassertions.mdx

@@ -997,18 +997,20 @@ await expect(page.locator('body')).toMatchAriaSnapshot(`
 
 Asserts that the target element matches the given [accessibility snapshot](../aria-snapshots.mdx).
 
+Snapshot is stored in a separate `.yml` file in a location configured by `expect.toMatchAriaSnapshot.pathTemplate` and/or `snapshotPathTemplate` properties in the configuration file.
+
 **Usage**
 
 ```js
 await expect(page.locator('body')).toMatchAriaSnapshot();
-await expect(page.locator('body')).toMatchAriaSnapshot({ name: 'snapshot' });
+await expect(page.locator('body')).toMatchAriaSnapshot({ name: 'body.yml' });
 ```
 
 **Arguments**
 - `options` [Object] *(optional)*
   - `name` [string] *(optional)*<a aria-hidden="true" tabIndex="-1" class="list-anchor-link" id="locator-assertions-to-match-aria-snapshot-2-option-name"/><a href="#locator-assertions-to-match-aria-snapshot-2-option-name" class="list-anchor">#</a>
 
-    Name of the snapshot to store in the snapshot (screenshot) folder corresponding to this test. Generates sequential names if not specified.
+    Name of the snapshot to store in the snapshot folder corresponding to this test. Generates sequential names if not specified.
   - `timeout` [number] *(optional)*<a aria-hidden="true" tabIndex="-1" class="list-anchor-link" id="locator-assertions-to-match-aria-snapshot-2-option-timeout"/><a href="#locator-assertions-to-match-aria-snapshot-2-option-timeout" class="list-anchor">#</a>
 
     Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.

nodejs/docs/api/class-testconfig.mdx

@@ -101,8 +101,17 @@ export default defineConfig({
     - `threshold` [number] *(optional)*
 
       An acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and `1` (lax). `"pixelmatch"` comparator computes color difference in [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`.
+    - `pathTemplate` [string] *(optional)*
+
+      A template controlling location of the screenshots. See [testConfig.snapshotPathTemplate](/api/class-testconfig.mdx#test-config-snapshot-path-template) for details.
 
     Configuration for the [expect(page).toHaveScreenshot()](/api/class-pageassertions.mdx#page-assertions-to-have-screenshot-1) method.
+  - `toMatchAriaSnapshot` [Object] *(optional)*
+    - `pathTemplate` [string] *(optional)*
+
+      A template controlling location of the aria snapshots. See [testConfig.snapshotPathTemplate](/api/class-testconfig.mdx#test-config-snapshot-path-template) for details.
+
+    Configuration for the [expect(locator).toMatchAriaSnapshot()](/api/class-locatorassertions.mdx#locator-assertions-to-match-aria-snapshot-2) method.
   - `toMatchSnapshot` [Object] *(optional)*
     - `maxDiffPixels` [number] *(optional)*
 
@@ -332,15 +341,17 @@ export default defineConfig({
 
 <font size="2" style={{position: "relative", top: "-20px"}}>Added in: v1.10</font><x-search>testConfig.metadata</x-search>
 
-Metadata that will be put directly to the test report serialized as JSON.
+Metadata contains key-value pairs to be included in the report. For example, HTML report will display it as key-value pairs, and JSON report will include metadata serialized as json.
+
+See also [testConfig.populateGitInfo](/api/class-testconfig.mdx#test-config-populate-git-info) that populates metadata.
 
 **Usage**
 
 ```js title="playwright.config.ts"
 import { defineConfig } from '@playwright/test';
 
 export default defineConfig({
-  metadata: 'acceptance tests',
+  metadata: { title: 'acceptance tests' },
 });
 ```
 
@@ -411,7 +422,9 @@ test('example test', async ({}, testInfo) => {
 
 <font size="2" style={{position: "relative", top: "-20px"}}>Added in: v1.51</font><x-search>testConfig.populateGitInfo</x-search>
 
-Whether to populate [testConfig.metadata](/api/class-testconfig.mdx#test-config-metadata) with Git info. The metadata will automatically appear in the HTML report and is available in Reporter API.
+Whether to populate `'git.commit.info'` field of the [testConfig.metadata](/api/class-testconfig.mdx#test-config-metadata) with Git commit info and CI/CD information.
+
+This information will appear in the HTML and JSON reports and is available in the Reporter API.
 
 **Usage**
 
@@ -653,7 +666,9 @@ export default defineConfig({
 
 <font size="2" style={{position: "relative", top: "-20px"}}>Added in: v1.28</font><x-search>testConfig.snapshotPathTemplate</x-search>
 
-This option configures a template controlling location of snapshots generated by [expect(page).toHaveScreenshot()](/api/class-pageassertions.mdx#page-assertions-to-have-screenshot-1) and [expect(value).toMatchSnapshot()](/api/class-snapshotassertions.mdx#snapshot-assertions-to-match-snapshot-1).
+This option configures a template controlling location of snapshots generated by [expect(page).toHaveScreenshot()](/api/class-pageassertions.mdx#page-assertions-to-have-screenshot-1), [expect(locator).toMatchAriaSnapshot()](/api/class-locatorassertions.mdx#locator-assertions-to-match-aria-snapshot-2) and [expect(value).toMatchSnapshot()](/api/class-snapshotassertions.mdx#snapshot-assertions-to-match-snapshot-1).
+
+You can configure templates for each assertion separately in [testConfig.expect](/api/class-testconfig.mdx#test-config-expect).
 
 **Usage**
 
@@ -662,7 +677,19 @@ import { defineConfig } from '@playwright/test';
 
 export default defineConfig({
   testDir: './tests',
+
+  // Single template for all assertions
   snapshotPathTemplate: '{testDir}/__screenshots__/{testFilePath}/{arg}{ext}',
+
+  // Assertion-specific templates
+  expect: {
+    toHaveScreenshot: {
+      pathTemplate: '{testDir}/__screenshots__{/projectName}/{testFilePath}/{arg}{ext}',
+    },
+    toMatchAriaSnapshot: {
+      pathTemplate: '{testDir}/__snapshots__/{testFilePath}/{arg}{ext}',
+    },
+  },
 });
 ```
 
@@ -695,22 +722,22 @@ test.describe('suite', () => {
 ```
 
 The list of supported tokens:
-* `{arg}` - Relative snapshot path **without extension**. These come from the arguments passed to the `toHaveScreenshot()` and `toMatchSnapshot()` calls; if called without arguments, this will be an auto-generated snapshot name.
+* `{arg}` - Relative snapshot path **without extension**. This comes from the arguments passed to `toHaveScreenshot()`, `toMatchAriaSnapshot()` or `toMatchSnapshot()`; if called without arguments, this will be an auto-generated snapshot name.
   * Value: `foo/bar/baz`
-* `{ext}` - snapshot extension (with dots)
+* `{ext}` - Snapshot extension (with the leading dot).
   * Value: `.png`
 * `{platform}` - The value of `process.platform`.
 * `{projectName}` - Project's file-system-sanitized name, if any.
   * Value: `''` (empty string).
-* `{snapshotDir}` - Project's [testConfig.snapshotDir](/api/class-testconfig.mdx#test-config-snapshot-dir).
+* `{snapshotDir}` - Project's [testProject.snapshotDir](/api/class-testproject.mdx#test-project-snapshot-dir).
   * Value: `/home/playwright/tests` (since `snapshotDir` is not provided in config, it defaults to `testDir`)
-* `{testDir}` - Project's [testConfig.testDir](/api/class-testconfig.mdx#test-config-test-dir).
-  * Value: `/home/playwright/tests` (absolute path is since `testDir` is resolved relative to directory with config)
+* `{testDir}` - Project's [testProject.testDir](/api/class-testproject.mdx#test-project-test-dir).
+  * Value: `/home/playwright/tests` (absolute path since `testDir` is resolved relative to directory with config)
 * `{testFileDir}` - Directories in relative path from `testDir` to **test file**.
   * Value: `page`
 * `{testFileName}` - Test file name with extension.
   * Value: `page-click.spec.ts`
-* `{testFilePath}` - Relative path from `testDir` to **test file**
+* `{testFilePath}` - Relative path from `testDir` to **test file**.
   * Value: `page/page-click.spec.ts`
 * `{testName}` - File-system-sanitized test title, including parent describes but excluding file name.
   * Value: `suite-test-should-work`

nodejs/docs/api/class-testproject.mdx

@@ -138,8 +138,17 @@ testProject.expect
     - `stylePath` [string] | [Array]<[string]> *(optional)*
 
       See [style](/api/class-page.mdx#page-screenshot-option-style) in [page.screenshot()](/api/class-page.mdx#page-screenshot).
+    - `pathTemplate` [string] *(optional)*
+
+      A template controlling location of the screenshots. See [testProject.snapshotPathTemplate](/api/class-testproject.mdx#test-project-snapshot-path-template) for details.
 
     Configuration for the [expect(page).toHaveScreenshot()](/api/class-pageassertions.mdx#page-assertions-to-have-screenshot-1) method.
+  - `toMatchAriaSnapshot` [Object] *(optional)*
+    - `pathTemplate` [string] *(optional)*
+
+      A template controlling location of the aria snapshots. See [testProject.snapshotPathTemplate](/api/class-testproject.mdx#test-project-snapshot-path-template) for details.
+
+    Configuration for the [expect(locator).toMatchAriaSnapshot()](/api/class-locatorassertions.mdx#locator-assertions-to-match-aria-snapshot-2) method.
   - `toMatchSnapshot` [Object] *(optional)*
     - `threshold` [number] *(optional)*
 
@@ -408,7 +417,9 @@ testProject.snapshotDir
 
 <font size="2" style={{position: "relative", top: "-20px"}}>Added in: v1.28</font><x-search>testProject.snapshotPathTemplate</x-search>
 
-This option configures a template controlling location of snapshots generated by [expect(page).toHaveScreenshot()](/api/class-pageassertions.mdx#page-assertions-to-have-screenshot-1) and [expect(value).toMatchSnapshot()](/api/class-snapshotassertions.mdx#snapshot-assertions-to-match-snapshot-1).
+This option configures a template controlling location of snapshots generated by [expect(page).toHaveScreenshot()](/api/class-pageassertions.mdx#page-assertions-to-have-screenshot-1), [expect(locator).toMatchAriaSnapshot()](/api/class-locatorassertions.mdx#locator-assertions-to-match-aria-snapshot-2) and [expect(value).toMatchSnapshot()](/api/class-snapshotassertions.mdx#snapshot-assertions-to-match-snapshot-1).
+
+You can configure templates for each assertion separately in [testConfig.expect](/api/class-testconfig.mdx#test-config-expect).
 
 **Usage**
 
@@ -417,7 +428,19 @@ import { defineConfig } from '@playwright/test';
 
 export default defineConfig({
   testDir: './tests',
+
+  // Single template for all assertions
   snapshotPathTemplate: '{testDir}/__screenshots__/{testFilePath}/{arg}{ext}',
+
+  // Assertion-specific templates
+  expect: {
+    toHaveScreenshot: {
+      pathTemplate: '{testDir}/__screenshots__{/projectName}/{testFilePath}/{arg}{ext}',
+    },
+    toMatchAriaSnapshot: {
+      pathTemplate: '{testDir}/__snapshots__/{testFilePath}/{arg}{ext}',
+    },
+  },
 });
 ```
 
@@ -450,22 +473,22 @@ test.describe('suite', () => {
 ```
 
 The list of supported tokens:
-* `{arg}` - Relative snapshot path **without extension**. These come from the arguments passed to the `toHaveScreenshot()` and `toMatchSnapshot()` calls; if called without arguments, this will be an auto-generated snapshot name.
+* `{arg}` - Relative snapshot path **without extension**. This comes from the arguments passed to `toHaveScreenshot()`, `toMatchAriaSnapshot()` or `toMatchSnapshot()`; if called without arguments, this will be an auto-generated snapshot name.
   * Value: `foo/bar/baz`
-* `{ext}` - snapshot extension (with dots)
+* `{ext}` - Snapshot extension (with the leading dot).
   * Value: `.png`
 * `{platform}` - The value of `process.platform`.
 * `{projectName}` - Project's file-system-sanitized name, if any.
   * Value: `''` (empty string).
-* `{snapshotDir}` - Project's [testConfig.snapshotDir](/api/class-testconfig.mdx#test-config-snapshot-dir).
+* `{snapshotDir}` - Project's [testProject.snapshotDir](/api/class-testproject.mdx#test-project-snapshot-dir).
   * Value: `/home/playwright/tests` (since `snapshotDir` is not provided in config, it defaults to `testDir`)
-* `{testDir}` - Project's [testConfig.testDir](/api/class-testconfig.mdx#test-config-test-dir).
-  * Value: `/home/playwright/tests` (absolute path is since `testDir` is resolved relative to directory with config)
+* `{testDir}` - Project's [testProject.testDir](/api/class-testproject.mdx#test-project-test-dir).
+  * Value: `/home/playwright/tests` (absolute path since `testDir` is resolved relative to directory with config)
 * `{testFileDir}` - Directories in relative path from `testDir` to **test file**.
   * Value: `page`
 * `{testFileName}` - Test file name with extension.
   * Value: `page-click.spec.ts`
-* `{testFilePath}` - Relative path from `testDir` to **test file**
+* `{testFilePath}` - Relative path from `testDir` to **test file**.
   * Value: `page/page-click.spec.ts`
 * `{testName}` - File-system-sanitized test title, including parent describes but excluding file name.
   * Value: `suite-test-should-work`

nodejs/docs/release-notes.mdx

@@ -51,6 +51,7 @@ import LiteYouTube from '@site/src/components/LiteYouTube';
 
 * Option [testConfig.webServer](/api/class-testconfig.mdx#test-config-web-server) added a `gracefulShutdown` field for specifying a process kill signal other than the default `SIGKILL`.
 * Exposed [testStep.attachments](/api/class-teststep.mdx#test-step-attachments) from the reporter API to allow retrieval of all attachments created by that step.
+* New option `pathTemplate` for `toHaveScreenshot` and `toMatchAriaSnapshot` assertions in the [testConfig.expect](/api/class-testconfig.mdx#test-config-expect) configuration.
 
 ### UI updates
 * Updated default HTML reporter to improve display of attachments.

nodejs/docs/test-snapshots.mdx

@@ -51,7 +51,7 @@ The snapshot name `example-test-1-chromium-darwin.png` consists of a few parts:
 
 - `chromium-darwin` - the browser name and the platform. Screenshots differ between browsers and platforms due to different rendering, fonts and more, so you will need different snapshots for them. If you use multiple projects in your [configuration file](./test-configuration.mdx), project name will be used instead of `chromium`.
 
-The snapshot name and path can be configured with [`snapshotPathTemplate`](./api/class-testproject#test-project-snapshot-path-template) in the playwright config.
+The snapshot name and path can be configured with [testConfig.snapshotPathTemplate](/api/class-testconfig.mdx#test-config-snapshot-path-template) in the playwright config.
 
 ## Updating screenshots