# Testing Strategy

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.
