Backend Functions

Create a 400 error for invalid client input.

badRequest = (message: string, details?: unknown) => new HttpError(400, message, details)

Create a 409 error for duplicate or conflicting state.

conflict = (message: string) => new HttpError(409, message)

Create a 403 error for authenticated users without access.

forbidden = (message = 'Forbidden') => new HttpError(403, message)

A thin error type carrying an HTTP status code. Thrown anywhere in a route and translated into a JSON `{ error }` body by the global error handler.

class HttpError extends Error

Create a 404 error when a requested record does not exist.

notFound = (message = 'Not found') => new HttpError(404, message)

Create a 401 error for missing or invalid authentication.

unauthorized = (message = 'Unauthorized') => new HttpError(401, message)

Shared Winston logger used by the API, worker and supporting services.

logger = winston.createLogger(

Emit a Socket.io event to everyone watching a specific test run.

function emitToTestRun(testRunId: string, event: string, data: unknown): void

Return the Socket.io server instance after it has been initialised.

function getIO(): IOServer | undefined

Attaches Socket.io to the HTTP server. Two scalability features: 1. A Redis adapter so socket rooms work across multiple API instances. 2. A subscription to the `test-run-logs:all` Redis channel (published by the worker's LoggingService) that forwards each log line to the matching `test-run-<id>` room — so clients see live logs even though the work runs in a separate worker process.

async function initSocket(server: HttpServer): Promise<IOServer>

Extract the host-independent path (pathname + search) from a URL.

function pathFromUrl(url: string): string

Build a canonical URL on the suite's base origin for a given path.

function urlFromBase(baseUrl: string, path: string): string

Map a current Baseline pointer document to the shared Baseline DTO.

function toBaselineDTO(doc: any): Baseline

Map an immutable BaselineVersion document to the shared history DTO.

function toBaselineVersionDTO(doc: any): BaselineVersion

Map a GitHub App installation document to the linking UI DTO.

function toGitHubInstallationDTO(doc: any): GitHubInstallation

Map one PageResult document to the shared PageResult DTO.

function toPageResultDTO(doc: any): PageResult

Map a discovered SitePage document to the shared SitePage DTO.

function toSitePageDTO(doc: any): SitePage

Map stored crawl state to the shared SuiteCrawlState DTO.

function toSuiteCrawlStateDTO(crawl: any): SuiteCrawlState

Map a TestRun document to the shared TestRun DTO.

function toTestRunDTO(doc: any): TestRun

Map a stored structured log line to the shared TestRunLog DTO.

function toTestRunLogDTO(doc: any): TestRunLog

Map a TestSuite document to the shared TestSuite DTO.

function toTestSuiteDTO(doc: any): TestSuite

Map a User document to the safe user DTO returned to browsers.

function toUserDTO(doc: any): User

Map a user reference to a minimal summary. Handles both a populated user doc and a bare ObjectId/string (returns id-only in that case); null stays null.

function toUserSummaryDTO(doc: any): UserSummary | null

Register the worker processor that reconciles discovered site pages.

function registerCrawlProcessor(): void

Bull job name used for one-off and scheduled site-discovery crawls.

CRAWL_JOB_NAME = 'crawlSite'

Dedicated queue for site-discovery crawls, kept separate from the visual diff queue so a long crawl never blocks screenshot/diff runs (and vice versa). The worker process consumes both queues.

crawlQueue = new Queue('site-discovery crawls', env.redisUrl,

Enqueue a one-off discovery crawl for a suite.

async function enqueueCrawl(data: CrawlJobData)

Sync a suite's repeatable recrawl job with its configured interval. Removes any existing schedule for the suite, then registers a new one unless the interval is 'off' or the suite is inactive. Call on suite create/update; call removeRecrawlSchedule on delete.

async function reconcileRecrawlSchedule( testSuiteId: string, interval: RecrawlInterval | undefined | null, isActive = true ): Promise<void>

Remove any repeatable recrawl job registered for a suite.

async function removeRecrawlSchedule(testSuiteId: string): Promise<void>

Register the worker processor that executes full suite, branch and PR runs.

function registerTestRunProcessor(): void

Register the worker processor for targeted page-result reruns.

function registerRerunPageProcessor(): void

Re-run a handful of errored viewport results in place. Unlike a full run we disable retries: the rerun mutates baselines/results and is cheap to trigger again from the UI, so an automatic retry would risk double-seeding baselines.

async function enqueueRerunPage(data: RerunPageJobData)

Add a full visual-regression run job to the worker queue.

async function enqueueTestRun(data: TestRunJobData)

Bull queue that carries full visual-regression runs and targeted reruns.

testRunQueue = new Queue('visual regression tests', env.redisUrl,

Append a new BaselineVersion for a (suite, path, viewport) and repoint the Baseline doc at it. Idempotent enough for retries: the unique (suite,path,viewport,version) index rejects a duplicate version number, and we recompute `version` from the current max each call.

async function recordBaselineVersion( params: RecordBaselineVersionParams ): Promise<IBaselineVersion | null>

Promote a PR run's accepted screenshots to the suite's main baselines.

async function promoteRunBaselines(testRunId: string): Promise<PromotionResult>

Approve every changed (FAIL) result in a run at once. - MANUAL/BRANCH: write a baseline from each changed screenshot immediately. - PR: defer baselines to merge (PromotionService); just accept. In both cases the changed results become PASS/approved and the gate is recomputed (to APPROVED). The PR GitHub-check unblock stays in the route.

async function approveAllRunDiffs( testRunId: string, approvedBy?: string | null ): Promise<ApproveAllResult>

Pure: derive a run's review gate from its current page results. - any unresolved diff (status FAIL) still present -> PENDING - no diffs left but at least one was approved -> APPROVED - never had a diff -> NOT_REQUIRED

function computeReviewState(results: ResultGateInput[]): VisualReviewState

Recompute a run's review gate from its page results and persist it. Returns the new state. Call this after any approval mutation.

async function recomputeRunReviewState(testRunId: string): Promise<VisualReviewState>

Promote one approved PageResult to the current baseline and append history.

async function upsertBaselineFromResult( suite: any, result: any, opts: UpsertBaselineOpts =

Recompute and persist a run's status/reviewState/metadata from its PageResults. Best-effort updates the PR GitHub check to match. Never throws on GitHub errors.

async function finalizeRunOutcome(testRunId: string): Promise<void>

Validate that the suite has tracked pages, create a TestRun, and enqueue it. Throws `badRequest` (handled by the global error handler) when there's nothing to diff or the target URL is invalid.

async function startSuiteRun( testSuiteId: string, opts: StartSuiteRunOptions =

Discovers crawlable pages for one site using sitemap data, links and a Playwright fallback for client-rendered pages.

class SiteCrawler