Eve library

Testing Strategy

Guide

Revision 1

On this page

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-jest in ESM mode. Every service should use jest.config.service.cjs as the base config.
  • Mobile: Jest (React Native setup) under mobile/.
  • Web: Vitest for UI/unit tests in web/.
  • E2E: Playwright (tests/), run with npx playwright test.

Use the framework that matches the area you are changing; avoid mixing frameworks inside a single package.

Standard Jest setup for services#

  1. Create jest.config.cjs in the service and extend the shared config:

    js
    const service = require('../../jest.config.service.cjs');
    
    /** @type {import('jest').Config} */
    module.exports = {
      ...service,
      rootDir: __dirname,
      // Add per-service overrides here (e.g., moduleNameMapper mocks)
    };
    
  2. Keep configs in .cjs (do not use .js/ESM configs); Jest picks them automatically.

  3. jest.config.service.cjs enforces:

    • ESM test execution (ts-jest/presets/default-esm)
    • Coverage thresholds at 70% (branches/functions/lines/statements)
    • Coverage collection from src/**/*.{js,ts} excluding dist and tests
    • Common moduleNameMapper to strip .js extensions for NodeNext

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 than listen(). Live under __tests__/ or tests/.
  • 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/-g for 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:

  1. 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);
    
  2. 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);
    
  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();
    
  4. 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:

  1. 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);
    
  2. 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 });
    
  3. Error condition testing

    javascript
    // ✅ GOOD: Tests error handling behavior
    await expect(service.process({ invalid: true })).rejects.toThrow(
      'Validation failed: missing required field'
    );
    
  4. 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 testSkipVectorDbCalls or MOCK_MODE that 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* or MOCK_MODE flags 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.