@argos-ci/playwright 3.2.0 → 3.4.0

package/dist/index.d.ts

@@ -20,6 +20,31 @@ type ArgosScreenshotOptions = {
      * @default true
      */
     disableHover?: boolean;
+    /**
+     * Sensitivity threshold between 0 and 1.
+     * The higher the threshold, the less sensitive the diff will be.
+     * @default 0.5
+     */
+    threshold?: number;
 } & LocatorOptions & ScreenshotOptions<LocatorScreenshotOptions> & ScreenshotOptions<PageScreenshotOptions>;
-declare function argosScreenshot(page: Page, name: string, options?: ArgosScreenshotOptions): Promise<void>;
+/**
+ * Stabilize the UI and takes a screenshot of the application under test.
+ *
+ * @example
+ *    argosScreenshot(page, "my-screenshot")
+ * @see https://argos-ci.com/docs/playwright#api-overview
+ */
+declare function argosScreenshot(
+/**
+ * Playwright `page` object.
+ */
+page: Page, 
+/**
+ * Name of the screenshot. Must be unique.
+ */
+name: string, 
+/**
+ * Options for the screenshot.
+ */
+options?: ArgosScreenshotOptions): Promise<void>;
 export { ArgosScreenshotOptions, argosScreenshot };

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { mkdir } from 'node:fs/promises';
 import { relative, resolve, dirname } from 'node:path';
 import { resolveViewport, getGlobalScript } from '@argos-ci/browser';
-import { getGitRepositoryPath, readVersionFromPackage, getScreenshotName, writeMetadata, getMetadataPath } from '@argos-ci/util';
+import { getGitRepositoryPath, readVersionFromPackage, getScreenshotName, validateThreshold, writeMetadata, getMetadataPath } from '@argos-ci/util';
 import { createRequire } from 'node:module';
 
 function getAttachmentName(name, type) {
@@ -60,6 +60,7 @@ async function getTestMetadataFromTestInfo(testInfo) {
         titlePath: testInfo.titlePath,
         retry: testInfo.retry,
         retries: testInfo.project.retries,
+        repeat: testInfo.repeatEachIndex,
         location: {
             file: repositoryPath ? relative(repositoryPath, testInfo.file) : testInfo.file,
             line: testInfo.line,
@@ -125,7 +126,40 @@ function getViewportSize(page) {
         });
     };
 }
