Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
feat: Add global config option for `/children` property of aria snapshots (#39466)
Chris9605ceae3d61
diff --git a/docs/src/aria-snapshots.md b/docs/src/aria-snapshots.mdindex 00321151aa..ad0ee92d74 100644--- a/docs/src/aria-snapshots.md+++ b/docs/src/aria-snapshots.md@@ -307,6 +307,25 @@ Following snapshot will fail due to Feature C not being in the template:- listitem: Feature B```+#### Setting `children` mode globally++Instead of adding a `/children` property to every snapshot, you can set the default children matching mode for all+`toMatchAriaSnapshot` calls in the configuration file:++```js title="playwright.config.ts"+import { defineConfig } from '@playwright/test';++export default defineConfig({+ expect: {+ toMatchAriaSnapshot: {+ children: 'equal',+ },+ },+});+```++Individual snapshots can still override the global setting by including an explicit `/children` property in the template.+### Matching with regular expressionsRegular expressions allow flexible matching for elements with dynamic or variable text. Accessible names and text candiff --git a/docs/src/test-api/class-testconfig.md b/docs/src/test-api/class-testconfig.mdindex a01babad1f..fb642f79d6 100644--- a/docs/src/test-api/class-testconfig.md+++ b/docs/src/test-api/class-testconfig.md@@ -83,6 +83,7 @@ The structure of the git commit metadata is subject to change.- `pathTemplate` ?<[string]> A template controlling location of the screenshots. See [`property: TestConfig.snapshotPathTemplate`] for details.- `toMatchAriaSnapshot` ?<[Object]> Configuration for the [`method: LocatorAssertions.toMatchAriaSnapshot#2`] method.- `pathTemplate` ?<[string]> A template controlling location of the aria snapshots. See [`property: TestConfig.snapshotPathTemplate`] for details.+ - `children` ?<["contain" | "equal" | "deep-equal"]> Controls how children of the snapshot root are matched against the actual accessibility tree. This is equivalent to adding a `/children` property at the top of every aria snapshot template. Individual snapshots can override this by including an explicit `/children` property.- `toMatchSnapshot` ?<[Object]> Configuration for the [`method: SnapshotAssertions.toMatchSnapshot#1`] method.- `maxDiffPixels` ?<[int]> An acceptable amount of pixels that could be different, unset by default.- `maxDiffPixelRatio` ?<[float]> An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by default.diff --git a/docs/src/test-api/class-testproject.md b/docs/src/test-api/class-testproject.mdindex 30f316c82b..d301719c7c 100644--- a/docs/src/test-api/class-testproject.md+++ b/docs/src/test-api/class-testproject.md@@ -101,6 +101,7 @@ export default defineConfig({- `pathTemplate` ?<[string]> A template controlling location of the screenshots. See [`property: TestProject.snapshotPathTemplate`] for details.- `toMatchAriaSnapshot` ?<[Object]> Configuration for the [`method: LocatorAssertions.toMatchAriaSnapshot#2`] method.- `pathTemplate` ?<[string]> A template controlling location of the aria snapshots. See [`property: TestProject.snapshotPathTemplate`] for details.+ - `children` ?<["contain" | "equal" | "deep-equal"]> Controls how children of the snapshot root are matched against the actual accessibility tree. This is equivalent to adding a `/children` property at the top of every aria snapshot template. Individual snapshots can override this by including an explicit `/children` property.- `toMatchSnapshot` ?<[Object]> Configuration for the [`method: SnapshotAssertions.toMatchSnapshot#1`] method.- `threshold` ?<[float]> 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`.- `maxDiffPixels` ?<[int]> an acceptable amount of pixels that could be different, unset by default.diff --git a/packages/playwright/src/matchers/toMatchAriaSnapshot.ts b/packages/playwright/src/matchers/toMatchAriaSnapshot.tsindex 15e828f70b..8212ad6623 100644--- a/packages/playwright/src/matchers/toMatchAriaSnapshot.ts+++ b/packages/playwright/src/matchers/toMatchAriaSnapshot.ts@@ -80,6 +80,11 @@ export async function toMatchAriaSnapshot(}expected = unshift(expected);++ const globalChildren = testInfo._projectInternal.expect?.toMatchAriaSnapshot?.children;+ if (globalChildren && !expected.match(/^- \/children:/m))+ expected = `- /children: ${globalChildren}\n` + expected;+const { matches: pass, received, log, timedOut, errorMessage } = await locator._expect('to.match.aria', { expectedValue: expected, isNot: this.isNot, timeout });const typedReceived = received as MatcherReceived;diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.tsindex 0553609ebd..c30f7bca04 100644--- a/packages/playwright/types/test.d.ts+++ b/packages/playwright/types/test.d.ts@@ -250,6 +250,13 @@ interface TestProject<TestArgs = {}, WorkerArgs = {}> {* for details.*/pathTemplate?: string;++ /**+ * Controls how children of the snapshot root are matched against the actual accessibility tree. This is equivalent to+ * adding a `/children` property at the top of every aria snapshot template. Individual snapshots can override this by+ * including an explicit `/children` property.+ */+ children?: "contain"|"equal"|"deep-equal";};/**@@ -1181,6 +1188,13 @@ interface TestConfig<TestArgs = {}, WorkerArgs = {}> {* for details.*/pathTemplate?: string;++ /**+ * Controls how children of the snapshot root are matched against the actual accessibility tree. This is equivalent to+ * adding a `/children` property at the top of every aria snapshot template. Individual snapshots can override this by+ * including an explicit `/children` property.+ */+ children?: "contain"|"equal"|"deep-equal";};/**diff --git a/tests/playwright-test/aria-snapshot-file.spec.ts b/tests/playwright-test/aria-snapshot-file.spec.tsindex f568dc5c31..ded73bcc3c 100644--- a/tests/playwright-test/aria-snapshot-file.spec.ts+++ b/tests/playwright-test/aria-snapshot-file.spec.ts@@ -251,3 +251,182 @@ test('should respect config.expect.toMatchAriaSnapshot.pathTemplate', async ({ rexpect(result.exitCode).toBe(0);expect(result.passed).toBe(1);});++test('should fail with config.expect.toMatchAriaSnapshot.children=equal when root children mismatch', async ({ runInlineTest }) => {+ const result = await runInlineTest({+ 'playwright.config.ts': `+ export default {+ expect: {+ toMatchAriaSnapshot: {+ children: 'equal',+ },+ },+ };+ `,+ 'a.spec.ts': `+ import { test, expect } from '@playwright/test';+ test('test', async ({ page }) => {+ await page.setContent(\`<h1>Title</h1><p>Paragraph</p>\`);+ await expect(page.locator('body')).toMatchAriaSnapshot(\`+ - heading "Title" [level=1]+ \`, { timeout: 1000 });+ });+ `+ });++ expect(result.exitCode).toBe(1);+ expect(result.output).toContain('+ - paragraph: Paragraph');+});++test('should respect config.expect.toMatchAriaSnapshot.children=equal with file snapshot', async ({ runInlineTest }) => {+ const result = await runInlineTest({+ 'playwright.config.ts': `+ export default {+ expect: {+ toMatchAriaSnapshot: {+ children: 'equal',+ },+ },+ };+ `,+ 'a.spec.ts-snapshots/test.aria.yml': `+ - list:+ - listitem: "One"+ - listitem: "Two"+ - listitem: "Three"+ `,+ 'a.spec.ts': `+ import { test, expect } from '@playwright/test';+ test('test', async ({ page }) => {+ await page.setContent(\`<ul><li>One</li><li>Two</li><li>Three</li></ul>\`);+ await expect(page.locator('body')).toMatchAriaSnapshot({ name: 'test.aria.yml' });+ });+ `+ });++ expect(result.exitCode).toBe(0);+});++test('should respect config.expect.toMatchAriaSnapshot.children=deep-equal', async ({ runInlineTest }) => {+ const result = await runInlineTest({+ 'playwright.config.ts': `+ export default {+ expect: {+ toMatchAriaSnapshot: {+ children: 'deep-equal',+ },+ },+ };+ `,+ 'a.spec.ts': `+ import { test, expect } from '@playwright/test';+ test('test', async ({ page }) => {+ await page.setContent(\`<ul><li><ul><li>1.1</li><li>1.2</li></ul></li></ul>\`);+ await expect(page.locator('body')).toMatchAriaSnapshot(\`+ - list:+ - listitem:+ - list:+ - listitem: "1.1"+ \`, { timeout: 1000 });+ });+ `+ });++ expect(result.exitCode).toBe(1);+ expect(result.output).toContain('+ - listitem: "1.2"');+});++test('inline /children property should override global children config', async ({ runInlineTest }) => {+ const result = await runInlineTest({+ 'playwright.config.ts': `+ export default {+ expect: {+ toMatchAriaSnapshot: {+ children: 'equal',+ },+ },+ };+ `,+ 'a.spec.ts': `+ import { test, expect } from '@playwright/test';+ test('test', async ({ page }) => {+ await page.setContent(\`<ul><li>One</li><li>Two</li><li>Three</li></ul>\`);+ await expect(page.locator('body')).toMatchAriaSnapshot(\`+ - list:+ - /children: contain+ - listitem: "One"+ - listitem: "Three"+ \`);+ });+ `+ });++ expect(result.exitCode).toBe(0);+});++test('should respect project-level expect.toMatchAriaSnapshot.children=equal', async ({ runInlineTest }) => {+ const result = await runInlineTest({+ 'playwright.config.ts': `+ export default {+ projects: [+ {+ name: 'strict',+ expect: {+ toMatchAriaSnapshot: {+ children: 'equal',+ },+ },+ },+ ],+ };+ `,+ 'a.spec.ts': `+ import { test, expect } from '@playwright/test';+ test('matching passes', async ({ page }) => {+ await page.setContent(\`<h1>Title</h1>\`);+ await expect(page.locator('body')).toMatchAriaSnapshot(\`+ - heading "Title" [level=1]+ \`);+ });+ test('extra root child fails', async ({ page }) => {+ await page.setContent(\`<h1>Title</h1><p>Paragraph</p>\`);+ await expect(page.locator('body')).toMatchAriaSnapshot(\`+ - heading "Title" [level=1]+ \`, { timeout: 1000 });+ });+ `+ });++ expect(result.exitCode).toBe(1);+ expect(result.passed).toBe(1);+ expect(result.failed).toBe(1);+ expect(result.output).toContain('+ - paragraph: Paragraph');+});+++test('top-level equal should overwrite deep-equal children config', async ({ runInlineTest }) => {+ const result = await runInlineTest({+ 'playwright.config.ts': `+ export default {+ expect: {+ toMatchAriaSnapshot: {+ children: 'deep-equal',+ },+ },+ };+ `,+ 'a.spec.ts': `+ import { test, expect } from '@playwright/test';+ test('equal matches part of tree', async ({ page }) => {+ await page.setContent(\`<ul><li>One</li><li>Two</li></ul>\`);+ await expect(page.locator('body')).toMatchAriaSnapshot(\`+ - /children: equal+ - list:+ - listitem: "One"+ \`);+ });+ `+ });++ expect(result.exitCode).toBe(0);+});