archestra-dev-backend-tests

name	archestra-dev-backend-tests
description	Use when writing or modifying Archestra backend unit tests (platform/backend/src/**/*.test.ts) — mocking modules, stubbing globals, database fixtures, vitest projects/isolation, or test performance.

Archestra Backend Unit Tests

Run commands from platform/ unless specifically instructed otherwise. Run a single file with cd backend && npx vitest run <file>.

The two vitest projects (why mocking style matters)

backend/vitest.config.ts splits test files into two projects at config-load time by grepping file content:

• clean — files with NO vi.mock/vi.doMock/vi.hoisted run with isolate: false: files in the same worker process share the module cache, so the backend module graph is imported once per worker instead of once per file. This is the fast path.
• mocked — files using module mocking keep full isolation, because Vitest never resets the module-mock registry between files in a shared worker (vitest-dev/vitest#4894).

Consequences:

• Prefer not mocking modules at all. Every file that drops its last vi.mock automatically joins the fast project. Mock at the process boundary instead (fetch, network) when possible.
• Routing is automatic — never maintain a file list; adding vi.mock to a file safely moves it to the isolated project on the next run.

HTTP boundary mocking (instead of vi.mock on client libraries)

Never vi.mock an HTTP client library (jira.js, @gitbeaker/rest, openai, ...). Use MSW via the useMswServer helper — the real client runs and only the network is faked (MSW intercepts axios, fetch, and undici alike):

import { http, HttpResponse } from "msw";
import { useMswServer } from "@/test/msw";

const server = useMswServer();
test("...", async () => {
  server.use(
    http.get("https://example.atlassian.net/rest/api/3/search/jql", () =>
      HttpResponse.json({ issues: [] }),
    ),
  );
});

Unhandled requests fail the test loudly. The helper's lifecycle is per test (it must be — the shared setup restores globalThis.fetch after every test); don't hand-roll setupServer with beforeAll listen.

Wire-level gotchas learned in past conversions: clients retry — gitbeaker retries 429/502 up to 10× with backoff and openai retries 429/5xx (choose a status that the specific client does not retry, or configure/account for its retries; OpenAI retries 500); MSW 2.x route paths use path-to-regexp 8, which rejects RegExp paths and bare * — use :param segments (URL-encoded slashes like %2F stay one segment and decode in the param).

Module mocking rules

• @/auth: activate with a bare vi.mock("@/auth"); — Vitest resolves the Jest-style src/auth/__mocks__/index.ts, which re-exports the canonical factory (src/test/mocks/auth.ts: every export a bare vi.fn()). Configure behavior per test via vi.mocked(...):

  vi.mock("@/auth");
  import { hasPermission } from "@/auth";
  beforeEach(() => {
    vi.mocked(hasPermission).mockResolvedValue({ success: true, error: null });
  });
  

• @/auth/utils: bare vi.mock("@/auth/utils"); (resolves src/auth/__mocks__/utils.ts). Needed separately from @/auth when the code under test imports from "@/auth/utils" directly — module mocks match specifiers, not re-exports.

• @/observability: bare vi.mock("@/observability"); (resolves src/observability/__mocks__/index.ts). metrics/tracing are memoized proxy trees — any metrics.<ns>.<fn> access yields a stable vi.fn(), so assert via vi.mocked(metrics.llm.someFn) with no factory.

• @/cache-manager: bare vi.mock("@/cache-manager"); (resolves src/__mocks__/cache-manager.ts) — a Map-backed cacheManager fake with real cache semantics that needs no start(), auto-reset before every test; CacheKey and LRUCacheManager stay real. Tests needing a cache MISS mid-test call await cacheManager.delete(key).

• @/logging: do NOT mock just to silence output — the shared setup already runs the real logger at level . Only mock when a test asserts on logger calls, with a bare (resolves ). does not work — the export is a Proxy binding methods to a private pino instance.

Global stubs (fetch, window, env)

The config sets unstubGlobals: true / unstubEnvs: true: every vi.stubGlobal/vi.stubEnv is auto-reverted after EACH test.

• Stub in beforeEach, never only at module scope or in beforeAll — a module-scope stub is silently removed after the first test:

  const fetchMock = vi.fn();
  vi.stubGlobal("fetch", fetchMock); // covers import time
  beforeEach(() => {
    vi.stubGlobal("fetch", fetchMock); // re-applied per test
  });
  

• Never raw-assign globalThis.fetch = ... — use vi.stubGlobal. (The shared setup restores the real fetch after every test as a safety net, so a raw assignment doesn't survive anyway.)

• Faking browser globals (window, location) confuses PGlite's environment detection; the shared setup finishes PGlite init before test code runs, but always clean such globals up in afterAll.

Database

• Never mock @/database or model modules for DB behavior — every file gets a real PGlite loaded from a pre-migrated snapshot (src/test/global-setup.ts + src/test/setup.ts); tables are truncated between tests.
• Create data through fixtures from @/test (makeUser, makeOrganization, makeAgent, ...) — see the Backend Test Fixtures section in platform/CLAUDE.md.
• On file teardown the injected DB is cleared: module-level code that runs between files gets getDb()'s "Database not initialized" (a handled condition), never a closed PGlite.

Performance etiquette

• The suite's budget is module-import cost. Heavy new top-level imports in widely-imported modules cost every worker; test-only helpers belong under src/test/.
• Local full-suite runs cap workers at half the cores (config) so the machine stays usable, further bounded by a ~5 GB-per-fork memory cap; CI uses all cores under the same memory cap and runs 4 shards via vitest run --shard=k/4 behind the Backend Unit Tests gate job.