Testing Guide

Last Updated: 2025-12-04
Coverage Goal: 70%+ overall, 80%+ for critical paths

Overview

This guide covers testing strategies, patterns, and best practices for the Synap backend. We use Vitest for all testing with real PostgreSQL databases for integration tests.

Quick Start

Running Tests

# Run all tests
pnpm test
 
# Run specific package tests
pnpm --filter @synap/database test
pnpm --filter @synap/domain test
 
# Run with coverage
pnpm --filter @synap/database test:coverage
 
# Watch mode
pnpm --filter @synap/database test:watch

Test Infrastructure

Vitest Configuration

Each package has a vitest.config.ts that auto-loads environment variables:

// packages/database/vitest.config.ts
import { defineConfig } from 'vitest/config';
import { loadEnv } from 'vite';
 
export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '');
  
  return {
    test: {
      globals: true,
      environment: 'node',
      setupFiles: ['./src/__tests__/setup.ts'],
      env: {
        DATABASE_URL: env.DATABASE_URL || 'postgresql://postgres:postgres@localhost:5432/synap',
        NODE_ENV: 'test',
      },
      coverage: {
        provider: 'v8',
        reporter: ['text', 'json', 'html'],
        exclude: ['node_modules/', 'dist/', '**/*.test.ts'],
      },
    },
  };
});

Environment Files

.env.test (auto-loaded):

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/synap
OPENAI_API_KEY=test-key
NODE_ENV=test

Test Data Management

Convention: test-* Prefix

All test data must use test- prefix for user IDs:

// ✅ Correct
const userId = generateTestUserId();  // Returns "test-abc123"
 
// ❌ Wrong
const userId = 'user-123';  // Will pollute real data

Cleanup Pattern

// setup.ts or test file
beforeAll(async () => {
  // Clean all test data before running
  await sql`DELETE FROM events_timescale WHERE user_id LIKE 'test-%'`;
  await sql`DELETE FROM entities WHERE user_id LIKE 'test-%'`;
  await sql`DELETE FROM entity_vectors WHERE user_id LIKE 'test-%'`;
});
 
afterAll(async () => {
  // Clean up after tests
  await sql`DELETE FROM events_timescale WHERE user_id LIKE 'test-%'`;
  await sql.end();  // Close connection
});

Test Utilities

Helper Functions

packages/database/src/__tests__/test-utils.ts:

import crypto from 'crypto';
import { sql } from '../index.js';
 
// Generate test user ID with prefix
export function generateTestUserId(prefix = 'test'): string {
  return `${prefix}-${crypto.randomUUID().slice(0, 8)}`;
}
 
// Clean all test data
export async function cleanTestData() {
  await sql`DELETE FROM events_timescale WHERE user_id LIKE 'test-%'`;
  await sql`DELETE FROM entities WHERE user_id LIKE 'test-%'`;
  await sql`DELETE FROM entity_vectors WHERE user_id LIKE 'test-%'`;
  await sql`DELETE FROM conversation_messages WHERE user_id LIKE 'test-%'`;
}
 
// Wait for async operations
export async function waitFor(ms: number): Promise<void> {
  return new Promise(resolve => setTimeout(resolve, ms));
}
 
// Create test event
export function createTestEvent(userId: string, type: string, data: any): SynapEvent {
  return {
    id: crypto.randomUUID(),
    version: 'v1',
    type,
    userId,
    data,
    source: 'api',
    timestamp: new Date(),
  };
}

Repository Testing

Example: EventRepository Tests

import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { sql } from '@synap/database';
import { eventRepository } from '@synap/database';
import { generateTestUserId, createTestEvent } from './test-utils.js';
 
describe('EventRepository', () => {
  beforeAll(async () => {
    await sql`DELETE FROM events_timescale WHERE user_id LIKE 'test-%'`;
  });
 
  afterAll(async () => {
    await sql`DELETE FROM events_timescale WHERE user_id LIKE 'test-%'`;
    await sql.end();
  });
 
  it('should append event successfully', async () => {
    const userId = generateTestUserId();
    const event = createTestEvent(userId, 'note.created', { content: 'Test' });
 
    await eventRepository.append(event);
 
    const [stored] = await sql`
      SELECT * FROM events_timescale WHERE user_id = ${userId}
    `;
 
    expect(stored).toBeDefined();
    expect(stored.type).toBe('note.created');
  });
 
  it('should enforce user isolation', async () => {
    const user1 = generateTestUserId();
    const user2 = generateTestUserId();
 
    await eventRepository.append(createTestEvent(user1, 'note.created', {}));
    await eventRepository.append(createTestEvent(user2, 'note.created', {}));
 
    const user1Events = await sql`
      SELECT * FROM events_timescale WHERE user_id = ${user1}
    `;
 
    expect(user1Events.length).toBe(1);
    expect(user1Events[0].user_id).toBe(user1);
  });
});

