Conversation
… tokens
`imagesPath` gains three tokens: `{os}` (Cypress.platform), `{browser}`
(Cypress.browser.name) and `{platform}` = `{os}-{browser}`. Unlike
`{spec_path}` they can sit anywhere inside a segment; values are sanitised
so custom browser names stay valid directory names.
BREAKING CHANGE: the default `imagesPath` is now
`{spec_path}/__image_snapshots__/{platform}`, so every OS/browser
combination keeps its own baselines and local runs stop fighting with CI
images. MIGRATION.md shows how to keep the 4.x layout
(`pluginVisualRegressionImagesPath={spec_path}/__image_snapshots__`) or
move existing baselines. The example baselines move into
`linux-electron/`, which is what the CI job produces.
Refs: #212
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
FRSgit
force-pushed
the
feat/manifest
branch
from
September 23, 2026 12:14
967d80c to
d34ddb1
Compare
FRSgit
force-pushed
the
feat/platform-token
branch
from
September 23, 2026 12:14
be07022 to
1eaeff4
Compare
# Conflicts: # packages/cypress-plugin-visual-regression-diff/MIGRATION.md
The default imagesPath stays {spec_path}/__image_snapshots__, as planned in
RENDERER-DESIGN.md: once pixels come from a pinned renderer the local vs CI
drift disappears by construction, so a per-platform default would only make
that migration harder. The tokens stay available for people who want to
split baselines by OS and browser today. {browser} is documented as the
browser that rendered the screenshot, which is Cypress's browser for native
screenshots and will be the renderer's browser later. The example baselines
move back to their flat folder and the MIGRATION entry goes away since
nothing breaks any more.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
FRSgit
changed the title
2 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This is the path-token half of the #212 story (the first half is the deterministic rendering preset in #421). Cross-OS rendering drift can't be fixed inside the browser, so
imagesPathgets tokens that let you keep one set of baselines per OS and browser instead of having macOS and Linux fight over the same files.What changed:
imagesPathunderstands three new tokens:{os}(Cypress.platform, solinux/darwin/win32),{browser}(the browser that rendered the screenshot,Cypress.browser.nametoday) and{platform}, which is just{os}-{browser}. Unlike{spec_path}, they can also be part of a segment, soshots-{platform}works. Custom browser names get sanitised so they're always valid directory names.imagesPathstays{spec_path}/__image_snapshots__, so nothing changes for existing users and this isn't a breaking change any more. An earlier version of this PR switched the default to{spec_path}/__image_snapshots__/{platform}; I backed that out because the plan inRENDERER-DESIGN.mdis a renderer that produces the pixels in a pinned Docker image no matter where Cypress runs, which makes local-vs-CI drift disappear by construction. A per-platform default would only have made that migration harder (everybody moving their baselines twice).{platform}stays useful later for keeping several rendered browsers apart..gitignorerecipe for committing only the CI platform, the cleanup caveat, and a short note on where this is heading. The FAQ about browser names in filenames now just points at{browser}instead of theCommands.overwritehack.pathVariables) rather than readingCypress.*itself, so the renderer can later hand it its own browser name without touching the path code.One thing worth knowing:
pluginVisualRegressionCleanupUnusedImagesdoesn't know about platforms. It globs the whole project, so a local macOS run with cleanup on would delete the committed Linux baselines as "unused". I documented that cleanup should only run on the platform whose baselines you commit (CI). Making the sweep platform-aware is a good follow-up but I didn't want to grow this PR.The manifest records the same
os/browservalues per entry, plus arendererblock (that landed in #414, which is why this PR is based onfeat/manifest; it'll retarget tofeat/major-5once that merges).matchAgainstPathis intentionally not expanded, it's an explicit file path.Tests cover whole-segment and embedded tokens,
{spec_path}staying whole-segment only, absolute unix/windows paths, sanitisation, and that another platform's screenshot doesn't count as "used" for cleanup. I didn't run the headed example on this Mac; the default path is only exercised incommands.ts, which the e2e job covers.Refs: #212
🤖 Generated with Claude Code