HeurAMS/tests

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

python tests/run_tests.py
# or
python -m pytest tests/

Run Specific Tests

# 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

python tests/run_tests.py --examples

Using Pytest Directly

# 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