Service Testing (with Mocks)

Example: VectorService with Mocked Embeddings

import { describe, it, expect, vi } from 'vitest';
import { VectorService } from '../services/vectors.js';
 
// Mock AI embeddings to avoid real API calls
vi.mock('@synap/ai-embeddings', () => ({
  generateEmbedding: vi.fn(async (text: string) => {
    // Return deterministic mock based on text
    const hash = text.split('').reduce((acc, c) => acc + c.charCodeAt(0), 0);
    return Array.from({ length: 1536 }, (_, i) => 
      Math.sin(hash + i) * 0.5 + 0.5
    );
  }),
}));
 
describe('VectorService', () => {
  const vectorService = new VectorService(db);
 
  it('should store embedding', async () => {
    const userId = generateTestUserId();
    const entityId = crypto.randomUUID();
 
    await vectorService.upsertEntityEmbedding({
      entityId,
      userId,
      entityType: 'note',
      title: 'Test',
      content: 'Test content',
    });
 
    const [stored] = await sql`
      SELECT * FROM entity_vectors WHERE entity_id = ${entityId}
    `;
 
    expect(stored).toBeDefined();
  });
});

Testing Inngest Workers

Overview

Synap uses Inngest workers for 3-phase event processing. Testing workers requires:

Mocking Inngest events
Testing permission validation logic
Verifying DB operations
Testing event emissions

Example: Permission Validator Worker

Worker code:

// packages/jobs/src/functions/permission-validator.ts
export const permissionValidator = inngest.createFunction(
  { id: 'permission-validator' },
  [{ event: 'entities.create.requested' }],
  async ({ event }) => {
    const hasPermission = event.user.id === event.data.userId;
    
    if (hasPermission) {
      await publishEvent({
        type: 'entities.create.approved',
        data: event.data,
        userId: event.user.id
      });
    }
    
    return { approved: hasPermission };
  }
);

Test:

import { describe, it, expect, beforeAll, vi } from 'vitest';
import { permissionValidator } from '../permission-validator.js';
 
// Mock publishEvent
vi.mock('@synap/events', () => ({
  publishEvent: vi.fn()
}));
 
describe('Permission Validator Worker', () => {
  it('should approve when user owns resource', async () => {
    const userId = generateTestUserId();
    
    // Mock Inngest event
    const mockEvent = {
      event: {
        name: 'entities.create.requested',
        data: { userId, type: 'note', title: 'Test' },
        user: { id: userId }
      },
      step: {
        run: vi.fn((name, fn) => fn())  // Execute steps immediately
      }
    };
    
    const result = await permissionValidator.handler(mockEvent);
    
    expect(result.approved).toBe(true);
    expect(publishEvent).toHaveBeenCalledWith({
      type: 'entities.create.approved',
      data: expect.objectContaining({ userId }),
      userId
    });
  });
  
  it('should reject when user does not own resource', async () => {
    const ownerId = generateTestUserId();
    const requesterId = generateTestUserId();
    
    const mockEvent = {
      event: {
        name: 'entities.create.requested',
        data: { userId: ownerId, type: 'note' },
        user: { id: requesterId }  // Different user
      },
      step: {
        run: vi.fn((name, fn) => fn())
      }
    };
    
    const result = await permissionValidator.handler(mockEvent);
    
    expect(result.approved).toBe(false);
    expect(publishEvent).not.toHaveBeenCalled();
  });
});

Testing CRUD Workers

Worker code:

// packages/jobs/src/functions/entities.ts
export const entitiesWorker = inngest.createFunction(
  { id: 'entities-worker' },
  [{ event: 'entities.create.approved' }],
  async ({ event, step }) => {
    await step.run('create-entity', async () => {
      await db.insert(entities).values({
        id: event.data.entityId,
        userId: event.user.id,
        type: event.data.type,
        title: event.data.title
      });
    });
    
    await step.run('emit-validated', async () => {
      await publishEvent({
        type: 'entities.create.validated',
        data: { entityId: event.data.entityId },
        userId: event.user.id
      });
    });
  }
);

