Backend Testing

Overview

Backend tests use Node.js 24's built-in test runner and TypeScript test files. The suite is split into three layers:

Layer	Command	Location	Purpose
Unit	`npm run test`	`backend/tests/*.test.ts`	Pure helpers, validators, policy decisions, service contracts, and file/session utilities
Integration	`npm run test:integration`	`backend/tests/integration/*.test.ts`	Cross-module behavior such as DB-backed access policy and Express router factory contracts
E2E	`npm run test:e2e`	`backend/tests/e2e/*.test.ts`	Real HTTP request/response checks against local Express test apps
Full suite	`npm run test:all`	all test folders	Runs unit, integration, and e2e in sequence
Verification	`npm run verify`	static checks plus all test folders	Runs typecheck, lint, ESM boundary checks, and the full test suite

Current Coverage

Request validation and commonErrorHandler JSON handling.
Publish, file upload/presign, upload chunk, and tour page reorder request validation contracts.
File service path validation, structured file error payloads, and local presigned URL fallback behavior.
Environment validation for config-only runtime settings, including normalized file-storage provider overrides.
Circuit breaker behavior for ignored failures, recorded failures, and open breaker rejection.
Auth service password reset, password update rejection rules, and email verification token behavior with real bcrypt and DB writes.
Route ID/body ID update contract enforcement.
Permission name mapping, own-user route bypass, runtime public read bypass, and AccessPolicy public-user hardening.
Generic DB API and entity service object-signature contracts.
OpenAPI route coverage and internal $ref resolution.
UploadSessionManager metadata, chunk tracking, assembly order, and cleanup behavior.
createEntityRouter service/DB option propagation, query normalization, update ID mismatch handling, and CSV export behavior.
Public runtime list blocking and response sanitization for presentation data.
Publish service environment copy behavior for dev to stage and stage to production, including target replacement, source preservation, audio tracks, transition settings, and UI-control settings.
Runtime context HTTP behavior for default, valid, and unsupported runtime headers.

Environment Notes

DB-backed integration tests authenticate against the configured PostgreSQL connection. If PostgreSQL is unavailable, those tests call t.skip() with the connection error so non-DB integration tests can still run. npm run test:integration runs with --test-concurrency=1 because several integration tests share a PostgreSQL transaction connection; keep DB-backed tests sequential unless they use isolated connections.

E2E tests bind a local HTTP listener on 127.0.0.1 with an ephemeral port. In restricted sandboxes this may require elevated permission for local socket binding.

Test Helpers

backend/tests/http-test-utils.ts provides startTestServer(app), which starts an Express app on an ephemeral local port and returns { baseUrl, close }. Use it only for e2e-style tests that must exercise real HTTP semantics.

Integration tests that do not need a network socket should drive Express apps in memory with node-mocks-http; this keeps them usable in restricted sandboxes.

Adding Tests

Prefer unit tests for pure helpers, validators, policies, and isolated service logic.
Use integration tests when behavior crosses route, middleware, service, DB API, or Sequelize transaction boundaries.
Use e2e tests when the behavior depends on real HTTP parsing, headers, status codes, or socket-level request handling.
Keep new backend tests strict TypeScript compatible and avoid casts, any, eslint-disable, and @ts-ignore.
When config-backed behavior must be overridden in tests, mutate the typed config object and restore it in finally; do not rely on changing process.env after modules have imported backend/src/config.ts.
For DB integration tests, wrap writes in a transaction and roll it back.

4.1 KiB Raw Blame History