Backend Functions

The authenticated caller's id.

function currentUserId(req: FastifyRequest): string

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)

Launch headless Chromium for screenshot capture.

async function launchChromium(): Promise<Browser>

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

logger = winston.createLogger(

No summary comment yet.

async function seedPreviewIfEmpty(): Promise<void>

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 minimal team reference to the shared TeamSummary DTO.

function toTeamSummaryDTO(doc: any): TeamSummary | null

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, extras?: TestSuiteDTOExtras): TestSuite

Map a TestSuiteGrant document to the shared DTO.

function toTestSuiteGrantDTO( doc: any, resolved?:

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

Choose the job backend.

function resolveQueueBackend(): QueueBackend

Enqueue a site-discovery crawl.

async function enqueueCrawl(data: CrawlJobData): Promise<void>

Enqueue a targeted page rerun. Retries are disabled conceptually — the UI can trigger again; automatic retry would risk double-seeding baselines.

async function enqueueRerunPage(data: RerunPageJobData): Promise<void>

Enqueue a full visual-regression run.

async function enqueueTestRun(data: TestRunJobData): Promise<void>

Recrawl schedule is no longer a Redis repeatable job. Suites store their interval on `config.recrawlInterval`; a Vercel Cron (or local timer) calls `enqueueDueRecrawls` to pick up suites that are due.

async function reconcileRecrawlSchedule( _testSuiteId: string, _interval?: string | null, _isActive = true ): Promise<void>

No summary comment yet.

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

A Mongo filter selecting the suites a user may see, honouring `scope`. Compose it with other filters (kind, isActive, …) via `$and` or by spreading.

async function accessibleSuiteFilter( userId: string, scope: SuiteScope = SuiteScope.ALL ): Promise<Record<string, unknown>>

Remove every grant on a suite — called when the suite is deleted.

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

Resolve a caller's standing on a suite. Returns `role: null` when they have no access; throws only when the suite genuinely does not exist.

async function getSuiteAccess( userId: string, testSuiteId: string, preloadedSuite?: any ): Promise<SuiteAccess>

Ids of every suite shared with the user (owned suites not included).

async function grantedSuiteIds(userId: string): Promise<Types.ObjectId[]>

The run-scoped equivalent: resolve a run, then gate on its parent suite. Returns both so handlers don't re-read either document.

async function requireRunCapability( userId: string, testRunId: string, capability: SuiteCapability ): Promise<

Gate a suite operation. Returns the suite plus the caller's resolved role.

async function requireSuiteCapability( userId: string, testSuiteId: string, capability: SuiteCapability, preloadedSuite?: any ): Promise<GrantedSuiteAccess>

Expand a user into every principal they act as.

async function resolvePrincipals(userId: string): Promise<PrincipalRef[]>

Grant counts per suite (owner excluded), for the "shared" badge in lists.

async function shareCountsForSuites( suiteIds: Types.ObjectId[] ): Promise<Map<string, number>>

Build the viewer-access DTO attached to suite responses.

function toViewerAccess(access: SuiteAccess): TestSuiteViewerAccess | null

Batch version of `getSuiteAccess` for list endpoints: one grant query for every suite on the page instead of one per suite.

async function viewerAccessForSuites( userId: string, suites: any[] ): Promise<Map<string, TestSuiteViewerAccess>>

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