mev-beta/docs/AUDIT_AND_TESTING.md

# Audit and Testing Guide

Comprehensive guide for testing and auditing the MEV bot codebase.

## Quick Reference

```bash
# Run everything
./scripts/dev.sh test all          # All tests
./scripts/dev.sh audit             # Code quality audit
./scripts/dev.sh check-compliance  # SPEC.md compliance
./scripts/dev.sh check-docs        # Documentation coverage

# Specific tests
./scripts/dev.sh test unit         # Unit tests only
./scripts/dev.sh test coverage     # Coverage report
./scripts/dev.sh test race         # Race detection
./scripts/dev.sh test bench        # Benchmarks
```

## Testing Suite

### 1. Unit Tests

Fast tests that verify individual components in isolation.

```bash
# Run all unit tests
./scripts/dev.sh test unit

# Run tests for specific package
./scripts/dev.sh test pkg sequencer

# Verbose output
./scripts/test.sh unit true
```

**What it tests:**
- Individual function correctness
- Edge cases and error handling
- Component behavior in isolation

**Files:** All `*_test.go` files in `pkg/`

### 2. Integration Tests

Tests that verify components work together correctly.

```bash
# Run integration tests
./scripts/dev.sh test integration
```

**What it tests:**
- Sequencer → Swap Filter → Pool Cache pipeline
- Database operations
- External service interactions

**Files:** `tests/*_integration_test.go`

### 3. Race Detection

Detects data races in concurrent code.

```bash
# Run with race detector
./scripts/dev.sh test race
```

**What it checks:**
- Concurrent access to shared state
- Mutex usage correctness
- Channel safety

**Important:** Always run before committing concurrent code changes.

### 4. Benchmarks

Performance testing for critical paths.

```bash
# Run benchmarks
./scripts/dev.sh test bench
```

**What it measures:**
- Swap parsing throughput
- Pool cache lookup speed
- Channel message processing rate

**Files:** Functions named `Benchmark*` in `*_test.go`

### 5. Coverage Report

Measures test coverage percentage.

```bash
# Generate coverage report
./scripts/dev.sh test coverage
```

**Output:**
- `coverage/coverage.out` - Coverage data
- `coverage/coverage.html` - HTML report (open in browser)

**Target:** >70% coverage for production code

## Audit Suite

### 1. Codebase Audit

Comprehensive code quality and security check.

```bash
./scripts/dev.sh audit
```

**Checks:**

#### Code Quality
- `go vet` warnings
- TODO/FIXME comments
- panic() usage
- Error handling patterns

#### Security
- Hardcoded secrets
- SQL injection risks
- Command injection
- Unsafe pointer usage

#### Concurrency
- Race condition risks
- Mutex coverage
- Channel usage

#### SPEC.md Compliance
- Hardcoded function selectors (forbidden)
- HTTP RPC in sequencer (forbidden)
- Blocking operations in hot paths (forbidden)
- Manual ABI files (forbidden)

**Exit codes:**
- 0: No issues
- 1: Issues found (review required)

### 2. Documentation Coverage

Verifies all code is properly documented.

```bash
./scripts/dev.sh check-docs
```

**Checks:**

- Package `doc.go` files
- Exported function comments
- Exported type comments
- README files in key directories
- Project documentation (SPEC.md, CLAUDE.md, etc.)
- Inline comment density

**Target:** >80% documentation coverage

### 3. SPEC.md Compliance

Ensures code adheres to all SPEC.md requirements.

```bash
./scripts/dev.sh check-compliance
```

**Validates:**

#### MUST DO ✅
- ✓ Use Arbitrum sequencer feed
- ✓ Channel-based communication
- ✓ Official contract ABIs
- ✓ Generated bindings
- ✓ Data validation
- ✓ Thread-safe structures
- ✓ Comprehensive metrics
- ✓ Container-based development

#### MUST NOT DO ❌
- ✗ HTTP RPC in sequencer
- ✗ Manual ABI files
- ✗ Hardcoded selectors
- ✗ Zero addresses/amounts propagation
- ✗ Blocking operations
- ✗ Unprotected shared state
- ✗ Silent failures

**Exit codes:**
- 0: Fully compliant
- 1: Violations found

## Continuous Integration

### Pre-Commit Checks

Run before every commit:

```bash
# Quick validation
./scripts/dev.sh test unit
./scripts/dev.sh check-compliance

# Full pre-commit
./scripts/dev.sh test all
./scripts/dev.sh audit
```

### Pre-Push Checks

Run before pushing to remote:

```bash
# Comprehensive check
./scripts/dev.sh test all
./scripts/dev.sh test race
./scripts/dev.sh audit
./scripts/dev.sh check-compliance
./scripts/dev.sh check-docs
```

