oracle-testing

Testing Skill

Stub-Driven Test-Driven Development and layer boundary testing for functional core and effectful edge architecture.

Core Principle: Stub-Driven TDD

Test-Driven Development workflow for the functional core / effectful edge pattern:

1. Stub   → Create minimal interface/function signatures
2. Test   → Write tests against stubs
3. Implement → Make tests pass with real implementation
4. Refactor  → Improve code while keeping tests green

Key insight: Write interface signatures first, test against those, then implement—not the other way around.

See [references/stub-driven-tdd.md] for complete workflow examples.

Layer Boundary Testing

Test at the boundaries between functional core and effectful edge, not internal implementation.

Test here ──────▼──────────────────▼────── Test here
          Effectful Edge    │    Functional Core
              (stub)        │       (unit test)

Where to Test Each Layer

Layer	Test Type	What to Stub	What to Assert
Entity	Unit	Nothing (pure)	Validation, rules, transforms
Service	Unit	Repositories	Orchestration logic, error handling
Router	Integration	Service	Status codes, response format
Repository	Integration	DB connection	CRUD operations, queries
Consumer	Integration	Service	Event parsing, service calls

See [references/boundaries.md] for detailed testing patterns by layer.

Functional Core Testing

Entity Tests (Pure Functions)

Focus: Validation, business rules, data transformations

describe('Order entity', () => {
  describe('validation', () => {
    it('rejects empty items', () => {
      const order = new Order('1', 'C1', [], 'pending', 0);
      expect(order.validate().ok).toBe(false);
    });
  });

  describe('business rules', () => {
    it('prevents cancelling shipped order', () => {
      const order = new Order('1', 'C1', [], 'shipped', 0);
      expect(order.canCancel()).toBe(false);
    });
  });

  describe('transformations', () => {
    it('converts request to entity with calculated total', () => {
      const order = Order.fromRequest({
        customerId: 'C1',
        items: [
          { productId: 'P1', quantity: 2, price: 10 },
          { productId: 'P2', quantity: 1, price: 15 }
        ]
      });
      expect(order.total).toBe(35);
    });
  });
});

Service Tests (Stubbed Dependencies)

Focus: Orchestration logic with stubbed repositories

describe('OrderService.createOrder', () => {
  let service: OrderService;
  let mockRepo: OrderRepository;

  beforeEach(() => {
    mockRepo = {
      save: vi.fn().mockResolvedValue({ id: '123' }),
      findById: vi.fn()
    };
    service = new OrderService(mockRepo);
  });

  it('creates order with valid data', async () => {
    const result = await service.createOrder({
      customerId: 'C1',
      items: [{ productId: 'P1', quantity: 2 }]
    });

    expect(result.ok).toBe(true);
    expect(mockRepo.save).toHaveBeenCalled();
  });

  it('does not save when validation fails', async () => {
    const result = await service.createOrder({
      customerId: 'C1',
      items: [] // Invalid
    });

    expect(result.ok).toBe(false);
    expect(mockRepo.save).not.toHaveBeenCalled();
  });
});

See [references/core-testing.md] for comprehensive Entity and Service examples.

Effectful Edge Testing

Router, Repository, Consumer Integration Tests

Focus: Real HTTP/database/events with stubbed core

// Router: real HTTP, stub service
describe('POST /orders', () => {
  it('returns 201 for valid request', async () => {
    const mockService = {
      createOrder: vi.fn().mockResolvedValue(Ok({ id: '123' }))
    };
    const app = createApp(mockService);

    const response = await request(app)
      .post('/orders')
      .send({ customerId: 'C1', items: [{ productId: 'P1', quantity: 2 }] });

    expect(response.status).toBe(201);
  });
});

// Repository: real test database
describe('OrderRepository.save', () => {
  it('persists order to database', async () => {
    const repo = new OrderRepository(testDb);
    const saved = await repo.save({
      id: '123',
      customer_id: 'C1',
      items: '[]',
      status: 'pending',
      total: 0
    });

    const found = await testDb.orders.findOne({ id: '123' });
    expect(found).toBeDefined();
  });
});

// Consumer: real events, stub service
describe('OrderConsumer', () => {
  it('handles OrderPlaced event', async () => {
    const mockService = {
      processOrder: vi.fn().mockResolvedValue(Ok({}))
    };
    const consumer = new OrderConsumer(mockService);

    await consumer.handle({
      type: 'OrderPlaced',
      data: { orderId: '123' }
    });

    expect(mockService.processOrder).toHaveBeenCalledWith('123');
  });
});

See [references/edge-testing.md] for Router, Repository, Consumer, Producer, and Client patterns.

Test Coverage Guidelines

Aim for strategic coverage, not 100%:

High Coverage (Critical):

• Entity validation and business rules
• Service orchestration logic
• Critical user journeys (integration tests)
• Data transformations with logic

Medium Coverage (Important):

• Error handling paths
• Edge cases in business logic
• API contract validation

Low Coverage (Optional):

• Simple getters/setters
• Framework boilerplate
• Trivial mappings
• Internal utilities

What NOT to Test

Avoid testing implementation details, framework behavior, and trivial code:

• Don't test private methods (test through public API)
• Don't test simple getters/setters (no logic = no test value)
• Don't test framework behavior (Express, database driver already tested)
• Don't test third-party library behavior (lodash, validation libraries)
• Don't test trivial mappings without logic

See [references/anti-patterns.md] for anti-patterns with examples and fixes.

Testing → Implementation Flow

Follow this dependency order:

1. Entity tests    (pure functions, fast)
2. Service tests   (stubbed dependencies, fast)
3. Integration tests (real IO, slower)

This enables TDD: write tests first at lower layers, then implement, then build upward.

Quick Reference

For Entity Testing: See [references/core-testing.md] For Service Testing: See [references/core-testing.md] For Router/Repo/Consumer: See [references/edge-testing.md] For Workflow Examples: See [references/stub-driven-tdd.md] For What NOT to Do: See [references/anti-patterns.md]