From 42d64d3b39294cc07cd023c3e0513e4875f3d070 Mon Sep 17 00:00:00 2001 From: Karl Horky Date: Fri, 28 Aug 2026 19:11:19 +0200 Subject: [PATCH 1/5] Document mouse position to avoid unintended screenshot hovers --- docs/src/test-snapshots-js.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/src/test-snapshots-js.md b/docs/src/test-snapshots-js.md index ed69bbcde2856..fe6c2cd43c80a 100644 --- a/docs/src/test-snapshots-js.md +++ b/docs/src/test-snapshots-js.md @@ -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 before taking the screenshot, for example to the viewport origin when no element there responds to hover. + +
+Helper for repeated named screenshots + +```ts title="test-utils.ts" +import { + expect, + type Page, + type PageAssertionsToHaveScreenshotOptions, +} from '@playwright/test'; + +export async function expectPageToHaveScreenshotWithMouseAtOrigin( + page: Page, + screenshotName: string, + options?: PageAssertionsToHaveScreenshotOptions, +) { + await page.mouse.move(0, 0); + await expect(page).toHaveScreenshot(screenshotName, options); +} +``` + +```ts title="example.spec.ts" +await expectPageToHaveScreenshotWithMouseAtOrigin(page, 'landing.png', { + fullPage: true, +}); +``` + +
+ ## Updating screenshots Sometimes you need to update the reference screenshot, for example when the page has changed. Do this with the `--update-snapshots` flag. From b49e08947db4ee7a15dacc813bc82075cbe0d553 Mon Sep 17 00:00:00 2001 From: Karl Horky Date: Sat, 29 Aug 2026 08:17:19 +0200 Subject: [PATCH 2/5] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Karl Horky --- docs/src/test-snapshots-js.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/test-snapshots-js.md b/docs/src/test-snapshots-js.md index fe6c2cd43c80a..3d88a56fbd156 100644 --- a/docs/src/test-snapshots-js.md +++ b/docs/src/test-snapshots-js.md @@ -73,7 +73,7 @@ import { export async function expectPageToHaveScreenshotWithMouseAtOrigin( page: Page, - screenshotName: string, + screenshotName: string | ReadonlyArray, options?: PageAssertionsToHaveScreenshotOptions, ) { await page.mouse.move(0, 0); From e158a8fdbf8f4f0acd3d2d58a21402dea3d3915b Mon Sep 17 00:00:00 2001 From: Karl Horky Date: Sat, 29 Aug 2026 08:20:31 +0200 Subject: [PATCH 3/5] Reset mouse position to -1, -1 as per review feedback Signed-off-by: Karl Horky --- docs/src/test-snapshots-js.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/test-snapshots-js.md b/docs/src/test-snapshots-js.md index 3d88a56fbd156..2e5f3d379e09d 100644 --- a/docs/src/test-snapshots-js.md +++ b/docs/src/test-snapshots-js.md @@ -76,7 +76,7 @@ export async function expectPageToHaveScreenshotWithMouseAtOrigin( screenshotName: string | ReadonlyArray, options?: PageAssertionsToHaveScreenshotOptions, ) { - await page.mouse.move(0, 0); + await page.mouse.move(-1, -1); await expect(page).toHaveScreenshot(screenshotName, options); } ``` From ca838fc72c82ced217f336f86ed79004e5889bd5 Mon Sep 17 00:00:00 2001 From: Karl Horky Date: Sat, 29 Aug 2026 09:11:25 +0200 Subject: [PATCH 4/5] Describe off-viewport mouse position for screenshot helper --- docs/src/test-snapshots-js.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/test-snapshots-js.md b/docs/src/test-snapshots-js.md index 2e5f3d379e09d..4ecfe76b23b6b 100644 --- a/docs/src/test-snapshots-js.md +++ b/docs/src/test-snapshots-js.md @@ -59,7 +59,7 @@ 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 before taking the screenshot, for example to the viewport origin when no element there responds to hover. +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.
Helper for repeated named screenshots From cb4ff84838fe324c3e303204548fce4c7ac5c663 Mon Sep 17 00:00:00 2001 From: Karl Horky Date: Sat, 29 Aug 2026 09:13:15 +0200 Subject: [PATCH 5/5] Rename screenshot helper for off-viewport mouse position --- docs/src/test-snapshots-js.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/test-snapshots-js.md b/docs/src/test-snapshots-js.md index 4ecfe76b23b6b..4c9b0c7658042 100644 --- a/docs/src/test-snapshots-js.md +++ b/docs/src/test-snapshots-js.md @@ -71,7 +71,7 @@ import { type PageAssertionsToHaveScreenshotOptions, } from '@playwright/test'; -export async function expectPageToHaveScreenshotWithMouseAtOrigin( +export async function expectPageToHaveScreenshotWithMouseOutsideViewport( page: Page, screenshotName: string | ReadonlyArray, options?: PageAssertionsToHaveScreenshotOptions, @@ -82,7 +82,7 @@ export async function expectPageToHaveScreenshotWithMouseAtOrigin( ``` ```ts title="example.spec.ts" -await expectPageToHaveScreenshotWithMouseAtOrigin(page, 'landing.png', { +await expectPageToHaveScreenshotWithMouseOutsideViewport(page, 'landing.png', { fullPage: true, }); ```