@argos-ci/core/dist/index.d.mts

Node.js SDK for visual testing with Argos.

import { ArgosAPISchema } from "@argos-ci/api-client";
import { ScreenshotMetadata } from "@argos-ci/util";

//#region src/config.d.ts
interface Config {
  /**
   * Base URL of the Argos API.
   * Use this to target a self-hosted installation.
   * @default "https://api.argos-ci.com/v2/"
   */
  apiBaseUrl: string;
  /**
   * Git commit SHA.
   */
  commit: string;
  /**
   * Git branch name of the build.
   * @example "main", "develop", "release/1.0"
   */
  branch: string;
  /**
   * Argos repository access token.
   */
  token: string | null;
  /**
   * Custom build name.
   * Useful for multi-build setups on the same commit.
   */
  buildName: string | null;
  /**
   * Whether this build is split across multiple parallel jobs.
   * @default false
   */
  parallel: boolean;
  /**
   * Unique identifier shared by all parallel jobs.
   */
  parallelNonce: string | null;
  /**
   * Index of the current parallel job.
   * Must be between 1 and `parallelTotal`, or null if not set.
   */
  parallelIndex: number | null;
  /**
   * Total number of parallel jobs.
   * Use -1 if unknown, or null if not set.
   */
  parallelTotal: number | null;
  /**
   * Git branch used as the baseline for screenshot comparison.
   */
  referenceBranch: string | null;
  /**
   * Git commit SHA used as the baseline for screenshot comparison.
   */
  referenceCommit: string | null;
  /**
   * Repository slug of the source repository.
   * Example: "my-org/my-repo" or "my-user/my-repo".
   * If from a fork, this refers to the fork repository.
   */
  repository: string | null;
  /**
   * Repository slug of the original (base) repository.
   * Example: "my-org/my-repo" or "my-user/my-repo".
   * If from a fork, this refers to the base repository.
   */
  originalRepository: string | null;
  /**
   * CI job identifier (if provided by the CI environment).
   */
  jobId: string | null;
  /**
   * CI run identifier (if provided by the CI environment).
   */
  runId: string | null;
  /**
   * CI run attempt number (if provided by the CI environment).
   */
  runAttempt: number | null;
  /**
   * Pull request number associated with the build.
   */
  prNumber: number | null;
  /**
   * Pull request head commit SHA (if available).
   */
  prHeadCommit: string | null;
  /**
   * Pull request base branch (if available).
   */
  prBaseBranch: string | null;
  /**
   * Build mode to use.
   * - "ci": Review visual changes introduced by a feature branch and prevent regressions.
   * - "monitoring": Track visual changes outside the standard CI flow, either on a schedule or before a release.
   * @see https://argos-ci.com/docs/build-modes
   */
  mode: "ci" | "monitoring" | null;
  /**
   * Name of the detected CI provider (if available).
   * @example "github-actions", "gitlab-ci", "circleci"
   */
  ciProvider: string | null;
  /**
   * Diff sensitivity threshold between 0 and 1.
   * Higher values make Argos less sensitive to differences.
   */
  threshold: number | null;
  /**
   * Base URL to use for preview links.
   * @example "https://my-preview.example.com"
   */
  previewBaseUrl: string | null;
  /**
   * Skip this build.
   * No screenshots are uploaded, and the commit status is marked as success.
   */
  skipped?: boolean;
  /**
   * Pull request numbers aggregated by the merge queue build.
   */
  mergeQueuePrNumbers?: number[] | null;
  /**
   * Whether this build contains only a subset of screenshots.
   * This is useful when a build is created from an incomplete test suite where some tests are skipped.
   */
  subset?: boolean;
}
declare function readConfig(options?: Partial<Config>): Promise<Config>;
declare function getConfigFromOptions({
  parallel,
  ...options
}: Omit<Partial<Config>, "parallel"> & {
  parallel?: {
    /** Unique build ID for this parallel build */nonce: string; /** The number of parallel nodes being ran */
    total: number; /** The index of the parallel node */
    index?: number;
  } | false | undefined;
}): Promise<Config>;
//#endregion
//#region src/deploy.d.ts
interface DeployParameters {
  /**
   * Directory containing the static files to deploy.
   */
  root: string;
  /**
   * Argos repository access token.
   */
  token?: string;
  /**
   * Base URL of the Argos API.
   * @default "https://api.argos-ci.com/v2/"
   */
  apiBaseUrl?: string;
  /**
   * Git commit SHA of the deployment.
   */
  commit?: string;
  /**
   * Git branch name of the deployment.
   */
  branch?: string;
  /**
   * Pull request number associated with the deployment.
   */
  prNumber?: number;
  /**
   * Deployment environment.
   */
  environment?: "preview" | "production";
}
/**
 * Deploy a static site (e.g. Storybook) to Argos.
 */
declare function deploy(params: DeployParameters): Promise<{
  id: string;
  status: "pending" | "ready" | "error";
  environment: "preview" | "production";
  branch: string;
  commitSha: string;
  url: string;
  createdAt: string;
}>;
//#endregion
//#region src/finalize.d.ts
type FinalizeParameters = {
  parallel?: {
    nonce: string;
  };
};
/**
 * Finalize pending builds.
 */
