feat: enhance menu theming with comprehensive documentation and testing support

2025-08-05 14:06:42 -07:00
parent c3c88c63d2
commit df9738ab17
11 changed files with 985 additions and 13 deletions
--- a/docs/DOCUMENTATION_SUMMARY.md
+++ b/docs/DOCUMENTATION_SUMMARY.md
@@ -48,6 +48,20 @@ docs/
 ├── README.md              # Documentation index and navigation guide
 ├── FEATURES.md            # Complete feature documentation (includes UI/UX)
 ├── KEYBOARD_SHORTCUTS.md  # Comprehensive shortcut reference
+├── MENU_THEMING.md        # Menu theming system documentation
+├── TESTING.md             # Comprehensive testing guide (NEW)
+├── EXPORT_SYSTEM.md       # Data export functionality
+├── DEVELOPMENT.md         # Development guidelines
+├── CHANGELOG.md           # Version history and changes
+└── DOCUMENTATION_SUMMARY.md  # This summary file
+```
+
+### Testing Documentation Consolidation (NEW)
+- **Added**: `docs/TESTING.md` - Comprehensive testing guide
+- **Updated**: `scripts/README.md` - Reorganized test script documentation
+- **Added**: `tests/test_theme_manager.py` - Unit tests for menu theming
+- **Updated**: `scripts/test_menu_theming.py` - Converted to interactive demo
+- **Organized**: Clear separation of unit tests, integration tests, and demos
 ├── EXPORT_SYSTEM.md       # Data export functionality
 ├── DEVELOPMENT.md         # Development setup and testing
 ├── CHANGELOG.md           # Version history and improvements
--- a/docs/FEATURES.md
+++ b/docs/FEATURES.md
@@ -24,6 +24,7 @@ TheChart features a sophisticated theme system powered by ttkthemes, offering 8
 - **Improved Tables**: Better selection highlighting and alternating row colors
 - **Settings System**: Comprehensive preferences with theme persistence
 - **Responsive Design**: Automatic layout adjustments and scaling
+- **Menu Theming**: Complete menu integration with theme colors and hover effects

 ### ⌨️ Comprehensive Keyboard Shortcuts
 Professional keyboard shortcut system for efficient navigation and operation.
--- a/docs/MENU_THEMING.md
+++ b/docs/MENU_THEMING.md
@@ -0,0 +1,105 @@
+# Menu Theming Documentation
+
+## Overview
+
+TheChart application now supports full menu theming that integrates seamlessly with the application's theme system. All menus (File, Tools, Theme, Help) will automatically adopt colors that match the selected application theme.
+
+## Features
+
+### Automatic Theme Integration
+- Menus automatically inherit colors from the current application theme
+- Background colors are slightly adjusted to provide subtle visual distinction
+- Hover effects use the theme's accent colors for consistency
+
+### Supported Menu Elements
+- Main menu bar
+- All dropdown menus (File, Tools, Theme, Help)
+- Menu items and separators
+- Hover/active states
+- Disabled menu items
+
+### Theme Colors Applied
+
+For each theme, the following color properties are applied to menus:
+
+- **Background**: Slightly darker/lighter than the main theme background
+- **Foreground**: Uses the theme's text color
+- **Active Background**: Uses the theme's selection/accent color
+- **Active Foreground**: Uses the theme's selection text color
+- **Disabled Foreground**: Grayed out color for disabled items
+
+## Technical Implementation
+
+### ThemeManager Methods
+
+#### `get_menu_colors() -> dict[str, str]`
+Returns a dictionary of colors specifically optimized for menu theming:
+```python
+{
+    "bg": "#edeeef",           # Menu background
+    "fg": "#5c616c",           # Menu text
+    "active_bg": "#0078d4",    # Hover background
+    "active_fg": "#ffffff",    # Hover text
+    "disabled_fg": "#888888"   # Disabled text
+}
+```
+
+#### `configure_menu(menu: tk.Menu) -> None`
+Applies theme colors to a specific menu widget:
+```python
+theme_manager.configure_menu(menubar)
+theme_manager.configure_menu(file_menu)
+```
+
+### Automatic Updates
+
+When themes are changed using the Theme menu:
+1. The new theme is applied to all UI components
+2. The menu setup is refreshed (`_setup_menu()` is called)
+3. All menus are automatically re-themed with the new colors
+
+## Usage Example
+
+```python
+# Create menu
+menubar = tk.Menu(root)
+file_menu = tk.Menu(menubar, tearoff=0)
+
+# Apply theming
+theme_manager.configure_menu(menubar)
+theme_manager.configure_menu(file_menu)
+
+# Menus will now match the current theme
+```
+
+## Color Calculation
+
+The menu background color is automatically calculated based on the main theme:
+
+- **Light themes**: Menu background is made slightly darker than the main background
+- **Dark themes**: Menu background is made slightly lighter than the main background
+
+This provides subtle visual distinction while maintaining theme consistency.
+
+## Supported Themes
+
+Menu theming works with all available themes:
+- arc
+- equilux
+- adapta
+- yaru
+- ubuntu
+- plastik
+- breeze
+- elegance
+
+## Testing
+
+A test script is available to verify menu theming functionality:
+
+```bash
+cd /home/will/Code/thechart
+.venv/bin/python scripts/test_menu_theming.py
+```
+
+This script creates a test window with menus that can be used to verify theming across different themes.
--- a/docs/README.md
+++ b/docs/README.md
@@ -53,7 +53,7 @@ Welcome to TheChart documentation! This guide will help you navigate the availab

 ### Development
 1. **Setup**: See [DEVELOPMENT.md - Development Environment Setup](DEVELOPMENT.md#development-environment-setup)
-2. **Testing**: See [DEVELOPMENT.md - Testing Framework](DEVELOPMENT.md#testing-framework)
+2. **Testing**: See [TESTING.md](TESTING.md) - Comprehensive testing guide
 3. **Architecture**: See [FEATURES.md - Technical Architecture](FEATURES.md#technical-architecture)
 4. **Contributing**: See [DEVELOPMENT.md - Development Workflow](DEVELOPMENT.md#development-workflow)

@@ -78,6 +78,8 @@ Welcome to TheChart documentation! This guide will help you navigate the availab
 - **UI/UX and Themes** → [FEATURES.md - Modern UI/UX System](FEATURES.md#-modern-uiux-system-new-in-v195)
 - **Feature Usage** → [FEATURES.md](FEATURES.md)
 - **Keyboard Shortcuts** → [KEYBOARD_SHORTCUTS.md](KEYBOARD_SHORTCUTS.md)
+- **Menu Theming** → [MENU_THEMING.md](MENU_THEMING.md)
+- **Testing** → [TESTING.md](TESTING.md)
 - **Data Export** → [EXPORT_SYSTEM.md](EXPORT_SYSTEM.md)
 - **Development** → [DEVELOPMENT.md](DEVELOPMENT.md)
 - **Version History** → [CHANGELOG.md](CHANGELOG.md)
@@ -85,8 +87,8 @@ Welcome to TheChart documentation! This guide will help you navigate the availab
 ### By User Type
 - **End Users** → Start with [README.md](../README.md), then [FEATURES.md](FEATURES.md)
 - **Power Users** → [KEYBOARD_SHORTCUTS.md](KEYBOARD_SHORTCUTS.md) and [EXPORT_SYSTEM.md](EXPORT_SYSTEM.md)
- **Developers** → [DEVELOPMENT.md](DEVELOPMENT.md) and [FEATURES.md - Technical Architecture](FEATURES.md#technical-architecture)
- **Contributors** → All documentation, especially [DEVELOPMENT.md](DEVELOPMENT.md)
+- **Developers** → [DEVELOPMENT.md](DEVELOPMENT.md), [TESTING.md](TESTING.md), and [FEATURES.md - Technical Architecture](FEATURES.md#technical-architecture)
+- **Contributors** → All documentation, especially [DEVELOPMENT.md](DEVELOPMENT.md) and [TESTING.md](TESTING.md)

 ### By Task
 - **Install TheChart** → [README.md - Installation](../README.md#installation)
@@ -95,7 +97,8 @@ Welcome to TheChart documentation! This guide will help you navigate the availab
 - **Add New Medicine** → [FEATURES.md - Modular Medicine System](FEATURES.md#-modular-medicine-system)
 - **Track Doses** → [FEATURES.md - Advanced Dose Tracking](FEATURES.md#-advanced-dose-tracking)
 - **Export Data** → [EXPORT_SYSTEM.md](EXPORT_SYSTEM.md)
- **Run Tests** → [DEVELOPMENT.md - Testing Framework](DEVELOPMENT.md#testing-framework)
+- **Run Tests** → [TESTING.md](TESTING.md) - Comprehensive testing guide
+- **Debug Issues** → [TESTING.md - Troubleshooting](TESTING.md#troubleshooting)
 - **Deploy Application** → [README.md - Deployment](../README.md#deployment)

 ---
--- a/docs/TESTING.md
+++ b/docs/TESTING.md
@@ -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