Skip to content

Testing

Jump to bottom
Raphael Constantinis edited this page Aug 3, 2025 · 2 revisions

Testing Guidelines

This page describes the purpose and organization of the Test folder for the entropic_measurement library, along with comprehensive testing guidelines and best practices.

Purpose of the Test Folder

The tests/ directory contains comprehensive test suites for the entropic_measurement library. It serves three primary purposes:

  • Quality Assurance: Ensures all library functions work correctly and handle edge cases appropriately
  • Regression Prevention: Validates that new changes don't break existing functionality
  • Documentation: Provides practical examples of how library functions should be used

Folder Structure

The test directory is organized as follows:

tests/
├── test_core.py           # Tests for core entropy calculation functions
├── test_utils.py          # Tests for utility functions and helpers
├── test_integration.py    # End-to-end workflow tests
├── test_performance.py    # Performance benchmarks and stress tests
├── fixtures/              # Test data files and fixtures
│   ├── sample_data.json
│   └── test_datasets.csv
└── conftest.py           # Pytest configuration and shared fixtures

Running Tests

Basic Usage with pytest

The library uses pytest as the primary testing framework. To run all tests:

# Install test dependencies
pip install pytest pytest-cov

# Run all tests
pytest tests/

# Run tests with coverage report
pytest --cov=entropic_measurement tests/

# Run specific test file
pytest tests/test_core.py

# Run tests matching a pattern
pytest -k "shannon" tests/

Advanced Usage

# Run tests in parallel (requires pytest-xdist)
pytest -n auto tests/

# Generate HTML coverage report
pytest --cov=entropic_measurement --cov-report=html tests/

# Run performance tests only
pytest tests/test_performance.py -v

Types of Tests

Unit Tests

  • Purpose: Test individual functions in isolation
  • Location: test_core.py, test_utils.py
  • Focus: Input validation, edge cases, mathematical correctness

Integration Tests

  • Purpose: Verify end-to-end workflows and component interactions
  • Location: test_integration.py
  • Focus: Data loading → processing → output workflows

Performance Tests

  • Purpose: Benchmark execution time and memory usage
  • Location: test_performance.py
  • Focus: Large datasets, scalability, resource efficiency

Example Test Implementation

Basic Unit Test

from entropic_measurement import shannon_entropy
import pytest

def test_shannon_entropy_binary():
    """Test Shannon entropy for binary distribution."""
    data = [0.5, 0.5]
    result = shannon_entropy(data)
    assert abs(result - 1.0) < 1e-10

def test_shannon_entropy_edge_cases():
    """Test edge cases and error conditions."""
    # Test empty input
    with pytest.raises(ValueError):
        shannon_entropy([])
    
    # Test negative probabilities
    with pytest.raises(ValueError):
        shannon_entropy([-0.1, 0.6, 0.5])

Integration Test Example

def test_full_entropy_analysis_workflow():
    """Test complete analysis from data loading to results."""
    # Load test data
    data = load_test_dataset('sample_data.json')
    
    # Process through full pipeline
    config = {
        'method': 'shannon',
        'normalize': True
    }
    
    result = analyze_entropy(data, config)
    
    # Validate results structure and values
    assert 'entropy' in result
    assert 'metadata' in result
    assert result['entropy'] > 0

Best Practices for Contributors

Writing New Tests

  1. Test Naming: Use descriptive names that explain what is being tested

    # Good
def test_shannon_entropy_handles_zero_probabilities():

# Avoid
def test_shannon():

  2. Test Organization: Group related tests in classes

    class TestShannonEntropy:
    def test_binary_distribution(self):
    def test_uniform_distribution(self):
    def test_edge_cases(self):

  3. Use Fixtures: Create reusable test data

    @pytest.fixture
def sample_distribution():
    return [0.3, 0.4, 0.2, 0.1]

Coverage Requirements

  • Minimum Coverage: Aim for 90% code coverage
  • Critical Paths: 100% coverage for core entropy calculations
  • Error Handling: Test all exception paths and edge cases

Test Data Guidelines

  • Use small, predictable datasets for unit tests
  • Include real-world data samples for integration tests
  • Test with various data types and distributions
  • Validate both typical and edge cases

Adding New Tests

When contributing new functionality:

  1. Create corresponding tests in the appropriate test file
  2. Follow existing patterns for test structure and naming
  3. Include edge cases and error conditions
  4. Add performance tests for computationally intensive functions
  5. Update fixtures if new test data is needed

Checklist for New Test Contributions

  • Tests cover the happy path (normal usage)
  • Tests cover edge cases (empty inputs, extreme values)
  • Tests verify error handling (invalid inputs)
  • Tests include performance considerations for large data
  • Test names are descriptive and follow conventions
  • Documentation strings explain test purpose
  • New fixtures are properly configured

Continuous Integration

Tests are automatically run on:

  • Pull Requests: All tests must pass before merging
  • Main Branch: Continuous monitoring for regressions
  • Multiple Python Versions: Compatibility testing across supported versions

Local Pre-commit Testing

Before submitting contributions:

# Run full test suite
pytest tests/ -v

# Check coverage
pytest --cov=entropic_measurement tests/ --cov-report=term-missing

# Run performance benchmarks
pytest tests/test_performance.py --benchmark-only

Troubleshooting Common Issues

Test Failures

  • Check that all dependencies are installed: pip install -e .[test]
  • Verify Python version compatibility
  • Review test data file paths and permissions

Performance Test Issues

  • Performance tests may vary based on system resources
  • Use relative comparisons rather than absolute timing
  • Consider system load when interpreting results

Further Documentation

Note: This testing framework ensures the entropic_measurement library maintains high quality and reliability. All contributors are encouraged to write comprehensive tests for their code contributions.

Clone this wiki locally