175 lines
5.3 KiB
Markdown
175 lines
5.3 KiB
Markdown
# HeurAMS Test Suite
|
|
|
|
This directory contains comprehensive unit tests and examples for the Heuristic Assisted Memory Scheduler (HeurAMS) system.
|
|
|
|
## Test Structure
|
|
|
|
### Unit Tests
|
|
|
|
- **`test_particles.py`** - Tests for core particle modules:
|
|
- `Atom` - Data container management
|
|
- `Electron` - Memory algorithm metadata and SM-2 implementation
|
|
- `Nucleon` - Content data management
|
|
- `Orbital` - Learning strategy configuration
|
|
- `Probe` - File detection and cloze deletion scanning
|
|
- `Loader` - Data loading and saving
|
|
|
|
- **`test_algorithms.py`** - Tests for algorithm modules:
|
|
- `BaseAlgorithm` - Abstract algorithm base class
|
|
- `SM2Algorithm` - SuperMemo-2 interval repetition algorithm
|
|
|
|
- **`test_puzzles.py`** - Tests for puzzle generation modules:
|
|
- `BasePuzzle` - Abstract puzzle base class
|
|
- `ClozePuzzle` - Cloze deletion puzzle generator
|
|
- `MCQPuzzle` - Multiple choice question generator
|
|
|
|
- **`test_reactor.py`** - Tests for reactor system modules:
|
|
- `Phaser` - Global scheduling state management
|
|
- `Procession` - Memory process queue management
|
|
- `Fission` - Single atom scheduling and puzzle generation
|
|
- `States` - State enumeration definitions
|
|
|
|
- **`test_services.py`** - Tests for service modules:
|
|
- `Config` - Configuration management
|
|
- `Hasher` - Hash computation utilities
|
|
- `Timer` - Time services with override capability
|
|
- `Version` - Version information management
|
|
- `AudioService` - Audio feedback service
|
|
- `TTSService` - Text-to-speech service
|
|
|
|
### Examples
|
|
|
|
- **`examples.py`** - Comprehensive usage examples demonstrating:
|
|
- Basic atom creation and management
|
|
- Algorithm usage and review processing
|
|
- Puzzle generation for different content types
|
|
- Reactor system workflows
|
|
- Service integration patterns
|
|
- File operations and data persistence
|
|
|
|
### Test Utilities
|
|
|
|
- **`conftest.py`** - Pytest configuration and fixtures:
|
|
- `temp_config_file` - Temporary configuration file
|
|
- `sample_atom_data` - Sample atom data for testing
|
|
- `sample_markdown_content` - Sample markdown with cloze deletions
|
|
|
|
- **`run_tests.py`** - Test runner with flexible options
|
|
|
|
## Running Tests
|
|
|
|
### Run All Tests
|
|
```bash
|
|
python tests/run_tests.py
|
|
# or
|
|
python -m pytest tests/
|
|
```
|
|
|
|
### Run Specific Tests
|
|
```bash
|
|
# Run specific test file
|
|
python tests/run_tests.py --file test_particles.py
|
|
|
|
# Run specific test class
|
|
python tests/run_tests.py --file test_particles.py --class TestAtom
|
|
|
|
# Run specific test method
|
|
python tests/run_tests.py --file test_particles.py --class TestAtom --method test_atom_creation
|
|
```
|
|
|
|
### Run Examples
|
|
```bash
|
|
python tests/run_tests.py --examples
|
|
```
|
|
|
|
### Using Pytest Directly
|
|
```bash
|
|
# Run all tests with coverage
|
|
pytest tests/ --cov=src.heurams --cov-report=html
|
|
|
|
# Run tests with specific markers
|
|
pytest tests/ -m "not slow"
|
|
|
|
# Run tests with verbose output
|
|
pytest tests/ -v
|
|
```
|
|
|
|
## Test Coverage
|
|
|
|
The test suite provides comprehensive coverage for:
|
|
|
|
- **Core Data Structures**: Atom, Electron, Nucleon, Orbital
|
|
- **Algorithms**: SM-2 interval repetition implementation
|
|
- **Puzzle Generation**: Cloze deletions and multiple choice questions
|
|
- **State Management**: Reactor system state transitions
|
|
- **Configuration**: Settings management and validation
|
|
- **Utilities**: Hashing, timing, and file operations
|
|
|
|
## Key Test Scenarios
|
|
|
|
### Algorithm Testing
|
|
- SM-2 interval calculation in learning phase
|
|
- Ease factor adjustments based on review quality
|
|
- Repetition counting and reset logic
|
|
- Boundary conditions and edge cases
|
|
|
|
### Puzzle Generation
|
|
- Cloze deletion detection and processing
|
|
- Multiple choice question generation with distractors
|
|
- Content type detection and appropriate puzzle selection
|
|
|
|
### Reactor System
|
|
- State transitions (IDLE → LEARNING → REVIEW → FINISHED)
|
|
- Procession queue management
|
|
- Fission workflow for single atom processing
|
|
|
|
### Service Integration
|
|
- Configuration loading and validation
|
|
- Time service with override capability
|
|
- Hash consistency and file operations
|
|
|
|
## Fixtures and Test Data
|
|
|
|
The test suite includes reusable fixtures for:
|
|
|
|
- Temporary configuration files
|
|
- Sample atom data structures
|
|
- Test markdown content with cloze deletions
|
|
- Mock time values for testing scheduling
|
|
|
|
## Example Usage Patterns
|
|
|
|
The `examples.py` file demonstrates common usage patterns:
|
|
|
|
1. **Basic Atom Creation** - Creating simple question-answer pairs
|
|
2. **Cloze Content** - Working with cloze deletion content
|
|
3. **Algorithm Integration** - Processing reviews with SM-2
|
|
4. **Puzzle Generation** - Creating different puzzle types
|
|
5. **Workflow Management** - Using the reactor system
|
|
6. **Configuration** - Customizing learning parameters
|
|
7. **Data Persistence** - Saving and loading atom collections
|
|
|
|
## Test Dependencies
|
|
|
|
- `pytest` - Test framework
|
|
- `pytest-cov` - Coverage reporting (optional)
|
|
- Standard Python libraries only
|
|
|
|
## Adding New Tests
|
|
|
|
When adding new tests:
|
|
|
|
1. Follow the existing naming conventions
|
|
2. Use the provided fixtures when appropriate
|
|
3. Include both positive and negative test cases
|
|
4. Test boundary conditions and edge cases
|
|
5. Ensure tests are independent and repeatable
|
|
|
|
## Continuous Integration
|
|
|
|
The test suite is designed to run in CI environments and provides:
|
|
|
|
- Fast execution (most tests complete in seconds)
|
|
- No external dependencies
|
|
- Clear failure reporting
|
|
- Comprehensive coverage of core functionality |