### Pre-Release Checks

Run before creating a release:

```bash
# Full audit
./scripts/dev.sh test coverage  # Ensure >70%
./scripts/dev.sh test bench     # Check performance
./scripts/dev.sh audit          # Security & quality
./scripts/dev.sh check-compliance  # SPEC.md adherence
./scripts/dev.sh check-docs     # Documentation complete
```

## Test Writing Guidelines

### Unit Test Example

```go
// pkg/sequencer/swap_filter_test.go
func TestSwapFilter_DetectUniswapV2Swap(t *testing.T) {
    // Setup
    filter := NewSwapFilter(logger, poolCache)

    // Create test message with known swap
    msg := map[string]interface{}{
        "messages": []interface{}{
            map[string]interface{}{
                "message": map[string]interface{}{
                    "l2Msg": base64EncodedSwapTx,
                },
            },
        },
    }

    // Execute
    filter.ProcessMessage(msg)

    // Verify
    select {
    case swap := <-filter.SwapCh():
        assert.Equal(t, "UniswapV2", swap.Protocol.Name)
        assert.NotEqual(t, common.Address{}, swap.Pool.Address)
    case <-time.After(time.Second):
        t.Fatal("timeout waiting for swap event")
    }
}
```

### Benchmark Example

```go
// pkg/pools/cache_bench_test.go
func BenchmarkPoolCache_Lookup(b *testing.B) {
    cache := NewPoolCache(...)

    // Pre-populate cache
    for i := 0; i < 1000; i++ {
        cache.AddOrUpdate(generateTestPool())
    }

    addr := testPoolAddress

    b.ResetTimer()
    for i := 0; i < b.N; i++ {
        cache.Get(addr)
    }
}
```

### Integration Test Example

```go
// tests/sequencer_integration_test.go
func TestSequencerToPoolCache_Pipeline(t *testing.T) {
    // Start real sequencer feed
    reader := sequencer.NewReader(config)
    swapFilter := sequencer.NewSwapFilter(logger, poolCache)

    // Connect pipeline
    go reader.Start(ctx)
    go swapFilter.Start(ctx)

    // Wait for real swaps from mainnet
    timeout := time.After(30 * time.Second)
    swapsFound := 0

    for swapsFound < 5 {
        select {
        case swap := <-swapFilter.SwapCh():
            // Verify swap is valid
            assert.NotEqual(t, common.Address{}, swap.Pool.Address)
            swapsFound++
        case <-timeout:
            t.Fatalf("only found %d swaps in 30s", swapsFound)
        }
    }
}
```

## Common Issues

### Issue: Tests timeout

**Cause:** Blocking operations in tests

**Fix:**
```go
// Bad
time.Sleep(10 * time.Second)

// Good
select {
case result := <-resultCh:
    // ...
case <-time.After(5 * time.Second):
    t.Fatal("timeout")
}
```

### Issue: Race detector reports races

**Cause:** Unprotected shared state

**Fix:**
```go
// Bad
var counter int
func increment() { counter++ }

// Good
var mu sync.Mutex
var counter int
func increment() {
    mu.Lock()
    defer mu.Unlock()
    counter++
}
```

### Issue: Low coverage

**Cause:** Missing test cases

**Fix:**
1. Identify uncovered code: `go tool cover -func=coverage/coverage.out`
2. Add tests for edge cases
3. Test error paths
4. Add table-driven tests

## Metrics and Monitoring

### Coverage Trends

Track coverage over time:

```bash
# Generate report
./scripts/dev.sh test coverage

# View current coverage
grep "total:" coverage/coverage.out
```

### Performance Baselines

Establish performance baselines:

```bash
# Run benchmarks
./scripts/dev.sh test bench > benchmarks/baseline-$(date +%Y%m%d).txt

# Compare with previous
benchstat benchmarks/baseline-old.txt benchmarks/baseline-new.txt
```

## CI/CD Integration

### GitHub Actions Example

```yaml
name: Test Suite

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Start dev environment
        run: ./scripts/dev.sh up

      - name: Run tests
        run: ./scripts/dev.sh test all

      - name: Run audit
        run: ./scripts/dev.sh audit

      - name: Check compliance
        run: ./scripts/dev.sh check-compliance

      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          file: ./coverage/coverage.out
```

## References

- [Go Testing Package](https://pkg.go.dev/testing)
- [Table Driven Tests](https://github.com/golang/go/wiki/TableDrivenTests)
- [Go Race Detector](https://go.dev/blog/race-detector)
- SPEC.md - Technical requirements
- CLAUDE.md - Development guidelines