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:

```bash
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:

```bash
# 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:

```bash
# 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:**
   ```python
   # 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:

```python
# 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:

```python
# 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

```python
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

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

### Check Intermediate Results

Add logging at each step:

```python
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