@tonycasey/lisa 0.5.13

package/dist/templates/rules/shared/testing-principles.md

@@ -0,0 +1,469 @@
+# Testing Principles
+
+**Note:** These principles apply to ALL programming languages. See your language-specific rules for testing frameworks and syntax.
+
+## Testing Pyramid
+
+The testing pyramid guides how much testing to do at each level:
+
+```
+       /\
+      /  \     E2E Tests (10%)
+     /____\
+    /      \   Integration Tests (20%)
+   /________\
+  /          \ Unit Tests (70%)
+ /____________\
+```
+
+### Unit Tests (70%)
+
+**What:** Test individual components in isolation
+
+**Characteristics:**
+- Fast (milliseconds)
+- No external dependencies
+- Test one thing at a time
+- Use mocks/stubs for dependencies
+
+**Examples:**
+- Domain entity behavior
+- Business logic in services
+- Validation rules
+- Utility functions
+
+### Integration Tests (20%)
+
+**What:** Test components working together
+
+**Characteristics:**
+- Slower (seconds)
+- May use real dependencies (database, etc.)
+- Test integration points
+- Verify contracts between layers
+
+**Examples:**
+- Repository with real database
+- Service with real repositories
+- API endpoint with real database
+- External service integration
+
+### End-to-End Tests (10%)
+
+**What:** Test complete user workflows
+
+**Characteristics:**
+- Slowest (minutes)
+- Uses real system
+- Tests critical user paths
+- Brittle, expensive to maintain
+
+**Examples:**
+- User registration flow
+- Checkout process
+- Complete order workflow
+
+## Testing Principles
+
+### 1. Tests Should Be FIRST
+
+- **Fast**: Run quickly (unit tests in milliseconds)
+- **Independent**: Don't depend on other tests
+- **Repeatable**: Same result every time
+- **Self-Validating**: Pass or fail, no manual checking
+- **Timely**: Written with or before the code
+
+### 2. Arrange-Act-Assert Pattern
+
+Structure tests in three clear phases:
+
+```
+// Arrange - Set up test data and dependencies
+setup test data
+create mocks
+configure system
+
+// Act - Execute the behavior being tested
+result = systemUnderTest.method(input)
+
+// Assert - Verify the outcome
+assert result equals expected
+assert mock was called correctly
+```
+
+### 3. Test Behavior, Not Implementation
+
+**Good:** Test what the code does (public interface)
+**Bad:** Test how it does it (internal details)
+
+**Why:**
+- Tests survive refactoring
+- More maintainable
+- Focus on contracts
+
+### 4. One Assertion Per Test Concept
+
+Each test should verify one logical concept.
+
+**Not:** One assert statement per test
+**Instead:** One logical verification per test
+
+Multiple asserts are fine if they verify the same concept.
+
+### 5. Meaningful Test Names
+
+Test names should describe:
+- What is being tested
+- Under what conditions
+- What the expected outcome is
+
+**Patterns:**
+- `methodName_givenCondition_shouldExpectedOutcome`
+- `should_expectedOutcome_when_condition`
+- `test_specificBehavior`
+
+## Test Organization
+
+### Test File Structure
+
+Tests should mirror source code structure:
+
+```
+src/
+└── domain/
+    └── services/
+        └── ProductService
+
+tests/
+└── unit/
+    └── domain/
+        └── services/
+            └── ProductService.test
+```
+
+### Test Suite Organization
+
+Group related tests with clear hierarchy:
+
+```
+describe ProductService
+    describe getById
+        test should return product when exists
+        test should throw error when not found
+        test should handle invalid ID format
+
+    describe create
+        test should create product with valid data
+        test should validate required fields
+        test should throw error for duplicate SKU
+```
+
+## Mocking Strategies
+
+### When to Mock
+
+**Mock:**
+- External dependencies (database, API, file system)
+- Dependencies in unit tests
+- Slow or non-deterministic operations
+- Components you don't control
+
+**Don't mock:**
+- The system under test
+- Simple value objects
+- Domain entities (usually)
+- Trivial dependencies
+
+### Types of Test Doubles
+
+1. **Dummy**: Passed but never used
+2. **Stub**: Returns predefined values
+3. **Spy**: Records how it was called
+4. **Mock**: Pre-programmed with expectations
+5. **Fake**: Working implementation (e.g., in-memory database)
+
+### Mock Verification
+
+Verify mocks were called correctly:
+
+```
+// Verify method was called
+assert mock.method was called
+
+// Verify with specific arguments
+assert mock.method was called with (arg1, arg2)
+
+// Verify call count
+assert mock.method was called exactly once
+
+// Verify order
+assert mock.methodA was called before mock.methodB
+```
+
+## Testing Repositories
+
+### Unit Tests (Mocked)
+
+Test services using repository interfaces:
+
+**What to test:**
+- Business logic using the repository
+- Error handling
+- Edge cases
+
+**How:**
+- Mock the repository interface
+- Configure return values
+- Verify correct calls
+
+### Integration Tests (Real Database)
+
+Test repository implementations:
+
+**What to test:**
+- CRUD operations work correctly
+- Query methods return right data
+- Constraints are enforced
+- Transactions work
+
+**How:**
+- Use test database
+- Clean up after each test
+- Test with real data
+
+## Testing Services
+
+### Test with Mocked Dependencies
+
+Services should be tested with mocked repositories:
+
+**Setup:**
+1. Create mock repositories
+2. Configure mock responses
+3. Inject mocks into service
+4. Test service behavior
+
+**Verify:**
+- Service returns correct results
+- Service calls repositories correctly
+- Service handles errors
+- Service implements business logic
+
+### Test Error Handling
+
+Every error path should be tested:
+
+**Scenarios:**
+- Invalid input
+- Not found errors
+- Constraint violations
+- External service failures
+
+## Test Data Management
+
+### Test Fixtures
+
+Reusable test data:
+
+**Benefits:**
+- Consistent test data
+- DRY principle
+- Easy to maintain
+
+**Approaches:**
+- Factory functions
+- Builder pattern
+- Fixture files
+
+### Test Data Builders
+
+Use builders for complex objects:
+
+**Benefits:**
+- Flexible test data creation
+- Clear test setup
+- Easy to customize
+
+**Pattern:**
+```
+builder = EntityBuilder()
+    .withProperty1(value1)
+    .withProperty2(value2)
+
+entity = builder.build()
+```
+
+### Data Cleanup
+
+Clean up test data after tests:
+
+**Why:**
+- Tests remain independent
+- Avoid side effects
+- Fresh state for each test
+
+**How:**
+- Use setup/teardown hooks
+- Clean database in integration tests
+- Reset mocks in unit tests
+
+## Test Coverage
+
+### Coverage Goals
+
+**Targets:**
+- Critical business logic: 95%+
+- Services and repositories: 90%+
+- Utilities and helpers: 80%+
+- Overall project: 80%+
+
+### What NOT to Test
+
+Don't waste time testing:
+- Third-party libraries
+- Framework code
+- Generated code
+- Simple getters/setters
+- Configuration files
+
+### Coverage vs Quality
+
+**Remember:**
+- 100% coverage doesn't mean bug-free
+- Focus on meaningful tests
+- Quality over quantity
+- Test important paths first
+
+## Testing Async Code
+
+### Promises/Futures
+
+Test asynchronous operations properly:
+
+**Requirements:**
+- Await async operations
+- Handle rejections/errors
+- Test timeout scenarios
+- Verify async error handling
+
+### Callbacks
+
+If using callbacks:
+- Use test framework support
+- Mark test as async
+- Call done/completion
+- Handle timeouts
+
+## Performance Testing
+
+### Test Speed
+
+**Unit tests:**
+- Should run in milliseconds
+- No I/O operations
+- No network calls
+- No database access
+
+**Integration tests:**
+- Should run in seconds
+- Can use real dependencies
+- Should still be reasonably fast
+
+### Parallel Execution
+
+Run tests in parallel:
+- Speeds up test suite
+- Tests must be independent
+- No shared state
+- Careful with database tests
+
+## Common Anti-Patterns
+
+### ❌ Testing Implementation Details
+
+**Problem:** Tests break on refactoring
+
+**Solution:** Test public interface and behavior
+
+### ❌ One Giant Test
+
+**Problem:** Hard to debug failures, tests multiple things
+
+**Solution:** Split into focused tests
+
+### ❌ Test Interdependence
+
+**Problem:** Tests depend on each other's state
+
+**Solution:** Make tests independent with setup/teardown
+
+### ❌ Ignoring Failures
+
+**Problem:** Commented out or skipped failing tests
+
+**Solution:** Fix or delete, don't ignore
+
+### ❌ No Assertions
+
+**Problem:** Test runs but doesn't verify anything
+
+**Solution:** Every test needs assertions
+
+### ❌ Overuse of Mocks
+
+**Problem:** Mocking everything, including trivial code
+
+**Solution:** Only mock external dependencies
+
+## Test-Driven Development (TDD)
+
+### Red-Green-Refactor Cycle
+
+1. **Red**: Write a failing test
+2. **Green**: Write minimum code to pass
+3. **Refactor**: Improve code while keeping tests green
+
+### Benefits of TDD
+
+- Better design (testable by default)
+- Living documentation
+- Confidence in changes
+- Fewer bugs
+
+### When to Use TDD
+
+**Good for:**
+- Well-understood requirements
+- Complex business logic
+- Critical functionality
+- Learning new concepts
+
+**Skip for:**
+- Prototyping
+- UI exploration
+- Spike solutions
+- Trivial code
+
+## Testing Checklist
+
+- [ ] Tests follow FIRST principles
+- [ ] Test pyramid respected (70/20/10)
+- [ ] Arrange-Act-Assert structure
+- [ ] Meaningful test names
+- [ ] Tests are independent
+- [ ] One concept per test
+- [ ] Appropriate use of mocks
+- [ ] Error cases tested
+- [ ] Test data cleaned up
+- [ ] Tests run fast
+- [ ] Coverage on critical paths
+- [ ] Tests are maintainable
+
+## Language-Specific Testing
+
+For testing frameworks, assertion libraries, and syntax in your language:
+
+- **TypeScript**: `languages/typescript/testing.md`
+- **Python**: `languages/python/testing.md`
+- **Go**: `languages/go/testing.md`
+- **Java**: `languages/java/testing.md`