devflow-kit 0.8.1 → 1.0.0

package/shared/skills/test-patterns/references/patterns.md

@@ -0,0 +1,220 @@
+# Test Patterns - Correct Examples
+
+Reference for proper test patterns and approaches.
+
+---
+
+## Simple Setup Patterns
+
+### Pure Function Testing
+
+```typescript
+// CORRECT: Simple setup indicates good design
+describe('createUser', () => {
+  it('should return Ok with valid data', () => {
+    const result = createUser({ name: 'test', email: 'test@example.com' });
+    expect(result.ok).toBe(true);
+    expect(result.value.name).toBe('test');
+  });
+
+  it('should return Err with invalid email', () => {
+    const result = createUser({ name: 'test', email: 'invalid' });
+    expect(result.ok).toBe(false);
+    expect(result.error.type).toBe('ValidationError');
+  });
+});
+```
+
+---
+
+## Minimal Mocking Patterns
+
+### Single Dependency Injection
+
+```typescript
+// CORRECT: Single mock for focused test
+describe('OrderCalculator', () => {
+  it('should calculate total with tax', () => {
+    const taxService = { getRate: () => 0.1 }; // Simple mock
+    const calculator = new OrderCalculator(taxService);
+    const result = calculator.calculateTotal([
+      { price: 100, quantity: 2 },
+      { price: 50, quantity: 1 },
+    ]);
+    expect(result).toBe(275);
+  });
+});
+```
+
+---
+
+## Behavior-Focused Testing
+
+```typescript
+// CORRECT: Testing behavior, not implementation
+describe('ShoppingCart', () => {
+  it('should calculate correct total after adding items', () => {
+    const cart = new ShoppingCart();
+    cart.addItem({ id: '1', price: 10 });
+    cart.addItem({ id: '2', price: 20 });
+    expect(cart.getTotal()).toBe(30);
+  });
+
+  it('should be empty after clearing', () => {
+    const cart = new ShoppingCart();
+    cart.addItem({ id: '1', price: 10 });
+    cart.clear();
+    expect(cart.getItems()).toEqual([]);
+    expect(cart.getTotal()).toBe(0);
+  });
+});
+```
+
+---
+
+## Coverage Patterns
+
+### Branch Coverage
+
+```typescript
+describe('calculateDiscount', () => {
+  it('returns 10% for regular customers', () => {
+    expect(calculateDiscount(100, 'regular')).toBe(10);
+  });
+  it('returns 20% for premium customers', () => {
+    expect(calculateDiscount(100, 'premium')).toBe(20);
+  });
+  it('returns 30% for VIP customers', () => {
+    expect(calculateDiscount(100, 'vip')).toBe(30);
+  });
+});
+```
+
+### Error Path Coverage
+
+```typescript
+describe('fetchUser', () => {
+  it('returns user data on success', async () => { /* ... */ });
+  it('throws ApiError on 404', async () => {
+    api.get.mockResolvedValue({ ok: false, status: 404 });
+    await expect(fetchUser('123')).rejects.toThrow(ApiError);
+  });
+  it('handles network errors', async () => {
+    api.get.mockRejectedValue(new Error('Network error'));
+    await expect(fetchUser('123')).rejects.toThrow('Network error');
+  });
+});
+```
+
+---
+
+## Separation of Concerns Testing
+
+```typescript
+// CORRECT: Business logic tested without I/O
+describe('OrderPricing (pure logic)', () => {
+  it('should calculate subtotal', () => {
+    const items = [{ price: 100, quantity: 2 }, { price: 50, quantity: 1 }];
+    expect(calculateSubtotal(items)).toBe(250);
+  });
+  it('should apply percentage discount', () => {
+    expect(applyDiscount(100, { type: 'percent', value: 20 })).toBe(80);
+  });
+});
+
+// Integration test for I/O wrapper
+describe('OrderService (integration)', () => {
+  it('should persist order and return result', async () => {
+    const mockRepo = { save: jest.fn().mockResolvedValue({ id: '1' }) };
+    const service = new OrderService(mockRepo);
+    const result = await service.createOrder({ items: [{ price: 100, quantity: 1 }] });
+    expect(result.ok).toBe(true);
+  });
+});
+```
+
+---
+
+## Parameterized Testing
+
+```typescript
+describe('validateEmail', () => {
+  const validEmails = ['test@example.com', 'user.name@domain.org', 'user+tag@example.co.uk'];
+  const invalidEmails = ['', 'invalid', '@nodomain.com', 'spaces in@email.com'];
+
+  test.each(validEmails)('should accept valid email: %s', (email) => {
+    expect(validateEmail(email).ok).toBe(true);
+  });
+
+  test.each(invalidEmails)('should reject invalid email: %s', (email) => {
+    expect(validateEmail(email).ok).toBe(false);
+  });
+});
+```
+
+---
+
+## Boundary Mocking
+
+```typescript
+// CORRECT: Wrap third-party libraries in your own interface
+interface HttpClient {
+  get<T>(url: string): Promise<T>;
+}
+
+class MockHttpClient implements HttpClient {
+  private responses: Map<string, any> = new Map();
+  mockResponse(url: string, data: any) { this.responses.set(url, data); }
+  async get<T>(url: string): Promise<T> { return this.responses.get(url); }
+}
+
+// Tests use MockHttpClient, production uses AxiosHttpClient
+```
+
+---
+
+## Test Organization
+
+```typescript
+describe('UserService', () => {
+  let service: UserService;
+  let repo: InMemoryUserRepo;
+
+  beforeEach(() => {
+    repo = new InMemoryUserRepo();
+    service = new UserService(repo);
+  });
+
+  describe('create', () => {
+    it('creates user with valid data', async () => { /* ... */ });
+    it('rejects invalid email', async () => { /* ... */ });
+  });
+
+  describe('update', () => {
+    it('updates existing user', async () => { /* ... */ });
+    it('returns error for non-existent user', async () => { /* ... */ });
+  });
+});
+```
+
+---
+
+## Test Data Factories
+
+```typescript
+// CORRECT: Factories for test data, not test setup
+const createTestUser = (overrides = {}): User => ({
+  id: 'test-id',
+  name: 'Test User',
+  email: 'test@example.com',
+  role: 'user',
+  ...overrides,
+});
+
+describe('UserPermissions', () => {
+  it('should allow admin to delete users', () => {
+    const admin = createTestUser({ role: 'admin' });
+    expect(canDeleteUser(admin)).toBe(true);
+  });
+});
+```

