claude-autopm 2.8.2 → 2.8.4

package/packages/plugin-languages/rules/testing-standards.md

@@ -0,0 +1,768 @@
+---
+name: testing-standards
+priority: high
+tags:
+  - testing
+  - tdd
+  - quality
+  - coverage
+appliesTo:
+  - commands
+  - agents
+enforcesOn:
+  - python-backend-engineer
+  - python-backend-expert
+  - nodejs-backend-engineer
+  - javascript-frontend-engineer
+  - bash-scripting-expert
+---
+
+# Testing Standards Rule
+
+**MANDATORY**: All code MUST follow Test-Driven Development (TDD) methodology with comprehensive test coverage.
+
+## Purpose
+
+Ensure reliable, maintainable code through:
+- Test-First Development (TDD)
+- Comprehensive test coverage (>80%)
+- Multiple test layers (unit, integration, E2E)
+- Language-specific testing best practices
+- Automated test execution
+
+## Test-Driven Development (TDD) Workflow
+
+### Red-Green-Refactor Cycle (MANDATORY)
+
+**1. RED - Write Failing Test First**
+```
+Write a test that fails ❌
+↓
+Verify the test fails for the right reason
+↓
+Commit the failing test
+```
+
+**2. GREEN - Make it Pass**
+```
+Write minimal code to pass the test ✅
+↓
+Run tests and verify all pass
+↓
+Commit the passing code
+```
+
+**3. REFACTOR - Improve Code**
+```
+Improve code quality 🔄
+↓
+Ensure all tests still pass
+↓
+Commit the refactoring
+```
+
+### TDD Principles
+
+- **Test-First**: Always write test before implementation
+- **One Test at a Time**: Focus on single functionality
+- **Minimal Code**: Write only enough code to pass
+- **Refactor Safely**: Improve with test safety net
+- **Fast Feedback**: Run tests continuously
+
+## Language-Specific Testing Standards
+
+### Python Testing (pytest)
+
+**Test Structure:**
+```python
+# tests/test_user_service.py
+import pytest
+from app.services.user_service import UserService
+from app.models.user import User
+
+class TestUserService:
+    """Test suite for UserService."""
+
+    # TDD Step 1: RED - Write failing test first
+    @pytest.mark.asyncio
+    async def test_create_user_success(self, user_service, db_session):
+        """
+        GIVEN valid user data
+        WHEN creating a new user
+        THEN user is created and returned with ID
+        """
+        # Arrange
+        user_data = {
+            "email": "test@example.com",
+            "username": "testuser",
+            "password": "securepass123"
+        }
+
+        # Act
+        user = await user_service.create_user(user_data)
+
+        # Assert
+        assert user.id is not None
+        assert user.email == "test@example.com"
+        assert user.username == "testuser"
+        assert user.password != "securepass123"  # Should be hashed
+
+    @pytest.mark.asyncio
+    async def test_create_user_duplicate_email(self, user_service, db_session):
+        """
+        GIVEN existing user with email
+        WHEN creating user with same email
+        THEN raises ValueError
+        """
+        # Arrange
+        existing_user = {"email": "test@example.com", "username": "user1"}
+        await user_service.create_user(existing_user)
+
+        # Act & Assert
+        with pytest.raises(ValueError, match="Email already exists"):
+            await user_service.create_user({
+                "email": "test@example.com",
+                "username": "user2"
+            })
+
+# Fixtures for test setup
+@pytest.fixture
+async def user_service(db_session):
+    """Create UserService instance with test database."""
+    return UserService(db_session)
+
+@pytest.fixture
+async def db_session():
+    """Create test database session."""
+    # Setup
+    async with async_session_maker() as session:
+        yield session
+        # Teardown
+        await session.rollback()
+```
+
+**pytest Configuration:**
+```toml
+# pyproject.toml
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_classes = "Test*"
+python_functions = "test_*"
+addopts = [
+    "--cov=app",
+    "--cov-report=html",
+    "--cov-report=term-missing",
+    "--cov-fail-under=80",
+    "-v",
+    "--tb=short",
+    "--strict-markers",
+    "--asyncio-mode=auto"
+]
+markers = [
+    "unit: Unit tests",
+    "integration: Integration tests",
+    "e2e: End-to-end tests",
+    "slow: Slow running tests"
+]
+```
+
+**Coverage Requirements:**
+- **Minimum**: 80% overall coverage
+- **Critical paths**: 100% coverage
+- **Branch coverage**: Enabled
+- **Report**: HTML + Terminal
+
+### JavaScript/TypeScript Testing (Jest/Vitest)
+
+**Test Structure:**
+```typescript
+// tests/user.service.test.ts
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { UserService } from '@/services/user.service';
+import { User } from '@/models/user.model';
+
+describe('UserService', () => {
+  let userService: UserService;
+  let mockRepository: any;
+
+  beforeEach(() => {
+    // Setup fresh mocks for each test
+    mockRepository = {
+      findById: vi.fn(),
+      create: vi.fn(),
+      update: vi.fn(),
+      delete: vi.fn(),
+    };
+    userService = new UserService(mockRepository);
+  });
+
+  // TDD Step 1: RED - Write failing test
+  describe('createUser', () => {
+    it('should create user with hashed password', async () => {
+      // Arrange
+      const userData = {
+        email: 'test@example.com',
+        username: 'testuser',
+        password: 'securepass123',
+      };
+
+      const expectedUser = {
+        id: 1,
+        email: userData.email,
+        username: userData.username,
+        password: 'hashed_password',
+      };
+
+      mockRepository.create.mockResolvedValue(expectedUser);
+
+      // Act
+      const result = await userService.createUser(userData);
+
+      // Assert
+      expect(result.id).toBeDefined();
+      expect(result.email).toBe(userData.email);
+      expect(result.password).not.toBe(userData.password);
+      expect(mockRepository.create).toHaveBeenCalledTimes(1);
+    });
+
+    it('should throw error for duplicate email', async () => {
+      // Arrange
+      const userData = { email: 'test@example.com', username: 'user' };
+      mockRepository.create.mockRejectedValue(
+        new Error('Email already exists')
+      );
+
+      // Act & Assert
+      await expect(userService.createUser(userData)).rejects.toThrow(
+        'Email already exists'
+      );
+    });
+  });
+
+  // Integration test example
+  describe('Integration: User workflow', () => {
+    it('should complete full user lifecycle', async () => {
+      // Create → Read → Update → Delete
+      const user = await userService.createUser({ /* data */ });
+      const found = await userService.findById(user.id);
+      const updated = await userService.update(user.id, { /* updates */ });
+      await userService.delete(user.id);
+
+      expect(found).toBeDefined();
+      expect(updated.email).toBe(/* expected */);
+    });
+  });
+});
+```
+
+**Jest/Vitest Configuration:**
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'html', 'lcov'],
+      exclude: [
+        'node_modules/',
+        'tests/',
+        '**/*.test.ts',
+        '**/*.spec.ts',
+      ],
+      statements: 80,
+      branches: 80,
+      functions: 80,
+      lines: 80,
+    },
+    include: ['tests/**/*.test.ts'],
+    setupFiles: ['./tests/setup.ts'],
+  },
+});
+```
+
+### Node.js API Testing (Supertest)
+
+**API Test Structure:**
+```typescript
+// tests/api/users.test.ts
+import request from 'supertest';
+import { app } from '@/app';
+import { setupTestDB, cleanupTestDB } from './helpers/db';
+
+describe('User API', () => {
+  beforeAll(async () => {
+    await setupTestDB();
+  });
+
+  afterAll(async () => {
+    await cleanupTestDB();
+  });
+
+  describe('POST /api/users', () => {
+    it('should create new user', async () => {
+      const response = await request(app)
+        .post('/api/users')
+        .send({
+          email: 'test@example.com',
+          username: 'testuser',
+          password: 'password123',
+        })
+        .expect(201);
+
+      expect(response.body).toHaveProperty('id');
+      expect(response.body.email).toBe('test@example.com');
+    });
+
+    it('should return 400 for invalid email', async () => {
+      await request(app)
+        .post('/api/users')
+        .send({
+          email: 'invalid-email',
+          username: 'testuser',
+        })
+        .expect(400);
+    });
+
+    it('should return 409 for duplicate email', async () => {
+      // First request succeeds
+      await request(app)
+        .post('/api/users')
+        .send({ email: 'test@example.com', username: 'user1' })
+        .expect(201);
+
+      // Second request fails
+      await request(app)
+        .post('/api/users')
+        .send({ email: 'test@example.com', username: 'user2' })
+        .expect(409);
+    });
+  });
+
+  describe('GET /api/users/:id', () => {
+    it('should return user by id', async () => {
+      // Create user first
+      const createResponse = await request(app)
+        .post('/api/users')
+        .send({ email: 'get@example.com', username: 'getuser' });
+
+      const userId = createResponse.body.id;
+
+      // Get user
+      const response = await request(app)
+        .get(`/api/users/${userId}`)
+        .expect(200);
+
+      expect(response.body.id).toBe(userId);
+      expect(response.body.email).toBe('get@example.com');
+    });
+
+    it('should return 404 for non-existent user', async () => {
+      await request(app)
+        .get('/api/users/99999')
+        .expect(404);
+    });
+  });
+});
+```
+
+### Bash Script Testing (bats)
+
+**Test Structure:**
+```bash
+#!/usr/bin/env bats
+# tests/deploy.bats
+
+setup() {
+    # Test setup
+    export TEST_DIR="$(mktemp -d)"
+    source ./scripts/deploy.sh
+
+    # Mock functions
+    git() {
+        echo "git $*" >> "$TEST_DIR/git.log"
+        return 0
+    }
+    export -f git
+}
+
+teardown() {
+    # Cleanup
+    rm -rf "$TEST_DIR"
+}
+
+@test "validate_environment accepts valid env" {
+    run validate_environment "production"
+    [ "$status" -eq 0 ]
+}
+
+@test "validate_environment rejects invalid env" {
+    run validate_environment "invalid"
+    [ "$status" -eq 1 ]
+    [[ "$output" =~ "Invalid environment" ]]
+}
+
+@test "check_dependencies finds all required commands" {
+    # Mock command availability
+    function command() {
+        case "$2" in
+            git|docker|curl) return 0 ;;
+            *) return 1 ;;
+        esac
+    }
+    export -f command
+
+    run check_dependencies
+    [ "$status" -eq 0 ]
+}
+
+@test "deploy creates backup before deployment" {
+    run deploy "staging"
+
+    [ "$status" -eq 0 ]
+    [ -f "$TEST_DIR/backup.tar.gz" ]
+}
+
+@test "rollback restores previous version on failure" {
+    # Simulate deployment failure
+    function deploy_new_version() {
+        return 1
+    }
+    export -f deploy_new_version
+
+    run main "production"
+
+    [ "$status" -eq 1 ]
+    [[ "$output" =~ "Rolling back" ]]
+}
+```
+
+**bats Configuration:**
+```bash
+# tests/test_helper.bash
+# Common test utilities
+
+load '/usr/local/lib/bats-support/load.bash'
+load '/usr/local/lib/bats-assert/load.bash'
+
+# Setup test environment
+setup_test_env() {
+    export TEST_DIR="$(mktemp -d)"
+    export LOG_FILE="$TEST_DIR/test.log"
+}
+
+# Cleanup test environment
+cleanup_test_env() {
+    rm -rf "$TEST_DIR"
+}
+
+# Assert file exists
+assert_file_exists() {
+    [ -f "$1" ] || fail "File does not exist: $1"
+}
+
+# Assert command succeeds
+assert_success() {
+    run "$@"
+    assert_equal "$status" 0
+}
+```
+
+## Test Categories
+
+### Unit Tests
+
+**Characteristics:**
+- Test single function/method
+- No external dependencies
+- Fast execution (<100ms per test)
+- Mock all I/O operations
+- High coverage (>90%)
+
+**What to Test:**
+- Business logic
+- Data transformations
+- Validation logic
+- Error handling
+- Edge cases
+
+### Integration Tests
+
+**Characteristics:**
+- Test component interactions
+- Real database connections
+- API calls to external services
+- Moderate execution time (<5s per test)
+- Medium coverage (>70%)
+
+**What to Test:**
+- Database operations
+- API endpoints
+- Service integrations
+- Authentication flows
+- Authorization logic
+
+### End-to-End (E2E) Tests
+
+**Characteristics:**
+- Test complete workflows
+- Real infrastructure
+- User-facing scenarios
+- Slow execution (<30s per test)
+- Lower coverage (~20 critical paths)
+
+**What to Test:**
+- User registration flow
+- Login/logout workflow
+- Critical business processes
+- Payment workflows
+- Data migration scenarios
+
+## Test Naming Conventions
+
+### Python (pytest)
+```python
+def test_<function>_<scenario>_<expected_result>():
+    """
+    GIVEN <context>
+    WHEN <action>
+    THEN <expected_outcome>
+    """
+```
+
+**Examples:**
+- `test_create_user_with_valid_data_returns_user_with_id()`
+- `test_update_user_with_invalid_email_raises_value_error()`
+- `test_delete_user_that_does_not_exist_raises_not_found_error()`
+
+### JavaScript/TypeScript (Jest/Vitest)
+```typescript
+describe('<Component/Function>', () => {
+  it('should <expected behavior> when <condition>', () => {
+    // Test
+  });
+});
+```
+
+**Examples:**
+- `it('should return user when valid ID provided')`
+- `it('should throw error when email already exists')`
+- `it('should hash password before storing')`
+
+### Bash (bats)
+```bash
+@test "<command> <scenario> <expected result>" {
+    # Test
+}
+```
+
+**Examples:**
+- `@test "validate_input accepts valid email"`
+- `@test "deploy fails with exit code 1 on error"`
+- `@test "cleanup removes all temp files"`
+
+## Coverage Requirements
+
+### Minimum Thresholds
+
+```yaml
+coverage:
+  statements: 80
+  branches: 80
+  functions: 80
+  lines: 80
+```
+
+### Critical Paths (100% Coverage Required)
+
+- Authentication and authorization
+- Payment processing
+- Data validation
+- Security-sensitive operations
+- Data persistence
+- Error handling
+
+### Excluded from Coverage
+
+- Generated code
+- Configuration files
+- Test fixtures
+- Third-party code
+- Deprecated code
+
+## Test Execution
+
+### Local Development
+
+```bash
+# Python
+pytest                    # Run all tests
+pytest -v                 # Verbose output
+pytest -k "test_user"     # Run specific tests
+pytest --cov              # With coverage
+pytest -m unit            # Run only unit tests
+
+# JavaScript/TypeScript
+npm test                  # Run all tests
+npm run test:watch        # Watch mode
+npm run test:coverage     # With coverage
+npm run test:unit         # Unit tests only
+
+# Bash
+bats tests/               # Run all tests
+bats tests/deploy.bats    # Specific file
+```
+
+### CI/CD Pipeline
+
+```yaml
+# .github/workflows/test.yml
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Run tests
+        run: |
+          npm install
+          npm run test:coverage
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v3
+        with:
+          file: ./coverage/lcov.info
+
+      - name: Check coverage threshold
+        run: |
+          if [ $(cat coverage/coverage-summary.json | jq '.total.statements.pct') -lt 80 ]; then
+            echo "Coverage below 80%"
+            exit 1
+          fi
+```
+
+## Continuous Testing
+
+### Watch Mode
+- Run tests automatically on file changes
+- Immediate feedback during development
+- Faster red-green-refactor cycles
+
+### Pre-commit Hooks
+```bash
+# .husky/pre-commit
+#!/bin/sh
+npm run test:staged  # Run tests for staged files only
+```
+
+### Pre-push Hooks
+```bash
+# .husky/pre-push
+#!/bin/sh
+npm run test:all     # Run full test suite
+npm run test:coverage  # Verify coverage
+```
+
+## Test Data Management
+
+### Fixtures
+- Use factories for test data creation
+- Keep fixtures minimal and focused
+- Use realistic but safe test data
+- Reset state between tests
+
+### Mocking
+- Mock external services
+- Mock slow operations
+- Mock non-deterministic behavior
+- Keep mocks simple and maintainable
+
+### Test Databases
+- Use separate test database
+- Reset before each test suite
+- Seed with minimal data
+- Clean up after tests
+
+## Performance Targets
+
+### Test Execution Speed
+
+```
+Unit tests:        < 100ms per test
+Integration tests: < 5s per test
+E2E tests:         < 30s per test
+Full suite:        < 5 minutes
+```
+
+### Optimization Strategies
+
+- Parallelize test execution
+- Use test database transactions
+- Mock slow external services
+- Cache test dependencies
+- Run fast tests first
+
+## Enforcement
+
+### Blocked Actions
+
+- **Cannot merge**: If tests fail
+- **Cannot deploy**: If coverage below threshold
+- **Cannot commit**: If test syntax invalid (pre-commit hook)
+
+### Quality Gates
+
+```yaml
+gates:
+  - name: Tests
+    condition: all_pass
+    required: true
+
+  - name: Coverage
+    condition: ">= 80%"
+    required: true
+
+  - name: Performance
+    condition: "< 5 minutes"
+    required: true
+```
+
+## Monitoring
+
+### Metrics
+
+- Test count (should grow with codebase)
+- Test execution time (should stay under threshold)
+- Test flakiness rate (should be <1%)
+- Coverage percentage (should be >80%)
+
+### Reports
+
+- Daily: Test execution summary
+- Weekly: Coverage trends
+- Monthly: Flaky test analysis
+- Quarterly: Test suite health review
+
+## References
+
+- Python: [pytest Documentation](https://docs.pytest.org/)
+- JavaScript: [Jest](https://jestjs.io/), [Vitest](https://vitest.dev/)
+- Node.js: [Supertest](https://github.com/visionmedia/supertest)
+- Bash: [bats](https://github.com/bats-core/bats-core)
+- TDD: [Test-Driven Development](https://martinfowler.com/bliki/TestDrivenDevelopment.html)
+
+---
+
+**Enforcement Level**: MANDATORY
+**Review Frequency**: Every commit
+**Last Updated**: 2025-01-15
+**TDD Required**: ✅ Red-Green-Refactor cycle mandatory for all code