# Typescript Testing Backend

> Use when writing or reviewing TypeScript backend tests — Jest unit tests for services/controllers (mocked Prisma) or Supertest integration tests against a real isolated PostgreSQL test database. Triggers on edits to `*.service.test.ts`, `*.controller.test.ts`, `*.integration.test.ts`, service/controller/API test files (`.ts`, not `.tsx`) under `**/__tests__/`, or mentions of "backend test", "service test", "API test", "database test".

- Skill: `lazyisefficient/typescript-testing-backend` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add lazyisefficient/typescript-testing-backend`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lazyisefficient/typescript-testing-backend/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: LazyIsEfficient (https://skillmd.com/u/lazyisefficient)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lazyisefficient/typescript-testing-backend

---


# TypeScript Testing — Backend

You are operating as a backend test engineer. Mock at the module edge for units, hit a real Postgres for integration, and never assert on internal call shapes.

Reference stack: Jest 29 with `@swc/jest`, Supertest for HTTP, a custom `TestServer` helper that simulates Next.js route handlers, and a `TestDatabase` helper that provisions isolated PostgreSQL instances per run with migrations + seed. Tests live co-located in `__tests__/` folders.

Unit tests mock the Prisma client at the module boundary; integration tests use the real DB plus an auth-state helper for authenticated request flows.

## Universal Rules

1. **Use Jest** — `jest.mock()` / `jest.fn()`, never `vi.*`.
2. **Co-locate tests** in `__tests__/` next to the source.
3. **Mock at the module boundary** — not internal functions.
4. **Literal expected values** — `expect(total).toBe(70)`, never expressions.
5. **Every `it()` asserts** observable behavior with at least one `expect()`.
6. **`beforeEach` cleanup**, scoped to test-created records — never truncate seed data.
7. **Clear auth/state helpers between tests** so authenticated flows don't bleed across cases.
8. **Never `test.skip()`** — fix or delete.
9. **Real DB for integration tests**, mocked Prisma for unit tests.
10. **Internal utils stay real** — only mock external boundaries.

## References

- [references/framework-and-structure.md](references/framework-and-structure.md) — Jest config, test scripts, directory layout, file naming conventions, coverage
- [references/unit-testing.md](references/unit-testing.md) — service unit tests with mocked Prisma, controller unit tests with injected service mocks
- [references/integration-testing.md](references/integration-testing.md) — shared setup, full Supertest example, `TestServer` pattern, `authTestHelpers` API
- [references/database-testing.md](references/database-testing.md) — `setupTestDatabase`, isolated DBs, cleanup rules, accessing seeded data
- [references/mock-policy-and-quality.md](references/mock-policy-and-quality.md) — mock scope table, quality criteria, test failure triage