package/shared/skills/test-patterns/references/report-template.md

@@ -0,0 +1,108 @@
+# Test Quality Report Template
+
+Use this template when reporting test design issues.
+
+---
+
+## Report Format
+
+```markdown
+## Test Design Issues Detected
+
+## [SEVERITY] - [Category] ([Root Cause Type])
+**File**: path/to/file.test.ts:line-range
+**Issue**: Brief description of the problem
+**Root Cause**: What architectural issue causes this
+**Symptom**:
+```code
+// The problematic code snippet
+```
+**Correct Design**:
+```code
+// What good design looks like
+```
+**Action Required**: Specific action to fix
+
+## Summary
+- **Critical**: N issues (block implementation)
+- **High**: N issues (refactor needed)
+- **Files affected**: N test files
+- **Root cause**: Brief architectural diagnosis
+
+## STOP - Design Issues Detected
+
+[List fundamental design flaws discovered]
+
+**DO NOT work around these issues in tests.**
+**DO NOT add more complex test helpers.**
+**DO NOT mock more things to make tests pass.**
+
+## Next Steps
+
+1. **STOP writing tests** - Current design cannot be tested simply
+2. **ANALYZE root cause** - Identify architectural issue
+3. **PROPOSE redesign** - Show correct pattern
+4. **GET APPROVAL** - User confirms design changes
+5. **IMPLEMENT redesign** - Fix architecture first
+6. **WRITE SIMPLE TESTS** - Tests should be trivial after redesign
+```
+
+---
+
+## Severity Levels
+
+| Severity | Use For | Examples |
+|----------|---------|---------|
+| **CRITICAL** | Fundamental design flaws | Complex setup >10 lines, repetitive boilerplate >3 times, mock objects >5 methods, testing private methods |
+| **HIGH** | Maintenance complications | Difficult mocking >20 lines, implementation testing, environment manipulation, database seeding |
+| **MEDIUM** | Reduced clarity | Test helper abuse, inconsistent assertion patterns, missing edge case coverage |
+| **LOW** | Minor improvements | Organization, naming clarity |
+
+---
+
+## Category Labels
+
+| Category | Root Cause Type | Indicates |
+|----------|-----------------|-----------|
+| Complex Setup | Design Problem | Too many dependencies |
+| Repetitive Boilerplate | API Problem | Inconsistent error handling |
+| Difficult Mocking | Coupling Problem | Tight coupling to externals |
+| Implementation Testing | Fragile Tests | Tests coupled to internals |
+| Environment Manipulation | DI Problem | Direct environment access |
+| Database Seeding | Separation Problem | Logic mixed with data access |
+
+---
+
+## Test Suite Safety Configuration
+
+### Full Configuration Examples
+
+```typescript
+// vitest.config.ts
+export default defineConfig({
+  test: {
+    fileParallelism: false,
+    maxWorkers: 1,
+    pool: 'forks',
+    testTimeout: 10000,
+  }
+});
+
+// jest.config.js
+module.exports = {
+  maxWorkers: 1,
+  runInBand: true,
+  testTimeout: 10000,
+};
+```
+
+```bash
+# Memory limits
+NODE_OPTIONS="--max-old-space-size=512" npm test
+
+# Go
+go test -p 1 ./...
+
+# Rust
+cargo test -- --test-threads=1
+```

