institutional-trader/backend/python_service/TESTING.md

Testing Guide

Overview

This guide explains how to test the Python implementation and validate it against the SQL query.

Quick Start

1. Run Validation Script

Compare Python output with SQL output:

cd backend/python_service
python scripts/validate_against_sql.py

This will:

• Run the SQL query
• Run the Python processing
• Compare outputs
• Generate a detailed report

2. Test API Endpoint

Start the service and test the endpoint:

# Terminal 1: Start Python service
cd backend/python_service
uvicorn main:app --reload --port 8000

# Terminal 2: Test endpoint
curl "http://localhost:8000/api/options-flow?start_date=2024-01-01&end_date=2024-01-02"

3. Integration Test with Node.js

Test the full stack:

# Terminal 1: Start Python service
cd backend/python_service
uvicorn main:app --reload --port 8000

# Terminal 2: Start Node.js backend
cd backend
npm run dev

# Terminal 3: Test Node.js endpoint (should call Python service)
curl "http://localhost:3010/api/options/flow?startDate=2024-01-01&endDate=2024-01-02"

Validation Checklist

✅ Data Accuracy

• Row counts match SQL
• All columns present
• Numeric values match (within tolerance)
• Text values match
• Dates/times formatted correctly

✅ Business Logic

• Badge calculations correct
• Rocket scores match
• Price context correct
• Alert matching works
• Filtering logic matches SQL

✅ Performance

• Processing time acceptable
• Memory usage reasonable
• Database queries optimized
• No N+1 query problems

✅ Error Handling

• Handles missing data gracefully
• Handles invalid dates
• Handles database errors
• Returns meaningful error messages

Manual Testing

Test Edge Cases

1. Empty Data:

   # Test with date range that has no data
   start_date = "2020-01-01"
   end_date = "2020-01-02"
   

2. Null Values:

   • Test with missing Premium
   • Test with missing dates
   • Test with missing prices

3. Date Formats:

   • Test various date formats in input
   • Test timezone conversions

4. Large Datasets:

   • Test with 10,000+ rows
   • Monitor memory usage
   • Check processing time

Test Badge Logic

Verify each badge type:

• 💎 Diamond badge conditions
• ⭐ Star badge conditions
• 💰 Money badge conditions
• ✔ Check badge conditions
• ⚡ Flash badge conditions
• 🚀 Rocket badge conditions

Test Scoring

Verify rocket score calculation:

• Premium tier scoring
• Net premium imbalance
• Volume > OI bonus
• Session weights
• Catalyst flag
• OTM bias
• Tape alignment

Automated Testing

Unit Tests (Recommended)

Create unit tests for each component:

# tests/test_options_flow_processor.py
import pytest
from services.options_flow_processor import OptionsFlowProcessor

def test_normalize_call_put():
    processor = OptionsFlowProcessor()
    assert processor.normalize_call_put('C') == 'CALL'
    assert processor.normalize_call_put('P') == 'PUT'
    assert processor.normalize_call_put('invalid') is None

def test_calculate_moneyness():
    # Test ITM/OTM calculations
    pass

# Add more tests...

Integration Tests

Test the full pipeline:

# tests/test_integration.py
import pytest
from datetime import datetime
from services.options_flow_processor import OptionsFlowProcessor

@pytest.mark.asyncio
async def test_full_pipeline():
    # Load test data
    # Run processing
    # Verify output
    pass

Performance Testing

Benchmark Script

import time
from datetime import datetime, timedelta

start = time.time()
# Run processing
end = time.time()
print(f"Processing time: {end - start:.2f} seconds")

Load Testing

Use tools like:

• locust for load testing
• ab (Apache Bench) for simple load tests
• Custom scripts for specific scenarios

Debugging

Enable Debug Logging

from utils.logger import setup_logger
logger = setup_logger(level=logging.DEBUG)

Check Intermediate Results

Add logging at each step:

logger.debug(f"After step X: {len(df)} rows, columns: {df.columns.tolist()}")

Compare Step-by-Step

Compare each processing step with SQL equivalent:

1. Base normalization
2. Flow filtering
3. Moneyness calculation
4. Aggregations
5. Badges
6. Price context
7. Alert matching
8. Final formatting

Common Issues

Issue: Row Count Mismatch

Possible causes:

• Date filtering differences
• NULL handling differences
• Filter logic differences

Solution:

• Check date parsing
• Verify NULL handling
• Compare WHERE clause logic

Issue: Value Differences

Possible causes:

• Floating point precision
• Rounding differences
• Calculation order

Solution:

• Use tolerance for comparisons
• Check rounding logic
• Verify calculation formulas

Issue: Missing Columns

Possible causes:

• Column name mismatches
• Missing processing steps
• Output formatting issues

Solution:

• Check column mappings
• Verify all processing steps
• Compare output formatter

Next Steps

1. Create comprehensive unit tests
2. Set up CI/CD with automated testing
3. Add performance benchmarks
4. Create test data fixtures
5. Add regression tests