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

# 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)

./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

./scripts/test-docker.sh unit

• Tests individual components in isolation
• Fast execution (~30 seconds)
• No external dependencies
• Coverage: pkg/, internal/

Integration Tests

./scripts/test-docker.sh integration

• Tests component interactions
• Slower execution (~2-5 minutes)
• May require mock services
• Coverage: test/integration/*

Race Detector Tests

./scripts/test-docker.sh race

• Detects race conditions
• Tests concurrent code paths
• Critical for arbitrage executor
• Coverage: pkg/arbitrage/, pkg/scanner/

Build Verification

./scripts/test-docker.sh build

• Verifies compilation
• Checks dependencies
• Tests binary creation
• Fast (~10 seconds)

Coverage Report

./scripts/test-docker.sh coverage

• Generates HTML coverage report
• Output: coverage/coverage.html
• Shows line-by-line coverage
• Identifies untested code

Security Scan

./scripts/test-docker.sh security

• Runs gosec security scanner
• Checks for vulnerabilities
• Output: coverage/gosec-report.json
• Identifies security issues

Linting

./scripts/test-docker.sh lint

• Runs golangci-lint
• Checks code quality
• Enforces style guide
• Catches common bugs

---

🔧 Docker Compose Configuration

Services Overview

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:

GO_ENV=test          # Test environment
CGO_ENABLED=1        # For race detector

---

📊 Test Results

Coverage Report

# Generate coverage
./scripts/test-docker.sh coverage

# View in browser
open coverage/coverage.html

Expected Coverage: >80% (current target)

Security Report

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

# 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

# .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

# .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

# 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

docker-compose -f docker-compose.test.yml run --rm test-unit \
    go test -v -run TestSpecificFunction ./pkg/...

Debug Race Conditions

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:

curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
sudo usermod -aG docker $USER

macOS:

brew install docker docker-compose

Verify:

docker --version
docker-compose --version

---

🛠️ Troubleshooting

Issue: "Cannot connect to Docker daemon"

Solution:

# Start Docker service
sudo systemctl start docker

# Or on macOS
open -a Docker

Issue: "Build failed - dependency errors"

Solution:

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

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

# Fix script permissions
chmod +x scripts/test-docker.sh

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

---

📈 Best Practices

Before Committing

# Always run full test suite
./scripts/test-docker.sh all

During Development

# Run unit tests frequently
./scripts/test-docker.sh unit

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

Before Release

# 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

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

2. Run Locally

./scripts/test-docker.sh unit

3. Verify Coverage

./scripts/test-docker.sh coverage
open coverage/coverage.html

4. Check Security

./scripts/test-docker.sh security

---

🆘 Getting Help

Check Logs

# 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

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

./scripts/test-docker.sh all

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