foxhunt/testing/integration/fixtures/README.md

# Foxhunt Test Fixtures System

## Overview

This directory contains a comprehensive test fixtures system for the Foxhunt HFT Trading System. The fixtures provide standardized test data, mock services, and utilities for testing all components of the system.

## Architecture

### Core Modules

1. **`mod.rs`** - Main module with test symbols and base infrastructure
2. **`builders.rs`** - Builder patterns for creating test objects
3. **`scenarios.rs`** - Predefined test scenarios for various conditions
4. **`test_data.rs`** - Data generators and utilities
5. **`test_config.rs`** - Configuration management for tests
6. **`test_database.rs`** - Database setup and utilities
7. **`mock_services.rs`** - Mock implementations of external services

## Key Features

### ✅ Standardized Test Symbols

```rust
// Predefined symbols for consistent testing
pub const TEST_EQUITY_1: &str = "TEST_EQ_001";
pub const TEST_FOREX_1: &str = "TEST_FX_EURUSD";
pub const TEST_FUTURE_1: &str = "TEST_FUT_ES001";
// ... and many more

// Dynamic symbol generation
let symbol = generate_test_symbol(AssetClass::Equities);
```

### ✅ Builder Patterns

```rust
// Fluent API for building test objects
let portfolio = PortfolioBuilder::new()
    .with_id(TEST_PORTFOLIO_1)
    .with_name("Test Portfolio")
    .with_base_currency("USD")
    .strategy_portfolio()
    .build();

let position = PositionBuilder::new()
    .with_portfolio_id(TEST_PORTFOLIO_1)
    .with_symbol(TEST_EQUITY_1)
    .long_position(1000)
    .profitable(10.0) // 10% profit
    .build();
```

### ✅ Predefined Scenarios

```rust
// Market crash stress test
let (stress_scenario, stressed_positions) = ScenarioFactory::market_crash();

// High frequency trading scenario
let (orders, ticks) = ScenarioFactory::high_frequency_trading(60); // 60 seconds

// Risk limit breach scenario
let (portfolio, positions) = ScenarioFactory::risk_limit_breach();
```

### ✅ Data Generators

```rust
// Market data generation
let generator = MarketDataGenerator::new()
    .with_symbol(TEST_EQUITY_1)
    .with_volatility(0.02)
    .with_drift(0.0001);

let prices = generator.generate_price_series(1000);
let ohlcv = generator.generate_ohlcv_bars(100, ChronoDuration::minutes(1));

// Random data generation
let mut random_gen = RandomDataGenerator::new();
let (portfolio, instruments, positions) = random_gen.generate_random_portfolio(10);
```

### ✅ Test Database Management

```rust
// Isolated test database
let test_db = TestDatabase::new().await?;
test_db.insert_test_data().await?;

// Shared test database for integration tests
let shared_db = get_shared_test_db().await?;

// Transaction-based testing
test_transaction!(test_db, {
    // Your test code here
    // Automatically rolled back
});
```

### ✅ Mock Services

```rust
// Mock trading service
let trading_service = MockTradingService::new(config);
let response = trading_service.submit_order(order_request).await?;

// Mock ML training service
let ml_service = MockMLTrainingService::new(config);
let job = ml_service.start_training(training_request).await?;

// Mock backtesting service
let backtest_service = MockBacktestingService::new(config);
let backtest = backtest_service.start_backtest(backtest_request).await?;
```

### ✅ Configuration Management

```rust
// Different configurations for different test types
let unit_config = TestConfig::for_unit_tests();     // Fast, mocked
let integration_config = TestConfig::for_integration_tests(); // Realistic
let performance_config = TestConfig::for_performance_tests(); // Demanding
let stress_config = TestConfig::for_stress_tests();  // Extreme

// Builder pattern for custom configs
let config = TestConfigBuilder::new()
    .with_max_latency_ns(10_000)
    .with_mocks_enabled(false)
    .build()?;
```

## Symbol Categories

### Asset Classes Covered

- **Equities**: `TEST_EQ_001`, `TEST_EQ_002`, etc.
- **Forex**: `TEST_FX_EURUSD`, `TEST_FX_GBPUSD`, etc.
- **Futures**: `TEST_FUT_ES001`, `TEST_FUT_NQ001`, etc.
- **Bonds**: `TEST_BOND_UST10Y`, `TEST_BOND_UST2Y`, etc.
- **Commodities**: `TEST_COMM_GOLD`, `TEST_COMM_SILVER`, etc.
- **Crypto**: `TEST_CRYPTO_BTC`, `TEST_CRYPTO_ETH`, etc.

