Lilith uses a small set of testing tools with clear roles. Follow this guidance to keep tests consistent across the monorepo.
Framework choices#
- Services (Node/Fastify): Jest +
ts-jestin ESM mode. Every service should usejest.config.service.cjsas the base config. - Mobile: Jest (React Native setup) under
mobile/. - Web: Vitest for UI/unit tests in
web/. - E2E: Playwright (
tests/), run withnpx playwright test.
Use the framework that matches the area you are changing; avoid mixing frameworks inside a single package.
Standard Jest setup for services#
-
Create
jest.config.cjsin the service and extend the shared config:jsconst service = require('../../jest.config.service.cjs'); /** @type {import('jest').Config} */ module.exports = { ...service, rootDir: __dirname, // Add per-service overrides here (e.g., moduleNameMapper mocks) }; -
Keep configs in
.cjs(do not use.js/ESM configs); Jest picks them automatically. -
jest.config.service.cjsenforces:- ESM test execution (
ts-jest/presets/default-esm) - Coverage thresholds at 70% (branches/functions/lines/statements)
- Coverage collection from
src/**/*.{js,ts}excludingdistand tests - Common
moduleNameMapperto strip.jsextensions for NodeNext
- ESM test execution (
Per-service additions should be minimal: mocks in moduleNameMapper, optional
setupFilesAfterEnv, or test-specific ignore patterns.
When to write which tests#
- Unit tests: Fast, isolated, use Fastify
app.inject()rather thanlisten(). Live under__tests__/ortests/. - Integration tests: For service-to-service behaviour, still prefer injection and mocked dependencies over real network calls.
- E2E: Only for user flows across services (Playwright). Target a file or
test via
--project/-gfor focus.
Coverage expectations#
- Baseline: 70% global (branches/functions/lines/statements) for services; apply similar targets for mobile/web suites.
- Prefer meaningful assertions over coverage-only executions; remove trivial "coverage-fill" tests.
Test Quality Policy#
Prohibited Patterns#
The following test patterns are not acceptable and must be refactored:
-
Static value assertions only
javascript// ❌ BAD: Only asserts static/hardcoded values expect(agentCount).toBe(5); expect(config.version).toBe('1.0.0'); expect(Array.isArray(items)).toBe(true); -
Length-only assertions without content validation
javascript// ❌ BAD: Only checks array length, not actual behavior const results = await service.getItems(); expect(results.length).toBe(3); -
Mock-only tests that don't exercise real code
javascript// ❌ BAD: Test only verifies mock was called, not behavior const mockFn = jest.fn().mockResolvedValue({ success: true }); await mockFn(); expect(mockFn).toHaveBeenCalled(); -
Type-only assertions
javascript// ❌ BAD: Only checks types, not actual functionality expect(typeof result).toBe('object'); expect(result).toBeDefined();
Required Test Patterns#
Tests must validate actual behavior:
-
Functional behavior tests
javascript// ✅ GOOD: Tests actual service behavior const result = await userService.createUser({ email: 'test@example.com' }); expect(result.id).toMatch(/^user_/); expect(result.email).toBe('test@example.com'); expect(result.createdAt).toBeInstanceOf(Date); -
State change verification
javascript// ✅ GOOD: Verifies state actually changed await cart.addItem({ productId: 'prod_123', quantity: 2 }); const items = await cart.getItems(); expect(items).toContainEqual({ productId: 'prod_123', quantity: 2 }); -
Error condition testing
javascript// ✅ GOOD: Tests error handling behavior await expect(service.process({ invalid: true })).rejects.toThrow( 'Validation failed: missing required field' ); -
Integration with test doubles (not pure mocks)
javascript// ✅ GOOD: Uses in-memory implementation, tests real logic const db = createInMemoryDatabase(); const service = createService({ database: db }); await service.save({ id: '1', data: 'test' }); expect(await db.get('1')).toEqual({ id: '1', data: 'test' });
Test Flags and Mock Modes#
- Avoid skip flags in production code: Do not add flags like
testSkipVectorDbCallsorMOCK_MODEthat bypass real implementations - Use dependency injection: Swap implementations via constructor, not runtime flags
- Test doubles over mocks: Prefer in-memory implementations that exercise real code paths
- Environment-based skipping: For tests requiring external services (LLM,
databases), use
describe.skipIf(!process.env.INTEGRATION_TESTS)at the test level, not skip flags in production code
PR Checklist for Tests#
Before merging, verify:
- No tests only assert static/hardcoded values
- Tests exercise actual code paths, not just mocks
- Error cases are tested with real error conditions
- No new
testSkip*orMOCK_MODEflags added to production code - Coverage increase comes from meaningful tests, not coverage-fill patterns
Running tests locally#
- Services:
npm test --workspace services/<name>(inherits shared config). - Web:
npm run test --workspace web. - Mobile:
npm test --workspace mobile. - E2E:
npx playwright test tests/<file>.spec.js --reporter=line.
Keep runs scoped and fast; add --config or -g to narrow focus when
iterating.