View on GitHub

TradeTrack

A modern CLI stock portfolio tracker with real-time data and beautiful displays

Development Guide

This document provides comprehensive information for developers working on TradeTrack.

Table of Contents

Getting Started for Developers

Prerequisites

Development Setup

  1. Clone the repository:

    git clone https://github.com/randyoyarzabal/stocks.git
cd stocks

  2. Set up development environment:

    # Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   
# Install production dependencies
pip install -r requirements.txt
   
# Install development dependencies
pip install -r tests/requirements.txt

  3. Verify development setup:

    # Run the automated test setup
python tests/setup_tests.py
   
# Run basic tests
python tests/run_tests.py --syntax

🧪 Testing

Test Structure

The test suite is located in the tests/ directory and follows a practical approach for a small CLI project:

tests/
├── __init__.py
├── conftest.py
├── requirements.txt          # Test dependencies
├── setup_tests.py           # Automated test setup
├── run_tests.py             # Test runner script
├── README.md                # Test documentation
├── test_basic.py            # Core functionality tests
├── test_config_loader.py    # Configuration tests
├── test_currency_formatter.py
├── test_portfolio_loader.py
├── test_yahoo_quotes.py
├── test_rich_display.py
└── test_portfolio_library.py

Test Philosophy

This test suite follows a focused approach:

Running Tests

Quick Test Commands

# Run all tests

python tests/run_tests.py

# Run specific test categories

python tests/run_tests.py --basic
python tests/run_tests.py --component

# Run tests with pattern matching

python tests/run_tests.py --pattern "test_config"

# Enable debug mode for detailed error output

python tests/run_tests.py --debug
python tests/run_tests.py --component --debug

# Run with pytest directly

pytest tests/ -v
pytest tests/test_config_loader.py -v

Test Categories

Debug Mode

The test runner includes a debug mode that provides detailed error information when tests fail. This is particularly useful during development and troubleshooting.

Usage:

# Enable debug mode for all tests
python tests/run_tests.py --debug

# Enable debug mode for specific test categories
python tests/run_tests.py --basic --debug
python tests/run_tests.py --component --debug

# Enable debug mode for pattern matching
python tests/run_tests.py --pattern "test_config" --debug

Debug Output Includes:

When to Use Debug Mode:

Test Dependencies

Test dependencies are managed in tests/requirements.txt:

# Install test dependencies

pip install -r tests/requirements.txt

# Or use the automated setup

python tests/setup_tests.py

Writing Tests

Test Naming Convention

Example Test Structure

def test_config_loader_init_default(self):
    """✓ Test ConfigLoader initialization with default config path."""
    # Arrange
    loader = ConfigLoader()
    
    # Act
    config = loader.load_config()
    
    # Assert
    assert config is not None
    assert loader.config_path == Path('conf/config.yaml')

Best Practices

Development Tools

Code Quality

Formatting

# Format code with Black

black libs/ tests/

# Sort imports with isort

isort libs/ tests/

Linting

# Run flake8 linting

flake8 libs/ tests/

# Run type checking with mypy

mypy libs/ --ignore-missing-imports

Security Scanning

# Run security linting

bandit -r libs/

# Check for vulnerable dependencies

safety check

Continuous Integration

The project uses GitHub Actions for automated testing:

See .github/workflows/test.yml for CI configuration.

📁 Project Structure

tradetrack/
├── libs/                    # Core application modules
│   ├── config_loader.py     # Configuration management
│   ├── currency_formatter.py
│   ├── portfolio_library.py
│   ├── portfolio_loader.py
│   ├── rich_display.py
│   ├── tax_analysis.py
│   ├── yahoo_quotes.py
│   └── lot_analysis.py
├── conf/                    # Configuration files
│   ├── config.yaml         # Default configuration
│   └── version.py          # Version information
├── docs/                   # Documentation
│   ├── configuration.md
│   ├── dependencies.md
│   └── development.md      # This file
├── tests/                  # Test suite
├── templates/              # Template files
├── ttrack.py              # Main application entry point
├── requirements.txt        # Production dependencies
└── README.md              # User documentation

🐛 Debugging

Common Issues

  1. Import Errors: Ensure all dependencies are installed
  2. Test Failures: Check test data and mock configurations
  3. Performance Issues: Use profiling tools to identify bottlenecks
  4. Memory Leaks: Monitor memory usage in long-running tests

Debug Commands

# Run tests with debug output

pytest tests/ -v -s --tb=long

# Run specific test with debug

pytest tests/test_config_loader.py::TestConfigLoader::test_config_loader_init_default -v -s

# Profile test performance

pytest tests/ --profile

📊 Performance Testing

Memory Testing

# Run memory tests

python tests/run_tests.py --memory

# Monitor memory usage

python -m memory_profiler tests/test_runtime.py

Performance Benchmarks

# Run performance tests

python tests/run_tests.py --performance

# Benchmark specific functions

pytest tests/ -k "performance" --benchmark-only

🔄 Contributing

Development Workflow

  1. Create feature branch: 
    git checkout -b feature/new-feature
  2. Make changes and test: 
    # Run tests
python tests/run_tests.py
   
# Check code quality
black libs/ tests/
flake8 libs/ tests/
  3. Commit changes: 
    git add .
git commit -m "Add new feature with tests"
  4. Push and create PR: 
    git push origin feature/new-feature

Code Review Checklist

📚 Learning Resources

Python Testing

Development Tools

🆘 Getting Help

Internal Resources

External Resources

Note: This development guide is maintained alongside the codebase. Please update it when adding new features or changing the development process.