Contracts

Standard error body returned by every endpoint on failure.

Body for POST /test-runs/:id/approve-visuals.

MessageResponse

Baseline

Baseline[]

A version reduced to what the compare result needs to label each side.

Response of GET /baseline-versions?suiteId=&path=&viewport=

BaselineVersion[]

'cancel'

Body for POST /baseline-versions/compare — diff any two versions.

Response of POST /baseline-versions/compare — an on-demand generated diff.

Response of POST /test-suites/:id/crawl.

Body for POST /manual-runs — create a quick single-URL bucket. The URL's origin becomes the bucket's baseUrl and the URL is added directly as a tracked page (no crawl). The first run is kicked off automatically and captures the baseline; later runs diff against it.

Response of POST /manual-runs — the created bucket plus its first run id.

GitHubInstallation[]

GitHubRepo[]

Optional filters for GET /test-suites.

Payload broadcast to a `test-run-:id` room when a new log line is emitted.

A manual-run bucket is a TestSuite with kind === MANUAL.

TestSuite

TestSuiteDetail

TestSuiteWithCountAndRuns[]

Generic success message body.

Response of GET /test-suites/:id/pages/:pageId — a single page with its current per-viewport baselines and latest run outcome.

Response of GET /test-suites/:id/pages/:pageId/history — the baseline timeline, newest first. Optional ?viewport= filter narrows to one viewport.

Offset-based pagination envelope.

Body for POST /test-runs/:id/rerun — re-test the errored viewports of a single page (identified by its URL) within an existing run. Re-screenshots and re-compares only the ERROR-status results for that URL and overwrites them in place; passing/changed viewports are left untouched.

Response of POST /test-runs/:id/rerun.

Response of POST /manual-runs/:id/run — re-test the bucket's URL.

Optional body for POST /test-suites/:id/run. Omitted/empty => a MANUAL run against the suite's own baseUrl. A BRANCH run targets a preview URL and never mutates baselines or GitHub.

Bulk actions on a suite's discovered pages.

| 'track' /** Deselect pages from visual diffing. */ | 'untrack' /** Clear NEW flags without tracking (mark reviewed). */ | 'acknowledge' /** Delete page entries entirely (used to clean up REMOVED pages). */ | 'delete'

Body for PATCH /test-suites/:id/pages.

Response of GET /test-suites/:id/pages — the combined sitemap view.

(typeof SOCKET_EVENTS)[keyof typeof SOCKET_EVENTS]

TestRunDetail

TestSuiteDetail

TestSuiteWithCountAndRuns[]

How often a suite's site map is automatically recrawled to discover added/removed pages. 'off' disables automatic recrawls.

'off' | '6h' | '12h' | 'daily' | 'weekly'

Test suite configuration Contains all settings for test execution, crawling, and comparison

Viewport configuration for responsive testing

Wait strategy options for page loading

'networkidle' | 'domcontentloaded' | 'load'

An approved reference screenshot for a URL/viewport pair.

An immutable record of one approved baseline for a (suite, path, viewport). Appended — never overwritten — every time a baseline is promoted, so a page accrues a full, attributable history. The newest version for a key is the current baseline (mirrored onto the Baseline pointer for the hot read path).

A single entry in a page's baseline timeline. Carries the previous version's file so the UI can render before→after without a second request.

Counters describing what the most recent discovery crawl found.

A GitHub App installation that has granted this app access to repos.

A repo selectable when linking a suite (from the installation's repo list).

Record<string, PageResult[]>

ISO-8601 timestamp string (e.g. "2026-06-02T10:00:00.000Z").

string

The current baseline for one viewport, summarised for the page detail view.

Summary of how a page fared in the most recent finished manual run, aggregated across viewports (worst status wins).

The comparison outcome for one URL at one viewport within a run.

A page discovered on a suite's site by the discovery crawl. Unique per (suite, path). `tracked` pages are the ones screenshotted/diffed by runs.

A site page enriched with its latest diff outcome for the pages view.

The state of a suite's site-discovery crawl (stored on the suite).

A single execution of a test suite.

Git/PR context attached to a PR- or branch-triggered run.

A single structured log line emitted during a run.

Aggregated counters recorded when a run finishes.

A configured site/test target.

Link between a test suite and a GitHub repository (one suite ↔ one repo).

Minimal suite info embedded in run responses.

Authenticated user, safe for client exposure (never includes password).

Minimal user shape for attribution (who approved a baseline, etc.) — embedded in history responses so the UI can show a name without a separate lookup.

How an approved baseline came to exist. Stored on each immutable BaselineVersion so a page's history reads as a meaningful audit trail. - INITIAL: first screenshot captured for a page/viewport (new page, no prior baseline) — auto-seeded, no human approver. - MANUAL: approved from a MANUAL run in-app. - BRANCH: approved from a BRANCH diff in-app. - PR_MERGE: promoted when a linked GitHub PR merged. - API: promoted via the baselines API directly.

Status of a suite's site-discovery crawl.

Test run log message type

Lifecycle status of a discovered site page. - NEW: discovered by a recrawl and not yet reviewed by the user. - ACTIVE: known page, present in the latest crawl. - REMOVED: previously discovered but missing from the latest crawl.

Page comparison result status

Test run EXECUTION status — answers "did the worker do its job?", nothing more. Visual differences do NOT make a run FAILED; that is tracked separately by VisualReviewState. A run that finished but has diffs is COMPLETED. - PENDING/RUNNING: in flight. - COMPLETED: the worker finished, whether or not diffs were found. - FAILED: genuine execution failure (worker threw, or every page errored). - CANCELLED: cancelled by the user.

What triggered a test run. - MANUAL: started from the dashboard against the suite's own baseUrl. - PR: triggered by a GitHub pull request, run against its Vercel preview. - BRANCH: an ad-hoc branch/preview diff started from the dashboard.

Distinguishes a full crawl-based test suite from a lightweight manual-run bucket. Stored on TestSuite so both share one run/baseline/diff pipeline. - SUITE: the standard suite — discovers pages via a sitemap crawl, the user tracks pages, and runs diff every tracked page. - MANUAL: a quick single-URL bucket. No crawl/sitemap ceremony — the URL is added directly as a tracked page so it can be screenshotted and re-tested over time against the first run's baseline.

Visual review gate for a run — the "have the visual changes been reviewed?" axis, kept separate from RunStatus (the "did the run execute?" axis). Applies to ALL run types: a run that finished but has diffs is COMPLETED with a PENDING gate, not FAILED. - NOT_REQUIRED: nothing to review — all pages passed, or only new pages were captured (no diffs). - PENDING: one or more changed pages awaiting approval. For PR runs this also blocks the GitHub check. - APPROVED: there were changes and they have all been approved. For MANUAL/BRANCH the baselines were updated immediately; for PR the GitHub check is unblocked and baselines promote on merge.