Skip to content

Commit 91a926c

Browse files
DinisCruzDinisCruz
committed
added dev brief for code-coverage
1 parent 727ef04 commit 91a926c

1 file changed

Lines changed: 261 additions & 0 deletions

File tree

‎docs/dev-briefs/v0.32.1__improve-test-coverage/v0.32.1__dev-brief__improve-test-coverage.md‎

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
# Dev Brief: Improve Test Coverage
2+
3+
**Version**: v0.32.1
4+
**Date**: January 2025
5+
**Status**: Planning
6+
**Target Package**: `osbot_fast_api`
7+
8+
---
9+
10+
## Executive Summary
11+
12+
This document outlines a systematic approach to **improve test coverage** for the OSBot-Fast-API project. The goal is to identify coverage gaps, prioritize high-value test additions, and implement comprehensive tests that follow the project's established testing patterns.
13+
14+
### Key Outcomes
15+
16+
1. **Establish baseline coverage metrics** via pytest-cov
17+
2. **Identify untested or under-tested modules** across the codebase
18+
3. **Prioritize coverage improvements** by criticality and risk
19+
4. **Implement new tests** following existing patterns (unittest.TestCase, singleton fixtures)
20+
5. **Document coverage targets** and establish ongoing coverage monitoring
21+
22+
---
23+
24+
## Current State Analysis
25+
26+
### Project Structure
27+
28+
```
29+
osbot_fast_api/ # 87 Python source files
30+
├── api/ # Core API implementation
31+
│ ├── Fast_API.py # Main FastAPI wrapper class
32+
│ ├── decorators/ # Route path decorators
33+
│ ├── middlewares/ # Built-in middleware
34+
│ ├── routes/ # Route handling and registration
35+
│ ├── schemas/ # API schemas and configuration
36+
│ └── transformers/ # Type conversion system
37+
├── client/ # API client generation
38+
├── events/ # HTTP event tracking system
39+
└── utils/ # Utility modules
40+
41+
tests/ # 60 test files, ~704 test methods
42+
├── unit/ # Unit tests (majority)
43+
│ ├── api/ # API component tests
44+
│ ├── client/ # Client tests
45+
│ ├── events/ # Events tests
46+
│ ├── schemas/ # Schema tests
47+
│ └── utils/ # Utility tests
48+
└── integration/ # Integration tests
49+
```
50+
51+
### Testing Infrastructure
52+
53+
| Component | Current State |
54+
|-----------|---------------|
55+
| Test Framework | pytest |
56+
| Coverage Tool | coverage (installed, not actively measured) |
57+
| Test Dependencies | pytest, coverage, httpx |
58+
| Singleton Fixtures | `tests/unit/fast_api__for_tests.py` |
59+
| CI/CD | GitHub Actions (runs pytest, no coverage threshold) |
60+
61+
### Known Characteristics
62+
63+
- **Test style**: `unittest.TestCase` base class
64+
- **Naming convention**: `test__<method_name>__<scenario>`
65+
- **Multi-angle testing**: Internal state, HTTP client, behavioral
66+
- **Performance optimization**: Shared Fast_API instance via singleton fixture
67+
68+
---
69+
70+
## Approach
71+
72+
### Phase 1: Measure Current Coverage
73+
74+
Run comprehensive coverage analysis to establish baseline:
75+
76+
```bash
77+
poetry run pytest --cov=osbot_fast_api --cov-report=term-missing --cov-report=html
78+
```
79+
80+
This will produce:
81+
- Overall coverage percentage
82+
- Per-file coverage breakdown
83+
- Line-by-line missing coverage report
84+
- HTML report for visual analysis
85+
86+
### Phase 2: Identify Coverage Gaps
87+
88+
Analyze the coverage report to identify:
89+
90+
```
91+
┌─────────────────────────────────────────────────────────────────────────────┐
92+
│ COVERAGE GAP CATEGORIES │
93+
├─────────────────────────────────────────────────────────────────────────────┤
94+
│ │
95+
│ 1. UNTESTED MODULES 2. LOW-COVERAGE MODULES │
96+
│ ────────────────── ────────────────────── │
97+
│ • Source files with 0% coverage • Files with < 50% coverage │
98+
│ • No corresponding test file • Missing branch coverage │
99+
│ • New features without tests • Error paths not exercised │
100+
│ │
101+
│ 3. UNTESTED METHODS 4. UNCOVERED BRANCHES │
102+
│ ─────────────────── ──────────────────── │
103+
│ • Public methods with no tests • if/else paths not covered │
104+
│ • Critical paths untested • try/except blocks untested │
105+
│ • Edge cases not covered • Conditional logic gaps │
106+
│ │
107+
└─────────────────────────────────────────────────────────────────────────────┘
108+
```
109+
110+
### Phase 3: Prioritization Matrix
111+
112+
Prioritize test additions based on:
113+
114+
| Priority | Criteria | Examples |
115+
|----------|----------|----------|
116+
| **Critical** | Core functionality, public API, frequently used | `Fast_API`, route registration, middleware |
117+
| **High** | Type conversion, schema validation | Transformers, Type_Safe integration |
118+
| **Medium** | Utility functions, edge cases | Helpers, error handling paths |
119+
| **Low** | Internal utilities, deprecated code | Private methods, legacy support |
120+
121+
### Phase 4: Implementation Strategy
122+
123+
Follow existing project patterns:
124+
125+
```python
126+
# ═══════════════════════════════════════════════════════════════════════════════
127+
# Test Structure Pattern
128+
# ═══════════════════════════════════════════════════════════════════════════════
129+
130+
from unittest import TestCase
131+
132+
class test_<ClassName>(TestCase):
133+
134+
def test__<method_name>__<scenario>(self):
135+
# Arrange
136+
with <ClassName>() as _:
137+
# Act
138+
result = _.<method_name>()
139+
140+
# Assert
141+
assert result == expected_value
142+
```
143+
144+
#### Test Categories to Add
145+
146+
1. **Unit Tests** - Individual method/class testing
147+
2. **Integration Tests** - Cross-component interaction
148+
3. **Edge Case Tests** - Boundary conditions, error handling
149+
4. **Regression Tests** - Bug fixes with test coverage
150+
151+
---
152+
153+
## Execution Environment
154+
155+
### Environment Details
156+
157+
| Aspect | Configuration |
158+
|--------|---------------|
159+
| **Execution Context** | Direct execution on host machine (macOS darwin) |
160+
| **Python Environment** | Poetry virtual environment (isolated from system Python) |
161+
| **Working Directory** | Git worktree: `distracted-shirley` branch |
162+
| **Dependency Isolation** | Poetry venv at `~/.cache/pypoetry/virtualenvs/` |
163+
164+
### Git Worktree Structure
165+
166+
```
167+
Main repository:
168+
/Users/diniscruz/_dev/.../OSBot-Fast-API (branch: dev)
169+
│
170+
└── .git/worktrees/distracted-shirley/
171+
172+
Worktree (current):
173+
/Users/diniscruz/.claude-worktrees/OSBot-Fast-API/distracted-shirley
174+
│
175+
└── .git (pointer file to main repo)
176+
```
177+
178+
**Key Points**:
179+
- Changes are isolated to the `distracted-shirley` branch
180+
- Main working directory (`dev` branch) remains unaffected
181+
- Commits can be pushed and merged via PR
182+
183+
### Commands to Run Tests
184+
185+
```bash
186+
# Install dependencies
187+
poetry install
188+
poetry run pip install -r requirements-test.txt
189+
190+
# Run tests with coverage
191+
poetry run pytest --cov=osbot_fast_api --cov-report=term-missing
192+
193+
# Generate HTML coverage report
194+
poetry run pytest --cov=osbot_fast_api --cov-report=html
195+
196+
# Run specific test file
197+
poetry run pytest tests/unit/api/test_Fast_API.py -v
198+
```
199+
200+
---
201+
202+
## Expected Deliverables
203+
204+
### Coverage Reports
205+
206+
1. **Baseline coverage report** - Current state metrics
207+
2. **Gap analysis document** - List of uncovered modules/methods
208+
3. **Priority matrix** - Ranked list of coverage improvements
209+
210+
### New Tests
211+
212+
Following the existing test patterns:
213+
- Test files in appropriate `tests/unit/` or `tests/integration/` directories
214+
- Naming convention: `test_<ClassName>.py`
215+
- Method naming: `test__<method>__<scenario>`
216+
217+
### Documentation Updates
218+
219+
- Updated testing documentation if new patterns are introduced
220+
- Coverage thresholds added to CI pipeline (optional)
221+
222+
---
223+
224+
## Success Criteria
225+
226+
| Metric | Target |
227+
|--------|--------|
228+
| Overall coverage increase | Measurable improvement from baseline |
229+
| Critical modules coverage | > 80% for core API components |
230+
| New tests pass | All new tests green in CI |
231+
| No regressions | Existing tests continue to pass |
232+
233+
---
234+
235+
## Risk Considerations
236+
237+
| Risk | Mitigation |
238+
|------|------------|
239+
| Tests affect other worktrees | Using isolated git worktree |
240+
| Dependency conflicts | Poetry venv provides isolation |
241+
| Slow test execution | Leverage singleton fixture pattern |
242+
| Flaky tests | Follow deterministic testing patterns |
243+
244+
---
245+
246+
## Next Steps
247+
248+
1. [ ] Run initial coverage report to establish baseline
249+
2. [ ] Analyze report and identify top coverage gaps
250+
3. [ ] Create prioritized list of modules needing tests
251+
4. [ ] Begin implementing tests for highest-priority gaps
252+
5. [ ] Track coverage improvement iteratively
253+
254+
---
255+
256+
## References
257+
258+
- **Testing Guide**: `docs/testing/comprehensive-testing-guide.md`
259+
- **Test Patterns**: `docs/testing/test-patterns-reference.md`
260+
- **Singleton Fixture**: `tests/unit/fast_api__for_tests.py`
261+
- **CI Pipeline**: `.github/workflows/ci-pipeline__dev.yml`

0 commit comments

Comments
 (0)