Skip to content

docs(test): document mouse-outside-viewport screenshot helper #42446

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Karl Horky (karlhorky) wants to merge 5 commits into
base: main
Choose a base branch
from
+30 −0
Open

docs(test): document mouse-outside-viewport screenshot helper #42446

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
42d64d3
Document mouse position to avoid unintended screenshot hovers
karlhorky Aug 28, 2026
b49e089
Potential fix for pull request finding
karlhorky Aug 29, 2026
e158a8f
Reset mouse position to -1, -1 as per review feedback
karlhorky Aug 29, 2026
ca838fc
Describe off-viewport mouse position for screenshot helper
karlhorky Aug 29, 2026
cb4ff84
Rename screenshot helper for off-viewport mouse position
karlhorky Aug 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions docs/src/test-snapshots-js.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,36 @@ await expect(page).toHaveScreenshot('landing.webp');
> Note that `toHaveScreenshot()` also accepts an array of path segments to the snapshot file such as `expect().toHaveScreenshot(['relative', 'path', 'to', 'snapshot.png'])`.
> However, this path must stay within the snapshots directory for each test file (i.e. `a.spec.js-snapshots`), otherwise it will throw.

Mouse actions such as [`method: Locator.click`] leave the pointer at its last position. If the page changes afterwards, another element can end up under the pointer and appear hovered in the screenshot. To avoid this, move the mouse outside the viewport before taking the screenshot.

@dgozman Dmitry Gozman (dgozman) Sep 2, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's make a separate section "Hover effects" and put it right before "Options".

In the section, explain that screenshots contain any hover effects present in the page at the moment, and if one would like to avoid any hover effects, we recommend to move the mouse somewhere, or hover an element that has no effects.

A two-line snippet with mouse.move + screenshot would be nice there.


<details>
<summary>Helper for repeated named screenshots</summary>

```ts title="test-utils.ts"
import {
expect,
type Page,
type PageAssertionsToHaveScreenshotOptions,
} from '@playwright/test';

export async function expectPageToHaveScreenshotWithMouseOutsideViewport(
page: Page,
screenshotName: string | ReadonlyArray<string>,
options?: PageAssertionsToHaveScreenshotOptions,
) {
await page.mouse.move(-1, -1);
await expect(page).toHaveScreenshot(screenshotName, options);
}
```

```ts title="example.spec.ts"
await expectPageToHaveScreenshotWithMouseOutsideViewport(page, 'landing.png', {
fullPage: true,
});
```

</details>

@karlhorky Karl Horky (karlhorky) Aug 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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();


## Updating screenshots

Sometimes you need to update the reference screenshot, for example when the page has changed. Do this with the `--update-snapshots` flag.
Expand Down