There are 2 issues here:

1. screenshotDirectory is overloaded for 2 uses, the 1st being normal screenshots while the 2nd being visual regression test references.
2. there's a broken "relativization" of the screenshotDirectory path

For screenshots, this option is described as:

/**
 * Directory where screenshots will be saved when page.screenshot() is called
 * If not set, all screenshots are saved to __screenshots__ directory in the same folder as the test file.
 * If this is set, it will be resolved relative to the project root.
 * @default __screenshots__
 */

While for the assertion it is described as as:

/**
 * The value provided to `browser.screenshotDirectory`,
 * if none is provided, its default value.
 */

They promise 2 different things to the user, while sharing the same value under the hood.

This, in combination with resolveScreenshotPath's default value (see below), made the reference path generation act like page.screenshot()'s even if not intended (and broken because of the relativization).

/**
 * Overrides default reference screenshot path.
 *
 * @default `${root}/${testFileDirectory}/${screenshotDirectory}/${testFileName}/${arg}-${browserName}-${platform}${ext}`
 */

On top of that, the broken relativization made it impossible for users to use absolute paths.

I'm still not sure if this is the best possible solution, but seems like a good middle ground without breaking too much existing behavior.

✅ Deploy Preview for vitest-dev ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	05e00c4
🔍 Latest deploy log	https://app.netlify.com/projects/vitest-dev/deploys/6a3bc1684aa0b30008f0773d
😎 Deploy Preview	https://deploy-preview-10592--vitest-dev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

Added a new config value as suggested by @sheremet-va, which should solve this overlap.

This makes sense to me, but I think this should also be mentioned in the migration guide