From 55097dea3f820bfa815af49c2a470e53176e9e6e Mon Sep 17 00:00:00 2001
From: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
Date: Thu, 30 Jan 2025 10:11:10 +0000
Subject: [PATCH] feat(roll): roll to ToT Playwright (30-01-25)

---
 nodejs/docs/api/class-locatorassertions.mdx |  6 ++-
 nodejs/docs/api/class-testconfig.mdx        | 47 ++++++++++++++++-----
 nodejs/docs/api/class-testproject.mdx       | 37 +++++++++++++---
 nodejs/docs/release-notes.mdx               |  1 +
 nodejs/docs/test-snapshots.mdx              |  2 +-
 5 files changed, 73 insertions(+), 20 deletions(-)

diff --git a/nodejs/docs/api/class-locatorassertions.mdx b/nodejs/docs/api/class-locatorassertions.mdx
index f2d3b71a041..baec3e7feef 100644
--- a/nodejs/docs/api/class-locatorassertions.mdx
+++ b/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`.
diff --git a/nodejs/docs/api/class-testconfig.mdx b/nodejs/docs/api/class-testconfig.mdx
index d3f0b97ef82..2db0f5aa530 100644
--- a/nodejs/docs/api/class-testconfig.mdx
+++ b/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,7 +341,9 @@ 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**
 
@@ -340,7 +351,7 @@ Metadata that will be put directly to the test report serialized as JSON.
 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`
diff --git a/nodejs/docs/api/class-testproject.mdx b/nodejs/docs/api/class-testproject.mdx
index fa53caaad8c..566602efddb 100644
--- a/nodejs/docs/api/class-testproject.mdx
+++ b/nodejs/docs/api/class-testproject.mdx
@@ -138,8 +138,17 @@ testProject.expect
     - `stylePath` [string] | [Array]&lt;[string]&gt; *(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`
diff --git a/nodejs/docs/release-notes.mdx b/nodejs/docs/release-notes.mdx
index 71c5d110fb7..f2712ab1b28 100644
--- a/nodejs/docs/release-notes.mdx
+++ b/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.
diff --git a/nodejs/docs/test-snapshots.mdx b/nodejs/docs/test-snapshots.mdx
index 21fbee2d26f..6a759de3f6d 100644
--- a/nodejs/docs/test-snapshots.mdx
+++ b/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