| name | coverage-analysis |
| description | Code coverage analysis using coverage.sh script and pytest-cov |
| type | usage |
| scope | project |
Coverage Analysis Guide
Purpose
Provide Claude with a comprehensive reference for running code coverage analysis in WorldArchitect.AI. This skill covers the coverage.sh script usage, interpreting results, and best practices.
Activation Cues
- Running coverage analysis
- Checking test coverage before PRs
- Investigating which code paths need more tests
- Generating coverage reports
Quick Reference
./coverage.sh
./coverage.sh --no-html
./coverage.sh --integration
./coverage.sh --integration --no-html
Output Locations
| Output | Location |
|---|
| Text report | /tmp/worldarchitectai/coverage/coverage_report.txt |
| HTML report | /tmp/worldarchitectai/coverage/index.html |
| Quick link | file:///tmp/coverage.html (symlink) |
Understanding Results
Test Summary
Test Summary:
Total tests: 232
Passed: 204
Failed: 28
Coverage Summary
Overall Coverage: 69%
Key Files Coverage:
main.py 44%
llm_service.py 74%
game_state.py 57%
firestore_service.py 53%
Coverage Thresholds
CI Workflow Thresholds
| Coverage | CI Result | Badge Color |
|---|
| ≥80% | Pass | Green (MINIMUM_GREEN: 80) |
| 60-79% | Pass (warning) | Orange (MINIMUM_ORANGE: 60) |
| <60% | Fail | Red |
Quality Guidelines
| Coverage | Status | Action | CI Threshold |
|---|
| 80%+ | Excellent | Maintain | Green (MINIMUM_GREEN: 80) |
| 60-79% | Good | Minor improvements | Orange (MINIMUM_ORANGE: 60) |
| 40-59% | Fair | Add targeted tests | Warning |
| <40% | Poor | Prioritize testing | Error |
Key Files to Monitor
Priority coverage targets for WorldArchitect.AI:
- narrative_response_schema.py - LLM response parsing
- llm_service.py - AI integration
- world_logic.py - Core game mechanics
- firestore_service.py - Data persistence
- game_state.py - State management
- main.py - API endpoints
Running Single Test Files
For focused development, run individual test files:
source venv/bin/activate
PYTHONPATH="$PWD:$PYTHONPATH" TESTING=true python mvp_site/tests/test_specific.py
Common Issues
ModuleNotFoundError: No module named 'mvp_site'
Cause: PYTHONPATH doesn't include project root.
Fix: The coverage.sh script sets PYTHONPATH="$PROJECT_ROOT:$PYTHONPATH" automatically. For manual runs:
export PYTHONPATH="$PWD:$PYTHONPATH"
Test Fails with Missing Dependencies
Fix: Install test dependencies:
pip install numpy fastembed onnxruntime
Browser/Integration Tests Failing
Some tests require additional setup:
- Browser tests need Playwright:
playwright install
- Integration tests may need running services
GitHub Actions Integration
For CI coverage reporting, use py-cov-action/python-coverage-comment-action@v3.32 (SHA-pinned in workflow):
- name: Coverage comment
uses: py-cov-action/python-coverage-comment-action@fb02115d6115e7b3325dc3295fe1dcfb1919248a
with:
GITHUB_TOKEN: ${{ github.token }}
MINIMUM_GREEN: 80
MINIMUM_ORANGE: 60
See .github/workflows/coverage.yml for the full workflow with threshold checks.
Best Practices
- Run before PRs: Check coverage impact before submitting
- Focus on critical paths: Prioritize business logic coverage
- Don't chase 100%: Focus on meaningful test coverage
- Review uncovered lines: Use HTML report for line-by-line analysis
- Mock external services: Use
TESTING=true for isolated testing
Related Skills
end2end-testing.md - E2E test patterns
evidence-standards.md - Test evidence collection