feat: support preview URL

Preview URL allow to set a custom URL to override the default URL and allow to navigate easily to a live environment deployed remotely instead of having a "localhost" URL.
argos-ci · Jan 18, 2025 · cb541de · cb541de
1 parent 7ae1fa3
commit cb541de
Show file tree

Hide file tree

Showing 9 changed files with 100 additions and 4 deletions.
diff --git a/packages/api-client/src/schema.ts b/packages/api-client/src/schema.ts
@@ -98,7 +98,7 @@ export interface components {
             /** @description The build number */
             number: number;
             /** @description The status of the build */
-            status: ("accepted" | "rejected") | ("stable" | "diffDetected") | ("expired" | "pending" | "progress" | "error" | "aborted");
+            status: ("accepted" | "rejected") | ("no-changes" | "changes-detected") | ("expired" | "pending" | "progress" | "error" | "aborted");
             /**
              * Format: uri
              * @description The URL of the build
@@ -142,6 +142,7 @@ export interface components {
             baseName?: string | null;
             metadata?: {
                 url?: string;
+                previewUrl?: string;
                 viewport?: {
                     width: number;
                     height: number;

diff --git a/packages/core/src/config.ts b/packages/core/src/config.ts
@@ -162,6 +162,12 @@ const schema = {
     default: null,
     nullable: true,
   },
+  previewBaseUrl: {
+    env: "ARGOS_PREVIEW_BASE_URL",
+    format: String,
+    default: null,
+    nullable: true,
+  },
 };
 
 export interface Config {
@@ -187,6 +193,7 @@ export interface Config {
   mode: "ci" | "monitoring" | null;
   ciProvider: string | null;
   threshold: number | null;
+  previewBaseUrl: string | null;
 }
 
 const createConfig = () => {
@@ -229,6 +236,7 @@ export async function readConfig(options: Partial<Config> = {}) {
     parallelIndex: options.parallelIndex ?? config.get("parallelIndex") ?? null,
     mode: options.mode || config.get("mode") || null,
     ciProvider: ciEnv?.key || null,
+    previewBaseUrl: config.get("previewBaseUrl") || null,
   });
 
   config.validate();

diff --git a/packages/core/src/upload.ts b/packages/core/src/upload.ts
@@ -98,6 +98,15 @@ export interface UploadParameters {
    * Build metadata.
    */
   metadata?: BuildMetadata;
+  /**
+   * Preview URL configuration.
+   * Accepts a base URL or a function that receives the URL and returns the preview URL.
+   */
+  previewUrl?:
+    | {
+        baseUrl: string;
+      }
+    | ((url: string) => string);
 }
 
 async function getConfigFromOptions({
@@ -143,6 +152,23 @@ async function uploadFilesToS3(
   }
 }
 
+/**
+ * Format the preview URL.
+ */
+function formatPreviewUrl(
+  url: string,
+  formatter: NonNullable<UploadParameters["previewUrl"]>,
+) {
+  if (typeof formatter === "function") {
+    return formatter(url);
+  }
+  const urlObj = new URL(url);
+  return new URL(
+    urlObj.pathname + urlObj.search + urlObj.hash,
+    formatter.baseUrl,
+  ).href;
+}
+
 /**
  * Upload screenshots to Argos.
  */
@@ -154,6 +180,10 @@ export async function upload(params: UploadParameters) {
     getConfigFromOptions(params),
     getArgosCoreSDKIdentifier(),
   ]);
+  const previewUrlFormatter: UploadParameters["previewUrl"] =
+    params.previewUrl ??
+    (config.previewBaseUrl ? { baseUrl: config.previewBaseUrl } : undefined);
+
   const files = params.files ?? ["**/*.{png,jpg,jpeg}"];
   debug("Using config and files", config, files);
 