-async function argosScreenshot(page, name, options = {}) {
+/**
+ * Get the screenshot names based on the test info.
+ */ function getScreenshotNames(name, testInfo) {
+    if (testInfo) {
+        const projectName = `${testInfo.project.name}/${name}`;
+        if (testInfo.repeatEachIndex > 0) {
+            return {
+                name: `${projectName} repeat-${testInfo.repeatEachIndex}`,
+                baseName: projectName
+            };
+        }
+        return {
+            name: projectName,
+            baseName: null
+        };
+    }
+    return {
+        name,
+        baseName: null
+    };
+}
+/**
+ * Stabilize the UI and takes a screenshot of the application under test.
+ *
+ * @example
+ *    argosScreenshot(page, "my-screenshot")
+ * @see https://argos-ci.com/docs/playwright#api-overview
+ */ async function argosScreenshot(/**
+   * Playwright `page` object.
+   */ page, /**
+   * Name of the screenshot. Must be unique.
+   */ name, /**
+   * Options for the screenshot.
+   */ options = {}) {
     const { element, has, hasText, viewports, argosCSS, ...playwrightOptions } = options;
     if (!page) {
         throw new Error("A Playwright `page` object is required.");
@@ -180,9 +214,17 @@ async function argosScreenshot(page, name, options = {}) {
     };
     const stabilizeAndScreenshot = async (name)=>{
         await page.waitForFunction(()=>window.__ARGOS__.waitForStability());
+        const names = getScreenshotNames(name, testInfo);
         const metadata = await collectMetadata(testInfo);
-        const nameInProject = testInfo?.project.name ? `${testInfo.project.name}/${name}` : name;
-        const screenshotPath = useArgosReporter && testInfo ? testInfo.outputPath("argos", `${nameInProject}.png`) : resolve(screenshotFolder, `${nameInProject}.png`);
+        metadata.transient = {};
+        if (options.threshold !== undefined) {
+            validateThreshold(options.threshold);
+            metadata.transient.threshold = options.threshold;
+        }
+        if (names.baseName) {
+            metadata.transient.baseName = `${names.baseName}.png`;
+        }
+        const screenshotPath = useArgosReporter && testInfo ? testInfo.outputPath("argos", `${names.name}.png`) : resolve(screenshotFolder, `${names.name}.png`);
         const dir = dirname(screenshotPath);
         if (dir !== screenshotFolder) {
             await mkdir(dirname(screenshotPath), {
@@ -204,11 +246,11 @@ async function argosScreenshot(page, name, options = {}) {
         ]);
         if (useArgosReporter && testInfo) {
             await Promise.all([
-                testInfo.attach(getAttachmentName(nameInProject, "metadata"), {
+                testInfo.attach(getAttachmentName(names.name, "metadata"), {
                     path: getMetadataPath(screenshotPath),
                     contentType: "application/json"
                 }),
-                testInfo.attach(getAttachmentName(nameInProject, "screenshot"), {
+                testInfo.attach(getAttachmentName(names.name, "screenshot"), {
                     path: screenshotPath,
                     contentType: "image/png"
                 })

package/dist/reporter.d.ts

@@ -1,15 +1,39 @@
 /// <reference types="node" />
 import { FullConfig, FullResult, Reporter, Suite, TestCase, TestResult } from "@playwright/test/reporter";
 import { UploadParameters } from "@argos-ci/core";
-type ArgosReporterOptions = Omit<UploadParameters, "files" | "root"> & {
+/**
+ * Dynamic build name.
+ * We require all values in order to ensure it works correctly in parallel mode.
+ */
+type DynamicBuildName<T extends readonly string[]> = {
+    /**
+     * The values that the build name can take.
+     * It is required to ensure Argos will always upload
+     * for each build name in order to work in sharding mode.
+     */
+    values: readonly [...T];
+    /**
+     * Get the build name for a test case.
+     * Returns any of the values in `values`.
+     */
+    get: (test: TestCase) => T[number];
+};
+type ArgosReporterOptions<T extends string[] = string[]> = Omit<UploadParameters, "files" | "root" | "buildName"> & {
     /**
      * Upload the report to Argos.
      * @default true
      */
     uploadToArgos?: boolean;
+    /**
+     * The name of the build in Argos.
+     * Can be a string or a function that receives the test case and returns the build name.
+     */
+    buildName?: string | DynamicBuildName<T> | null;
 };
+declare function createArgosReporterOptions<T extends string[]>(options: ArgosReporterOptions<T>): ArgosReporterOptions<T>;
 declare class ArgosReporter implements Reporter {
-    createUploadDirPromise: null | Promise<string>;
+    rootUploadDirectoryPromise: null | Promise<string>;
+    uploadDirectoryPromises: Map<string, Promise<string>>;
     config: ArgosReporterOptions;
     playwrightConfig: FullConfig;
     uploadToArgos: boolean;
@@ -35,12 +59,17 @@ declare class ArgosReporter implements Reporter {
      * Copy the trace file if found in the result.
      */
     copyTraceIfFound(result: TestResult, path: string): Promise<void>;
-    getAutomaticScreenshotName(test: TestCase, result: TestResult): string;
-    getUploadDir(): Promise<string>;
+    /**
+     * Get the root upload directory (cached).
+     */
+    /**
+     * Get the root upload directory (cached).
+     */
+    getRootUploadDirectory(): Promise<string>;
     onBegin(config: FullConfig, _suite: Suite): void;
     onTestEnd(test: TestCase, result: TestResult): Promise<void>;
     onEnd(_result: FullResult): Promise<{
         status: "failed";
     } | undefined>;
 }
-export { ArgosReporter as default, ArgosReporterOptions };
+export { ArgosReporter as default, ArgosReporterOptions, createArgosReporterOptions };

package/dist/reporter.mjs

@@ -1,7 +1,7 @@
 import chalk from 'chalk';
 import { upload, readConfig } from '@argos-ci/core';
 import { randomBytes } from 'node:crypto';
-import { mkdir, writeFile, copyFile } from 'node:fs/promises';
+import { writeFile, copyFile, readdir, mkdir } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { relative, dirname, join } from 'node:path';
 import { getGitRepositoryPath, readVersionFromPackage } from '@argos-ci/util';
@@ -84,6 +84,7 @@ async function getTestMetadataFromTestCase(testCase, testResult) {
         titlePath: testCase.titlePath(),
         retry: testResult.retry,
         retries: testCase.retries,
+        repeat: testCase.repeatEachIndex,
         location: {
             file: repositoryPath ? relative(repositoryPath, testCase.location.file) : testCase.location.file,
             line: testCase.location.line,
@@ -107,16 +108,38 @@ async function getMetadataFromTestCase(testCase, testResult) {
 const KEY = "@argos-ci/playwright";
 const debug = createDebug(KEY);
 
-async function createUploadDirectory() {
-    debug("Creating temporary directory for screenshots");
+const createDirectoryPromises = new Map();
+/**
+ * Create a directory if it doesn't exist.
+ */ async function createDirectory(pathname) {
+    let promise = createDirectoryPromises.get(pathname);
+    if (promise) {
+        return promise;
+    }
+    promise = mkdir(pathname, {
+        recursive: true
+    }).then(()=>{});
+    createDirectoryPromises.set(pathname, promise);
+    return promise;
+}
+/**
+ * Create temporary directory.
+ */ async function createTemporaryDirectory() {
+    debug("Creating temporary directory");
     const osTmpDirectory = tmpdir();
     const path = join(osTmpDirectory, "argos." + randomBytes(16).toString("hex"));
-    await mkdir(path, {
-        recursive: true
-    });
+    await createDirectory(path);
     debug(`Temporary directory created: ${path}`);
     return path;
 }
+/**
+ * Check if the build name is dynamic.
+ */ function checkIsDynamicBuildName(buildName) {
+    return Boolean(typeof buildName === "object" && buildName);
+}
+function createArgosReporterOptions(options) {
+    return options;
+}
 async function getParallelFromConfig(config) {
     if (!config.shard) return null;
     if (config.shard.total === 1) return null;
@@ -130,26 +153,30 @@ async function getParallelFromConfig(config) {
         index: config.shard.current
     };
 }
+/**
+ * Get the automatic screenshot name.
+ */ function getAutomaticScreenshotName(test, result) {
+    let name = test.titlePath().join(" ");
+    name += result.retry > 0 ? ` #${result.retry + 1}` : "";
+    name += result.status === "failed" || result.status === "timedOut" ? " (failed)" : "";
+    return name;
+}
 class ArgosReporter {
-    createUploadDirPromise;
+    rootUploadDirectoryPromise;
+    uploadDirectoryPromises;
     config;
     playwrightConfig;
     uploadToArgos;
     constructor(config){
         this.config = config;
         this.uploadToArgos = config.uploadToArgos ?? true;
-        this.createUploadDirPromise = null;
+        this.rootUploadDirectoryPromise = null;
+        this.uploadDirectoryPromises = new Map();
     }
     /**
    * Write a file to the temporary directory.
    */ async writeFile(path, body) {
-        const uploadDir = await this.getUploadDir();
-        const dir = dirname(path);
-        if (dir !== uploadDir) {
-            await mkdir(dir, {
-                recursive: true
-            });
-        }
+        await createDirectory(dirname(path));
         debug(`Writing file to ${path}`);
         await writeFile(path, body);
         debug(`File written to ${path}`);
@@ -157,13 +184,7 @@ class ArgosReporter {
     /**
    * Copy a file to the temporary directory.
    */ async copyFile(from, to) {
-        const uploadDir = await this.getUploadDir();
-        const dir = dirname(to);
-        if (dir !== uploadDir) {
-            await mkdir(dir, {
-                recursive: true
-            });
-        }
+        await createDirectory(dirname(to));
         debug(`Copying file from ${from} to ${to}`);
         await copyFile(from, to);
         debug(`File copied from ${from} to ${to}`);
@@ -176,24 +197,25 @@ class ArgosReporter {
             await this.copyFile(trace.path, path + ".pw-trace.zip");
         }
     }
-    getAutomaticScreenshotName(test, result) {
-        let name = test.titlePath().join(" ");
-        name += result.retry > 0 ? ` #${result.retry + 1}` : "";
-        name += result.status === "failed" || result.status === "timedOut" ? " (failed)" : "";
-        return name;
-    }
-    getUploadDir() {
-        if (!this.createUploadDirPromise) {
-            this.createUploadDirPromise = createUploadDirectory();
+    /**
+   * Get the root upload directory (cached).
+   */ getRootUploadDirectory() {
+        if (!this.rootUploadDirectoryPromise) {
+            this.rootUploadDirectoryPromise = createTemporaryDirectory();
         }
-        return this.createUploadDirPromise;
+        return this.rootUploadDirectoryPromise;
     }
     onBegin(config, _suite) {
         debug("ArgosReporter:onBegin");
         this.playwrightConfig = config;
     }
     async onTestEnd(test, result) {
-        const uploadDir = await this.getUploadDir();
+        const buildName = checkIsDynamicBuildName(this.config.buildName) ? this.config.buildName.get(test) : this.config.buildName;
+        if (buildName === "") {
+            throw new Error('Argos "buildName" cannot be an empty string.');
+        }
+        const rootUploadDir = await this.getRootUploadDirectory();
+        const uploadDir = buildName ? join(rootUploadDir, buildName) : rootUploadDir;
         debug("ArgosReporter:onTestEnd");
         await Promise.all(result.attachments.map(async (attachment)=>{
             if (checkIsArgosScreenshot(attachment) || checkIsArgosScreenshotMetadata(attachment)) {
@@ -207,7 +229,7 @@ class ArgosReporter {
             // Error screenshots are sent to Argos
             if (checkIsAutomaticScreenshot(attachment)) {
                 const metadata = await getMetadataFromTestCase(test, result);
-                const name = this.getAutomaticScreenshotName(test, result);
+                const name = getAutomaticScreenshotName(test, result);
                 const path = join(uploadDir, `${name}.png`);
                 await Promise.all([
                     this.writeFile(path + ".argos.json", JSON.stringify(metadata)),
@@ -220,10 +242,10 @@ class ArgosReporter {
     }
     async onEnd(_result) {
         debug("ArgosReporter:onEnd");
-        const uploadDir = await this.getUploadDir();
+        const rootUploadDir = await this.getRootUploadDirectory();
         if (!this.uploadToArgos) {
             debug("Not uploading to Argos because uploadToArgos is false.");
-            debug(`Upload directory: ${uploadDir}`);
+            debug(`Upload directory: ${rootUploadDir}`);
             return;
         }
         debug("Getting parallel from config");
@@ -233,17 +255,46 @@ class ArgosReporter {
         } else {
             debug("Non-parallel mode");
         }
+        const buildNameConfig = this.config.buildName;
+        const uploadOptions = {
+            files: [
+                "**/*.png"
+            ],
+            parallel: parallel ?? undefined,
+            ...this.config
+        };
         try {
-            debug("Uploading to Argos");
-            const res = await upload({
-                files: [
-                    "**/*.png"
-                ],
-                root: uploadDir,
-                parallel: parallel ?? undefined,
-                ...this.config
-            });
-            console.log(chalk.green(`✅ Argos build created: ${res.build.url}`));
+            if (checkIsDynamicBuildName(buildNameConfig)) {
+                debug(`Dynamic build names, uploading to Argos for each build name: ${buildNameConfig.values.join()}`);
+                const directories = await readdir(rootUploadDir);
+                // Check if the buildName.values are consistent with the directories created
+                if (directories.some((dir)=>!buildNameConfig.values.includes(dir))) {
+                    throw new Error(`The \`buildName.values\` (${buildNameConfig.values.join(", ")}) are inconsistent with the \`buildName.get\` returns values (${directories.join(", ")}). Please fix the configuration.`);
+                }
+                // In non-parallel mode, we iterate over the directories to avoid creating useless builds
+                const iteratesOnBuildNames = parallel ? buildNameConfig.values : directories;
+                // Iterate over each build name and upload the screenshots
+                for (const buildName of iteratesOnBuildNames){
+                    const uploadDir = join(rootUploadDir, buildName);
+                    await createDirectory(uploadDir);
+                    debug(`Uploading to Argos for build: ${buildName}`);
+                    const res = await upload({
+                        ...uploadOptions,
+                        root: uploadDir,
+                        buildName
+                    });
+                    console.log(chalk.green(`✅ Argos "${buildName}" build created: ${res.build.url}`));
+                }
+            } else {
+                debug("Uploading to Argos");
+                const uploadDir = buildNameConfig ? join(rootUploadDir, buildNameConfig) : rootUploadDir;
+                const res = await upload({
+                    ...uploadOptions,
+                    root: uploadDir,
+                    buildName: buildNameConfig ?? undefined
+                });
+                console.log(chalk.green(`✅ Argos build created: ${res.build.url}`));
+            }
         } catch (error) {
             console.error(error);
             return {
@@ -254,4 +305,4 @@ class ArgosReporter {
     }
 }
 
-export { ArgosReporter as default };
+export { createArgosReporterOptions, ArgosReporter as default };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@argos-ci/playwright",
   "description": "Visual testing solution to avoid visual regression. Playwright commands and utilities for Argos visual testing.",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "author": "Smooth Code",
   "license": "MIT",
   "repository": {
@@ -43,13 +43,13 @@
   },
   "dependencies": {
     "@argos-ci/browser": "2.1.2",
-    "@argos-ci/core": "2.3.0",
-    "@argos-ci/util": "2.0.0",
+    "@argos-ci/core": "2.4.0",
+    "@argos-ci/util": "2.1.0",
     "chalk": "^5.3.0",
     "debug": "^4.3.4"
   },
   "devDependencies": {
-    "@argos-ci/cli": "2.2.0",
+    "@argos-ci/cli": "2.3.0",
     "@argos-ci/playwright": "workspace:.",
     "@playwright/test": "^1.43.0",
     "@types/debug": "^4.1.12",
@@ -61,5 +61,5 @@
     "test": "pnpm exec -- playwright test",
     "e2e": "UPLOAD_TO_ARGOS=true pnpm run test"
   },
-  "gitHead": "0c328bfcd6475ad625c0335cab11e912e856173c"
+  "gitHead": "aca82cf842a6d8310611a8594c581794df85cbd8"
 }