feat: enhance menu theming with comprehensive documentation and testing support
Some checks failed
Build and Push Docker Image / build-and-push (push) Has been cancelled
Some checks failed
Build and Push Docker Image / build-and-push (push) Has been cancelled
This commit is contained in:
William Valentin
296
docs/TESTING.md
Normal file
296
docs/TESTING.md
Normal file
@@ -0,0 +1,296 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user