fix: onBeforeScreenshot and pause called before each theme screenshot (#61)

This adds extra screenshot stability by waiting for potential
layout and paint in browser triggered by theme change

Author: SwinX

actions/README.md

@@ -132,7 +132,8 @@ type MatchScreenshotOptions = {
      */
     themes?: Theme[];
     /**
-     * Callback before taking screenshot. Useful for special stabilizing actions
+     * Callback before taking screenshot. Useful for special stabilizing actions.
+     * Called before each individual screenshot (including each theme when multiple themes are configured).
      * @param page Page current page
      * @param options ScreenshotOptions screenshot options being used
      * @defaultValue globalSettings.matchScreenshot.onBeforeScreenshot
@@ -390,7 +391,8 @@ When reassigning settings, sections are merged, settings per section are also me
          */
         hideBySelector: undefined as string[] | undefined,
         /**
-         * Pause before screenshot (ms)
+         * Pause before each screenshot (ms).
+         * Applied per individual screenshot capture (including each theme).
          */
         pause: 1000,
         /**
@@ -411,7 +413,8 @@ When reassigning settings, sections are merged, settings per section are also me
          */
         themes: undefined as Theme[] | undefined,
         /**
-         * Callback before taking screenshot. Useful for special stabilizing actions
+         * Callback before taking screenshot. Useful for special stabilizing actions.
+         * Called before each individual screenshot (including each theme).
          */
         onBeforeScreenshot: undefined as OnBeforeScreenshotCallback | undefined,
         /**

actions/matchScreenshot.ts

@@ -158,33 +158,35 @@ export async function matchScreenshot(
         await page.mouse.move(x, y);
     }
 
-    await onBeforeScreenshot?.(page, combinedOptions);
-
     const slug = shouldPrependSlugToName ? getTestSlug(page) : undefined;
 
-    await page.waitForTimeout(pause);
-
     if (themes && themes.length) {
         for (const theme of themes) {
             await onSwitchTheme?.(theme, page);
 
             const resolvedName = name ? `${name}-${theme}` : undefined;
 
             await doMatchScreenshot({
+                page,
                 locator,
                 name: resolvedName,
                 slug,
                 options: combinedOptions,
                 soft,
+                onBeforeScreenshot,
+                pause,
             });
         }
     } else {
         await doMatchScreenshot({
+            page,
             locator,
             name,
             slug,
             options: combinedOptions,
             soft,
+            onBeforeScreenshot,
+            pause,
         });
     }
 
@@ -195,13 +197,20 @@ export async function matchScreenshot(
 }
 
 async function doMatchScreenshot(params: {
+    page: Page;
     locator: Locator | Page;
     name?: string;
     slug?: string;
     options: ScreenshotOptions;
     soft: boolean;
+    onBeforeScreenshot?: OnBeforeScreenshotCallback;
+    pause: number;
 }): Promise<void> {
-    const { locator, name, slug, options, soft } = params;
+    const { page, locator, name, slug, options, soft, onBeforeScreenshot, pause } = params;
+
+    await onBeforeScreenshot?.(page, options);
+    await page.waitForTimeout(pause);
+
     const resolvedName = resolveScreenshotName({ name, slug });
     const resolvedExpect = soft ? expect.soft : expect;
 

fixtures/README.md

@@ -118,7 +118,8 @@ type ExpectScreenshotFixtureBuilderParams = {
      */
     hideBySelector?: string[];
     /**
-     * Pause before screenshot (ms)
+     * Pause before each screenshot (ms).
+     * Applied per individual screenshot capture (including each theme).
      * @defaultValue `1000`
      */
     pause?: number;
@@ -138,7 +139,8 @@ type ExpectScreenshotFixtureBuilderParams = {
      */
     themes?: Theme[];
     /**
-     * Callback before taking screenshot. Useful for special stabilizing actions
+     * Callback before taking screenshot. Useful for special stabilizing actions.
+     * Called before each individual screenshot (including each theme when multiple themes are configured).
      * @param page Page current page
      */
     onBeforeScreenshot?: (page: Page, options: ScreenshotOptions) => Promise<void>;