@argos-ci/puppeteer 6.0.22 → 6.1.0

package/README.md

@@ -17,11 +17,11 @@
 
 Capture stable Argos screenshots from your [Puppeteer](https://github.com/puppeteer/puppeteer) tests.
 
-Visit the [Puppeteer SDK documentation](https://argos-ci.com/docs/sdks-reference/puppeteer) for guides, the API reference, and more.
+Visit the [Puppeteer SDK documentation](https://argos-ci.com/docs/reference/puppeteer) for guides, the API reference, and more.
 
 ## Installation
 
-Install the SDK alongside the [Argos CLI](https://argos-ci.com/docs/sdks-reference/argos-command-line-interface-cli), which uploads the screenshots to Argos:
+Install the SDK alongside the [Argos CLI](https://argos-ci.com/docs/reference/argos-command-line-interface-cli), which uploads the screenshots to Argos:
 
 ```sh
 npm install --save-dev @argos-ci/puppeteer @argos-ci/cli
@@ -50,6 +50,6 @@ npx @argos-ci/cli upload ./screenshots
 
 ## Links
 
-- [Official SDK Docs](https://argos-ci.com/docs/sdks-reference/puppeteer)
+- [Official SDK Docs](https://argos-ci.com/docs/reference/puppeteer)
 - [Quickstart](https://argos-ci.com/docs/quickstart/puppeteer-quickstart)
 - [Discord](https://argos-ci.com/discord)

package/dist/index.d.mts

@@ -29,6 +29,22 @@ type ArgosScreenshotOptions = Omit<ScreenshotOptions, "encoding" | "type" | "omi
    * @default 0.5
    */
   threshold?: number;
+  /**
+   * Name, or list of names, to compare this screenshot against instead of its
+   * own name. A list is tried in order and the first name found in the baseline
+   * build wins, which lets a brand new screenshot fall back to an existing one
+   * rather than showing up as added.
+   *
+   * The screenshot's own name is not implicitly included: list it first to keep
+   * comparing against itself when it exists.
+   *
+   * @example
+   *    // Compare "home-variant-b" against itself, or against "home" if it is new.
+   *    argosScreenshot(page, "home-variant-b", {
+   *      baseName: ["home-variant-b", "home"],
+   *    })
+   */
+  baseName?: string | string[];
   /**
    * Wait for the UI to stabilize before taking the screenshot.
    * Set to `false` to disable stabilization.
@@ -46,7 +62,7 @@ type ArgosScreenshotOptions = Omit<ScreenshotOptions, "encoding" | "type" | "omi
  *
  * @example
  *    argosScreenshot(page, "my-screenshot")
- * @see https://argos-ci.com/docs/sdks-reference/puppeteer
+ * @see https://argos-ci.com/docs/reference/puppeteer
  */
 declare function argosScreenshot(
 /**

package/dist/index.mjs

@@ -2,7 +2,7 @@ import { createRequire } from "node:module";
 import { resolve } from "node:path";
 import { mkdir } from "node:fs/promises";
 import { getGlobalScript, resolveViewport } from "@argos-ci/browser";
-import { getScreenshotName, readVersionFromPackage, validateThreshold, writeMetadata } from "@argos-ci/util";
+import { getScreenshotName, normalizeBaseNames, readVersionFromPackage, validateThreshold, writeMetadata } from "@argos-ci/util";
 //#region src/index.ts
 const require = createRequire(import.meta.url);
 /**
@@ -104,16 +104,17 @@ ${reasons.map((reason) => `- ${reason}`).join("\n")}
 *
 * @example
 *    argosScreenshot(page, "my-screenshot")
-* @see https://argos-ci.com/docs/sdks-reference/puppeteer
+* @see https://argos-ci.com/docs/reference/puppeteer
 */
 async function argosScreenshot(page, name, options = {}) {
-	const { element, viewports, argosCSS: _argosCSS, ...puppeteerOptions } = options;
+	const { element, viewports, argosCSS: _argosCSS, baseName, ...puppeteerOptions } = options;
+	const baseNames = normalizeBaseNames(baseName);
 	if (!page) throw new Error("A Puppeteer `page` object is required.");
 	if (!name) throw new Error("The `name` argument is required.");
 	const [originalViewport] = await Promise.all([getViewport(page), injectArgos(page)]);
 	const afterAll = await beforeAll(page, options);
 	const fullPage = checkIsFullPage(options);
-	async function collectMetadata() {
+	async function collectMetadata(baseNames) {
 		const [colorScheme, mediaType, puppeteerVersion, argosPuppeteerVersion, { browserName, browserVersion }] = await Promise.all([
 			page.evaluate(() => window.__ARGOS__.getColorScheme()),
 			page.evaluate(() => window.__ARGOS__.getMediaType()),
@@ -145,6 +146,7 @@ async function argosScreenshot(page, name, options = {}) {
 			}
 		};
 		metadata.transient = {};
+		if (baseNames) metadata.transient.baseName = baseNames;
 		if (options?.tag) metadata.tags = Array.isArray(options.tag) ? options.tag : [options.tag];
 		if (options?.threshold !== void 0) {
 			validateThreshold(options.threshold);
@@ -152,11 +154,11 @@ async function argosScreenshot(page, name, options = {}) {
 		}
 		return metadata;
 	}
-	async function stabilizeAndScreenshot(name) {
+	async function stabilizeAndScreenshot(name, baseNames) {
 		await waitForReadiness(page, options);
 		const afterEach = await beforeEach(page, options);
 		await waitForReadiness(page, options);
-		const [screenshotPath, metadata] = await Promise.all([getScreenshotPath(name), collectMetadata()]);
+		const [screenshotPath, metadata] = await Promise.all([getScreenshotPath(name), collectMetadata(baseNames)]);
 		await writeMetadata(screenshotPath, metadata);
 		const screenshotOptions = {
 			path: screenshotPath,
@@ -177,10 +179,10 @@ async function argosScreenshot(page, name, options = {}) {
 		for (const viewport of viewports) {
 			const viewportSize = resolveViewport(viewport);
 			await setViewportSize(page, viewportSize);
-			await stabilizeAndScreenshot(getScreenshotName(name, { viewportWidth: viewportSize.width }));
+			await stabilizeAndScreenshot(getScreenshotName(name, { viewportWidth: viewportSize.width }), baseNames?.map((baseName) => getScreenshotName(baseName, { viewportWidth: viewportSize.width })) ?? null);
 		}
 		await setViewportSize(page, originalViewport);
-	} else await stabilizeAndScreenshot(name);
+	} else await stabilizeAndScreenshot(name, baseNames);
 	await afterAll();
 }
 //#endregion

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@argos-ci/puppeteer",
   "description": "Puppeteer SDK for visual testing with Argos.",
-  "version": "6.0.22",
+  "version": "6.1.0",
   "author": "Smooth Code",
   "license": "MIT",
   "repository": {
@@ -9,7 +9,7 @@
     "url": "https://github.com/argos-ci/argos-javascript.git",
     "directory": "packages/puppeteer"
   },
-  "homepage": "https://argos-ci.com/docs/sdks-reference/puppeteer",
+  "homepage": "https://argos-ci.com/docs/reference/puppeteer",
   "bugs": {
     "url": "https://github.com/argos-ci/argos-javascript/issues"
   },
@@ -43,10 +43,10 @@
   },
   "dependencies": {
     "@argos-ci/browser": "6.4.4",
-    "@argos-ci/util": "4.0.4"
+    "@argos-ci/util": "4.1.0"
   },
   "devDependencies": {
-    "@argos-ci/cli": "6.4.0",
+    "@argos-ci/cli": "6.5.0",
     "@types/jest": "^30.0.0",
     "@types/node": "catalog:",
     "expect-puppeteer": "^11.0.0",
@@ -66,5 +66,5 @@
     "check-format": "prettier --check --ignore-unknown --ignore-path=../../.gitignore --ignore-path=../../.prettierignore .",
     "lint": "eslint ."
   },
-  "gitHead": "2fda63bc0d4ac0f1a2ef6a181361e8b0c4de8349"
+  "gitHead": "a3083087b11004e0b315e2d14f1e9179cbd56da2"
 }