Cline rules

1---
2description: 'Guides Cline to generate comprehensive test suites alongside code — covering TDD workflows, test pyramid strategy, framework patterns, and coverage analysis.'
3author: 'Cline Team'
4version: '1.0'
5category: 'Development'
6tags:
7  [
8    'testing',
9    'tdd',
10    'quality-assurance',
11    'test-generation',
12    'coverage',
13    'ci-cd',
14  ]
15globs:
16  [
17    '**/*.test.*',
18    '**/*.spec.*',
19    '**/__tests__/**',
20    '**/tests/**',
21    '**/*.py',
22    '**/*.ts',
23    '**/*.js',
24  ]
25---
26 
27# Testing Strategy & Test Generation Protocol
28 
29## Objective
30 
31Guide Cline to proactively generate, maintain, and improve test suites as a first-class development activity — not an afterthought. Testing is infrastructure: once embedded into CI/CD pipelines, it becomes the backbone of project reliability.
32 
33---
34 
35## Core Directive
36 
37You **MUST** treat tests as mandatory deliverables. When generating or modifying code, you **SHOULD** generate or update corresponding tests unless the user explicitly opts out.
38 
39Before using `attempt_completion`, verify:
40 
41- [ ] New/modified code has corresponding test coverage
42- [ ] Tests pass (or user has been informed of expected failures)
43- [ ] Edge cases and error paths are covered
44 
45---
46 
47## 1. Test Pyramid Strategy
48 
49Follow the test pyramid to allocate effort appropriately:
50 
51```
52        /  E2E  \          <- Few, slow, high-confidence
53       /----------\
54      / Integration \      <- Moderate, test boundaries
55     /----------------\
56    /    Unit Tests     \  <- Many, fast, isolated
57   /____________________\
58```
59 
60### Unit Tests (Foundation — 70% of tests)
61 
62- Test individual functions, methods, and classes in isolation
63- Mock external dependencies (databases, APIs, file system)
64- **MUST** be fast (< 100ms each)
65- **MUST** be deterministic — no flaky tests
66 
67### Integration Tests (Middle — 20% of tests)
68 
69- Test interactions between modules, services, or layers
70- Use real dependencies where practical (test databases, in-memory stores)
71- Verify API contracts, database queries, and service boundaries
72 
73### End-to-End Tests (Top — 10% of tests)
74 
75- Test critical user journeys through the full stack
76- Use sparingly — they are slow and brittle
77- Focus on happy paths and critical business flows
78 
79---
80 
81## 2. Test-Driven Development (TDD) Workflow
82 
83When the user requests TDD or when building new features:
84 
85```
861. RED    -> Write a failing test that defines the desired behavior
872. GREEN  -> Write the minimum code to make the test pass
883. REFACTOR -> Clean up code while keeping tests green
894. REPEAT
90```
91 
92**MUST** present each step clearly to the user. Do not skip ahead.
93 
94---
95 
96## 3. Framework-Specific Patterns
97 
98### JavaScript/TypeScript (Jest / Vitest)
99 
100```typescript
101describe('UserService', () => {
102  describe('createUser', () => {
103    it('should create a user with valid input', async () => {
104      const user = await userService.createUser({
105        name: 'Alice',
106        email: 'alice@example.com',
107      });
108      expect(user.id).toBeDefined();
109      expect(user.name).toBe('Alice');
110    });
111 
112    it('should throw on duplicate email', async () => {
113      await userService.createUser({name: 'Alice', email: 'alice@example.com'});
114      await expect(
115        userService.createUser({name: 'Bob', email: 'alice@example.com'}),
116      ).rejects.toThrow('Email already exists');
117    });
118 
119    it('should reject invalid email format', async () => {
120      await expect(
121        userService.createUser({name: 'Alice', email: 'not-an-email'}),
122      ).rejects.toThrow('Invalid email');
123    });
124  });
125});
126```
127 
128### Python (pytest)
129 
130```python
131import pytest
132from services.user_service import UserService
133 
134class TestUserService:
135    def test_create_user_with_valid_input(self, user_service):
136        user = user_service.create_user(name="Alice", email="alice@example.com")
137        assert user.id is not None
138        assert user.name == "Alice"
139 
140    def test_create_user_duplicate_email_raises(self, user_service):
141        user_service.create_user(name="Alice", email="alice@example.com")
142        with pytest.raises(ValueError, match="Email already exists"):
143            user_service.create_user(name="Bob", email="alice@example.com")
144 
145    def test_create_user_invalid_email_raises(self, user_service):
146        with pytest.raises(ValueError, match="Invalid email"):
147            user_service.create_user(name="Alice", email="not-an-email")
148```
149 
150### C# (xUnit)
151 
152```csharp
153public class UserServiceTests
154{
155    [Fact]
156    public async Task CreateUser_WithValidInput_ReturnsUser()
157    {
158        var service = new UserService(mockRepo.Object);
159        var user = await service.CreateUserAsync("Alice", "alice@example.com");
160        Assert.NotNull(user.Id);
161        Assert.Equal("Alice", user.Name);
162    }
163 
164    [Fact]
165    public async Task CreateUser_DuplicateEmail_ThrowsException()
166    {
167        var service = new UserService(mockRepo.Object);
168        await service.CreateUserAsync("Alice", "alice@example.com");
169        await Assert.ThrowsAsync<DuplicateEmailException>(
170            () => service.CreateUserAsync("Bob", "alice@example.com"));
171    }
172}
173```
174 
175---
176 
177## 4. What to Test — Mandatory Coverage Areas
178 
179For every function or module, **MUST** consider:
180 
181| Category              | Examples                                                      |
182| --------------------- | ------------------------------------------------------------- |
183| **Happy path**        | Valid inputs produce expected outputs                         |
184| **Edge cases**        | Empty strings, zero, null, boundary values, max-length        |
185| **Error handling**    | Invalid inputs, network failures, timeouts, permission errors |
186| **State transitions** | Before/after mutations, side effects                          |
187| **Concurrency**       | Race conditions, parallel execution (when applicable)         |
188 
189---
190 
191## 5. Mocking & Test Doubles Strategy
192 
193- **MUST** mock external services (APIs, databases, file system) in unit tests
194- **SHOULD** use dependency injection to make code testable
195- **MUST NOT** mock the system under test — only its dependencies
196- **SHOULD** prefer fakes over mocks when the dependency is complex
197 
198```
199Stub  -> Returns canned data (simplest)
200Mock  -> Verifies interactions (use sparingly)
201Fake  -> Simplified working implementation (e.g., in-memory DB)
202Spy   -> Records calls for later assertion
203```
204 
205---
206 
207## 6. Test Quality Checklist
208 
209Before completing any testing task, verify:
210 
211- [ ] **Descriptive names**: Test names describe the scenario, not the implementation (`should_reject_expired_token` not `test1`)
212- [ ] **Arrange-Act-Assert**: Each test follows the AAA pattern clearly
213- [ ] **One assertion per concept**: Tests verify one behavior (multiple `expect` calls are fine if they verify one logical outcome)
214- [ ] **No test interdependence**: Tests can run in any order
215- [ ] **No hardcoded sleep/delays**: Use polling, events, or test clocks
216- [ ] **Meaningful assertions**: Assert specific values, not just "no error thrown"
217 
218---
219 
220## 7. Coverage Analysis
221 
222When asked about coverage or when completing a testing task:
223 
224- **SHOULD** suggest running coverage tools (`jest --coverage`, `pytest --cov`, `dotnet test --collect:"XPlat Code Coverage"`)
225- **Target**: 80%+ line coverage for business logic, 90%+ for critical paths
226- **MUST NOT** chase 100% — focus on meaningful coverage, not vanity metrics
227- Uncovered code **SHOULD** be flagged with rationale (e.g., "UI rendering — covered by E2E tests")
228 
229---
230 
231## 8. CI/CD Integration Guidance
232 
233When setting up or advising on CI/CD:
234 
235- Tests **MUST** run on every PR/push
236- Fast unit tests run first; slow integration/E2E tests run after
237- Failed tests **MUST** block merge
238- Coverage reports **SHOULD** be posted as PR comments
239- Flaky tests **MUST** be quarantined and fixed, not ignored
240 
241---
242 
243## 9. Test Documentation
244 
245When adding/modifying/deleting tests, make sure that TEST_CATALOGUE is kept up to date.
246 
247<!--
248Enterprise Considerations:
249- Team-wide configurable coverage thresholds enforced across all repositories
250- Test health dashboards showing pass rates, flakiness trends, and coverage gaps
251- Shared test fixture and pattern libraries distributed across teams
252- Automated test quality scoring and team benchmark comparisons
253-->
254