backend-testing

Backend Testing Guidelines

The shared philosophy (no vi.mock except unavailable third parties, reusable mock helpers, Arrange/Act/Assert, no vitest imports) lives in the testing-philosophy rule. Below are the backend specifics.

Core Philosophy

Feature module tests (features/<domain>/modules/<feature>/index.ts) are INTEGRATION TESTS. They use real DB (Postgres), real cache (Valkey), real storage (S3/RustFS) from the test Docker environment. They create real data via db/mutations/ functions, query it back, and verify the full flow.

Everything runs real:

• Database queries/mutations — real Postgres from Docker
• Valkey operations — real Valkey from Docker
• S3/Storage operations — real RustFS from Docker
• Internal feature logic, helpers, utils, channels — all real

Only third-party SaaS without a local equivalent is mocked. Currently mocked:

• Resend (external SaaS — email sending), via the reusable helper in src/testing/mocks/resend.mock.ts

New third-party mocks go in src/testing/mocks/ as reusable helpers.

Unit tests are ONLY for:

• Pure utility functions with no side effects
• Schema validation logic
• Mapping/transformation functions
• Sub-components of features (not the main index.ts)

Setup Architecture

• Global (src/testing/setup/setup.ts): loads .env.test, sets NODE_ENV=test. Runs for every test.
• Integration (setupIntegrationTest() from src/testing/setup/test-utils.ts): connects to real Postgres, Valkey, S3. Call at top of integration test files.

import { setupIntegrationTest } from "@backend/testing/setup/test-utils";
const env = setupIntegrationTest();

beforeEach(async () => {
  await env.flushAll();
});

File Structure

• Feature integration tests: features/<domain>/modules/<feature>/index.test.ts (next to source)
• Cross-feature integration tests: features/<domain>/__tests__/<flow>.integration.test.ts
• Unit tests (utils, schemas, sub-components only): {filename}.test.ts next to source