@comfanion/workflow 4.38.4-dev.1 → 4.39.0-dev.0

package/src/opencode/skills/test-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: test-design
-description: Use when designing test strategy, writing unit/integration tests, or improving coverage
+description: Design test strategy, write unit/integration/E2E tests, plan test coverage, and define testing approach. Use when designing tests, writing test cases, planning test coverage, or when user mentions "test design", "test strategy", "unit tests", "integration tests", "test coverage", or "testing approach".
 license: MIT
 compatibility: opencode
 metadata:
@@ -10,102 +10,96 @@ metadata:
 
 # Test Design Skill
 
-Principles for writing effective tests.
-
-## Test Naming
-
+```xml
+<test_design>
+  <definition>Design test strategy, write unit/integration/E2E tests</definition>
+  
+  <test_types>
+    <unit>Individual components, fast, isolated → See [unit-tests.md](unit-tests.md)</unit>
+    <integration>Module contracts, API boundaries → See [integration-tests.md](integration-tests.md)</integration>
+    <e2e>User scenarios, critical paths → See [e2e-tests.md](e2e-tests.md)</e2e>
+  </test_types>
+  
+  <test_pyramid>
+    <many>Unit tests (70-80% coverage)</many>
+    <some>Integration tests (50-60% coverage)</some>
+    <few>E2E tests (20-30% critical paths)</few>
+  </test_pyramid>
+  
+  <quick_reference>
+    <what_to_test>Public API, Business logic, Error handling, Edge cases</what_to_test>
+    <what_not_to_test>Private methods, Getters/setters, Framework internals</what_not_to_test>
+    <naming>Test{Component}_{Method}_{Scenario}_{Expected}</naming>
+    <structure>AAA: Arrange → Act → Assert</structure>
+  </quick_reference>
+  
+  <coverage_targets>
+    <domain>80%+</domain>
+    <application>70%+</application>
+    <infrastructure>50%+</infrastructure>
+    <focus>Critical paths, not 100%</focus>
+  </coverage_targets>
+  
+  <when_to_test>
+    <tdd>Red → Green → Refactor (clear requirements)</tdd>
+    <after>Write code first (prototyping, unclear requirements)</after>
+  </when_to_test>
+</test_design>
 ```
-Test{Component}_{Method}_{Scenario}_{Expected}
-
-Examples:
-- TestUser_Create_ValidData_Success
-- TestUser_Create_EmptyEmail_ReturnsError
-- TestOrder_Cancel_AlreadyShipped_Fails
-```
-
-## Test Structure (AAA)
 
-```
-// Arrange - Setup
-input := ...
-expected := ...
+---
 
-// Act - Execute
-result := sut.Method(input)
+## Detailed Guides
 
-// Assert - Verify
-assert(result == expected)
-```
+**Unit Testing:**
+- [unit-tests.md](unit-tests.md) - Basics: what to test, AAA pattern, naming
+- [unit-tests-patterns.md](unit-tests-patterns.md) - Table-driven, state transitions, validation
+- [unit-tests-mocking.md](unit-tests-mocking.md) - Mocking, DI, test isolation
 
-## Table-Driven Tests
+**Integration Testing:**
+- [integration-tests.md](integration-tests.md) - Module contracts, API boundaries, events
 
-When testing multiple scenarios of same function:
+**E2E Testing:**
+- [e2e-tests.md](e2e-tests.md) - User scenarios, critical paths, smoke tests
 
-```
-tests := []struct {
-    name     string
-    input    Input
-    expected Output
-    wantErr  bool
-}{
-    {"valid input", validInput(), expectedOutput(), false},
-    {"empty input", emptyInput(), nil, true},
-}
-
-for _, tt := range tests {
-    t.Run(tt.name, func(t *testing.T) {
-        result, err := sut.Method(tt.input)
-        // assert
-    })
-}
-```
+**Strategy:**
+- [test-strategy.md](test-strategy.md) - Test pyramid, coverage targets, when to use what
 
-## What to Test
+**Templates:**
+- [templates/template-integration.md](templates/template-integration.md) - Architecture integration tests
+- [templates/template-module.md](templates/template-module.md) - Module test cases
 
-**Always test:**
-- Public API / exported functions
-- Business logic / domain rules
-- Error handling paths
-- Edge cases (empty, nil, zero, max)
-- State transitions
+---
 
-**Skip testing:**
-- Private implementation details
-- Simple getters/setters
-- Generated code
-- Framework internals
+## Quick Example
+
+```typescript
+// Unit test
+it('calculates order total', () => {
+  const order = new Order();
+  order.addItem({ price: 100, quantity: 2 });
+  expect(order.calculateTotal()).toBe(200);
+});
+
+// Integration test
+it('saves order to database', async () => {
+  const order = await orderService.create(orderData);
+  const saved = await db.orders.findById(order.id);
+  expect(saved).toMatchObject(orderData);
+});
+```
 
-## Mocking
+---
 
-Mock when:
-- External services (HTTP, DB)
-- Non-deterministic (time, random)
-- Slow operations
+## Test Pyramid
 
-Prefer interfaces for testability:
 ```