Test:

describe('Entities Worker', () => {
  beforeAll(async () => {
    await cleanTestData();
  });
  
  afterAll(async () => {
    await cleanTestData();
    await sql.end();
  });
  
  it('should create entity on approved event', async () => {
    const userId = generateTestUserId();
    const entityId = crypto.randomUUID();
    
    const mockEvent = {
      event: {
        name: 'entities.create.approved',
        data: {
          entityId,
          type: 'note',
          title: 'Test Note'
        },
        user: { id: userId }
      },
      step: {
        run: vi.fn((name, fn) => fn())
      }
    };
    
    await entitiesWorker.handler(mockEvent);
    
    // Verify DB operation
    const [created] = await sql`
      SELECT * FROM entities WHERE id = ${entityId}
    `;
    
    expect(created).toBeDefined();
    expect(created.user_id).toBe(userId);
    expect(created.type).toBe('note');
    expect(created.title).toBe('Test Note');
    
    // Verify validated event emission
    expect(publishEvent).toHaveBeenCalledWith({
      type: 'entities.create.validated',
      data: { entityId },
      userId
    });
  });
});

Testing 3-Phase Flow

Integration test:

describe('3-Phase Event Flow', () => {
  it('should complete full flow: requested → approved → validated', async () => {
    const userId = generateTestUserId();
    const entityId = crypto.randomUUID();
    
    // Phase 1: Publish .requested event
    await publishEvent({
      type: 'entities.create.requested',
      data: { entityId, type: 'note', title: 'Test' },
      userId
    });
    
    // Verify event in TimescaleDB
    const [requestedEvent] = await sql`
      SELECT * FROM events_timescale
      WHERE type = 'entities.create.requested'
      AND subject_id = ${entityId}
    `;
    expect(requestedEvent).toBeDefined();
    
    // Phase 2: Simulate permission validator
    const permResult = await permissionValidator.handler({
      event: {
        name: 'entities.create.requested',
        data: { entityId, userId, type: 'note' },
        user: { id: userId }
      },
      step: { run: (_, fn) => fn() }
    });
    
    expect(permResult.approved).toBe(true);
    
    // Verify .approved event
    const [approvedEvent] = await sql`
      SELECT * FROM events_timescale
      WHERE type = 'entities.create.approved'
      AND subject_id = ${entityId}
    `;
    expect(approvedEvent).toBeDefined();
    
    // Phase 3: Simulate entities worker
    await entitiesWorker.handler({
      event: {
        name: 'entities.create.approved',
        data: { entityId, type: 'note', title: 'Test' },
        user: { id: userId }
      },
      step: { run: (_, fn) => fn() }
    });
    
    // Verify entity created
    const [entity] = await sql`
      SELECT * FROM entities WHERE id = ${entityId}
    `;
    expect(entity).toBeDefined();
    
    // Verify .validated event
    const [validatedEvent] = await sql`
      SELECT * FROM events_timescale
      WHERE type = 'entities.create.validated'
      AND subject_id = ${entityId}
    `;
    expect(validatedEvent).toBeDefined();
    
    // Complete audit trail
    const allEvents = await sql`
      SELECT type FROM events_timescale
      WHERE subject_id = ${entityId}
      ORDER BY timestamp
    `;
    
    expect(allEvents.map(e => e.type)).toEqual([
      'entities.create.requested',
      'entities.create.approved',
      'entities.create.validated'
    ]);
  });
});

Testing Patterns

1. User Isolation

Always test that users can't access each other's data:

it('should enforce user isolation', async () => {
  const user1 = generateTestUserId();
  const user2 = generateTestUserId();
 
  // Create data for both users
  await createEntityForUser(user1);
  await createEntityForUser(user2);
 
  // Query should only return user1's data
  const results = await service.getEntities({ userId: user1 });
  
  expect(results.every(r => r.userId === user1)).toBe(true);
});

2. Data Serialization

Test that complex data types are handled correctly:

it('should serialize Date objects', async () => {
  const date = new Date('2024-01-15T10:30:00Z');
  const event = createTestEvent(userId, 'test', { date });
 
  await eventRepository.append(event);
 
  const [stored] = await sql`SELECT data FROM events WHERE id = ${event.id}`;
  expect(new Date(stored.data.date)).toEqual(date);
});

3. Edge Cases

Always test boundaries and edge cases:

it('should handle empty results', async () => {
  const userId = generateTestUserId();
  const results = await service.search({ userId, query: '' });
  expect(results).toEqual([]);
});
 
