Testing Best Practices

Rules that keep Node API test suites fast, reliable, and focused on observable behavior.

How to Use This List

• Apply when adding the first test to a new service.
• Review during PRs that add mocks or integration infrastructure.
• Enforce via CI (required npm test, separate integration job).

A - Test Design

• Test behavior, not private implementation. Assert HTTP status, returned JSON, and side effects - not internal call order.
• Follow the pyramid: many unit, fewer integration, rare E2E. Most tests complete in milliseconds.
• Name tests as specifications. returns 409 when invoice already paid beats test1.
• One primary assertion focus per test. Multiple asserts OK when verifying one behavior outcome.
• Table-driven cases for input variations. Cover edge cases without copy-paste tests.

B - HTTP & App Structure

• Export createApp() without auto-listen. Supertest and Fastify inject need in-process apps.
• Cover error paths: 400, 401, 404, 409, 500 handlers. Happy-path-only suites miss regressions.
• Use Supertest or Fastify inject, not random ports. Avoid EADDRINUSE and flaky CI.
• Do not hit production URLs in tests. Staging or in-process only.
• Freeze time when testing TTL/expiry logic. vi.setSystemTime or injected clock interface.

C - Data & Isolation

• Isolate database per CI job or suite. Testcontainers or dedicated schema; never shared dev DB.
• Truncate or rollback between integration tests. Prevent order-dependent failures.
• Use factories/builders for test entities. Readable setup without 50-line fixtures inline.
• Seed minimal data per test. Large shared fixtures hide which field caused failure.
• Run migrations against test DB same as prod. Catch SQL differences early.

D - Tooling & CI

• Single npm test entry; split unit vs integration when needed. test:integration may require Docker.
• Prefer node:test or Vitest for new code; plan Jest exit on brownfield. Avoid three runners.
• Run tests on every PR after typecheck and lint. Fail fast ordering in pipeline.
• Do not merge flaky tests. Quarantine with owner ticket and expiry, or fix immediately.
• Contract tests for cross-service HTTP dependencies. Pact or schema diff before deploy.

E - Load & Release

• k6/Artillery smoke on staging before major launches. p95 and error rate thresholds defined.
• Load test write paths with cleanup strategy. Idempotent prefixes or dedicated tenant.
• Measure coverage; do not worship 100%. Critical domain modules targeted; generated code excluded.
• Test auth middleware with realistic tokens. Not auth disabled in test globally unless isolated unit.
• Document how to run integration tests locally. Docker prerequisite in README.

FAQs

Related

• Testing Basics - pyramid introduction
• Supertest & HTTP Integration - in-process HTTP
• Testcontainers - real Postgres/Redis

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.