feat: add path option to toMatchSnapshot

[nickofthyme]

allow snapshotName to accept an array of path segments in toMathchSnapshot.

// example.spec.ts
import { test, expect } from '@playwright/test';

test('example test', async ({ page }) => {
  await page.goto('https://playwright.dev');
  expect(await page.screenshot()).toMatchSnapshot(['test', 'path', 'landing.png']);
});

This would set and lookup the screenshot from example.spec.ts-snapshots/test/path/landing-<suffix>.png.

The path segment is contained to within the base snapshot directory for the given test file (e.g. example.spec.ts-snapshots/). Any path resolving to outside of this directory is ignored.

The current functionality of snapshotName as a 'string' is preserved. This string will continue to be sanitized for file path as is currently done.

// example.spec.ts
import { test, expect } from '@playwright/test';

test('example test', async ({ page }) => {
  await page.goto('https://playwright.dev');
  expect(await page.screenshot()).toMatchSnapshot('test/path/landing.png');
});

This would set and lookup the screenshot from example.spec.ts-snapshots/test-path-landing-<suffix>.png.

Related to #7792

[ghost]

All CLA requirements met.

[dgozman]

Thank you for the PR! See comments inline.

[nickofthyme]

@dgozman I'm curious what your thoughts are on adding a config option much like outputDir for snapshotDir that would be the base directory for all snapshots seeing as this was the main request from #7792. For example...

// playwright.config.ts
import { PlaywrightTestConfig } from '@playwright/test';

const config: PlaywrightTestConfig = {
  snapshotDir: 'snapshots',
};

export default config;

playwright.config.ts
tests/
└── foo.spec.ts
snapshots/
└── foo.spec.ts-snapshots/
     ├── basic-test-Chrome-linux.png
     └── basic-test-Safari-linux.png

Would there be any issue with this? I have started on these changes but think I'll put them in a follow up PR to this one.

[dgozman]

@dgozman I'm curious what your thoughts are on adding a config option much like outputDir for snapshotDir that would be the base directory for all snapshots seeing as this would the main request for #7792.

Sounds good to me!

[dgozman]

I am sorry that this PR turns into a lot of work, but it is going to be a great feature!

[nickofthyme]

I am sorry that this PR turns into a lot of work, but it is going to be a great feature!

All good! Thanks for the quick review. I agree with all your comments, I'll address them tomorrow. 👍🏼

[nickofthyme]

I wasn't sure about the naming in the docs for toMatchSnapshot and changing it from snapshotName to pathSegments. Might be best to keep it as is with snapshotName with the note about using it as pathSegments. Also looks like I might need to fix some tests once you take another look.

[dgozman]

I think this works nicely, just a few code comments.

BTW do I need to manually update docs/src/test-api/class-testinfo.md and docs/src/test-snapshots-js.md from types/test.d.ts or is there some auto generation script I am missing?

Files in docs/src are the source of truth, types/test.d.ts is generated from them by npm run watch.

I wasn't sure about the naming in the docs for toMatchSnapshot and changing it from snapshotName to pathSegments. Might be best to keep it as is with snapshotName with the note about using it as pathSegments

I agree that it's better to keep snapshotName.

[dgozman]

Apart from the spread and some failing tests, this looks perfect!

[dgozman]

Two suggestions to fix failing tests, the rest is great!