Testing Standards: Unit, Integration, and E2E Tests

Figentra follows a test pyramid strategy: a broad base of fast unit tests, a mid-layer of integration tests that verify service boundaries, and a thin layer of end-to-end tests that validate complete user flows. This balance keeps the suite fast during development while giving you confidence that the system works as a whole. Every package you ship must include tests; coverage thresholds are verified automatically on each build.

Test Types

Unit Tests

Test a single function or class in complete isolation. Mock all external dependencies. Use the .test.ts suffix. These run on every save and should complete in milliseconds.

Integration Tests

Test multiple modules together or verify a service boundary such as a database query or HTTP handler. Use the .spec.ts suffix. These may spin up real infrastructure using containers.

E2E Tests

Test full user flows from the outside — HTTP request to response, or browser interaction to assertion. Live in tests/e2e/. Run in CI against a staging environment.

Test Framework

All Figentra projects use Vitest as the test runner. Vitest provides native TypeScript support, a Jest-compatible API, and first-class support for ESM — no transpilation step required. Add a vitest.config.ts at the root of each package:

vitest.config.ts

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
    environment: 'node',
    coverage: {
      provider: 'v8',
      reporter: ['text', 'lcov'],
    },
  },
});

Setting globals: true makes describe, it, and expect available without explicit imports — matching the Jest experience most contributors already know.

Writing a Unit Test

The example below tests a UserService class. Notice that the test file lives in tests/ and imports from ../src/:

user-service.test.ts

import { describe, it, expect } from 'vitest';
import { UserService } from '../src/user-service';

describe('UserService', () => {
  it('returns a user by id', async () => {
    const service = new UserService();
    const user = await service.findById('123');
    expect(user.id).toBe('123');
  });

  it('throws when the user is not found', async () => {
    const service = new UserService();
    await expect(service.findById('nonexistent')).rejects.toThrow('User not found');
  });
});

Follow the Arrange / Act / Assert pattern inside every it block. Keep each test focused on a single behaviour so failures are easy to diagnose.

Coverage Requirements

80%+ line coverage on all packages

Every published package must reach at least 80% line coverage. The build will fail if any package falls below this threshold, so check your coverage report before publishing.

100% coverage on critical paths

Error handling code, authentication logic, and data validation must have 100% line and branch coverage. Mark these files explicitly in your vitest.config.ts using the include option under coverage.

No untested exports

Every symbol exported from src/index.ts must have at least one direct test. Use the coverage report to identify untested exports before opening a pull request.

Running Tests

# Run the full test suite once
pnpm test

# Run with coverage report
pnpm test:coverage

# Run in watch mode during development
pnpm test:watch

# Run the full test suite once
npm test

# Run with coverage report
npm run test:coverage

# Run in watch mode during development
npm run test:watch

# Run the full test suite once
yarn test

# Run with coverage report
yarn test:coverage

# Run in watch mode during development
yarn test:watch

Shared Test Utilities

Use the @figentra/testing package for common setup and teardown helpers — database seed/reset utilities, mock factory functions, and custom Vitest matchers. Importing from @figentra/testing keeps boilerplate out of individual test files and ensures consistent behavior across the monorepo.

user-service.spec.ts

import { createTestDatabase, teardownTestDatabase } from '@figentra/testing';

beforeAll(async () => {
  await createTestDatabase();
});

afterAll(async () => {
  await teardownTestDatabase();
});

Get Started

Architecture

Standards

Operations

Testing Standards: Unit, Integration, and E2E Tests

Test Types

Unit Tests

Integration Tests

E2E Tests

Test Framework

Writing a Unit Test

Coverage Requirements

Running Tests

Shared Test Utilities

​Test Types

Unit Tests

Integration Tests

E2E Tests

​Test Framework

​Writing a Unit Test

​Coverage Requirements

​Running Tests

​Shared Test Utilities

Test Types

Test Framework

Writing a Unit Test

Coverage Requirements

Running Tests

Shared Test Utilities