Cursor rule

1---
2globs:
3  - "**/tests/**/*"
4  - "**/__tests__/**/*"
5  - "**/*.test.{ts,tsx,py}"
6  - "**/*.spec.{ts,tsx,py}"
7  - "**/test_*.py"
8---
9 
10# Cross-Cutting Testing Standards
11 
12## Testing Philosophy
13 
14### Test Pyramid
15- **Unit Tests (70%)**: Fast, isolated
16- **Integration Tests (20%)**: Component interactions
17- **E2E Tests (10%)**: Complete workflows
18 
19### What to Test
20✅ **Do test:**
21- Business logic
22- Edge cases and errors
23- API contracts
24- Critical workflows
25- Data transformations
26 
27❌ **Don't test:**
28- Third-party library internals
29- Trivial getters/setters
30- Framework code
31 
32## Test Organization
33 
34Python (hermes-api):
35```
36tests/
37├── conftest.py              # Shared fixtures
38├── test_api/                # API tests
39├── test_integration/        # Integration tests
40├── test_services/           # Service tests
41└── test_tasks/              # Task tests
42```
43 
44TypeScript (hermes-app):
45```
46src/
47├── components/__tests__/    # Component tests
48├── hooks/__tests__/         # Hook tests
49└── services/__tests__/      # Service tests
50```
51 
52### File Naming
53- Python: `test_*.py`
54- TypeScript: `*.test.ts`, `*.test.tsx`
55- Match test file to source file name
56 
57## Test Structure
58 
59### Arrange-Act-Assert
60```python
61def test_create_user():
62    # Arrange
63    user_data = {"username": "test", "email": "test@example.com"}
64    
65    # Act
66    result = create_user(user_data)
67    
68    # Assert
69    assert result.username == "test"
70    assert result.id is not None
71```
72 
73### Test Naming
74Follow: `test_<what>_<condition>_<expected>`
75 
76```python
77# ✅ Good
78def test_create_download_valid_url_returns_download():
79def test_get_download_not_found_raises_404():
80 
81# ❌ Bad
82def test_download():
83def test_1():
84```
85 
86## Best Practices
87 
88### Test Independence
89- Each test runs independently
90- Don't rely on order
91- Clean up after tests
92- Use fresh data
93 
94### Single Assertion Concept
95```python
96# ✅ Good - One concept (user creation)
97def test_create_user():
98    user = create_user({"username": "test"})
99    assert user.username == "test"
100    assert user.id is not None
101    assert user.created_at is not None
102 
103# ❌ Bad - Multiple concepts
104def test_user_workflow():
105    user = create_user({"username": "test"})
106    updated = update_user(user)
107    delete_user(user.id)
108```
109 
110### Descriptive Assertions
111```python
112assert response.status_code == 200, f"Expected 200, got {response.status_code}"
113assert len(downloads) > 0, "Should return downloads"
114assert "id" in data, "Missing required 'id' field"
115```
116 
117## Mocking
118 
119### When to Mock
120- External API calls
121- File system operations
122- Database calls (in unit tests)
123- Time-dependent code
124- Slow operations
125 
126### Python
127```python
128def test_fetch_video(mocker):
129    mock_api = mocker.patch("app.services.yt_dlp_service.extract_info")
130    mock_api.return_value = {"title": "Test", "duration": 120}
131    
132    result = get_video_info("https://example.com")
133    
134    assert result["title"] == "Test"
135    mock_api.assert_called_once()
136```
137 
138### TypeScript
139```typescript
140test("fetches user", async () => {
141  const mockFetch = jest.fn().mockResolvedValue({
142    json: async () => ({ id: "1", name: "Test" }),
143  });
144  global.fetch = mockFetch;
145  
146  const user = await fetchUser("1");
147  expect(user.name).toBe("Test");
148});
149```
150 
151## Test Data
152 
153### Fixtures (Python)
154```python
155@pytest.fixture
156def test_user():
157    return {
158        "username": "testuser",
159        "email": "test@example.com"
160    }
161 
162@pytest.fixture
163def test_download(test_user):
164    return {
165        "url": "https://example.com/video",
166        "user_id": test_user["id"]
167    }
168```
169 
170### Builders
171```python
172class DownloadBuilder:
173    def __init__(self):
174        self.data = {"url": "https://example.com", "status": "queued"}
175    
176    def with_url(self, url: str):
177        self.data["url"] = url
178        return self
179    
180    def build(self):
181        return self.data
182 
183# Usage
184download = DownloadBuilder().with_status("completed").build()
185```
186 
187## Coverage
188 
189### Running Coverage
190Python:
191```bash
192pytest --cov=app --cov-report=html
193```
194 
195TypeScript:
196```bash
197npm test -- --coverage
198```
199 
200### Goals
201- Aim for 80%+ on critical code
202- 100% not required
203- Focus on meaningful coverage
204- Prioritize complex logic
205 
206## Performance
207 
208### Mark Slow Tests
209```python
210@pytest.mark.slow
211def test_large_download():
212    pass
213 
214# Run fast tests only
215# pytest -m "not slow"
216```
217 
218## Integration Testing
219 
220```python
221@pytest.mark.integration
222async def test_full_flow(db_session, test_user):
223    repos = await get_repositories()
224    
225    # Create
226    download = await repos["downloads"].create({
227        "url": "https://example.com",
228        "user_id": test_user.id
229    })
230    
231    # Verify
232    retrieved = await repos["downloads"].get_by_id(download.id)
233    assert retrieved is not None
234```
235 
236## Error Testing
237 
238```python
239def test_invalid_url():
240    with pytest.raises(ValidationError) as exc:
241        create_download("not-a-url")
242    assert "Invalid URL" in str(exc.value)
243 
244def test_not_found():
245    with pytest.raises(HTTPException) as exc:
246        get_download("nonexistent")
247    assert exc.value.status_code == 404
248```
249 
250## CI Integration
251 
252- Run full suite on every commit
253- Run linting and type checking
254- Generate coverage reports
255- Fail build on failures
256 
257### Skip in CI
258```python
259@pytest.mark.skipif(
260    os.getenv("CI") == "true",
261    reason="Requires external service"
262)
263def test_external():
264    pass
265```
266 
267## Documentation
268 
269```python
270def test_download_formats():
271    """Test various supported URL formats."""
272    urls = [
273        "https://www.youtube.com/watch?v=abc",
274        "https://youtu.be/abc",
275    ]
276    for url in urls:
277        result = parse_url(url)
278        assert result is not None, f"Failed: {url}"
279```
280