it('should handle large data', async () => {
  const largeContent = 'A'.repeat(100_000);  // 100KB
  const event = createTestEvent(userId, 'test', { content: largeContent });
  await expect(eventRepository.append(event)).resolves.not.toThrow();
});
 
it('should handle special characters', async () => {
  const specialContent = "It's a test with \"quotes\" \n newlines & symbols: @#$%";
  const event = createTestEvent(userId, 'test', { content: specialContent });
  await expect(eventRepository.append(event)).resolves.not.toThrow();
});

4. Concurrent Operations

Test concurrent writes:

it('should handle concurrent writes', async () => {
  const userId = generateTestUserId();
  const events = Array.from({ length: 10 }, (_, i) =>
    createTestEvent(userId, 'test', { index: i })
  );
 
  // Run all appends concurrently
  await Promise.all(events.map(e => eventRepository.append(e)));
 
  const stored = await sql`
    SELECT * FROM events WHERE user_id = ${userId}
  `;
 
  expect(stored.length).toBe(10);
});

Coverage Goals

Critical Paths (80%+ coverage)

EventRepository
VectorRepository
EntityRepository
Core domain services

Standard Paths (70%+ coverage)

API routes
Business logic
Utilities

Lower Priority (50%+ coverage)

UI components
Admin tools
Dev utilities

Best Practices

1. Import Test Globals Explicitly

// ✅ Always import, even with globals: true
import { describe, it, expect, beforeAll, afterAll } from 'vitest';

2. Use Descriptive Test Names

// ✅ Clear what's being tested
it('should enforce user isolation in search results', async () => { /* ... */ });
 
// ❌ Vague
it('should work', async () => { /* ... */ });

3. One Assertion Per Test (When Possible)

// ✅ Focused test
it('should return correct count', async () => {
  const results = await service.count({ userId });
  expect(results).toBe(5);
});
 
// ❌ Multiple unrelated assertions
it('should do everything', async () => {
  expect(a).toBe(1);
  expect(b).toBe(2);
  expect(c).toBe(3);
});

4. Clean Up Properly

// ✅ Clean before and after
beforeAll(async () => await cleanTestData());
afterAll(async () => {
  await cleanTestData();
  await sql.end();  // Close connections
});

Common Pitfalls

❌ Not Using test- Prefix

const userId = 'user-123';  // ❌ Pollutes database

❌ Forgetting to Close Connections

afterAll(async () => {
  // ❌ Missing sql.end()
  await cleanTestData();
});

❌ Testing with Real API Keys

// ❌ Uses real OpenAI API
const embedding = await generateEmbedding(text);
 
// ✅ Mock it
vi.mock('@synap/ai-embeddings', () => ({ /* mock */ }));

❌ Not Cleaning Between Tests

// ❌ Tests depend on each other
it('test 1', async () => { await create(); });
it('test 2', async () => { /* expects test 1 data */ });
 
// ✅ Independent tests
beforeEach(async () => await cleanTestData());

Running Tests in CI/CD

GitHub Actions Example

name: Tests
 
on: [push, pull_request]
 
jobs:
  test:
    runs-on: ubuntu-latest
    
    services:
      postgres:
        image: pgvector/pgvector:pg16
        env:
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: synap
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432
    
    steps:
      - uses: actions/checkout@v3
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v3
        with:
          node-version: 20
          cache: 'pnpm'
      
      - run: pnpm install
      - run: pnpm build
      - run: pnpm test
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/synap

Debugging Tests

Enable Debug Logging

LOG_LEVEL=debug pnpm test

Run Single Test

it.only('should debug this specific test', async () => {
  // Only this test runs
});

Use Console Logging

console.log('Debug value:', result);  // Shows in test output

Check Database State

const state = await sql`SELECT * FROM table WHERE condition`;
console.log('Database state:', state);

Resources

Vitest Docs: https://vitest.dev
Test Examples: packages/database/src/__tests__/
Test Utilities: packages/database/src/__tests__/test-utils.ts
Error Report: error_resolution_report.md - Common test issues

Summary

Key Takeaways:

Always use test- prefix for test data
Clean up before and after tests
Test user isolation
Mock external APIs
Test edge cases (empty, large, special chars)
Keep tests independent
Aim for 70%+ coverage

Next Steps:

Review existing tests as examples
Write tests for new features
Run coverage reports regularly
Fix failing tests immediately

Testing Guide

On this page