docs(test): document mouse-outside-viewport screenshot helper - #42446
docs(test): document mouse-outside-viewport screenshot helper#42446Karl Horky (karlhorky) wants to merge 5 commits into
Conversation
| }); | ||
| ``` | ||
|
|
||
| </details> |
There was a problem hiding this comment.
In case the helper function seems like too much, a simpler alternative without a helper function could be this:
await page.mouse.move(-1, -1);
await expect(page).toHaveScreenshot();There was a problem hiding this comment.
Pull request overview
Updates Playwright Test visual comparison documentation to explain how preserved mouse position can unintentionally introduce hover states into screenshot assertions, and provides a reusable helper pattern to mitigate it.
Changes:
- Document why mouse position persistence can affect
expect(page).toHaveScreenshot()results after navigations/rerenders. - Add a collapsible TypeScript helper that moves the mouse to
(0, 0)before taking named screenshots. - Show an example of forwarding
toHaveScreenshot()options through the helper.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| screenshotName: string, | ||
| options?: PageAssertionsToHaveScreenshotOptions, | ||
| ) { | ||
| await page.mouse.move(0, 0); |
There was a problem hiding this comment.
(0, 0) is still inside the viewport and commonly hovers a header or any other full width element
(-1, -1) reliably clears hover across all three browsers and matches Playwright’s internal reset behavior
There was a problem hiding this comment.
Oh interesting, I didn't find that position in the codebase - maybe I didn't look hard enough
Done in e158a8f
|
|
||
| export async function expectPageToHaveScreenshotWithMouseAtOrigin( | ||
| page: Page, | ||
| screenshotName: string, |
There was a problem hiding this comment.
the helper unnecessarily excludes the supported ReadonlyArray<string>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Karl Horky <karl.horky@gmail.com>
Signed-off-by: Karl Horky <karl.horky@gmail.com>
Karl Horky (karlhorky)
changed the title
Mouse actions leave the pointer at their last position. If a navigation or re-render places another element under that position,
expect(page).toHaveScreenshot()can capture an unrelated hover state.Playwright keeps this browser behavior as-is in Firefox:
Chromium also preserves the last mouse position:
This adds concise guidance to the Visual comparisons page and a collapsed helper for repeated named screenshots. The helper moves the mouse to
-1, -1before callingtoHaveScreenshot()and forwards its screenshot options.The documentation notes that projects should choose another coordinate when an element at the viewport origin responds to hover.