Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

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.md
index 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 expressions
Regular expressions allow flexible matching for elements with dynamic or variable text. Accessible names and text can
diff --git a/docs/src/test-api/class-testconfig.md b/docs/src/test-api/class-testconfig.md
index 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.md
index 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.ts
index 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.ts
index 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.ts
index 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 ({ r
expect(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);
+});