@@ -191,6 +221,13 @@ export async function upload(params: UploadParameters) {
 
       if (metadata) {
         delete metadata.transient;
+
+        if (metadata.url && previewUrlFormatter) {
+          metadata.previewUrl = formatPreviewUrl(
+            metadata.url,
+            previewUrlFormatter,
+          );
+        }
       }
 
       return {

diff --git a/packages/cypress/docs/index.mdx b/packages/cypress/docs/index.mdx
@@ -21,6 +21,30 @@ While Cypress inherently provides screenshot functionality, the Argos Cypress in
 
 Please refer to our [Quickstart guide](/quickstart/cypress) to get started with Argos and Cypress.
 
+## Set a Preview URL
+
+Argos displays the URL of the page when a screenshot is taken, helping you understand the screenshot’s context in the Argos UI. If you run tests locally and deploy your pull requests (PRs) to a preview URL, you can link the two by setting the `ARGOS_PREVIEW_URL` environment variable or configuring the `previewUrl` option in the Cypress configuration.
+
+### Example Configuration
+
+```ts title="cypress.config.js"
+const { defineConfig } = require("cypress");
+const { registerArgosTask } = require("@argos-ci/cypress/task");
+
+module.exports = defineConfig({
+  e2e: {
+    async setupNodeEvents(on, config) {
+      registerArgosTask(on, config, {
+        uploadToArgos: !!process.env.CI,
+        previewUrl: {
+          baseUrl: "https://my-site.com", // Use a dynamic value here for different environments if needed.
+        },
+      });
+    },
+  },
+});
+```
+
 ## API Overview
 
 ### cy.argosScreenshot([name][, options])

diff --git a/packages/cypress/src/task.ts b/packages/cypress/src/task.ts
@@ -6,7 +6,7 @@ import { rename } from "node:fs/promises";
 
 export type RegisterArgosTaskOptions = Omit<
   UploadParameters,
-  "files" | "root"
+  "files" | "root" | "metadata"
 > & {
   /**
    * Upload the report to Argos.

diff --git a/packages/playwright/docs/index.mdx b/packages/playwright/docs/index.mdx
@@ -198,6 +198,30 @@ export default defineConfig({
 });
 ```
 
+## Set a Preview URL
+
+Argos displays the URL of the page when a screenshot is taken, helping you understand the screenshot’s context in the Argos UI. If you run tests locally and deploy your pull requests (PRs) to a preview URL, you can link the two by setting the `ARGOS_PREVIEW_URL` environment variable or configuring the `previewUrl` option in the Argos reporter.
+
+### Example Configuration
+
+```ts title="playwright.config.ts"
+import { defineConfig } from "@playwright/test";
+import { createArgosReporterOptions } from "@argos-ci/playwright/reporter";
+
+export default defineConfig({
+  reporter: [
+    [
+      "@argos-ci/playwright/reporter",
+      createArgosReporterOptions({
+        previewUrl: {
+          baseUrl: "https://my-site.com", // Use a dynamic value here for different environments if needed.
+        },
+      }),
+    ],
+  ],
+});
+```
+
 ## API Overview
 
 ### argosScreenshot(page, name[, options])

diff --git a/packages/playwright/src/reporter.ts b/packages/playwright/src/reporter.ts
@@ -71,7 +71,7 @@ type DynamicBuildName<T extends readonly string[]> = {
 
 export type ArgosReporterOptions<T extends string[] = string[]> = Omit<
   UploadParameters,
-  "files" | "root" | "buildName"
+  "files" | "root" | "buildName" | "metadata"
 > & {
   /**
    * Upload the report to Argos.

diff --git a/packages/playwright/src/screenshot.ts b/packages/playwright/src/screenshot.ts
@@ -283,9 +283,10 @@ export async function argosScreenshot(
     }
     const browserName = browser.browserType().name();
     const browserVersion = browser.version();
+    const url = page.url();
 
     const metadata: ScreenshotMetadata = {
-      url: page.url(),
+      url,
       viewport: viewportSize,
       colorScheme,
       mediaType,

diff --git a/packages/util/src/metadata.ts b/packages/util/src/metadata.ts
@@ -1,5 +1,6 @@
 export type ScreenshotMetadata = {
   url?: string;
+  previewUrl?: string;
   viewport?: {
     width: number;
     height: number;