declare function finalize(params: FinalizeParameters): Promise<{
  builds: {
    id: string;
    number: unknown;
    head: {
      sha: string;
      branch: string;
    };
    base: {
      sha: string;
      branch: string;
    } | null;
    status: ("accepted" | "rejected") | ("no-changes" | "changes-detected") | ("expired" | "pending" | "progress" | "error" | "aborted");
    conclusion: ("no-changes" | "changes-detected") | null;
    stats: {
      added: number;
      removed: number;
      unchanged: number;
      changed: number;
      ignored: number;
      failure: number;
      retryFailure: number;
      total: number;
    } | null;
    metadata: {
      testReport?: {
        status: "passed" | "failed" | "timedout" | "interrupted";
        stats?: {
          startTime?: string | undefined;
          duration?: number | undefined;
        } | undefined;
      } | undefined;
    } | null;
    url: string;
    notification: {
      description: string;
      context: string;
      github: {
        state: "pending" | "success" | "error" | "failure";
      };
      gitlab: {
        state: "pending" | "running" | "success" | "failed" | "canceled";
      };
    } | null;
  }[];
}>;
//#endregion
//#region src/upload.d.ts
type BuildMetadata = ArgosAPISchema.components["schemas"]["BuildMetadata"];
interface UploadParameters {
  /**
   * Globs that match image file paths to upload.
   */
  files?: string[];
  /**
   * Root directory used to resolve image paths.
   * @default process.cwd()
   */
  root?: string;
  /**
   * Globs that match image file paths to exclude from upload.
   * @default ["**\/*.{png,jpg,jpeg}"]
   */
  ignore?: string[];
  /**
   * Base URL of the Argos API.
   * @default "https://api.argos-ci.com/v2/"
   */
  apiBaseUrl?: string;
  /**
   * Git commit SHA of the build.
   */
  commit?: string;
  /**
   * Git branch name of the build.
   */
  branch?: string;
  /**
   * Argos repository access token.
   */
  token?: string;
  /**
   * Pull request number associated with the build.
   */
  prNumber?: number;
  /**
   * Custom build name. Useful when triggering multiple Argos builds
   * for the same commit.
   */
  buildName?: string;
  /**
   * Build mode to use.
   * - "ci": Review the visual changes introduced by a feature branch and prevent regressions.
   * - "monitoring": Track visual changes outside the standard CI flow, either on a schedule or before a release.
   * @see https://argos-ci.com/docs/build-modes
   * @default "ci"
   */
  mode?: "ci" | "monitoring";
  /**
   * Parallel test suite configuration.
   * @default false
   */
  parallel?: {
    /** Unique build identifier shared across parallel jobs. */nonce: string; /** Total number of parallel jobs, set to -1 to finalize manually. */
    total: number; /** Index of the current job (must start from 1). */
    index?: number;
  } | false;
  /**
   * Branch used as the baseline for screenshot comparison.
   */
  referenceBranch?: string;
  /**
   * Commit SHA used as the baseline for screenshot comparison.
   */
  referenceCommit?: string;
  /**
   * Diff sensitivity threshold between 0 and 1.
   * Higher values make Argos less sensitive to differences.
   * @default 0.5
   */
  threshold?: number;
  /**
   * Additional build metadata.
   */
  metadata?: BuildMetadata;
  /**
   * Preview URL configuration.
   * Can be a fixed base URL or a function to transform URLs dynamically.
   */
  previewUrl?: {
    baseUrl: string;
  } | ((url: string) => string);
  /**
   * Whether this build contains only a subset of screenshots.
   * This is useful when a build is created from an incomplete test suite where some tests are skipped.
   * @default false
   */
  subset?: boolean;
  /**
   * Pull request numbers aggregated by the merge queue build.
   * Providing this enables merge queue mode for the build.
   */
  mergeQueuePrNumbers?: number[];
}
interface Screenshot {
  hash: string;
  optimizedPath: string;
  metadata: ScreenshotMetadata | null;
  threshold: number | null;
  baseName: string | null;
  pwTrace: {
    path: string;
    hash: string;
  } | null;
  name: string;
  path: string;
}
/**
 * Upload screenshots to Argos.
 */
declare function upload(params: UploadParameters): Promise<{
  build: ArgosAPISchema.components["schemas"]["Build"];
  screenshots: Screenshot[];
}>;
//#endregion
//#region src/skip.d.ts
type SkipParameters = Pick<UploadParameters, "apiBaseUrl" | "commit" | "branch" | "token" | "prNumber" | "buildName" | "metadata">;
/**
 * Mark a build as skipped.
 */
declare function skip(params: SkipParameters): Promise<{
  build: ArgosAPISchema.components["schemas"]["Build"];
}>;
//#endregion
export { Config, DeployParameters, FinalizeParameters, UploadParameters, deploy, finalize, getConfigFromOptions, readConfig, skip, upload };