### Complete Symbol Collections

```rust
pub const ALL_TEST_SYMBOLS: &[&str] = &[...]; // All symbols
pub const ALL_TEST_EQUITIES: &[&str] = &[...]; // Just equities
pub const ALL_TEST_FX_PAIRS: &[&str] = &[...]; // Just FX pairs
// ... etc for each asset class
```

## Test Scenarios

### Market Conditions

1. **Basic Trading** - Balanced portfolio with mixed assets
2. **Market Crash** - 2008-style stress test with asset correlation
3. **Interest Rate Shock** - Bond duration-based impact
4. **High Frequency** - Rapid order flow and tick data
5. **Risk Limit Breach** - Concentrated positions and limit violations

### Risk Management

- VaR limit breaches
- Concentration risk scenarios
- Counterparty exposure limits
- Circuit breaker triggers
- Stress test scenarios

### Performance Testing

- High-frequency order flow
- Latency measurement scenarios
- Throughput testing data
- Memory usage patterns
- Concurrent operation testing

## Integration with Existing Code

### Database Schema Compatibility

The fixtures integrate with the existing `risk-data` models:

```rust
use risk_data::models::{AssetClass, InstrumentType, Portfolio, Position};

// Builders create objects compatible with existing schemas
let instrument = InstrumentBuilder::new()
    .equity()
    .build(); // Returns risk_data::models::Instrument
```

### Configuration Integration

```rust
// Uses existing configuration system
use config::{ServiceConfig, ConfigManager};

// Test configs integrate with production config system
let test_config = TestConfig::for_integration_tests();
let env_vars = test_config.to_env_vars(); // For child processes
```

## Usage Examples

### Unit Test Setup

```rust
#[tokio::test]
async fn test_portfolio_operations() {
    let test_db = setup_test_db!();
    
    let portfolio = PortfolioBuilder::new()
        .with_id("TEST_UNIT_PORTFOLIO")
        .build();
        
    let positions = BatchBuilder::create_test_positions(
        "TEST_UNIT_PORTFOLIO", 
        ALL_TEST_EQUITIES
    );
    
    // Test your portfolio logic here
}
```

### Integration Test Setup

```rust
#[tokio::test]
async fn test_trading_service_integration() {
    let config = TestConfig::for_integration_tests();
    let (trading, ml, backtesting) = MockServiceFactory::new(config)
        .create_all_services();
    
    let scenario = BasicTradingScenario::new();
    let positions = scenario.create_positions();
    
    // Test service interactions
}
```

### Performance Test Setup

```rust
#[tokio::test]
async fn test_hft_performance() {
    let config = TestConfig::for_performance_tests();
    let hft_scenario = HighFrequencyScenario::new()
        .with_order_rate(10000); // 10k orders/sec
    
    let orders = hft_scenario.generate_order_flow(60); // 1 minute
    
    // Measure latency and throughput
}
```

### Stress Test Setup

```rust
#[tokio::test]
async fn test_market_crash_stress() {
    let crash_scenario = MarketCrashScenario::new();
    let basic_scenario = BasicTradingScenario::new();
    
    let original_positions = basic_scenario.create_positions();
    let stressed_positions = crash_scenario.apply_shocks_to_positions(&original_positions);
    
    // Verify risk management under stress
}
```

## Benefits

### 🎯 **Consistency**
- Standardized symbols across all tests
- Predictable test data structures
- Consistent pricing and volatility

### 🚀 **Productivity**
- No more hardcoded test values
- Builder patterns for complex objects
- Predefined scenarios for common cases

### 🔒 **Reliability**
- Isolated test databases
- Deterministic random data (seeded)
- Proper cleanup and teardown

### 🔄 **Reusability**
- Modular builders and generators
- Configurable scenarios
- Cross-module compatibility

### 📊 **Comprehensive Coverage**
- All asset classes represented
- Multiple market conditions
- Various risk scenarios
- Performance testing data

## Future Enhancements

- [ ] Real-time data replay capabilities
- [ ] Advanced correlation modeling
- [ ] Regulatory scenario testing
- [ ] Machine learning test data sets
- [ ] Cross-asset scenario correlation
- [ ] Market microstructure simulation

This fixtures system provides a solid foundation for testing all aspects of the Foxhunt HFT trading system with realistic, consistent, and maintainable test data.