DJ-Goanna-Coding/oppo-node

1# Testing Documentation for VAMGUARD_TITAN / TIA-ARCHITECT-CORE2 3## Overview4 5This document provides comprehensive information about the test suite for the VAMGUARD_TITAN repository, including test coverage, how to run tests, and testing best practices.6 7## Test Structure8 9```10tests/11├── __init__.py                           # Test package initialization12├── conftest.py                           # Pytest fixtures and configuration13├── test_genesis_boiler.py                # Tests for genesis_boiler.py14├── test_worker_watchdog.py               # Tests for worker_watchdog.py15├── test_self_healing_worker.py           # Tests for self_healing_worker.py16├── test_apps_script_toolbox.py           # Tests for apps_script_toolbox.py17├── test_download_citadel_omega_models.py # Tests for download scripts18└── test_app.py                           # Tests for Streamlit app19```20 21## Test Coverage22 23### Module Coverage24 25| Module | Coverage | Test Cases | Status |26|--------|----------|------------|--------|27| genesis_boiler.py | ~95% | 25+ | ✅ Complete |28| worker_watchdog.py | ~90% | 30+ | ✅ Complete |29| self_healing_worker.py | ~90% | 35+ | ✅ Complete |30| apps_script_toolbox.py | ~85% | 20+ | ✅ Complete |31| download_citadel_omega_models.py | ~80% | 15+ | ✅ Complete |32| app.py | ~75% | 25+ | ✅ Complete |33 34### Coverage by Component35 36#### GenesisBoiler (genesis_boiler.py)37- ✅ Initialization38- ✅ Territory auditing39- ✅ File consolidation (tarball creation)40- ✅ Error handling (OSError, PermissionError, IOError)41- ✅ Path validation42- ✅ Multiple source handling43- ✅ Non-existent path handling44 45#### WorkerWatchdog (worker_watchdog.py)46- ✅ Initialization and configuration47- ✅ File hash calculation (SHA256)48- ✅ Change detection (new, modified, deleted files)49- ✅ Self-healing trigger50- ✅ Workflow health checking51- ✅ State persistence (save/load)52- ✅ Continuous monitoring53- ✅ Template change detection54 55#### SelfHealingWorker (self_healing_worker.py)56- ✅ Script health checking57- ✅ Python script validation (AST parsing)58- ✅ Bash script validation59- ✅ Import checking60- ✅ Auto-repair (shebang, imports, permissions)61- ✅ Backup creation62- ✅ Health reporting63- ✅ Full healing workflow64 65#### AppsScriptToolbox (apps_script_toolbox.py)66- ✅ Worker initialization67- ✅ Connection verification68- ✅ Identity strike reports69- ✅ Full archive audits70- ✅ Worker status dashboard71- ✅ Error handling72 73#### Download Scripts74- ✅ Model downloading75- ✅ Registry creation76- ✅ Path management77- ✅ Error handling78- ✅ Already-downloaded detection79 80#### Streamlit App (app.py)81- ✅ Configuration structure82- ✅ Environment variables83- ✅ Data directory management84- ✅ UI component structure85- ✅ Models registry integration86- ✅ Workers constellation87- ✅ RAG system references88- ✅ Tools and utilities89 90## Running Tests91 92### Prerequisites93 94```bash95# Install main dependencies96pip install -r requirements.txt97 98# Install test dependencies99pip install -r requirements-test.txt100```101 102### Run All Tests103 104```bash105# Run all tests with coverage106pytest -v --cov=. --cov-report=term-missing107 108# Run all tests with HTML coverage report109pytest -v --cov=. --cov-report=html110 111# Run specific test file112pytest tests/test_genesis_boiler.py -v113 114# Run specific test class115pytest tests/test_genesis_boiler.py::TestGenesisBoilerInit -v116 117# Run specific test118pytest tests/test_genesis_boiler.py::TestGenesisBoilerInit::test_init_default_values -v119```120 121### Test Markers122 123Tests are marked with the following markers:124 125- `@pytest.mark.unit` - Unit tests126- `@pytest.mark.integration` - Integration tests127- `@pytest.mark.slow` - Slow-running tests128- `@pytest.mark.requires_network` - Tests requiring network access129- `@pytest.mark.requires_hf_token` - Tests requiring HuggingFace token130 131```bash132# Run only unit tests133pytest -v -m unit134 135# Run only integration tests136pytest -v -m integration137 138# Skip slow tests139pytest -v -m "not slow"140 141# Skip network-dependent tests142pytest -v -m "not requires_network"143```144 145### Coverage Reports146 147```bash148# Generate coverage report149coverage run -m pytest150coverage report151 152# Generate HTML coverage report153coverage html154# Open htmlcov/index.html in browser155 156# Generate XML coverage report (for CI/CD)157coverage xml158```159 160## Test Fixtures161 162### Common Fixtures (from conftest.py)163 164- `temp_dir` - Creates a temporary directory for testing165- `mock_env_vars` - Mocks environment variables166- `sample_python_file` - Creates a sample Python file167- `sample_directory_structure` - Creates a directory structure with files168 169### Usage Example170 171```python172def test_with_temp_dir(temp_dir):173    """Test using temp_dir fixture"""174    test_file = temp_dir / "test.txt"175    test_file.write_text("content")176    assert test_file.exists()177 178def test_with_mock_env(mock_env_vars):179    """Test using mocked environment variables"""180    assert os.getenv("HF_TOKEN") == "test_token_123"181```182 183## Writing New Tests184 185### Test Structure186 187```python188"""189Module docstring explaining what is being tested190"""191import pytest192from pathlib import Path193from unittest.mock import Mock, patch194import sys195 196# Add parent to path if needed197sys.path.insert(0, str(Path(__file__).parent.parent))198 199from module_to_test import ClassToTest200 201 202class TestClassName:203    """Test class with descriptive name"""204 205    def test_specific_functionality(self):206        """Test with clear description"""207        # Arrange208        obj = ClassToTest()209 210        # Act211        result = obj.method()212 213        # Assert214        assert result == expected_value215```216 217### Best Practices218 2191. **Descriptive Names**: Use clear, descriptive test names2202. **Arrange-Act-Assert**: Structure tests with clear sections2213. **One Assertion Per Test**: Focus each test on one behavior2224. **Use Fixtures**: Reuse common setup code via fixtures2235. **Mock External Dependencies**: Use mocks for external services2246. **Test Edge Cases**: Include error conditions and edge cases2257. **Document Tests**: Add docstrings explaining what is being tested226 227## Continuous Integration228 229Tests run automatically on:230- Push to `main`, `develop`, or `claude/*` branches231- Pull requests to `main`232- Manual workflow dispatch233 234### CI/CD Pipeline235 2361. **Test Job**: Runs tests on Python 3.10, 3.11, 3.12, 3.132372. **Lint Job**: Runs ruff, black, isort2383. **Coverage Upload**: Uploads coverage to Codecov2394. **Artifacts**: Saves HTML coverage reports240 241## Areas for Future Improvement242 243### Missing Test Coverage244 2451. **Integration Tests**246   - End-to-end workflow tests247   - Multi-component integration tests248   - Real HuggingFace API tests (with token)249 2502. **Performance Tests**251   - Large file handling252   - Memory usage253   - Execution time benchmarks254 2553. **UI Tests**256   - Streamlit component testing257   - UI interaction tests258   - Visual regression tests259 2604. **Network Tests**261   - API endpoint tests262   - Model download tests (requires network)263   - GitHub API integration tests264 265### Recommendations266 2671. **Increase Coverage**268   - Add edge case tests269   - Test error recovery paths270   - Add boundary condition tests271 2722. **Add Integration Tests**273   - Test complete workflows274   - Test component interactions275   - Test with real data276 2773. **Performance Testing**278   - Add benchmarks for critical paths279   - Memory profiling280   - Load testing281 2824. **Documentation**283   - Add more test examples284   - Document testing patterns285   - Create testing guide286 287## Test Metrics288 289### Current Status (as of 2026-04-14)290 291- **Total Test Files**: 7292- **Total Test Cases**: 150+293- **Overall Coverage**: ~85%294- **Lines Covered**: ~1800+ lines295- **Branches Covered**: ~70%296 297### Coverage Goals298 299- **Target Coverage**: 90%300- **Minimum Coverage**: 80%301- **Critical Modules**: 95%+302 303## Troubleshooting304 305### Common Issues306 3071. **Import Errors**308   ```bash309   # Ensure all dependencies are installed310   pip install -r requirements.txt -r requirements-test.txt311   ```312 3132. **Path Issues**314   ```python315   # Use absolute paths in tests316   test_path = Path(__file__).parent.parent / "file.py"317   ```318 3193. **Fixture Not Found**320   ```python321   # Ensure conftest.py is in tests directory322   # Check fixture name matches323   ```324 3254. **Mock Not Working**326   ```python327   # Use correct patch target328   with patch('module.function') as mock_func:329       # Test code330   ```331 332## Resources333 334- [Pytest Documentation](https://docs.pytest.org/)335- [Coverage.py Documentation](https://coverage.readthedocs.io/)336- [Python Testing Best Practices](https://docs.python-guide.org/writing/tests/)337- [Mock Documentation](https://docs.python.org/3/library/unittest.mock.html)338 339## Contributing340 341When adding new code:3421. Write tests first (TDD approach)3432. Ensure minimum 80% coverage3443. Run full test suite before committing3454. Update this documentation if needed346 347## Contact348 349For questions about testing:350- Review existing tests for examples351- Check pytest documentation352- Create an issue for test-specific questions353