aigroup-workflow 2.1.1 → 2.2.0

package/skills/quality/test-master/references/tdd-iron-laws.md

@@ -0,0 +1,174 @@
+# TDD Iron Laws
+
+---
+
+## The Fundamental Principle
+
+> **NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.**
+
+This is non-negotiable. If you wrote production code before writing a failing test, delete it and start over. No exceptions.
+
+---
+
+## The Three Iron Laws
+
+### Iron Law 1: The Fundamental Rule
+
+> "You shall not write any production code unless it is to make a failing test pass."
+
+Every line of production code must have a corresponding test that:
+1. Was written first
+2. Was observed to fail
+3. Now passes because of that code
+
+### Iron Law 2: Proof Through Observation
+
+> "If you didn't watch the test fail, you don't know if it tests the right thing."
+
+Mandatory verification steps:
+- Write the test
+- Run it and **observe the failure**
+- Verify the failure message is meaningful
+- Only then implement the fix
+
+A test you've never seen fail proves nothing.
+
+### Iron Law 3: The Final Rule
+
+> "Production code exists → A test exists that failed first. Otherwise → It's not TDD."
+
+There is no middle ground. Code written without a prior failing test is not test-driven development, regardless of how many tests exist afterward.
+
+---
+
+## The RED-GREEN-REFACTOR Cycle
+
+### RED: Write One Minimal Failing Test
+
+```typescript
+// Start with the smallest possible failing test
+it('should return 0 for empty array', () => {
+  expect(sum([])).toBe(0);
+});
+// Run: ✗ FAIL - sum is not defined
+```
+
+**Requirements:**
+- One test at a time
+- Minimal scope
+- Clear failure message
+- Observe the red
+
+### GREEN: Implement Simplest Passing Code
+
+```typescript
+// Write only enough code to pass this specific test
+function sum(numbers: number[]): number {
+  return 0;
+}
+// Run: ✓ PASS
+```
+
+**Requirements:**
+- Simplest possible implementation
+- No extra features
+- No optimization
+- Just make it pass
+
+### REFACTOR: Improve While Keeping Tests Green
+
+```typescript
+// Now improve the code while tests stay green
+function sum(numbers: number[]): number {
+  return numbers.reduce((acc, n) => acc + n, 0);
+}
+// Run: ✓ PASS (still)
+```
+
+**Requirements:**
+- Tests must stay green
+- Remove duplication
+- Improve clarity
+- No new functionality
+
+---
+
+## Common Rationalizations to Reject
+
+These thoughts indicate you're about to violate TDD:
+
+| Rationalization | Why It's Wrong |
+|-----------------|----------------|
+| "I can manually test this quickly" | Manual testing doesn't prevent regression |
+| "I'll write tests after to save time" | You'll skip edge cases and test implementation |
+| "This is too simple to need a test" | Simple code changes; tests document expectations |
+| "I've already written the code, I can't delete it now" | Sunk cost fallacy; delete it |
+| "I know this works, I've done it before" | Your memory isn't documentation |
+| "We're in a hurry" | Technical debt costs more than TDD |
+
+---
+
+## Practical Application
+
+### Starting a New Feature
+
+```typescript
+// 1. RED: Write failing test for simplest behavior
+describe('UserValidator', () => {
+  it('should reject empty email', () => {
+    expect(validateEmail('')).toBe(false);
+  });
+});
+
+// 2. GREEN: Implement minimal passing code
+function validateEmail(email: string): boolean {
+  return email.length > 0;
+}
+
+// 3. RED: Add next failing test
+it('should reject email without @', () => {
+  expect(validateEmail('invalid')).toBe(false);
+});
+
+// 4. GREEN: Extend to pass both tests
+function validateEmail(email: string): boolean {
+  return email.length > 0 && email.includes('@');
+}
+
+// Continue cycle...
+```
+
+### Fixing a Bug
+
+```typescript
+// 1. RED: Write test that exposes the bug
+it('should handle negative numbers in sum', () => {
+  expect(sum([-1, -2, -3])).toBe(-6);
+});
+// Run: ✗ FAIL - got 0 instead of -6
+
+// 2. GREEN: Fix the bug
+function sum(numbers: number[]): number {
+  return numbers.reduce((acc, n) => acc + n, 0);
+}
+// Run: ✓ PASS
+
+// Bug is now fixed AND protected against regression
+```
+
+---
+
+## Verification Checklist
+
+Before claiming any code is complete:
+
+- [ ] Every production function has corresponding tests
+- [ ] Each test was written before its implementation
+- [ ] Each test was observed to fail first
+- [ ] Tests verify behavior, not implementation
+- [ ] Refactoring kept all tests green
+- [ ] No production code exists without a test
+
+---
+
+*Content adapted from [obra/superpowers](https://github.com/obra/superpowers) by Jesse Vincent (@obra), MIT License.*

package/skills/quality/test-master/references/test-reports.md

@@ -0,0 +1,104 @@
+# Test Reports
+
+## Test Report Template
+
+```markdown
+# Test Report: {Feature Name}
+
+**Date**: YYYY-MM-DD
+**Tester**: {Name}
+**Version**: {App Version}
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Total Tests | X |
+| Passed | X |
+| Failed | X |
+| Skipped | X |
+| Coverage | X% |
+
+## Test Scope
+
+- [x] Unit tests
+- [x] Integration tests
+- [x] E2E tests
+- [ ] Performance tests
+- [ ] Security tests
+
+## Findings
+
+### [CRITICAL] {Issue Title}
+- **Location**: src/api/users.ts:45
+- **Steps to Reproduce**:
+  1. Send POST to /api/users without auth
+  2. Request succeeds with 201
+- **Expected**: 401 Unauthorized
+- **Actual**: 201 Created
+- **Impact**: Unauthorized user creation
+- **Fix**: Add auth middleware
+
+### [HIGH] {Issue Title}
+- **Location**: src/services/orders.ts:123
+- **Description**: N+1 query in order list
+- **Impact**: 3s response time with 100 orders
+- **Fix**: Add eager loading for order items
+
+### [MEDIUM] {Issue Title}
+- **Details**: ...
+
+### [LOW] {Issue Title}
+- **Details**: ...
+
+## Coverage Analysis
+
+| Module | Lines | Branches | Functions |
+|--------|-------|----------|-----------|
+| api/ | 85% | 78% | 90% |
+| services/ | 92% | 85% | 95% |
+| utils/ | 100% | 100% | 100% |
+
+### Coverage Gaps
+- `src/api/admin.ts` - 0% (no tests)
+- `src/services/payment.ts:45-60` - Error handling untested
+
+## Recommendations
+
+1. **Immediate**: Add auth middleware to admin routes
+2. **High Priority**: Optimize order queries
+3. **Medium Priority**: Add tests for payment error handling
+4. **Low Priority**: Increase branch coverage in api/
+
+## Performance Results
+
+| Endpoint | p50 | p95 | p99 |
+|----------|-----|-----|-----|
+| GET /users | 45ms | 120ms | 250ms |
+| POST /orders | 150ms | 400ms | 800ms |
+
+## Sign-off
+
+- [ ] All critical issues addressed
+- [ ] Coverage meets threshold (80%)
+- [ ] Performance meets SLA
+```
+
+## Severity Definitions
+
+| Severity | Criteria |
+|----------|----------|
+| **CRITICAL** | Security vulnerability, data loss, system crash |
+| **HIGH** | Major functionality broken, severe performance |
+| **MEDIUM** | Feature partially working, workaround exists |
+| **LOW** | Minor issue, cosmetic, edge case |
+
+## Quick Reference
+
+| Section | Content |
+|---------|---------|
+| Summary | High-level metrics |
+| Findings | Issues by severity |
+| Coverage | Code coverage analysis |
+| Recommendations | Prioritized actions |
+| Sign-off | Approval criteria |

package/skills/quality/test-master/references/testing-anti-patterns.md

@@ -0,0 +1,231 @@
+# Testing Anti-Patterns
+
+---
+
+## Core Principle
+
+> **"Test what the code does, not what the mocks do."**
+
+When tests verify mock behavior instead of actual functionality, they provide false confidence while catching zero real bugs.
+
+---
+
+## The Five Anti-Patterns
+
+### Anti-Pattern 1: Testing Mock Behavior
+
+**The Problem:** Verifying that mocks exist and were called, rather than testing actual component output.
+
+```typescript
+// ❌ BAD: Testing the mock, not the behavior
+it('should call the API', () => {
+  const mockApi = jest.fn().mockResolvedValue({ data: 'test' });
+  const service = new UserService(mockApi);
+
+  service.getUser(1);
+
+  expect(mockApi).toHaveBeenCalledWith(1); // Testing mock, not result
+});
+```
+
+```typescript
+// ✅ GOOD: Testing actual behavior
+it('should return user data from API', async () => {
+  const mockApi = jest.fn().mockResolvedValue({ id: 1, name: 'Alice' });
+  const service = new UserService(mockApi);
+
+  const user = await service.getUser(1);
+
+  expect(user.name).toBe('Alice'); // Testing actual output
+});
+```
+
+**Solution:** Test the genuine component output. If you can only verify mock calls, reconsider whether the test adds value.
+
+---
+
+### Anti-Pattern 2: Test-Only Methods in Production
+
+**The Problem:** Adding methods to production classes solely for test setup or cleanup.
+
+```typescript
+// ❌ BAD: Production code polluted with test concerns
+class UserCache {
+  private cache: Map<number, User> = new Map();
+
+  getUser(id: number): User | undefined {
+    return this.cache.get(id);
+  }
+
+  // This method exists ONLY for tests
+  _resetForTesting(): void {
+    this.cache.clear();
+  }
+}
+```
+
+```typescript
+// ✅ GOOD: Test utilities separate from production
+// production/UserCache.ts
+class UserCache {
+  private cache: Map<number, User> = new Map();
+
+  getUser(id: number): User | undefined {
+    return this.cache.get(id);
+  }
+}
+
+// test/helpers.ts
+function createFreshCache(): UserCache {
+  return new UserCache(); // Fresh instance per test
+}
+```
+
+**Solution:** Relocate cleanup logic to test utility functions. Use fresh instances per test instead of reset methods.
+
+---
+
+### Anti-Pattern 3: Mocking Without Understanding
+
+**The Problem:** Over-mocking without grasping side effects, leading to tests that pass but hide real issues.
+
+```typescript
+// ❌ BAD: Mocking everything without understanding
+it('should process order', async () => {
+  jest.mock('./inventory');
+  jest.mock('./payment');
+  jest.mock('./shipping');
+  jest.mock('./notifications');
+
+  const result = await processOrder(order);
+
+  expect(result.success).toBe(true); // What did we actually test?
+});
+```
+
+```typescript
+// ✅ GOOD: Strategic mocking with real components where possible
+it('should process order with real inventory check', async () => {
+  // Real inventory service against test database
+  const inventory = new InventoryService(testDb);
+
+  // Mock only external services
+  const payment = mockPaymentGateway();
+
+  const processor = new OrderProcessor(inventory, payment);
+  const result = await processor.process(order);
+
+  expect(result.success).toBe(true);
+  expect(await inventory.getStock(order.itemId)).toBe(originalStock - 1);
+});
+```
+
+**Solution:** Run tests with real implementations first to understand behavior. Then mock at the appropriate level - external services, not internal logic.
+
+---
+
+### Anti-Pattern 4: Incomplete Mocks
+
+**The Problem:** Partial mock responses missing downstream fields that production code expects.
+
+```typescript
+// ❌ BAD: Incomplete mock response
+const mockUserApi = jest.fn().mockResolvedValue({
+  id: 1,
+  name: 'Test User'
+  // Missing: email, createdAt, permissions, settings...
+});
+
+// Test passes, but production crashes when accessing user.email
+```
+
+```typescript
+// ✅ GOOD: Complete mock matching real API response
+const mockUserApi = jest.fn().mockResolvedValue({
+  id: 1,
+  name: 'Test User',
+  email: 'test@example.com',
+  createdAt: '2024-01-01T00:00:00Z',
+  permissions: ['read', 'write'],
+  settings: {
+    theme: 'light',
+    notifications: true
+  }
+});
+
+// Or use a factory
+const mockUserApi = jest.fn().mockResolvedValue(
+  createMockUser({ name: 'Test User' }) // Factory fills defaults
+);
+```
+
+**Solution:** Mirror complete real API response structure. Use factories to generate complete mock objects with sensible defaults.
+
+---
+
+### Anti-Pattern 5: Integration Tests as Afterthought
+
+**The Problem:** Treating testing as optional follow-up work rather than integral to development.
+
+```typescript
+// ❌ BAD: "We'll add tests later"
+// Day 1: Write 500 lines of code
+// Day 2: Write 500 more lines
+// Day 3: "We need to ship, tests can wait"
+// Day 30: Catastrophic bug in production
+// Day 31: "Why didn't we have tests?"
+```
+
+```typescript
+// ✅ GOOD: Tests are part of implementation
+// Write failing test
+it('should reject duplicate usernames', async () => {
+  await createUser({ username: 'alice' });
+
+  await expect(createUser({ username: 'alice' }))
+    .rejects.toThrow('Username already exists');
+});
+
+// Make it pass
+async function createUser(data: UserInput): Promise<User> {
+  const existing = await db.users.findByUsername(data.username);
+  if (existing) {
+    throw new Error('Username already exists');
+  }
+  return db.users.create(data);
+}
+
+// Feature AND test ship together
+```
+
+**Solution:** Follow TDD - testing is implementation, not documentation. No feature is "done" without tests.
+
+---
+
+## Detection Checklist
+
+Review your tests for these warning signs:
+
+| Warning Sign | Anti-Pattern |
+|-------------|--------------|
+| `expect(mock).toHaveBeenCalled()` without testing output | Testing mock behavior |
+| Methods starting with `_` or `ForTesting` in production | Test-only methods |
+| Every dependency is mocked | Mocking without understanding |
+| Mocks return `{ success: true }` only | Incomplete mocks |
+| Test files added weeks after feature ships | Tests as afterthought |
+
+---
+
+## Quick Reference
+
+| Anti-Pattern | Symptom | Fix |
+|-------------|---------|-----|
+| Testing mocks | Only mock assertions, no behavior tests | Assert on actual output |
+| Test-only methods | `_reset()`, `_setForTest()` in prod | Use fresh instances |
+| Over-mocking | 10+ mocks per test | Test with real deps first |
+| Incomplete mocks | Minimal stub responses | Use factories, match reality |
+| Tests as afterthought | Features ship untested | TDD from the start |
+
+---
+
+*Content adapted from [obra/superpowers](https://github.com/obra/superpowers) by Jesse Vincent (@obra), MIT License.*

package/skills/quality/test-master/references/unit-testing.md

@@ -0,0 +1,113 @@
+# Unit Testing
+
+## Jest/Vitest Pattern
+
+```typescript
+describe('UserService', () => {
+  let service: UserService;
+  let mockRepo: jest.Mocked<UserRepository>;
+
+  beforeEach(() => {
+    mockRepo = { findById: jest.fn(), save: jest.fn() } as any;
+    service = new UserService(mockRepo);
+  });
+
+  afterEach(() => jest.clearAllMocks());
+
+  describe('getUser', () => {
+    it('returns user when found', async () => {
+      const user = { id: '1', name: 'Test' };
+      mockRepo.findById.mockResolvedValue(user);
+
+      const result = await service.getUser('1');
+
+      expect(result).toEqual(user);
+      expect(mockRepo.findById).toHaveBeenCalledWith('1');
+    });
+
+    it('throws NotFoundError when user not found', async () => {
+      mockRepo.findById.mockResolvedValue(null);
+
+      await expect(service.getUser('1')).rejects.toThrow(NotFoundError);
+    });
+  });
+});
+```
+
+## pytest Pattern
+
+```python
+import pytest
+from unittest.mock import Mock, AsyncMock
+
+class TestUserService:
+    @pytest.fixture
+    def mock_repo(self):
+        return Mock()
+
+    @pytest.fixture
+    def service(self, mock_repo):
+        return UserService(mock_repo)
+
+    async def test_get_user_returns_user(self, service, mock_repo):
+        mock_repo.find_by_id = AsyncMock(return_value={"id": "1", "name": "Test"})
+
+        result = await service.get_user("1")
+
+        assert result == {"id": "1", "name": "Test"}
+        mock_repo.find_by_id.assert_called_once_with("1")
+
+    async def test_get_user_raises_not_found(self, service, mock_repo):
+        mock_repo.find_by_id = AsyncMock(return_value=None)
+
+        with pytest.raises(NotFoundError):
+            await service.get_user("1")
+```
+
+## Mocking Patterns
+
+```typescript
+// Mock functions
+const mockFn = jest.fn();
+mockFn.mockReturnValue('value');
+mockFn.mockResolvedValue('async value');
+mockFn.mockRejectedValue(new Error('error'));
+
+// Mock modules
+jest.mock('./database', () => ({
+  query: jest.fn(),
+}));
+
+// Spy on existing methods
+jest.spyOn(console, 'log').mockImplementation(() => {});
+```
+
+## Test Organization
+
+```typescript
+describe('Feature', () => {
+  describe('happy path', () => {
+    it('does expected behavior', () => {});
+  });
+
+  describe('edge cases', () => {
+    it('handles empty input', () => {});
+    it('handles max values', () => {});
+  });
+
+  describe('error cases', () => {
+    it('throws on invalid input', () => {});
+  });
+});
+```
+
+## Quick Reference
+
+| Pattern | Use Case |
+|---------|----------|
+| `describe()` | Group related tests |
+| `it()` / `test()` | Single test case |
+| `beforeEach()` | Setup before each test |
+| `jest.fn()` | Create mock function |
+| `mockResolvedValue()` | Mock async return |
+| `expect().toThrow()` | Assert exception |