-type Repository interface {
-    Find(id string) (*Entity, error)
-}
-
-// Production: RealRepository
-// Tests: MockRepository
+        /\
+       /  \      E2E (Few)
+      /____\     
+     /      \    Integration (Some)
+    /        \   
+   /__________\  Unit (Many)
 ```
 
-## Test Isolation
-
-Each test should:
-- Setup its own data
-- Not depend on other tests
-- Clean up after itself
-- Run in any order
-
-## Coverage Guidelines
-
-| Layer | Target |
-|-------|--------|
-| Domain/Business | 80%+ |
-| Application/UseCase | 70%+ |
-| Infrastructure | 50%+ |
-
-Focus on critical paths, not 100% coverage.
+For full details, see the guides above.

package/src/opencode/skills/test-design/test-strategy.md

@@ -0,0 +1,279 @@
+# Test Strategy
+
+When to use which type of test and how much coverage.
+
+## Test Pyramid
+
+```
+        /\
+       /  \      E2E (Few)
+      /____\     - User scenarios
+     /      \    - Critical paths
+    /        \   
+   /__________\  Integration (Some)
+  /            \ - Module contracts
+ /              \- API boundaries
+/________________\ Unit (Many)
+                   - Business logic
+                   - Fast, isolated
+```
+
+**Principle:** More unit tests, fewer E2E tests.
+
+---
+
+## Test Types
+
+### Unit Tests
+**What:** Individual components in isolation  
+**When:** Business logic, calculations, validations  
+**Speed:** Fast (milliseconds)  
+**Coverage:** 70-80%
+
+**Example:**
+```typescript
+it('calculates order total', () => {
+  const order = new Order();
+  order.addItem({ price: 100, quantity: 2 });
+  expect(order.calculateTotal()).toBe(200);
+});
+```
+
+### Integration Tests
+**What:** Multiple components working together  
+**When:** Module boundaries, API contracts, DB operations  
+**Speed:** Medium (seconds)  
+**Coverage:** 50-60%
+
+**Example:**
+```typescript
+it('creates order in database', async () => {
+  const order = await orderService.create(orderData);
+  const saved = await db.orders.findById(order.id);
+  expect(saved).toMatchObject(orderData);
+});
+```
+
+### E2E Tests
+**What:** Complete user scenarios  
+**When:** Critical user flows, smoke tests  
+**Speed:** Slow (minutes)  
+**Coverage:** 20-30% of critical paths
+
+**Example:**
+```typescript
+it('user can place order', async () => {
+  await page.goto('/products');
+  await page.click('[data-testid="add-to-cart"]');
+  await page.click('[data-testid="checkout"]');
+  await page.fill('[name="email"]', 'test@example.com');
+  await page.click('[data-testid="place-order"]');
+  await expect(page.locator('.success')).toBeVisible();
+});
+```
+
+---
+
+## Coverage Targets
+
+### By Layer
+
+| Layer | Target | Focus |
+|-------|--------|-------|
+| **Domain** | 80%+ | Business rules, state transitions |
+| **Application** | 70%+ | Use cases, orchestration |
+| **Infrastructure** | 50%+ | Adapters, repositories |
+| **API** | 60%+ | Endpoints, validation |
+| **UI** | 40%+ | Critical user flows |
+
+### By Project Size
+
+| Size | Unit | Integration | E2E |
+|------|------|-------------|-----|
+| **TOY** | 60%+ | 30%+ | 10%+ |
+| **SMALL** | 70%+ | 40%+ | 20%+ |
+| **MEDIUM** | 75%+ | 50%+ | 25%+ |
+| **LARGE** | 80%+ | 60%+ | 30%+ |
+
+**Don't chase 100%** - Focus on critical paths.
+
+---
+
+## What to Test at Each Level
+
+### Unit Tests
+✅ **Test:**
+- Business logic
+- Calculations
+- Validations
+- State transitions
+- Error handling
+
+❌ **Don't test:**
+- Private methods
+- Getters/setters
+- Framework code
+
+### Integration Tests
+✅ **Test:**
+- Module contracts
+- API boundaries
+- Database operations
+- Event publishing/consuming
+- External service calls
+
+❌ **Don't test:**
+- Business logic (unit test it)
+- UI rendering (E2E test it)
+
+### E2E Tests
+✅ **Test:**
+- Critical user flows
+- Happy paths
+- Smoke tests
+- Cross-browser (if needed)
+
+❌ **Don't test:**
+- Edge cases (unit test them)
+- Error scenarios (integration test them)
+- Every feature (too slow)
+
+---
+
+## When to Write Tests
+
+### TDD (Test-Driven Development)
+**Process:** Red → Green → Refactor
+
+1. **Red:** Write failing test
+2. **Green:** Make it pass (simplest way)
+3. **Refactor:** Improve code
+
+**When to use:**
+- Clear requirements
+- Complex business logic
+- API design
+- Bug fixes
+
+**Example:**
+```typescript
+// 1. Red - write failing test
+it('calculates discount', () => {
+  expect(calculateDiscount(100, 0.1)).toBe(10);
+});
+
+// 2. Green - make it pass
+function calculateDiscount(price, rate) {
+  return price * rate;
+}
+
+// 3. Refactor - improve
+function calculateDiscount(price: number, rate: number): number {
+  if (rate < 0 || rate > 1) throw new Error('Invalid rate');
+  return price * rate;
+}
+```
+
+### Test After
+Write code first, then tests.
+
+**When to use:**
+- Prototyping
+- Unclear requirements
+- Exploratory coding
+- Spikes
+
+---
+
+## Cost vs Benefit
+
+### High Value Tests
+- Critical business logic
+- Payment processing
+- Security features
+- Data integrity
+- User authentication
+
+### Medium Value Tests
+- Standard CRUD operations
+- Common workflows
+- API endpoints
+- Form validation
+
+### Low Value Tests
+- Simple getters/setters
+- Configuration loading
+- Trivial formatting
+- Pass-through methods
+
+**Focus on high-value tests first.**
+
+---
+
+## Test Maintenance
+
+### Keep Tests Green
+- Fix failing tests immediately
+- Don't skip tests
+- Don't comment out tests
+
+### Refactor Tests
+- DRY (helper functions)
+- Clear names
+- Remove obsolete tests
+
+### Fast Feedback
+- Run unit tests on save
+- Run integration tests on commit
+- Run E2E tests on PR
+
+---
+
+## CI/CD Integration
+
+```yaml
+# Example CI pipeline
+stages:
+  - lint
+  - unit-tests      # Fast (1-2 min)
+  - integration     # Medium (5-10 min)
+  - e2e            # Slow (15-30 min)
+  - deploy
+
+unit-tests:
+  script: npm test
+  coverage: 80%
+  
+integration:
+  script: npm run test:integration
+  coverage: 50%
+  
+e2e:
+  script: npm run test:e2e
+  only: [main, develop]
+```
+
+---
+
+## Tips
+
+**Start with unit tests:**
+- Fastest feedback
+- Easiest to write
+- Most coverage
+
+**Add integration tests for boundaries:**
+- Module contracts
+- API endpoints
+- Database operations
+
+**E2E tests for critical flows:**
+- User registration
+- Checkout
+- Payment
+- Core features
+
+**Measure what matters:**
+- Coverage is a guide, not a goal
+- Focus on critical paths
+- Test behavior, not implementation

package/src/opencode/skills/test-design/unit-tests-mocking.md

@@ -0,0 +1,247 @@
+# Mocking and Test Isolation
+
+How to mock dependencies and isolate tests.
+
+## When to Mock
+
+**✅ Mock these:**
+- External services (HTTP, DB)
+- Non-deterministic (time, random)
+- Slow operations (file I/O, network)
+- Dependencies you don't control
+
+**❌ Don't mock these:**
+- Simple value objects
+- Pure functions
+- Your own domain logic
+
+---
+
+## Dependency Injection
+
+Make code testable by injecting dependencies.
+
+**Bad (hardcoded):**
+```typescript
+class OrderService {
+  async createOrder(data: OrderData) {
+    const db = new Database(); // hardcoded!
+    return db.save(data);
+  }
+}
+```
+
+**Good (injected):**
+```typescript
+class OrderService {
+  constructor(private db: Database) {}
+  
+  async createOrder(data: OrderData) {
+    return this.db.save(data);
+  }
+}
+
+// Test
+it('saves order', async () => {
+  const mockDb = { save: jest.fn().mockResolvedValue({ id: '123' }) };
+  const service = new OrderService(mockDb);
+  
+  await service.createOrder(orderData);
+  
+  expect(mockDb.save).toHaveBeenCalledWith(orderData);
+});
+```
+
+---
+
+## Interface-Based Mocking (Go)
+
+```go
+// Interface
+type Database interface {
+    Save(order Order) error
+}
+
+// Real implementation
+type PostgresDB struct {}
+func (db *PostgresDB) Save(order Order) error { /* ... */ }
+
+// Mock for tests
+type MockDB struct {
+    SaveFunc func(Order) error
+}
+func (m *MockDB) Save(order Order) error {
+    return m.SaveFunc(order)
+}
+
+// Test
+func TestOrderService_CreateOrder(t *testing.T) {
+    mockDB := &MockDB{
+        SaveFunc: func(o Order) error {
+            return nil // success
+        },
+    }
+    
+    service := NewOrderService(mockDB)
+    err := service.CreateOrder(order)
+    
+    assert.NoError(t, err)
+}
+```
+
+---
+
+## Mock Frameworks
+
+### TypeScript (Jest)
+
+```typescript
+// Mock function
+const mockSave = jest.fn();
+
+// Mock return value
+mockSave.mockResolvedValue({ id: '123' });
+
+// Mock error
+mockSave.mockRejectedValue(new Error('DB error'));
+
+// Verify calls
+expect(mockSave).toHaveBeenCalledWith(orderData);
+expect(mockSave).toHaveBeenCalledTimes(1);
+```
+
+### Python (unittest.mock)
+
+```python
+from unittest.mock import Mock, patch
+
+# Mock object
+mock_db = Mock()
+mock_db.save.return_value = {'id': '123'}
+
+# Verify calls
+mock_db.save.assert_called_once_with(order_data)
+
+# Patch dependency
+@patch('module.Database')
+def test_create_order(mock_db_class):
+    mock_db = mock_db_class.return_value
+    mock_db.save.return_value = {'id': '123'}
+    # test code
+```
+
+---
+
+## Test Isolation
+
+**Rules:**
+
+1. **Setup own data** - Don't depend on other tests
+2. **No shared state** - Each test is independent
+3. **Clean up** - Reset state after test
+4. **Run in any order** - No execution dependencies
+
+**Example:**
+
+```typescript
+describe('OrderRepository', () => {
+  let repository: OrderRepository;
+  let db: TestDatabase;
+  
+  beforeEach(async () => {
+    // Fresh database for each test
+    db = await TestDatabase.create();
+    repository = new OrderRepository(db);
+  });
+  
+  afterEach(async () => {
+    // Clean up after each test
+    await db.destroy();
+  });
+  
+  it('saves order', async () => {
+    const order = createTestOrder();
+    await repository.save(order);
+    // Independent of other tests
+  });
+});
+```
+
+---
+
+## Test Doubles
+
+### Stub
+Returns predefined values.
+
+```typescript
+const stub = {
+  getPrice: () => 100 // always returns 100
+};
+```
+
+### Mock
+Records calls for verification.
+
+```typescript
+const mock = {
+  save: jest.fn().mockResolvedValue({ id: '123' })
+};
+
+// Later verify
+expect(mock.save).toHaveBeenCalledWith(data);
+```
+
+### Spy
+Wraps real object, records calls.
+
+```typescript
+const realService = new OrderService();
+const spy = jest.spyOn(realService, 'createOrder');
+
+await realService.createOrder(data);
+
+expect(spy).toHaveBeenCalled();
+```
+
+### Fake
+Working implementation (simplified).
+
+```typescript
+class FakeDatabase implements Database {
+  private data = new Map();
+  
+  async save(order: Order) {
+    this.data.set(order.id, order);
+    return order;
+  }
+  
+  async find(id: string) {
+    return this.data.get(id);
+  }
+}
+```
+
+---
+
+## Tips
+
+**Prefer fakes over mocks:**
+- Fakes are more realistic
+- Less brittle tests
+- Easier to maintain
+
+**Keep mocks simple:**
+- Mock only what you need
+- Don't over-specify
+- Focus on behavior
+
+**Avoid mock hell:**
+- Too many mocks = bad design
+- Consider refactoring
+- Use real objects when possible
+
+**Test isolation:**
+- Each test is independent
+- No shared state
+- Clean up after yourself