API Testing Guide

Scope: apps/api — the Fastify REST + WebSocket server.

Table of Contents

1. Overview
2. Test Types
   • Unit Tests
   • Integration Tests
3. Test Infrastructure
   • Database
   • Helpers
   • Mocking strategy
4. How to Run
5. Current Coverage
6. Coverage Target
7. Known Issues
8. Backlog — Coverage Gaps

Overview

The API test suite uses Vitest v2 with a Node.js environment. Tests are split into two tiers with separate Vitest configs:

Unit tests run in CI (pnpm test:unit). Integration tests require a live PostgreSQL instance and are run separately (pnpm test:integration).

Integration files run serially (fileParallelism: false) because they share a single PostgreSQL test database and concurrent writes cause deadlocks.

Test Types

Unit Tests

Pure function tests that mock all external dependencies. No database, no HTTP server, no Redis.

Integration Tests

Each integration test:

• Spins up a full Fastify app via createApp()
• Sends requests via app.inject() (no real TCP)
• Hits the real PostgreSQL test database (leadmetrics_api_test)
• Mocks only external services (queue, nosqldb, S3/Spaces, Razorpay)

Test Infrastructure

Database

The test database is a separate instance from development. It must be created and migrated before running tests:

# One-time setup (from packages/db/)
DATABASE_URL="postgresql://postgres:postgres@127.0.0.1:5434/leadmetrics_api_test" \
  npx prisma db push

cleanDb() in helpers truncates all tables between test files in dependency order (child tables first).

Helpers

src/__tests__/integration/helpers.ts

Mocking Strategy

How to Run

All commands from apps/api/ or via turbo from repo root:

# Unit tests only — no DB required (CI)
pnpm test:unit
# or from repo root:
pnpm turbo run test:unit --filter=@leadmetrics/api
 
# Integration tests — requires PostgreSQL test DB
pnpm test:integration
 
# Watch mode (unit tests)
pnpm test:watch
 
# Run a single integration file
npx vitest run src/__tests__/integration/admin-billing.test.ts
 
# Run multiple files
npx vitest run src/__tests__/integration/dm.test.ts src/__tests__/jwt.test.ts
 
# Coverage report
pnpm test:coverage
 
# Force sequential when running ad-hoc integration subsets (avoids DB conflicts)
npx vitest run --sequence.concurrent=false

Do not run npx vitest run without --sequence.concurrent=false for integration tests — the default allows file-level parallelism and causes DB constraint violations.

The pnpm test:integration script uses vitest.config.ts which enforces fileParallelism: false.

Current Coverage

As of May 2026:

Unit tests (pnpm test:unit — no DB, runs in CI):

Integration tests (pnpm test:integration — requires PostgreSQL):

Route coverage by router:

Unit coverage:

Estimated line coverage: ~85–88% (exact figure requires @vitest/coverage-v8 install — see Backlog).

Coverage Target

Goal: 90–95% line/statement coverage across the codebase.

The gap between current (~85–88%) and target (~90–95%) is concentrated in:

1. media.ts real-path — 9 integration tests all skipped due to external API dependencies
2. Socket namespace edge cases — some event handler branches not exercised
3. Error branches in billing — Razorpay order creation failure paths
4. handleSubscriptionCharged / handleSubscriptionCancelled — DB lookup stub (not yet implemented)

Known Issues

1. Parallel DB conflicts when running integration tests concurrently

Status: Mitigated by fileParallelism: false in vitest.config.ts Symptom: When integration tests run in parallel (e.g., during ad-hoc npx vitest run without the config), you see:

• Unique constraint failed on the fields: (userId, tenantId)
• deadlock detected (40P01) on activity.create() Root cause: Multiple test files reuse the same user/tenant IDs (e.g., "test-super-admin", "test-tenant-user"). The cleanDb() helper truncates tables between files, but when files run concurrently the truncates race with inserts. Mitigation: Always use pnpm test (which runs serially) or pass --sequence.concurrent=false for ad-hoc subsets.

2. media.test.ts — 9 tests skipped

Status: By design Reason: These tests call real Pixabay and Unsplash APIs and upload to a real DigitalOcean Spaces bucket. They require PIXABAY_API_KEY, UNSPLASH_ACCESS_KEY, DO_SPACES_KEY, DO_SPACES_SECRET, and DO_SPACES_ENDPOINT to be set. How to run locally: Set those env vars and remove the .skip from the describe blocks in media.test.ts.

Backlog — Coverage Gaps

Items tracked here represent missing tests or test infrastructure improvements. They are ordered by impact.

High Priority

Medium Priority

Low Priority