thechart/docs/TESTING.md

# Testing Guide

This document provides a comprehensive guide to testing in TheChart application.

## Test Organization

### Directory Structure

```
thechart/
├── tests/                  # Unit tests (pytest)
│   ├── test_theme_manager.py
│   ├── test_data_manager.py
│   ├── test_ui_manager.py
│   ├── test_graph_manager.py
│   └── ...
├── scripts/               # Integration tests & demos
│   ├── integration_test.py
│   ├── test_menu_theming.py
│   ├── test_note_saving.py
│   └── ...
```

## Test Categories

### 1. Unit Tests (`/tests/`)

**Purpose**: Test individual components in isolation
**Framework**: pytest
**Location**: `/tests/` directory

#### Running Unit Tests
```bash
cd /home/will/Code/thechart
source .venv/bin/activate.fish
python -m pytest tests/
```

#### Available Unit Tests
- `test_theme_manager.py` - Theme system and menu theming
- `test_data_manager.py` - Data persistence and CSV operations
- `test_ui_manager.py` - UI component functionality
- `test_graph_manager.py` - Graph generation and display
- `test_constants.py` - Application constants
- `test_logger.py` - Logging system
- `test_main.py` - Main application logic

#### Writing Unit Tests
```python
# Example unit test structure
import unittest
import sys
import os

# Add src to path
sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'src'))

from your_module import YourClass

class TestYourClass(unittest.TestCase):
    def setUp(self):
        """Set up test fixtures."""
        pass

    def tearDown(self):
        """Clean up after tests."""
        pass

    def test_functionality(self):
        """Test specific functionality."""
        pass
```

### 2. Integration Tests (`/scripts/`)

**Purpose**: Test complete workflows and system interactions
**Framework**: Custom test scripts
**Location**: `/scripts/` directory

#### Available Integration Tests

##### `integration_test.py`
Comprehensive export system test:
- Tests JSON, XML, PDF export formats
- Validates data integrity
- Tests file creation and cleanup
- No GUI dependencies

```bash
.venv/bin/python scripts/integration_test.py
```

##### `test_note_saving.py`
Note persistence functionality:
- Tests note saving to CSV
- Validates special character handling
- Tests note retrieval

##### `test_update_entry.py`
Entry modification functionality:
- Tests data update operations
- Validates date handling
- Tests duplicate prevention

##### `test_keyboard_shortcuts.py`
Keyboard shortcut system:
- Tests key binding functionality
- Validates shortcut responses
- Tests keyboard event handling

### 3. Interactive Demonstrations (`/scripts/`)

**Purpose**: Visual and interactive testing of UI features
**Framework**: tkinter-based demos

##### `test_menu_theming.py`
Interactive menu theming demonstration:
- Live theme switching
- Visual color display
- Real-time menu updates

```bash
.venv/bin/python scripts/test_menu_theming.py
```

## Running Tests

### Complete Test Suite
```bash
cd /home/will/Code/thechart
source .venv/bin/activate.fish

# Run unit tests
python -m pytest tests/ -v

# Run integration tests
python scripts/integration_test.py

# Run specific feature tests
python scripts/test_note_saving.py
python scripts/test_update_entry.py
```

### Individual Test Categories
```bash
# Unit tests only
python -m pytest tests/

# Specific unit test file
python -m pytest tests/test_theme_manager.py -v

# Integration test
python scripts/integration_test.py

# Interactive demo
python scripts/test_menu_theming.py
```

### Test Runner Script
```bash
# Use the main test runner
python scripts/run_tests.py
```

## Test Environment Setup

### Prerequisites
1. **Virtual Environment**: Ensure `.venv` is activated
2. **Dependencies**: All requirements installed via `uv`
3. **Test Data**: Main `thechart_data.csv` file present

### Environment Activation
```bash
# Fish shell
source .venv/bin/activate.fish

# Bash/Zsh
source .venv/bin/activate
```

## Writing New Tests

### Unit Test Guidelines
1. Place in `/tests/` directory
2. Use pytest framework
3. Follow naming convention: `test_<module_name>.py`
4. Include setup/teardown for fixtures
5. Test edge cases and error conditions

### Integration Test Guidelines
1. Place in `/scripts/` directory
2. Test complete workflows
3. Include cleanup procedures
4. Document expected behavior
5. Handle GUI dependencies appropriately

### Interactive Demo Guidelines
1. Place in `/scripts/` directory
2. Include clear instructions
3. Provide visual feedback
4. Allow easy theme/feature switching
5. Include exit mechanisms

## Test Data Management

### Test File Creation
- Use `tempfile` module for temporary files
- Clean up created files in teardown
- Don't commit test data to repository

### CSV Test Data
- Most tests use main `thechart_data.csv`
- Some tests create temporary CSV files
- Integration tests may create export directories

## Continuous Integration

### Local Testing Workflow
```bash
# 1. Run linting
python -m flake8 src/ tests/ scripts/

# 2. Run unit tests
python -m pytest tests/ -v

# 3. Run integration tests
python scripts/integration_test.py

# 4. Run specific feature tests as needed
python scripts/test_note_saving.py
```

### Pre-commit Checklist
- [ ] All unit tests pass
- [ ] Integration tests pass
- [ ] New functionality has tests
- [ ] Documentation updated
- [ ] Code follows style guidelines

## Troubleshooting

### Common Issues

#### Import Errors
```python
# Ensure src is in path
import sys
import os
sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'src'))
```

#### GUI Test Issues
- Use `root.withdraw()` to hide test windows
- Ensure proper cleanup with `root.destroy()`
- Consider mocking GUI components for unit tests

#### File Permission Issues
- Ensure test has write permissions
- Use temporary directories for test files
- Clean up files in teardown methods

### Debug Mode
```bash
# Run with debug logging
python -c "import logging; logging.basicConfig(level=logging.DEBUG)" scripts/test_script.py
```

## Test Coverage

### Current Coverage Areas
- ✅ Theme management and menu theming
- ✅ Data persistence and CSV operations
- ✅ Export functionality (JSON, XML, PDF)
- ✅ UI component initialization
- ✅ Graph generation
- ✅ Note saving and retrieval
- ✅ Entry update operations
- ✅ Keyboard shortcuts

### Areas for Expansion
- Medicine and pathology management
- Settings persistence
- Error handling edge cases
- Performance testing
- UI interaction testing

## Contributing Tests

When contributing new tests:

1. **Choose the right category**: Unit vs Integration vs Demo
2. **Follow naming conventions**: Clear, descriptive names
3. **Include documentation**: Docstrings and comments
4. **Test edge cases**: Not just happy path
5. **Clean up resources**: Temporary files, windows, etc.
6. **Update documentation**: Add to this guide and scripts/README.md