Running Tests

NestFleet has four test layers: unit tests (fast, no I/O), integration tests (real PostgreSQL via Testcontainers), console type-checking, and end-to-end tests (Playwright, full stack). CI runs all of them on every pull request. Locally, you will most often run unit and integration tests.

Unit tests

Unit tests cover services and workers in isolation. All external dependencies (database, LLM clients, pg-boss) are mocked. They run in milliseconds and require no running services.

npm test

This runs Vitest in single-run mode, printing a pass/fail summary. Test files follow the naming convention *.unit.test.ts and live alongside the source files they test.

Watch mode

During active development, run tests in watch mode to get instant feedback on each file save:

npm run test:watch

Vitest watch mode only re-runs tests affected by the changed file, so even large test suites stay fast in watch mode.

Integration tests

Integration tests exercise the full request path — from the Hono route handler through the service and repository layers to a real PostgreSQL database. Testcontainers starts a fresh PostgreSQL 16 + pgvector container before the test suite and tears it down afterwards. Migrations are applied automatically.

npm run test:integration

Integration test files use the naming convention *.integration.test.ts. They are excluded from the default npm test run to keep the fast unit test loop unaffected.

Each integration test file gets its own isolated database schema (unique schema name per test file), so tests can run in parallel without interfering with each other.

Console type-check

The Next.js console is TypeScript-strict. Run the type-checker to catch type errors without building:

cd console && npm run type-check

This runs tsc --noEmit with the project's strict tsconfig. It is faster than a full Next.js build and catches most errors that would break the production build.

Build verification

To verify the API builds without TypeScript errors (runs the full tsc compilation):

npm run build

For the console build:

cd console && npm run build

Both must succeed before a PR can be merged. CI runs these as separate steps so you can see which one failed.

E2E tests (Playwright)

End-to-end tests use Playwright and require the full stack to be running locally (API + console + database). They exercise critical user flows through the browser: login, case creation, triage queue, auto-reply approval, and change request workflow.

Before running E2E tests, start the full development stack (see Contributing). Then:

cd console && npx playwright test

To run in headed mode (shows the browser) for debugging:

cd console && npx playwright test --headed

To open the Playwright UI (interactive, with time-travel debugging):

cd console && npx playwright test --ui

E2E tests are slower (~60–90 seconds for the full suite) and are not required to pass locally before submitting a PR. CI runs them automatically against a Docker Compose stack.

Coverage

Generate a coverage report for unit and integration tests:

npm run test:coverage

This produces an HTML report in coverage/ and prints a summary table to the terminal. Coverage is measured by Vitest's built-in V8 provider.

The project targets 80% line coverage for the service layer. Coverage is not enforced by CI as a hard gate — it is reported as an informational metric on each PR via the coverage summary comment.

Quick reference