Anything that reads Date.now() or new Date() — token expiry, rate-limit windows, "is this coupon still valid" checks — is nondeterministic in a test unless you control the clock. Jest's fake timers replace the global timer and date APIs so a test can move time forward on command instead of waiting in real time:

This is exactly the JWT expiry logic from P-2's generateAccessToken/verifyAccessToken — short-lived access tokens, longer-lived refresh tokens. Without fake timers, testing "does a 15-minute token actually expire" means either a real setTimeout delay that makes the suite crawl, or skipping the test and hoping the expiry math is right. jest.useFakeTimers() plus jest.advanceTimersByTime() makes it deterministic and instant.

One gotcha: jsonwebtoken computes expiresIn from Date.now() at sign time, so fake timers must be installed before the token is signed, not just before it's verified — otherwise the token's embedded exp claim is based on the real clock and the test's time travel has no effect on it.

---

Integration Testing: Routes with Supertest

Integration tests send real HTTP requests to your Express app (in memory — no server port needed) and assert on the response.

---

Separating the App from the Server

For Supertest to work, your Express app must be importable without starting a server. Split app.ts from index.ts:

Tests import app directly — no port, no network, no listen().

---

Test Helpers

Utilities that every test file needs:

---

Mocking Strategies

Mocking is a stunt double — watching the stunt double convincingly fall off a building tells you nothing about whether the real actor can act. Mock two layers down and you're reviewing the stunt double's contract instead of the scene: the test passes, but it never actually exercised the code you meant to test.

Mock at the right level. Mock the layer just below the layer under test:

Never mock things two layers away — that defeats the point of the test.

Module mocks with jest.mock:

Resetting mock state:

Spying on a function without replacing it:

---

Database Testing Strategies

Three options, in order of preference:

Option 1: Mock repositories entirely (preferred for unit/integration tests)

Repositories are mocked in service tests. The service never touches a real database. Fast, hermetic, no setup.

Production story: this is also where it can go wrong if it's the only strategy in use. An indexer team mocked the repository layer so thoroughly across their integration suite that a real Prisma migration silently renamed a column. The mocked repository kept returning whatever shape the test fixtures said it should — nothing in the suite ever ran a real query against the actual schema, so nothing could catch the mismatch. Every test stayed green for three weeks. The break only surfaced when a nightly reconciliation job ran against the live database and started throwing on the column that no longer existed. Option 1 is still the right default for speed, but a suite built entirely on it has zero coverage of the real schema — a handful of Option 2 tests per model closes exactly that gap.

Option 2: Test database with real Prisma

For testing repositories or critical data flows, use a separate test database:

Option 3: In-memory database (SQLite for fast repo tests)

Use an in-memory SQLite database for fast, zero-setup repository tests. Prisma does support SQLite, but switching providers is not a drop-in env var swap: the provider field in schema.prisma (postgresql, sqlite, etc.) is fixed per schema file, not selected at runtime via DATABASE_URL alone. In practice, testing against SQLite means maintaining a second schema (e.g. prisma/schema.test.prisma with provider = "sqlite") or a schema-per-provider setup, running prisma generate against it before tests run, and watching for the type and feature differences Prisma has between providers (SQLite lacks native enums and arrays, for example, which can make a schema that's valid for Postgres invalid for SQLite without changes). Some teams decide the extra schema-management overhead isn't worth it for the tests it saves, and use Option 2 (a real Postgres test database) for anything beyond pure unit tests.

---

Test Flakiness from Shared State

Tests that pass alone but fail — or hang — only when run alongside the rest of the suite are almost always caused by state leaking between test files. The most common culprit in a Node.js codebase is a module-level singleton:

Every test file that imports these gets the same connection. If one file calls prisma.$disconnect() in afterAll while another file's tests are still running against that same shared instance in a different order, you get failures that depend on Jest's worker scheduling that particular run — flaky in the worst way, because they're not reproducible on demand.

Jest runs test files in parallel worker processes by default (maxWorkers, roughly one per CPU core). That parallelism is exactly what turns a shared-connection bug into a flaky one:

A common CI setup: run the bulk of the suite (mocked dependencies, no shared state) with full parallelism, and run the smaller set of database-backed integration tests with --runInBand as a separate step — speed where it's safe, determinism where it isn't.

---

Snapshot Testing and Contract Testing

Snapshot tests capture a value the first time a test runs — often a serialized object or response body — and fail if a later run produces something different:

They're cheap to write but easy to rubber-stamp: a failing snapshot usually just prompts a developer to run jest -u and commit the new snapshot without reading the diff, which defeats the point of having the test. Snapshots earn their keep for output that's large, stable, and rarely expected to change on purpose — a generated SQL query, a rendered email template — not for API response shapes that change often and deserve an explicit expect(res.body).toMatchObject(...) instead, where a reviewer has to actually read what changed.

Contract testing addresses a different gap: when your service depends on an external API you don't control, mocking that dependency only proves your code handles the response shape you assumed it would send. If the real API's response shape changes, your mocked tests stay green while production breaks. Tools like Pact let the consumer (your service) record the request/response shape it expects as a "contract," which the provider verifies its own test suite still satisfies before shipping a breaking change — catching the mismatch in the provider's CI, not in your production logs.

---

Test Coverage: What Actually Matters

Coverage numbers are a proxy — what matters is whether your tests catch regressions. Some guidelines:

Focus coverage where bugs are expensive: services (business logic), validators (input contracts), error handling paths.

Don't chase 100%: boilerplate routes, configuration files, and type declaration files don't need tests. Use /* istanbul ignore next */ for legitimately untestable branches.

---

Running Tests in CI

---

What Not to Test

Some things are expensive to test and rarely break:

• External libraries — don't test that bcrypt.hash works. Trust the library.
• Express internals — don't test that router.get registers routes correctly.
• Simple getters/setters — user.name = 'Jatin' doesn't need a test.
• Trivially thin code — a repository function that calls prisma.user.findUnique and returns the result doesn't need a unit test; the integration test covers it.

Test the code you wrote. Mock the code others wrote.

---

Summary

• Unit tests target services and validators — fast, no database, mock dependencies one layer down.
• Integration tests target Express routes via Supertest — real validation middleware runs, services are mocked.
• Separate app.ts from index.ts — tests import the app without starting a listener.
• jest.mock() replaces entire modules; jest.spyOn() intercepts specific functions while leaving others intact. Always jest.clearAllMocks() in beforeEach.
• Mock at the right level — service tests mock repositories, route tests mock services. Never skip a layer.
• Coverage thresholds enforce a floor on test quality in CI — set them for the service layer first, where bugs are most expensive.
• CI runs tsc --noEmit before tests — catch type errors before runtime errors.

Next: configuration, environment management, and security hardening — environment variables, secrets management, rate limiting, CORS, and the security headers that prevent the most common API vulnerabilities.

---