backend-testing

# Backend Testing ## Quick Start Use these defaults for QuickStack backend tests: - Name unit tests `*.unit.spec.ts`. - Name integration tests `*.integration.spec.ts`. - Keep unit tests beside the source file. - Put integration tests in `src/__tests__/integration/` mirroring the source path. - Use Vitest globals without importing `describe`, `it`, `expect`, or `vi`. - Prefer `@/...` imports for app modules. ## Workflow When creating or updating backend tests: 1. Pick the right test type: unit, Prisma/SQLite integration, or k3s integration. 2. Place the file in the correct location and use the required filename suffix. 3. For unit tests, mock all external dependencies and keep the suite isolated. 4. For Prisma integration tests, use `createPrismaTestContext('label')`. 5. For k3s integration tests, use `createK3sTestContext()` and mock the Kubernetes adapter before imports. 6. Run the smallest relevant test command first, then broaden if needed. ## Unit Tests - Mock Prisma, Kubernetes, S3, Longhorn, filesystem, network calls, and singleton services. - Use `vi.mock()` and `vi.mocked()` for typed mocks. - Use `vi.importActual()` for partial mocks when needed. - If a module initializes from environment variables at import time, set env first and call `vi.resetModules()` before importing it. - Do not hit the real database, filesystem, or Kubernetes from unit tests. ## Integration Tests - Use a real temporary SQLite database file instead of mocks. - Use `createPrismaTestContext()` for DB lifecycle setup and teardown. - Static top-level imports of services are fine with the Prisma test context. - Use `ctx.getDataAccess().client` for direct DB assertions. - Run mutating integration suites with `--pool=forks` or `--no-file-parallelism` when Prisma singleton state is involved. ## K3s Tests - Use `createK3sTestContext()` for real Kubernetes integration coverage. - Mock `@/server/adapter/kubernetes-api.adapter` before any related imports. - Use `ctx.getClients()` for typed Kubernetes clients. - Use `ctx.getKubeConfig()` only when raw kubeconfig access is needed. - Expect slower startup and Docker requirements for these suites. ## Reference See `REFERENCE.md` for exact naming rules, folder structure, code examples, runtime caveats, and test commands.