mev-beta/test/README.md

# MEV Bot Parser Test Suite

This directory contains comprehensive test suites for validating the MEV bot's Arbitrum transaction parser. The test suite ensures that ALL values are parsed correctly from real-world transactions, which is critical for production MEV operations.

## 🏗️ Test Suite Architecture

```
test/
├── fixtures/
│   ├── real_arbitrum_transactions.json      # Real-world transaction test data
│   └── golden/                              # Golden file test outputs
├── parser_validation_comprehensive_test.go  # Main validation tests
├── golden_file_test.go                      # Golden file testing framework
├── performance_benchmarks_test.go           # Performance and stress tests
├── integration_arbitrum_test.go             # Live Arbitrum integration tests
├── fuzzing_robustness_test.go              # Fuzzing and robustness tests
└── README.md                               # This file
```

## 🎯 Test Categories

### 1. Comprehensive Parser Validation
**File:** `parser_validation_comprehensive_test.go`

Tests complete value parsing validation with real-world Arbitrum transactions:

- **High-Value Swaps**: Validates parsing of swaps >$10k, >$100k, >$1M
- **Complex Multi-Hop**: Tests Uniswap V3 multi-hop paths and routing
- **Failed Transactions**: Ensures graceful handling of reverted swaps
- **Edge Cases**: Tests overflow protection, zero values, unknown tokens
- **MEV Transactions**: Validates sandwich attacks, arbitrage, liquidations
- **Protocol-Specific**: Tests Curve, Balancer, GMX, and other protocols

### 2. Golden File Testing
**File:** `golden_file_test.go`

Provides regression testing with known-good outputs:

- **Consistent Validation**: Compares parser output against golden files
- **Regression Prevention**: Detects changes in parsing behavior
- **Complete Field Validation**: Tests every field in parsed structures
- **Mathematical Precision**: Validates wei-level precision in amounts

### 3. Performance Benchmarks
**File:** `performance_benchmarks_test.go`

Ensures parser meets production performance requirements:

- **Throughput Testing**: >1000 transactions/second minimum
- **Memory Efficiency**: <500MB memory usage validation
- **Concurrent Processing**: Multi-worker performance validation
- **Stress Testing**: Sustained load and burst testing
- **Protocol-Specific Performance**: Per-DEX performance metrics

### 4. Live Integration Tests
**File:** `integration_arbitrum_test.go`

Tests against live Arbitrum blockchain data:

- **Real-Time Validation**: Tests with current blockchain state
- **Network Resilience**: Handles RPC failures and rate limits  
- **Accuracy Verification**: Compares parsed data with on-chain reality
- **High-Value Transaction Validation**: Tests known valuable swaps
- **MEV Pattern Detection**: Validates MEV opportunity identification

### 5. Fuzzing & Robustness Tests
**File:** `fuzzing_robustness_test.go`

Ensures parser robustness against malicious or malformed data:

- **Transaction Data Fuzzing**: Random transaction input generation
- **Function Selector Fuzzing**: Tests unknown/malformed selectors
- **Amount Value Fuzzing**: Tests extreme values and overflow conditions
- **Concurrent Access Fuzzing**: Multi-threaded robustness testing
- **Memory Exhaustion Testing**: Large input handling validation

## 📊 Test Fixtures

### Real Transaction Data
The `fixtures/real_arbitrum_transactions.json` file contains carefully curated real-world transactions:

```json
{
  "high_value_swaps": [
    {
      "name": "uniswap_v3_usdc_weth_1m",
      "description": "Uniswap V3 USDC/WETH swap - $1M+ transaction",
      "tx_hash": "0xc6962004f452be9203591991d15f6b388e09e8d0",
      "protocol": "UniswapV3",
      "amount_in": "1000000000000",
      "expected_events": [...],
      "validation_criteria": {...}
    }
  ]
}
```

## 🚀 Running Tests

### Quick Test Suite
```bash
# Run all parser validation tests
go test ./test/ -v

# Run specific test category
go test ./test/ -run TestComprehensiveParserValidation -v
```

### Performance Benchmarks
```bash
# Run all benchmarks
go test ./test/ -bench=. -benchmem

# Run specific performance tests
go test ./test/ -run TestParserPerformance -v
```

### Golden File Testing
```bash
# Validate against golden files
go test ./test/ -run TestGoldenFiles -v

# Regenerate golden files (if needed)
REGENERATE_GOLDEN=true go test ./test/ -run TestGoldenFiles -v
```

### Live Integration Testing
```bash
# Enable live testing with real Arbitrum data
ENABLE_LIVE_TESTING=true go test ./test/ -run TestArbitrumIntegration -v

# With custom RPC endpoint
ARBITRUM_RPC_ENDPOINT="your-rpc-url" ENABLE_LIVE_TESTING=true go test ./test/ -run TestArbitrumIntegration -v
```

### Fuzzing Tests
```bash
# Run fuzzing tests
go test ./test/ -run TestFuzzingRobustness -v

# Run with native Go fuzzing
go test -fuzz=FuzzParserRobustness ./test/
```

## ✅ Validation Criteria

