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

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

# 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

.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

.venv/bin/python scripts/test_menu_theming.py

Running Tests

Complete Test Suite

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

# 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

# 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

# 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

# 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

# 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

# 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