custom stabilization

packages/api-client/tsup.config.ts

@@ -3,6 +3,5 @@ import { defineConfig } from "tsup";
 export default defineConfig({
   entry: ["src/index.ts"],
   dts: true,
-  clean: true,
   format: ["esm"],
 });

packages/browser/src/global/index.ts

@@ -1,14 +1,19 @@
 import {
-  waitForStability,
+  checkIsStable,
   setup,
   teardown,
   SetupOptions,
   TeardownOptions,
+  StabilizationOptions,
+  getStabilityFailureReasons,
 } from "./stabilization";
 import { getColorScheme, getMediaType } from "./media";
 
 const ArgosGlobal = {
-  waitForStability: () => waitForStability(document),
+  checkIsStable: (options?: StabilizationOptions) =>
+    checkIsStable(document, options),
+  getStabilityFailureReasons: (options?: StabilizationOptions) =>
+    getStabilityFailureReasons(document, options),
   setup: (options: SetupOptions = {}) => setup(document, options),
   teardown: (options: TeardownOptions = {}) => teardown(document, options),
   getColorScheme: () => getColorScheme(window),

packages/browser/src/global/stabilization.ts

@@ -255,14 +255,68 @@ function waitForNoBusy(document: Document) {
   return elements.every((element) => !checkIsVisible(element));
 }
 
+export type StabilizationOptions = {
+  /**
+   * Wait for [aria-busy="true"] elements to be invisible.
+   * @default true
+   */
+  ariaBusy?: boolean;
+  /**
+   * Wait for images to be loaded.
+   * @default true
+   */
+  images?: boolean;
+  /**
+   * Wait for fonts to be loaded.
+   * @default true
+   */
+  fonts?: boolean;
+};
+
+/**
+ * Get the stabilization state of the document.
+ */
+function getStabilityState(document: Document, options?: StabilizationOptions) {
+  const { ariaBusy = true, images = true, fonts = true } = options ?? {};
+  return {
+    ariaBusy: ariaBusy ? waitForNoBusy(document) : true,
+    images: images ? waitForImagesToLoad(document) : true,
+    fonts: fonts ? waitForFontsToLoad(document) : true,
+  };
+}
+
+const VALIDATION_ERRORS: Record<keyof StabilizationOptions, string> = {
+  ariaBusy: "Some elements still have `aria-busy='true'`",
+  images: "Some images are still loading",
+  fonts: "Some fonts are still loading",
+};
+
 /**
- * Wait for the document to be stable.
+ * Get the stability failure reasons.
  */
-export function waitForStability(document: Document) {
-  const results = [
-    waitForNoBusy(document),
-    waitForImagesToLoad(document),
-    waitForFontsToLoad(document),
-  ];
-  return results.every(Boolean);
+export function getStabilityFailureReasons(
+  document: Document,
+  options?: StabilizationOptions,
+) {
+  const stabilityState = getStabilityState(document, options);
+  return Object.entries(stabilityState).reduce<string[]>(
+    (reasons, [key, value]) => {
+      if (!value) {
+        reasons.push(VALIDATION_ERRORS[key as keyof typeof VALIDATION_ERRORS]);
+      }
+      return reasons;
+    },
+    [],
+  );
+}
+
+/**
+ * Check if the document is stable.
+ */
+export function checkIsStable(
+  document: Document,
+  options?: StabilizationOptions,
+) {
+  const stabilityState = getStabilityState(document, options);
+  return Object.values(stabilityState).every(Boolean);
 }

packages/browser/src/index.ts

@@ -1,2 +1,3 @@
 export * from "./viewport";
 export * from "./script";
+export type { StabilizationOptions } from "./global/stabilization";

packages/cli/tsup.config.ts

@@ -2,6 +2,5 @@ import { defineConfig } from "tsup";
 
 export default defineConfig({
   entry: ["src/index.ts"],
-  clean: true,
   format: ["esm"],
 });

packages/core/tsup.config.ts

@@ -3,6 +3,5 @@ import { defineConfig } from "tsup";
 export default defineConfig({
   entry: ["src/index.ts"],
   dts: true,
-  clean: true,
   format: ["esm"],
 });

packages/cypress/docs/index.mdx

@@ -31,6 +31,10 @@ Please refer to our [Quickstart guide](/quickstart/cypress) to get started with
 - `options.viewports`: Define specific viewports for capturing screenshots. More on [viewports configuration](/viewports).
 - `options.argosCSS`: Specific CSS applied during the screenshot process. More on [injecting CSS](/injecting-css)
 - `options.threshold`: Sensitivity threshold between 0 and 1. The higher the threshold, the less sensitive the diff will be. Default to `0.5`.
+- `options.stabilize`: Wait for the UI to stabilize before taking the screenshot. Set to `false` to disable stabilization. Pass an object to customize the stabilization. Default to `true`.
+- `options.stabilize.ariaBusy`: Wait for the `aria-busy` attribute to be removed from the document. Default to `true`.
+- `options.stabilize.fonts`: Wait for fonts to be loaded. Default to `true`.
+- `options.stabilize.images`: Wait for images to be loaded. Default to `true`.
 
 ## Helper Attributes for Visual Testing
 

packages/cypress/src/support.ts

@@ -2,6 +2,7 @@ import "cypress-wait-until";
 import {
   ArgosGlobal,
   resolveViewport,
+  StabilizationOptions,
   type ViewportOption,
 } from "@argos-ci/browser";
 import { getGlobalScript } from "@argos-ci/browser";
@@ -21,16 +22,26 @@ type ArgosScreenshotOptions = Partial<
    * Viewports to take screenshots of.
    */
   viewports?: ViewportOption[];
+
   /**
    * Custom CSS evaluated during the screenshot process.
    */
   argosCSS?: string;
+
   /**
    * Sensitivity threshold between 0 and 1.
    * The higher the threshold, the less sensitive the diff will be.
    * @default 0.5
    */
   threshold?: number;
+
+  /**
+   * Wait for the UI to stabilize before taking the screenshot.
+   * Set to `false` to disable stabilization.
+   * Pass an object to customize the stabilization.
+   * @default true
+   */
+  stabilize?: boolean | StabilizationOptions;
 };
 
 declare global {
@@ -88,7 +99,12 @@ Cypress.Commands.add(
   "argosScreenshot",
   { prevSubject: ["optional", "element", "window", "document"] },
   (subject, name, options = {}) => {
-    const { viewports, argosCSS, ...cypressOptions } = options;
+    const {
+      viewports,
+      argosCSS,
+      stabilize = true,
+      ...cypressOptions
+    } = options;
     if (!name) {
       throw new Error("The `name` argument is required.");
     }
@@ -104,13 +120,32 @@ Cypress.Commands.add(
     const teardown = setup(options);
 
     function stabilizeAndScreenshot(name: string) {
-      cy.waitUntil(() =>
-        cy
-          .window({ log: false })
-          .then((window) =>
-            ((window as any).__ARGOS__ as ArgosGlobal).waitForStability(),
-          ),
-      );
+      if (stabilize) {
+        const stabilizationOptions =
+          typeof stabilize === "object" ? stabilize : {};
+
+        cy.waitUntil(() =>
+          cy.window({ log: false }).then((window) => {
+            const isStable = (
+              (window as any).__ARGOS__ as ArgosGlobal
+            ).checkIsStable(stabilizationOptions);
+
+            if (isStable) {
+              return true;
+            }
+
+            const failureReasons = (
+              (window as any).__ARGOS__ as ArgosGlobal
+            ).getStabilityFailureReasons(stabilizationOptions);
+
+            failureReasons.forEach((reason) => {
+              cy.log(`[argos] stability: ${reason}`);
+            });
+
+            return false;
+          }),
+        );
+      }
 
       let ref: any = {};
 

packages/cypress/tsup.config.ts

@@ -4,13 +4,11 @@ export default defineConfig([
   {
     entry: ["src/support.ts"],
     dts: true,
-    clean: true,
     format: ["esm"],
   },
   {
     entry: ["src/task.ts"],
     dts: true,
-    clean: true,
     format: ["esm", "cjs"],
   },
 ]);

packages/gitlab/tsup.config.ts

@@ -4,13 +4,11 @@ export default defineConfig([
   {
     entry: ["src/index.ts"],
     dts: true,
-    clean: true,
     format: ["esm"],
   },
   {
     entry: ["src/cli.ts"],
     dts: false,
-    clean: true,
     format: ["esm"],
   },
 ]);

packages/playwright/docs/index.mdx

@@ -211,6 +211,10 @@ export default defineConfig({
 - `options.disableHover`: Disable hover effects by moving the mouse to the top-left corner of the page. Default to `true`.
 - `options.threshold`: Sensitivity threshold between 0 and 1. The higher the threshold, the less sensitive the diff will be. Default to `0.5`.
 - `options.root`: Folder where the screenshots will be saved if not using the Argos reporter. Default to `./screenshots`.
+- `options.stabilize`: Wait for the UI to stabilize before taking the screenshot. Set to `false` to disable stabilization. Pass an object to customize the stabilization. Default to `true`.
+- `options.stabilize.ariaBusy`: Wait for the `aria-busy` attribute to be removed from the document. Default to `true`.
+- `options.stabilize.fonts`: Wait for fonts to be loaded. Default to `true`.
+- `options.stabilize.images`: Wait for images to be loaded. Default to `true`.
 
 Unlike [Playwright's `screenshot` method](https://playwright.dev/docs/api/class-page#page-screenshot), set `fullPage` option to `true` by default. Feel free to override this option if you prefer partial screenshots of your pages.
 

packages/playwright/src/screenshot.ts

@@ -15,6 +15,7 @@ import {
   resolveViewport,
   ArgosGlobal,
   getGlobalScript,
+  StabilizationOptions,
 } from "@argos-ci/browser";
 import {
   getMetadataPath,
@@ -70,6 +71,14 @@ export type ArgosScreenshotOptions = {
    * @default "./screenshots"
    */
   root?: string;
+
+  /**
+   * Wait for the UI to stabilize before taking the screenshot.
+   * Set to `false` to disable stabilization.
+   * Pass an object to customize the stabilization.
+   * @default true
+   */
+  stabilize?: boolean | StabilizationOptions;
 } & LocatorOptions &
   ScreenshotOptions<LocatorScreenshotOptions> &
   ScreenshotOptions<PageScreenshotOptions>;
@@ -196,6 +205,7 @@ export async function argosScreenshot(
     hasText,
     viewports,
     argosCSS,
+    stabilize = true,
     root = DEFAULT_SCREENSHOT_ROOT,
     ...playwrightOptions
   } = options;
@@ -272,9 +282,32 @@ export async function argosScreenshot(
   };
 
   const stabilizeAndScreenshot = async (name: string) => {
-    await page.waitForFunction(() =>
-      ((window as any).__ARGOS__ as ArgosGlobal).waitForStability(),
-    );
+    if (stabilize) {
+      const stabilizationOptions =
+        typeof stabilize === "object" ? stabilize : {};
+      try {
+        await page.waitForFunction(
+          (options) =>
+            ((window as any).__ARGOS__ as ArgosGlobal).checkIsStable(options),
+          stabilizationOptions,
+        );
+      } catch (error) {
+        const reasons = await page.evaluate(
+          (options) =>
+            (
+              (window as any).__ARGOS__ as ArgosGlobal
+            ).getStabilityFailureReasons(options),
+          stabilizationOptions,
+        );
+        throw new Error(
+          `
+Failed to stabilize screenshot, found the following issues:
+${reasons.map((reason) => `- ${reason}`).join("\n")}
+        `.trim(),
+          { cause: error },
+        );
+      }
+    }
 
     const names = getScreenshotNames(name, testInfo);
 

packages/playwright/tsup.config.ts

@@ -4,14 +4,12 @@ export default defineConfig([
   {
     entry: ["src/index.ts"],
     dts: true,
-    clean: true,
     external: ["@playwright/test"],
     format: ["esm"],
   },
   {
     entry: ["src/reporter.ts"],
     dts: true,
-    clean: true,
     format: ["esm"],
   },
 ]);

packages/puppeteer/docs/index.mdx

@@ -58,6 +58,10 @@ Screenshots are stored in `screenshots/argos` folder, relative to current direct
 - `options.argosCSS`: Specific CSS applied during the screenshot process. More on [injecting CSS](/injecting-css)
 - `options.disableHover`: Disable hover effects by moving the mouse to the top-left corner of the page. Default to `true`.
 - `options.threshold`: Sensitivity threshold between 0 and 1. The higher the threshold, the less sensitive the diff will be. Default to `0.5`.
+- `options.stabilize`: Wait for the UI to stabilize before taking the screenshot. Set to `false` to disable stabilization. Pass an object to customize the stabilization. Default to `true`.
+- `options.stabilize.ariaBusy`: Wait for the `aria-busy` attribute to be removed from the document. Default to `true`.
+- `options.stabilize.fonts`: Wait for fonts to be loaded. Default to `true`.
+- `options.stabilize.images`: Wait for images to be loaded. Default to `true`.
 
 Unlike [Puppeteer's `screenshot` method](https://playwright.dev/docs/api/class-page#page-screenshot), `argosScreenshot` set `fullPage` option to `true` by default. Feel free to override this option if you prefer partial screenshots of your pages.