### Critical Requirements
- **100% Accuracy**: All amounts parsed with wei-precision
- **Complete Metadata**: All addresses, fees, and parameters extracted
- **Performance**: >1000 transactions/second throughput
- **Memory Efficiency**: <500MB memory usage
- **Error Handling**: Graceful handling of malformed data
- **Security**: No crashes or panics with any input

### Protocol Coverage
- ✅ Uniswap V2 (all swap functions)
- ✅ Uniswap V3 (exactInput, exactOutput, multicall)
- ✅ SushiSwap V2 (all variants)
- ✅ 1inch Aggregator (swap routing)
- ✅ Curve (stable swaps)
- ✅ Balancer V2 (batch swaps)
- ✅ Camelot DEX (Arbitrum native)
- ✅ GMX (perpetuals)
- ✅ TraderJoe (AMM + LB pairs)

### MEV Pattern Detection
- ✅ Sandwich attacks (frontrun/backrun detection)
- ✅ Arbitrage opportunities (cross-DEX price differences)
- ✅ Liquidation transactions (lending protocol liquidations)
- ✅ Flash loan transactions
- ✅ Gas price analysis (MEV bot identification)

## 🔧 Configuration

### Environment Variables
```bash
# Enable live testing
export ENABLE_LIVE_TESTING=true

# Arbitrum RPC endpoints
export ARBITRUM_RPC_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/your-key"
export ARBITRUM_WS_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/your-key"

# Test configuration
export TEST_TIMEOUT="30m"
export REGENERATE_GOLDEN=true
export LOG_LEVEL="debug"
```

### Performance Thresholds
```go
// Performance requirements (configurable)
const (
    MinThroughputTxPerS  = 1000  // Minimum transaction throughput
    MaxParsingTimeMs     = 100   // Maximum time per transaction
    MaxMemoryUsageMB     = 500   // Maximum memory usage
    MaxErrorRatePercent  = 5     // Maximum acceptable error rate
)
```

## 📈 Continuous Integration

The test suite integrates with GitHub Actions for automated validation:

### Workflow Triggers
- **Push/PR**: Runs core validation tests
- **Daily Schedule**: Runs full suite including live tests
- **Manual Dispatch**: Allows custom test configuration

### Test Matrix
```yaml
strategy:
  matrix:
    go-version: ['1.21', '1.20']
    test-suite: ['unit', 'integration', 'performance', 'fuzzing']
```

## 🛠️ Adding New Tests

### 1. Real Transaction Tests
Add new transaction data to `fixtures/real_arbitrum_transactions.json`:

```json
{
  "your_category": [
    {
      "name": "descriptive_test_name",
      "description": "What this test validates", 
      "tx_hash": "0x...",
      "protocol": "ProtocolName",
      "expected_values": {
        "amount_in": "exact_wei_amount",
        "token_addresses": ["0x...", "0x..."],
        "pool_fee": 500
      }
    }
  ]
}
```

### 2. Performance Tests
Add benchmarks to `performance_benchmarks_test.go`:

```go
func BenchmarkYourNewFeature(b *testing.B) {
    suite := NewPerformanceTestSuite(&testing.T{})
    defer suite.l2Parser.Close()
    
    b.ResetTimer()
    for i := 0; i < b.N; i++ {
        // Your benchmark code
    }
}
```

### 3. Golden File Tests
Add test cases to `golden_file_test.go`:

```go
func (suite *GoldenFileTestSuite) createYourNewTest() GoldenFileTest {
    return GoldenFileTest{
        Name: "your_test_name",
        Description: "What this validates",
        Input: GoldenFileInput{
            // Input data
        },
        // Expected output will be auto-generated
    }
}
```

## 🐛 Debugging Test Failures

### Common Issues
1. **Parsing Failures**: Check ABI encoding in test data
2. **Performance Issues**: Profile with `go tool pprof`
3. **Memory Leaks**: Run with `-race` flag
4. **Golden File Mismatches**: Regenerate with `REGENERATE_GOLDEN=true`

### Debug Commands
```bash
# Run with verbose output and race detection
go test ./test/ -v -race -run TestSpecificTest

# Profile memory usage
go test ./test/ -memprofile=mem.prof -run TestMemoryUsage
go tool pprof mem.prof

# Generate CPU profile
go test ./test/ -cpuprofile=cpu.prof -run TestPerformance
go tool pprof cpu.prof
```

## 📚 Related Documentation

- [Parser Architecture](../pkg/arbitrum/README.md)
- [Performance Tuning Guide](../docs/performance.md)
- [MEV Strategy Documentation](../docs/mev-strategies.md)
- [Contributing Guidelines](../CONTRIBUTING.md)

## ⚠️ Important Notes

### Production Considerations
- **Never commit real private keys or API keys to test fixtures**
- **Use mock data for sensitive operations in automated tests**
- **Validate all external dependencies before production deployment**
- **Monitor parser performance in production with similar test patterns**

### Security Warnings
- **Fuzzing tests may generate large amounts of random data**
- **Live integration tests make real network calls**
- **Performance tests may consume significant system resources**

---

For questions or issues with the test suite, please open an issue or contact the development team.