@argos-ci/core

import { ArgosAPISchema } from '@argos-ci/api-client'; import { ScreenshotMetadata } from '@argos-ci/util'; 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; /** * Whether the environment is a merge queue. */ mergeQueue?: boolean; /** * 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>; interface components { schemas: { /** @description SHA1 hash */ Sha1Hash: string; /** @description SHA256 hash */ Sha256Hash: string; /** * @description A unique identifier for the build * @example 12345 */ BuildId: string; /** @description Screenshot input */ ScreenshotInput: { key: string; name: string; baseName?: string | null; parentName?: string | null; metadata?: { /** * @description Ignored. Can be set to get completions, validations and documentation in some editors. * @example https://api.argos-ci.com/v2/screenshot-metadata.json */ $schema?: string; /** @description The URL of the page that was screenshotted */ url?: string | null; /** @description An URL to an accessible preview of the screenshot */ previewUrl?: string | null; viewport?: { /** @description The width of the viewport */ width: number; /** @description The height of the viewport */ height: number; } | null; /** @description The color scheme when the screenshot was taken */ colorScheme?: ("light" | "dark") | null; /** @description The media type when the screenshot was taken */ mediaType?: ("screen" | "print") | null; test?: ({ /** @description The unique identifier of the test */ id?: string | null; /** @description The title of the test */ title: string; /** @description The path of titles leading to the test */ titlePath: string[]; /** @description The number of retries for the test */ retries?: number | null; /** @description The current retry count */ retry?: number | null; /** @description The repeat count for the test */ repeat?: number | null; /** @description The location of the test in the source code */ location?: { /** @description The located file */ file: string; /** @description The line number in the file */ line: number; /** @description The column number in the file */ column: number; }; /** @description Annotations associated to the test */ annotations?: { /** @description The type of annotation */ type: string; /** @description The description of the annotation */ description?: string; /** @description The location of the annotation in the source code */ location?: { /** @description The located file */ file: string; /** @description The line number in the file */ line: number; /** @description The column number in the file */ column: number; }; }[]; } | null) | null; browser?: { /** @description The name of the browser */ name: string; /** @description The version of the browser */ version: string; } | null; /** @description The automation library that generated the screenshot */ automationLibrary: { /** @description The name of the automation library */ name: string; /** @description The version of the automation library */ version: string; }; /** @description The Argos SDK that generated the screenshot */ sdk: { /** @description The name of the Argos SDK */ name: string; /** @description The version of the Argos SDK */ version: string; }; } | null; pwTraceKey?: string | null; threshold?: number | null; /** @default image/png */ contentType: string; }; /** @description Build metadata */ BuildMetadata: { /** @description Test suite report */ testReport?: { /** * @description Status of the test suite * @enum {string} */ status: "passed" | "failed" | "timedout" | "interrupted"; stats?: { /** @description Date when the test suite started */ startTime?: string; /** @description Duration of the test suite in milliseconds */ duration?: number; }; }; }; /** @description Build */ Build: { id: components["schemas"]["BuildId"]; /** @description The build number */ number: number; /** @description The status of the build */ status: ("accepted" | "rejected") | ("no-changes" | "changes-detected") | ("expired" | "pending" | "progress" | "error" | "aborted"); /** @description The conclusion of the build */ conclusion: ("no-changes" | "changes-detected") | null; /** @description Stats of the diffs present in the build */ stats: { /** @description Added snapshots */ added: number; /** @description Removed snapshots */ removed: number; /** @description Unchanged snapshots */ unchanged: number; /** @description Changed snapshots */ changed: number; /** @description Ignored snapshots */ ignored: number; /** @description Failure screenshots */ failure: number; /** @description Retry failure screenshots */ retryFailure: number; /** @description Total number of snapshots */ total: number; } | null; metadata: { /** @description Test suite report */ testReport?: { /** * @description Status of the test suite * @enum {string} */ status: "passed" | "failed" | "timedout" | "interrupted"; stats?: { /** @description Date when the test suite started */ startTime?: string; /** @description Duration of the test suite in milliseconds */ duration?: number; }; }; } | null; /** * Format: uri * @description The URL of the build */ url: string; /** @description The notification payload for the build */ notification: { description: string; context: string; github: { /** @enum {string} */ state: "pending" | "success" | "error" | "failure"; }; gitlab: { /** @enum {string} */ state: "pending" | "running" | "success" | "failed" | "canceled"; }; } | null; }; /** @description Error response */ Error: { error: string; details?: { message: string; }[]; }; /** @description Page information */ PageInfo: { /** @description Total number of items */ total: number; /** @description Current page number */ page: number; /** @description Number of items per page */ perPage: number; }; /** @description Snapshot diff */ SnapshotDiff: { /** @description Unique identifier of the snapshot diff */ id: string; /** @description Name of the snapshot diff */ name: string; /** * @description Status of the snapshot diff * @enum {string} */ status: "pending" | "removed" | "failure" | "added" | "changed" | "unchanged" | "retryFailure" | "ignored"; /** @description Similarity score between snapshots */ score: number | null; /** @description Grouping key for the snapshot diff */ group: string | null; /** @description Parent name of the snapshot (usually the story id) */ parentName: string | null; /** @description URL of the diff image */ url: string | null; base: { /** @description Unique identifier of the snapshot */ id: string; /** @description Name of the snapshot */ name: string; metadata: { /** * @description Ignored. Can be set to get completions, validations and documentation in some editors. * @example https://api.argos-ci.com/v2/screenshot-metadata.json */ $schema?: string; /** @description The URL of the page that was screenshotted */ url?: string | null; /** @description An URL to an accessible preview of the screenshot */ previewUrl?: string | null; viewport?: { /** @description The width of the viewport */ width: number; /** @description The height of the viewport */ height: number; } | null; /** @description The color scheme when the screenshot was taken */ colorScheme?: ("light" | "dark") | null; /** @description The media type when the screenshot was taken */ mediaType?: ("screen" | "print") | null; test?: ({ /** @description The unique identifier of the test */ id?: string | null; /** @description The title of the test */ title: string; /** @description The path of titles leading to the test */ titlePath: string[]; /** @description The number of retries for the test */ retries?: number | null; /** @description The current retry count */ retry?: number | null; /** @description The repeat count for the test */ repeat?: number | null; /** @description The location of the test in the source code */ location?: { /** @description The located file */ file: string; /** @description The line number in the file */ line: number; /** @description The column number in the file */ column: number; }; /** @description Annotations associated to the test */ annotations?: { /** @description The type of annotation */ type: string; /** @description The description of the annotation */ description?: string; /** @description The location of the annotation in the source code */ location?: { /** @description The located file */ file: string; /** @description The line number in the file */ line: number; /** @description The column number in the file */ column: number; }; }[]; } | null) | null; browser?: { /** @description The name of the browser */ name: string; /** @description The version of the browser */ version: string; } | null; /** @description The automation library that generated the screenshot */ automationLibrary: { /** @description The name of the automation library */ name: string; /** @description The version of the automation library */ version: string; }; /** @description The Argos SDK that generated the screenshot */ sdk: { /** @description The name of the Argos SDK */ name: string; /** @description The version of the Argos SDK */ version: string; }; } | null; /** @description Width of the screenshot in pixels */ width: number | null; /** @description Height of the screenshot in pixels */ height: number | null; /** * Format: uri * @description Public URL of the snapshot */ url: string; /** @description Content type of the snapshot file */ contentType: string; } | null; head: { /** @description Unique identifier of the snapshot */ id: string; /** @description Name of the snapshot */ name: string; metadata: { /** * @description Ignored. Can be set to get completions, validations and documentation in some editors. * @example https://api.argos-ci.com/v2/screenshot-metadata.json */ $schema?: string; /** @description The URL of the page that was screenshotted */ url?: string | null; /** @description An URL to an accessible preview of the screenshot */ previewUrl?: string | null; viewport?: { /** @description The width of the viewport */ width: number; /** @description The height of the viewport */ height: number; } | null; /** @description The color scheme when the screenshot was taken */ colorScheme?: ("light" | "dark") | null; /** @description The media type when the screenshot was taken */ mediaType?: ("screen" | "print") | null; test?: ({ /** @description The unique identifier of the test */ id?: string | null; /** @description The title of the test */ title: string; /** @description The path of titles leading to the test */ titlePath: string[]; /** @description The number of retries for the test */ retries?: number | null; /** @description The current retry count */ retry?: number | null; /** @description The repeat count for the test */ repeat?: number | null; /** @description The location of the test in the source code */ location?: { /** @description The located file */ file: string; /** @description The line number in the file */ line: number; /** @description The column number in the file */ column: number; }; /** @description Annotations associated to the test */ annotations?: { /** @description The type of annotation */ type: string; /** @description The description of the annotation */ description?: string; /** @description The location of the annotation in the source code */ location?: { /** @description The located file */ file: string; /** @description The line number in the file */ line: number; /** @description The column number in the file */ column: number; }; }[]; } | null) | null; browser?: { /** @description The name of the browser */ name: string; /** @description The version of the browser */ version: string; } | null; /** @description The automation library that generated the screenshot */ automationLibrary: { /** @description The name of the automation library */ name: string; /** @description The version of the automation library */ version: string; }; /** @description The Argos SDK that generated the screenshot */ sdk: { /** @description The name of the Argos SDK */ name: string; /** @description The version of the Argos SDK */ version: string; }; } | null; /** @description Width of the screenshot in pixels */ width: number | null; /** @description Height of the screenshot in pixels */ height: number | null; /** * Format: uri * @description Public URL of the snapshot */ url: string; /** @description Content type of the snapshot file */ contentType: string; } | null; }; /** @description Project */ Project: { id: string; defaultBaseBranch: string; hasRemoteContentAccess: boolean; }; }; responses: never; parameters: never; requestBodies: never; headers: never; pathItems: never; } type FinalizeParameters = { parallel?: { nonce: string; }; }; /** * Finalize pending builds. */ declare function finalize(params: FinalizeParameters): Promise<{ builds: components["schemas"]["Build"][]; }>; 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; } 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[]; }>; 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"]; }>; export { type Config, type FinalizeParameters, type UploadParameters, finalize, getConfigFromOptions, readConfig, skip, upload };