Vetrix Docs

Testing

Reference for the Vetrix test surfaces: which suites exist, how to run them locally, and the rules a change must satisfy before it is merged.

The pages cover two separate codebases. The Go server repository owns the go-test / go-integration-test pipeline jobs, the internal/api router-test rule, and the repo-transfer fixture harness. The Next.js web repository owns the Playwright end-to-end suites and the Storybook visual-regression harness. The two headings below group the pages accordingly.

Go server suites

  • Contributor guide — Development setup (Go, Postgres, Node, Docker), package-layout and pgx/v5 database conventions, the unit-versus-//go:build integration test split, merge-request and commit-message rules, and the project naming rules ("merge request" for the MR surface, "Vetrix Workflows" for the CI surface).
  • Backend testing pipeline runbook — The two CI test jobs and what each exercises: go-test runs go vet plus every *_test.go with the result cache disabled, and go-integration-test stands up an ephemeral Postgres, migrates it with cmd/vetrix-migrate, exports TEST_DSN, and runs the integration-tagged suites. Includes the local run against the dev-stack Postgres container and cookbooks for adding a TEST_DSN-gated roundtrip test and a SELECT-projection structural guard.
  • Router-test rule — The mandatory rule for route changes: any pull request that adds, modifies, or moves an r.Post/Get/Put/Patch/Delete/Mount/Route/... registration under internal/api/ must add a test that builds the production router via NewRouter(svc) and drives the route by URL through r.ServeHTTP, asserting a non-404 status. A test that builds its own chi.NewRouter() and re-mounts routes, or that calls the handler method directly, does not satisfy the rule; a conditionally mounted route needs both a field-wired fixture and a field-unset fixture. Covers the trigger regex, the test skeleton, the anti-patterns, and the reviewer checklist.
  • Repo-transfer fixtures — The deterministic fixture set for the account-transfer feature: an idempotent seeder that creates a fixed entity count (2 users, 1 repository, 10 issues, 3 merge requests, 5 pages, 5 OCI manifests, 2 pull mirrors, 3 pipelines, 2 webhooks, 2 custom hooks), a cascade-ordered reset, and the four XFER_INJECT_* failure-injection flags that are compiled in only under the inject_failures build tag and dead-stripped from production binaries. The enforced contract is the pinned absolute stable_manifest_digest: the digest-pin test and the transfer round-trip test both assert equality against it, so any drift in the count contract or the deterministic-ID derivation fails first at that pin.

Web frontend suites

  • Playwright full-stack target — The source of truth for what live stack the frontend Playwright jobs run against. The web repository builds only the web service and ships no compose file, so the stack-dependent jobs point at the shared dev stack through the E2E_BASE_URL variable that playwright.config.ts resolves baseURL from. Documents the credential rule (source from a runner secret with secret: true, never plaintext YAML) and the allow_failure: true soft-fail on the slow browser lanes, removable with a single-line deletion to make them enforcing.
  • Running E2E specs offline — How a spec sheds its dev-stack dependency by seeding the vetrix_access_token in both slots the app reads — a cookie for the server-side middleware gate and sessionStorage for the client Bearer attach — using E2E_ACCESS_TOKEN when set and otherwise a structurally valid, deliberately unsigned local token that the Go backend still rejects. Includes the offline invocation against the bundled dev server and how to opt back into the live stack.
  • Storybook visual-regression harness — The storybook-chromatic CI job that builds the static Storybook bundle and uploads it for pixel diffing against an approved baseline. Covers the one-time operator setup that injects CHROMATIC_PROJECT_TOKEN as a runner-side environment variable, the no-op pass the job performs while that token is unwired, the per-story (not per-build) baseline approval policy and who approves shared primitives, and the known gaps — pinned Storybook version, no snapshot exclusions, no theme-matrix modes, no accessibility coverage inside the harness.