mev-beta/docs/DOCKER_TESTING.md

# Docker-Based Testing Guide

All MEV Bot tests run in isolated Docker containers to ensure reproducible, consistent test environments.

## 🐳 Quick Start

```bash
# Run all tests
./scripts/test-docker.sh

# Run specific test type
./scripts/test-docker.sh unit
./scripts/test-docker.sh integration
./scripts/test-docker.sh race
```

---

## 📋 Available Test Types

### All Tests (Recommended)
```bash
./scripts/test-docker.sh all
```

Runs complete test suite:
1. ✅ Build verification
2. ✅ Unit tests
3. ✅ Race detector tests
4. ✅ Integration tests
5. ✅ Coverage report
6. ✅ Linting
7. ✅ Security scan

### Unit Tests
```bash
./scripts/test-docker.sh unit
```
- Tests individual components in isolation
- Fast execution (~30 seconds)
- No external dependencies
- Coverage: pkg/*, internal/*

### Integration Tests
```bash
./scripts/test-docker.sh integration
```
- Tests component interactions
- Slower execution (~2-5 minutes)
- May require mock services
- Coverage: test/integration/*

### Race Detector Tests
```bash
./scripts/test-docker.sh race
```
- Detects race conditions
- Tests concurrent code paths
- Critical for arbitrage executor
- Coverage: pkg/arbitrage/*, pkg/scanner/*

### Build Verification
```bash
./scripts/test-docker.sh build
```
- Verifies compilation
- Checks dependencies
- Tests binary creation
- Fast (~10 seconds)

### Coverage Report
```bash
./scripts/test-docker.sh coverage
```
- Generates HTML coverage report
- Output: coverage/coverage.html
- Shows line-by-line coverage
- Identifies untested code

### Security Scan
```bash
./scripts/test-docker.sh security
```
- Runs gosec security scanner
- Checks for vulnerabilities
- Output: coverage/gosec-report.json
- Identifies security issues

### Linting
```bash
./scripts/test-docker.sh lint
```
- Runs golangci-lint
- Checks code quality
- Enforces style guide
- Catches common bugs

---

## 🔧 Docker Compose Configuration

### Services Overview

```yaml
services:
  test-unit:         # Unit tests
  test-integration:  # Integration tests
  test-race:         # Race detector
  test-build:        # Build verification
  test-coverage:     # Coverage report
  test-security:     # Security scan
  test-lint:         # Code linting
```

### Environment Variables

All test containers use:
```bash
GO_ENV=test          # Test environment
CGO_ENABLED=1        # For race detector
```

---

## 📊 Test Results

### Coverage Report
```bash
# Generate coverage
./scripts/test-docker.sh coverage

# View in browser
open coverage/coverage.html
```

**Expected Coverage**: >80% (current target)

### Security Report
```bash
# Run security scan
./scripts/test-docker.sh security

# View JSON report
cat coverage/gosec-report.json | jq
```

### Test Logs
All test output is displayed in terminal. For detailed logs:
```bash
# Run with verbose output
docker-compose -f docker-compose.test.yml run --rm test-unit 2>&1 | tee test-unit.log
```

---

## 🚀 CI/CD Integration

### GitHub Actions

```yaml
# .github/workflows/test.yml
name: Test Suite

on: [push, pull_request]

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

      - name: Run Docker Tests
        run: |
          ./scripts/test-docker.sh all

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

### GitLab CI

```yaml
# .gitlab-ci.yml
test:
  stage: test
  image: docker:latest
  services:
    - docker:dind
  script:
    - ./scripts/test-docker.sh all
  artifacts:
    paths:
      - coverage/
```

---

## 🔍 Debugging Tests

### Run Interactive Shell
```bash
# Build test image
docker-compose -f docker-compose.test.yml build test-unit

# Run interactive shell
docker-compose -f docker-compose.test.yml run --rm test-unit sh

# Inside container:
go test -v ./pkg/arbitrage/...
```

### Run Specific Test
```bash
docker-compose -f docker-compose.test.yml run --rm test-unit \
    go test -v -run TestSpecificFunction ./pkg/...
```

### Debug Race Conditions
```bash
docker-compose -f docker-compose.test.yml run --rm test-race \
    go test -race -v -run TestConcurrent ./pkg/arbitrage/...
```

---

## 📦 Dependencies

### Required
- Docker Engine 20.10+
- Docker Compose 2.0+

### Installation

**Ubuntu/Debian:**
```bash
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
sudo usermod -aG docker $USER
```

**macOS:**
```bash
brew install docker docker-compose
```

**Verify:**
```bash
docker --version
docker-compose --version
```

---

## 🛠️ Troubleshooting

### Issue: "Cannot connect to Docker daemon"

**Solution:**
```bash
# Start Docker service
sudo systemctl start docker

# Or on macOS
open -a Docker
```

### Issue: "Build failed - dependency errors"

**Solution:**
```bash
# Clean Docker cache
docker-compose -f docker-compose.test.yml down --volumes
docker system prune -af

# Rebuild
./scripts/test-docker.sh build
```

### Issue: "Tests timeout"

**Solution:**
```bash
# Increase timeout in docker-compose.test.yml
services:
  test-unit:
    command: >
      sh -c "
        timeout 600 go test -v ./...  # 10 minute timeout
      "
```

### Issue: "Permission denied"

**Solution:**
```bash
# Fix script permissions
chmod +x scripts/test-docker.sh

# Fix coverage directory
sudo chown -R $USER:$USER coverage/
```

---

## 📈 Best Practices

### Before Committing
```bash
# Always run full test suite
./scripts/test-docker.sh all
```

### During Development
```bash
# Run unit tests frequently
./scripts/test-docker.sh unit

# Check race conditions
./scripts/test-docker.sh race
```

### Before Release
```bash
# Full validation
./scripts/test-docker.sh all

# Review coverage
open coverage/coverage.html

# Check security
cat coverage/gosec-report.json | jq '.Issues'
```

---

## 🎯 Test Quality Metrics

### Current Status
```
Build: ✅ Passing
Unit Tests: ✅ 200+ tests passing
Integration Tests: ✅ All passing
Race Conditions: ✅ 0 detected
Coverage: ✅ >80%
Security: ✅ No critical issues
Lint: ✅ Clean
```

### Goals
- **Coverage**: Maintain >80%, target 90%
- **Race Conditions**: Zero tolerance
- **Security**: No high/critical issues
- **Build Time**: <5 minutes for full suite

---

## 🔐 Security Considerations

### Test Isolation
- ✅ Each test runs in isolated container
- ✅ No shared state between tests
- ✅ Clean environment every run

### Secrets Management
- ❌ Never commit test credentials
- ✅ Use environment variables
- ✅ Mock external services

### Test Data
- ✅ Use synthetic test data
- ✅ Never use production data
- ✅ Clear test data after run

---

## 📝 Adding New Tests

### 1. Write Test
```go
// pkg/arbitrage/executor_test.go
func TestNewFeature(t *testing.T) {
    // Test implementation
}
```

### 2. Run Locally
```bash
./scripts/test-docker.sh unit
```

### 3. Verify Coverage
```bash
./scripts/test-docker.sh coverage
open coverage/coverage.html
```

### 4. Check Security
```bash
./scripts/test-docker.sh security
```

---

## 🆘 Getting Help

### Check Logs
```bash
# View test output
docker-compose -f docker-compose.test.yml logs test-unit

# Debug specific test
docker-compose -f docker-compose.test.yml run --rm test-unit \
    go test -v -run TestProblematic ./...
```

### Clean Start
```bash
# Remove everything and rebuild
./scripts/test-docker.sh clean
docker system prune -af
./scripts/test-docker.sh all
```

---

## ✅ Summary

**Docker-based testing ensures:**
- ✅ Consistent test environment
- ✅ Reproducible results
- ✅ Isolated execution
- ✅ Easy CI/CD integration
- ✅ No "works on my machine" issues

**Run tests before every commit:**
```bash
./scripts/test-docker.sh all
```

**Questions?** Check docker-compose.test.yml for configuration details.