@martinffx/atelier 1.2.2 → 1.4.0

package/skills/oracle-testing/references/boundaries.md

@@ -1,579 +0,0 @@
-# Layer Boundary Testing Patterns
-
-Detailed boundary testing patterns for each layer in the architecture.
-
-## Core Principle
-
-Test the contract between layers, not the implementation within layers.
-
-```
-Test here ──────▼──────────────────▼────── Test here
-          Effectful Edge    │    Functional Core
-              (stub)        │       (unit test)
-```
-
-## Entity Boundary (Functional Core)
-
-Pure functions with no dependencies.
-
-### What to Test at Entity Boundary
-
-- Validation rules
-- Business rules
-- Data transformations (fromRequest, toRecord, toResponse)
-- Invariants and state management
-- Edge cases and error conditions
-
-### Entity Test Examples
-
-```typescript
-describe('Order entity', () => {
-  describe('validation', () => {
-    it('rejects empty items', () => {
-      const order = new Order('1', 'C1', [], 'pending', 0);
-      const result = order.validate();
-      expect(result.ok).toBe(false);
-      expect(result.error).toContain('at least one item');
-    });
-
-    it('rejects negative total', () => {
-      const order = new Order('1', 'C1', [], 'pending', -10);
-      const result = order.validate();
-      expect(result.ok).toBe(false);
-      expect(result.error).toContain('total must be positive');
-    });
-
-    it('accepts valid order', () => {
-      const order = new Order('1', 'C1', [{ productId: 'P1', quantity: 1, price: 10 }], 'pending', 10);
-      const result = order.validate();
-      expect(result.ok).toBe(true);
-    });
-  });
-
-  describe('business rules', () => {
-    it('cannot cancel shipped order', () => {
-      const order = new Order('1', 'C1', [], 'shipped', 0);
-      expect(order.canCancel()).toBe(false);
-    });
-
-    it('can cancel pending order', () => {
-      const order = new Order('1', 'C1', [], 'pending', 0);
-      expect(order.canCancel()).toBe(true);
-    });
-
-    it('calculates discount correctly', () => {
-      const order = new Order('1', 'C1', [], 'pending', 100);
-      const discounted = order.applyDiscount(0.1); // 10% discount
-      expect(discounted.total).toBe(90);
-    });
-  });
-
-  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.customerId).toBe('C1');
-      expect(order.total).toBe(35);
-      expect(order.status).toBe('pending');
-    });
-
-    it('converts entity to database record', () => {
-      const order = new Order('123', 'C1', [{ productId: 'P1', quantity: 2, price: 10 }], 'pending', 20);
-      const record = order.toRecord();
-
-      expect(record.id).toBe('123');
-      expect(record.customer_id).toBe('C1');
-      expect(record.status).toBe('pending');
-      expect(record.items).toBe(JSON.stringify([{ productId: 'P1', quantity: 2, price: 10 }]));
-      expect(record.total).toBe(20);
-    });
-
-    it('converts database record back to entity', () => {
-      const record = {
-        id: '123',
-        customer_id: 'C1',
-        items: '[{"productId":"P1","quantity":2,"price":10}]',
-        status: 'pending',
-        total: 20
-      };
-      const order = Order.fromRecord(record);
-
-      expect(order.id).toBe('123');
-      expect(order.customerId).toBe('C1');
-      expect(order.items).toHaveLength(1);
-      expect(order.items[0].productId).toBe('P1');
-    });
-
-    it('converts entity to API response', () => {
-      const order = new Order('123', 'C1', [{ productId: 'P1', quantity: 2, price: 10 }], 'pending', 20);
-      const response = order.toResponse();
-
-      expect(response.id).toBe('123');
-      expect(response.customerId).toBe('C1');
-      expect(response.status).toBe('pending');
-      expect(response.total).toBe(20);
-    });
-  });
-
-  describe('invariants', () => {
-    it('maintains total consistency with items', () => {
-      const order = new Order('1', 'C1', [{ productId: 'P1', quantity: 2, price: 10 }], 'pending', 20);
-
-      // Invariant: total always matches item calculation
-      const calculated = order.items.reduce((sum, item) => sum + item.quantity * item.price, 0);
-      expect(order.total).toBe(calculated);
-    });
-
-    it('prevents invalid status transitions', () => {
-      const order = new Order('1', 'C1', [], 'shipped', 0);
-
-      // Cannot go backwards
-      expect(() => order.updateStatus('pending')).toThrow('Invalid status transition');
-    });
-  });
-});
-```
-
-## Service Boundary (Functional Core)
-
-Orchestration logic with stubbed dependencies.
-
-### What to Test at Service Boundary
-
-- Business workflow execution
-- Orchestration of multiple entities
-- Error propagation and handling
-- Repository interaction patterns
-- Validation and state transitions
-
-### Service Test Examples
-
-```typescript
-describe('OrderService', () => {
-  let service: OrderService;
-  let mockOrderRepo: OrderRepository;
-  let mockInventoryRepo: InventoryRepository;
-
-  beforeEach(() => {
-    mockOrderRepo = {
-      save: vi.fn(),
-      findById: vi.fn(),
-      delete: vi.fn()
-    };
-    mockInventoryRepo = {
-      checkAvailability: vi.fn(),
-      reserve: vi.fn(),
-      release: vi.fn()
-    };
-
-    service = new OrderService(mockOrderRepo, mockInventoryRepo);
-  });
-
-  describe('createOrder', () => {
-    it('creates order with valid data', async () => {
-      mockInventoryRepo.checkAvailability.mockResolvedValue({ available: true });
-      mockOrderRepo.save.mockResolvedValue({ id: '123' });
-
-      const result = await service.createOrder({
-        customerId: 'C1',
-        items: [{ productId: 'P1', quantity: 2 }]
-      });
-
-      expect(result.ok).toBe(true);
-      expect(mockOrderRepo.save).toHaveBeenCalled();
-    });
-
-    it('checks inventory before saving', async () => {
-      mockInventoryRepo.checkAvailability.mockResolvedValue({ available: true });
-      mockOrderRepo.save.mockResolvedValue({ id: '123' });
-
-      await service.createOrder({
-        customerId: 'C1',
-        items: [
-          { productId: 'P1', quantity: 2 },
-          { productId: 'P2', quantity: 3 }
-        ]
-      });
-
-      expect(mockInventoryRepo.checkAvailability).toHaveBeenCalledWith(
-        expect.arrayContaining([
-          expect.objectContaining({ productId: 'P1', quantity: 2 }),
-          expect.objectContaining({ productId: 'P2', quantity: 3 })
-        ])
-      );
-    });
-
-    it('does not save order when inventory unavailable', async () => {
-      mockInventoryRepo.checkAvailability.mockResolvedValue({ available: false });
-
-      const result = await service.createOrder({
-        customerId: 'C1',
-        items: [{ productId: 'P1', quantity: 100 }]
-      });
-
-      expect(result.ok).toBe(false);
-      expect(mockOrderRepo.save).not.toHaveBeenCalled();
-    });
-
-    it('reverses inventory reservation on save failure', async () => {
-      mockInventoryRepo.checkAvailability.mockResolvedValue({ available: true });
-      mockOrderRepo.save.mockRejectedValue(new Error('DB error'));
-
-      const result = await service.createOrder({
-        customerId: 'C1',
-        items: [{ productId: 'P1', quantity: 2 }]
-      });
-
-      expect(result.ok).toBe(false);
-      expect(mockInventoryRepo.release).toHaveBeenCalled();
-    });
-  });
-
-  describe('cancelOrder', () => {
-    it('finds order and cancels it', async () => {
-      mockOrderRepo.findById.mockResolvedValue({ id: '123', status: 'pending' });
-      mockOrderRepo.save.mockResolvedValue({ id: '123', status: 'cancelled' });
-
-      const result = await service.cancelOrder('123');
-
-      expect(result.ok).toBe(true);
-      expect(mockOrderRepo.save).toHaveBeenCalled();
-    });
-
-    it('releases inventory when cancelling', async () => {
-      mockOrderRepo.findById.mockResolvedValue({
-        id: '123',
-        status: 'pending',
-        items: [{ productId: 'P1', quantity: 2 }]
-      });
-
-      await service.cancelOrder('123');
-
-      expect(mockInventoryRepo.release).toHaveBeenCalledWith(
-        expect.arrayContaining([
-          expect.objectContaining({ productId: 'P1', quantity: 2 })
-        ])
-      );
-    });
-
-    it('returns error if order not found', async () => {
-      mockOrderRepo.findById.mockResolvedValue(null);
-
-      const result = await service.cancelOrder('999');
-
-      expect(result.ok).toBe(false);
-      expect(mockOrderRepo.save).not.toHaveBeenCalled();
-    });
-
-    it('returns error if order cannot be cancelled', async () => {
-      mockOrderRepo.findById.mockResolvedValue({ id: '123', status: 'shipped' });
-
-      const result = await service.cancelOrder('123');
-
-      expect(result.ok).toBe(false);
-    });
-  });
-});
-```
-
-## Router Boundary (Effectful Edge)
-
-HTTP request/response handling.
-
-### What to Test at Router Boundary
-
-- Request parsing and validation
-- Response status codes and format
-- Error response handling
-- Request/response transformations
-- HTTP headers and content types
-
-### Router Test Examples
-
-```typescript
-describe('Order API', () => {
-  let app: Express;
-  let mockService: OrderService;
-
-  beforeEach(() => {
-    mockService = {
-      createOrder: vi.fn(),
-      cancelOrder: vi.fn(),
-      getOrder: vi.fn()
-    };
-    app = createApp(mockService);
-  });
-
-  describe('POST /orders', () => {
-    it('returns 201 for valid request', async () => {
-      mockService.createOrder.mockResolvedValue(
-        Ok(new Order('123', 'C1', [], 'pending', 0))
-      );
-
-      const response = await request(app)
-        .post('/orders')
-        .send({ customerId: 'C1', items: [{ productId: 'P1', quantity: 2 }] });
-
-      expect(response.status).toBe(201);
-      expect(response.body.id).toBe('123');
-      expect(response.body.status).toBe('pending');
-    });
-
-    it('returns 400 for invalid request body', async () => {
-      const response = await request(app)
-        .post('/orders')
-        .send({ customerId: 'C1' }); // Missing items
-
-      expect(response.status).toBe(400);
-      expect(response.body.error).toBeDefined();
-    });
-
-    it('returns 400 when service returns error', async () => {
-      mockService.createOrder.mockResolvedValue(
-        Err('Invalid order')
-      );
-
-      const response = await request(app)
-        .post('/orders')
-        .send({ customerId: 'C1', items: [] });
-
-      expect(response.status).toBe(400);
-      expect(response.body.error).toBe('Invalid order');
-    });
-
-    it('includes correct content-type header', async () => {
-      mockService.createOrder.mockResolvedValue(
-        Ok(new Order('123', 'C1', [], 'pending', 0))
-      );
-
-      const response = await request(app)
-        .post('/orders')
-        .send({ customerId: 'C1', items: [{ productId: 'P1', quantity: 2 }] });
-
-      expect(response.headers['content-type']).toMatch(/application\/json/);
-    });
-  });
-
-  describe('GET /orders/:id', () => {
-    it('returns 200 with order', async () => {
-      mockService.getOrder.mockResolvedValue(
-        Ok(new Order('123', 'C1', [], 'pending', 0))
-      );
-
-      const response = await request(app)
-        .get('/orders/123');
-
-      expect(response.status).toBe(200);
-      expect(response.body.id).toBe('123');
-    });
-
-    it('returns 404 when order not found', async () => {
-      mockService.getOrder.mockResolvedValue(
-        Err('Order not found')
-      );
-
-      const response = await request(app)
-        .get('/orders/999');
-
-      expect(response.status).toBe(404);
-    });
-  });
-
-  describe('DELETE /orders/:id', () => {
-    it('returns 204 on successful cancel', async () => {
-      mockService.cancelOrder.mockResolvedValue(Ok(undefined));
-
-      const response = await request(app)
-        .delete('/orders/123');
-
-      expect(response.status).toBe(204);
-      expect(response.body).toEqual({});
-    });
-
-    it('returns 400 when cancel fails', async () => {
-      mockService.cancelOrder.mockResolvedValue(
-        Err('Cannot cancel shipped order')
-      );
-
-      const response = await request(app)
-        .delete('/orders/123');
-
-      expect(response.status).toBe(400);
-      expect(response.body.error).toBe('Cannot cancel shipped order');
-    });
-  });
-});
-```
-
-## Repository Boundary (Effectful Edge)
-
-Database operations.
-
-### What to Test at Repository Boundary
-
-- Save operations preserve data
-- Retrieval returns correct data
-- Updates modify existing records
-- Deletes remove records
-- Complex queries return expected results
-- Transaction handling
-
-### Repository Test Examples
-
-```typescript
-describe('OrderRepository', () => {
-  let repo: OrderRepository;
-  let testDb: Database;
-
-  beforeEach(async () => {
-    testDb = await createTestDatabase();
-    repo = new OrderRepository(testDb);
-  });
-
-  afterEach(async () => {
-    await testDb.close();
-  });
-
-  describe('save', () => {
-    it('saves order to database', async () => {
-      const record = {
-        id: '123',
-        customer_id: 'C1',
-        items: JSON.stringify([{ productId: 'P1', quantity: 2 }]),
-        status: 'pending',
-        total: 20
-      };
-
-      const saved = await repo.save(record);
-
-      expect(saved.id).toBe('123');
-      expect(saved.customer_id).toBe('C1');
-
-      // Verify in database
-      const found = await testDb.orders.findOne({ id: '123' });
-      expect(found).toBeDefined();
-    });
-
-    it('updates existing order', async () => {
-      const record = {
-        id: '123',
-        customer_id: 'C1',
-        items: JSON.stringify([]),
-        status: 'pending',
-        total: 0
-      };
-
-      await repo.save(record);
-
-      const updated = { ...record, status: 'shipped' };
-      await repo.save(updated);
-
-      const found = await testDb.orders.findOne({ id: '123' });
-      expect(found.status).toBe('shipped');
-    });
-  });
-
-  describe('findById', () => {
-    it('retrieves order by id', async () => {
-      const record = {
-        id: '123',
-        customer_id: 'C1',
-        items: JSON.stringify([]),
-        status: 'pending',
-        total: 0
-      };
-
-      await repo.save(record);
-      const found = await repo.findById('123');
-
-      expect(found).toEqual(record);
-    });
-
-    it('returns null for non-existent id', async () => {
-      const found = await repo.findById('999');
-
-      expect(found).toBeNull();
-    });
-  });
-
-  describe('delete', () => {
-    it('removes order from database', async () => {
-      const record = {
-        id: '123',
-        customer_id: 'C1',
-        items: JSON.stringify([]),
-        status: 'pending',
-        total: 0
-      };
-
-      await repo.save(record);
-      await repo.delete('123');
-
-      const found = await testDb.orders.findOne({ id: '123' });
-      expect(found).toBeUndefined();
-    });
-  });
-});
-```
-
-## Consumer Boundary (Effectful Edge)
-
-Event message handling.
-
-### Consumer Test Examples
-
-```typescript
-describe('OrderConsumer', () => {
-  let consumer: OrderConsumer;
-  let mockService: OrderService;
-
-  beforeEach(() => {
-    mockService = {
-      processOrder: vi.fn(),
-      handlePayment: vi.fn()
-    };
-    consumer = new OrderConsumer(mockService);
-  });
-
-  describe('OrderPlaced event', () => {
-    it('calls service with event data', async () => {
-      mockService.processOrder.mockResolvedValue(Ok({}));
-
-      const event = {
-        type: 'OrderPlaced',
-        data: { orderId: '123', customerId: 'C1' }
-      };
-
-      await consumer.handle(event);
-
-      expect(mockService.processOrder).toHaveBeenCalledWith('123');
-    });
-
-    it('ignores unknown event types', async () => {
-      const event = {
-        type: 'UnknownEvent',
-        data: {}
-      };
-
-      await consumer.handle(event);
-
-      expect(mockService.processOrder).not.toHaveBeenCalled();
-    });
-  });
-});
-```
-
-## Summary Table
-
-| Boundary | Test Type | What to Stub | What to Assert |
-|----------|-----------|--------------|-----------------|
-| **Entity** | Unit | Nothing (pure) | Validation, rules, transforms |
-| **Service** | Unit | Repositories, other services | Orchestration logic, error handling |
-| **Router** | Integration | Service | Status codes, response format, headers |
-| **Repository** | Integration | Database connection | CRUD operations, queries |
-| **Consumer** | Integration | Service, event source | Event parsing, service calls |