package/shared/skills/test-patterns/references/violations.md

@@ -0,0 +1,221 @@
+# Test Pattern Violations - Extended Examples
+
+Reference examples for common test quality violations across both design and review contexts.
+
+---
+
+## Complex Setup Violations
+
+### Multi-Dependency Service Setup
+
+```typescript
+// VIOLATION: Complex setup indicates design problem
+describe('UserService', () => {
+  let service: UserService;
+  let mockDb: MockDatabase;
+  let mockCache: MockCache;
+  let mockLogger: MockLogger;
+  let mockConfig: MockConfig;
+
+  beforeEach(async () => {
+    mockDb = new MockDatabase();
+    await mockDb.connect();
+    await mockDb.seed();
+    mockCache = new MockCache();
+    mockCache.clear();
+    mockLogger = new MockLogger();
+    mockConfig = new MockConfig();
+    mockConfig.set('env', 'test');
+    // ... 10+ more lines
+    service = new UserService(mockDb, mockCache, mockLogger, mockConfig);
+  });
+
+  it('should create user', async () => {
+    const result = await service.createUser({ name: 'test' });
+    expect(result.ok).toBe(true);
+  });
+});
+```
+
+**Root Cause**: UserService has too many dependencies (6+ injected services)
+
+**Solution**: Split into focused services with single responsibility
+
+---
+
+## Repetitive Boilerplate Violations
+
+### Try/Catch Pattern Repetition
+
+```typescript
+// VIOLATION: Repetitive error handling indicates API problem
+describe('API endpoints', () => {
+  it('should handle user creation error', async () => {
+    try {
+      await api.createUser(invalidData);
+      fail('Should have thrown');
+    } catch (error) {
+      expect(error.status).toBe(400);
+      expect(error.message).toContain('validation');
+    }
+  });
+
+  // ... repeated pattern 10+ times
+});
+```
+
+**Root Cause**: API throws exceptions instead of returning Results
+
+**Solution**: Migrate API to Result pattern
+
+---
+
+## Difficult Mocking Violations
+
+### Nested Mock Object Structures
+
+```typescript
+// VIOLATION: Complex mocking indicates tight coupling
+beforeEach(() => {
+  mockDb = {
+    transaction: jest.fn((callback) => callback(mockDb)),
+    orders: { create: jest.fn(), update: jest.fn(), findById: jest.fn() },
+    users: { findById: jest.fn(), update: jest.fn() },
+    inventory: { decrement: jest.fn(), check: jest.fn(), reserve: jest.fn() }
+  };
+  // 5+ more mock objects...
+});
+```
+
+**Root Cause**: OrderProcessor directly depends on too many external systems
+
+**Solution**: Separate pure business logic from I/O; use composition
+
+---
+
+## Implementation Testing Violations
+
+### Spying on Private Methods
+
+```typescript
+// VIOLATION: Testing implementation details
+it('should call updateTotal after addItem', () => {
+  const cart = new ShoppingCart();
+  const spy = jest.spyOn(cart as any, 'updateTotal');
+  cart.addItem({ id: '1', price: 10 });
+  expect(spy).toHaveBeenCalled();  // Testing implementation!
+});
+```
+
+**Root Cause**: Tests coupled to implementation details
+
+**Solution**: Test observable behavior only
+
+---
+
+## Coverage Violations
+
+### Missing Edge Cases
+
+```typescript
+// INCOMPLETE TESTS
+describe('divide', () => {
+  it('divides two numbers', () => {
+    expect(divide(10, 2)).toBe(5);  // Happy path only
+  });
+});
+
+// COMPLETE TESTS
+describe('divide', () => {
+  it('divides two positive numbers', () => { expect(divide(10, 2)).toBe(5); });
+  it('handles division by zero', () => { expect(divide(10, 0)).toBe(Infinity); });
+  it('handles negative numbers', () => { expect(divide(-10, 2)).toBe(-5); });
+  it('handles decimal results', () => { expect(divide(10, 3)).toBeCloseTo(3.333, 2); });
+});
+```
+
+### Unclear Test Names
+
+```typescript
+// UNCLEAR: What does this test?
+it('test1', () => { /* ... */ });
+it('should work', () => { /* ... */ });
+
+// CLEAR: Describes behavior
+it('validates email format on creation', () => { /* ... */ });
+it('rejects passwords shorter than 8 characters', () => { /* ... */ });
+```
+
+---
+
+## Test Design Violations
+
+### Slow Tests (Real Delays)
+
+```typescript
+// SLOW: Real delays
+const result = await fetchWithRetry();  // Waits real 1000ms
+
+// FAST: Mock timers
+jest.useFakeTimers();
+const promise = fetchWithRetry();
+jest.advanceTimersByTime(1000);
+```
+
+### Flaky Tests (Timing Dependencies)
+
+```typescript
+// FLAKY: Race condition
+subscribe(callback);
+emit('update', { value: 1 });
+expect(callback).toHaveBeenCalled();  // Might not have fired yet
+
+// STABLE: Explicit waiting
+const received = new Promise(resolve => { subscribe(data => resolve(data)); });
+emit('update', { value: 1 });
+const data = await received;
+expect(data.value).toBe(1);
+```
+
+### Over-Mocking
+
+```typescript
+// OVER-MOCKED: Tests nothing real
+const mockValidator = { validate: jest.fn().mockReturnValue(true) };
+const mockHasher = { hash: jest.fn().mockReturnValue('hashed') };
+const mockRepo = { create: jest.fn().mockResolvedValue({ id: '1' }) };
+// What did we actually test? Just that mocks were called.
+
+// BETTER: Use real implementations where possible
+const repo = new InMemoryUserRepo();
+const service = new UserService(new RealValidator(), new RealHasher(), repo);
+const saved = await repo.findByEmail('test@test.com');
+expect(await bcrypt.compare('password', saved.password)).toBe(true);
+```
+
+---
+
+## Environment & Database Violations
+
+### Environment Manipulation
+
+```typescript
+// VIOLATION: Tests modifying environment
+beforeEach(() => {
+  process.env = { ...process.env, DATABASE_URL: 'postgres://test', API_KEY: 'test-key' };
+});
+```
+
+**Solution**: Inject configuration as a dependency
+
+### Database State Dependencies
+
+```typescript
+// VIOLATION: Tests depend on specific seeded data
+beforeAll(async () => {
+  await db.users.insert([/* ... */]);
+  await db.orders.insert([/* ... */]);
+});
+```
+
+**Solution**: Separate data access from business logic; test calculation separately