torrent-gateway/test/README.md

# Blossom-BitTorrent Gateway Testing Suite

Comprehensive testing suite for validating the Blossom-BitTorrent Gateway in real-world scenarios.

## Overview

This testing suite provides multiple layers of validation:

1. **Integration Tests**: End-to-end testing with real Blossom servers
2. **Load Tests**: Performance testing under concurrent load
3. **Compatibility Tests**: Protocol compliance and format support
4. **Docker Environment**: Isolated test environment with all dependencies

## Quick Start

### Prerequisites

- Docker and Docker Compose
- Go 1.21+ (for local testing)
- curl, jq, bc (for shell scripts)

### Run All Tests

```bash
# Start the complete test environment
cd test
docker-compose --profile orchestrate up --build

# Or run specific test suites
docker-compose --profile test up --build        # Integration tests
docker-compose --profile load up --build        # Load tests
docker-compose --profile compatibility up --build # Compatibility tests
```

### Quick Smoke Test

```bash
# Start core services
docker-compose up -d gateway blossom-server

# Run quick validation
./integration_test.sh
```

## Test Suites

### 1. Integration Tests (`integration_test.sh`)

Tests the complete workflow with various file sizes and formats.

**Features:**
- Real Blossom server integration
- File upload/download integrity verification
- BitTorrent torrent generation
- WebSeed (BEP-19) functionality
- HLS streaming for video files
- Nostr NIP-35 event compliance

**Usage:**
```bash
# Local execution
GATEWAY_URL=http://localhost:9876 ./integration_test.sh

# With custom Blossom server
BLOSSOM_SERVER=https://blossom.example.com ./integration_test.sh

# Docker execution
docker-compose --profile test run integration-test
```

**Test Files Generated:**
- Small file (1KB) - Basic functionality
- Medium file (10MB) - Chunk handling
- Large file (100MB) - Performance validation
- Video files (.mp4, .mkv, .avi, .mov, .webm) - HLS streaming

**Expected Output:**
```
🚀 Blossom-BitTorrent Gateway Integration Tests
=============================================

=== Creating Test Files ===
✅ Test files created successfully

=== Checking Services ===
✅ PASS: Gateway Health Check (1s)
✅ PASS: Blossom Server Check (2s)

=== File Upload and Validation Tests ===
  ✅ PASS: Upload small_file.txt (3s) - Hash: abc123..., Speed: 0.33MB/s
  ✅ PASS: Download small_file.txt (1s) - Integrity verified, Speed: 1.00MB/s
  ✅ PASS: Torrent small_file.txt (2s) - Generated torrent file (456 bytes)
  ✅ PASS: WebSeed small_file.txt (1s) - Full file access successful
...
```

### 2. Load Tests (`load_test.go`)

Stress testing with configurable concurrent users and duration.

**Features:**
- Concurrent file uploads
- Performance metrics collection
- Response time percentiles (P95, P99)
- Throughput measurement
- Resource usage monitoring
- Bottleneck identification

**Usage:**
```bash
# Local execution
go run load_test.go

# With custom parameters
GATEWAY_URL=http://localhost:9876 \
CONCURRENT_USERS=50 \
TEST_DURATION=10m \
FILE_SIZE=5242880 \
go run load_test.go

# Docker execution
docker-compose --profile load run load-test
```

**Configuration:**
- `GATEWAY_URL`: Target gateway URL
- `CONCURRENT_USERS`: Number of concurrent connections (default: 10)
- `TEST_DURATION`: Test duration (default: 2m)
- `FILE_SIZE`: Upload file size in bytes (default: 1MB)

**Expected Output:**
```
🚀 Starting Load Test
=====================
Gateway URL:        http://localhost:9876
Concurrent Users:   10
Test Duration:      2m0s
File Size:          1.00 MB

📊 Load Test Report (Elapsed: 2m0s)
====================================
Total Requests:     245
Successful:         243 (99.2%)
Failed:             2 (0.8%)
Requests/sec:       2.04
Data Uploaded:      243.00 MB
Upload Speed:       2.03 MB/s

Response Times:
  Average:          4.2s
  Min:              1.1s
  Max:              12.3s
  95th percentile:  8.7s
  99th percentile:  11.2s
```

### 3. Compatibility Tests (`compatibility_test.go`)

Validates protocol compliance and format support.

**Features:**
- Blossom server compatibility
- BitTorrent protocol validation
- Video format support (MP4, MKV, AVI, MOV, WebM, etc.)
- Nostr NIP-35 compliance
- Error handling verification
- Magnet link validation
- HLS streaming compatibility

**Usage:**
```bash
# Local execution
go run compatibility_test.go

# With custom servers
GATEWAY_URL=http://localhost:9876 \
BLOSSOM_SERVERS=http://server1:3000,http://server2:3001 \
go run compatibility_test.go

# Docker execution
docker-compose --profile compatibility run compatibility-test
```

**Test Categories:**
- **Blossom Compatibility**: Server connectivity and protocol compliance
- **BitTorrent Compatibility**: Torrent generation, WebSeed, magnet links
- **Video Format Support**: HLS streaming for various video formats
- **Nostr Compliance**: NIP-35 event structure validation
- **Error Handling**: Proper HTTP status codes and JSON responses

### 4. Docker Test Environment

Complete isolated testing environment with all dependencies.

**Services:**
- `gateway`: The Blossom-BitTorrent Gateway
- `blossom-server`: Real Blossom server (hzrd149/blossom-server)
- `nostr-relay`: Nostr relay for testing (scsibug/nostr-rs-relay)
- `test-file-generator`: Creates test files of various sizes
- `prometheus`: Metrics collection (optional)
- `grafana`: Metrics visualization (optional)

**Profiles:**
- `setup`: Generate test files
- `test`: Run integration tests
- `load`: Run load tests
- `compatibility`: Run compatibility tests
- `monitoring`: Start monitoring stack
- `orchestrate`: Run comprehensive test orchestration

## Test Orchestration

The test orchestrator (`test-orchestrator.sh`) coordinates multiple test suites:

```bash
# Run all test suites
TEST_SUITE=all docker-compose --profile orchestrate up

# Run specific suite
TEST_SUITE=integration docker-compose --profile orchestrate up
TEST_SUITE=load docker-compose --profile orchestrate up
TEST_SUITE=compatibility docker-compose --profile orchestrate up

# Quick smoke tests
TEST_SUITE=quick docker-compose --profile orchestrate up
```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `GATEWAY_URL` | Gateway base URL | `http://localhost:9876` |
| `BLOSSOM_SERVER` | Blossom server URL | `http://localhost:3000` |
| `NOSTR_RELAYS` | Comma-separated Nostr relays | `wss://relay.damus.io` |
| `CONCURRENT_USERS` | Load test concurrent users | `10` |
| `TEST_DURATION` | Load test duration | `2m` |
| `FILE_SIZE` | Test file size in bytes | `1048576` (1MB) |
| `PARALLEL_TESTS` | Run tests in parallel | `true` |

### Service Configuration

#### Blossom Server (`blossom-config.json`)
```json
{
  "port": 3000,
  "storage": {
    "type": "filesystem",
    "path": "/data/blobs"
  },
  "limits": {
    "max_blob_size": 104857600,
    "max_total_size": 10737418240
  }
}
```

#### Nostr Relay (`nostr-relay-config.toml`)
```toml
[network]
port = 7777
address = "0.0.0.0"

[limits]
messages_per_sec = 100
max_message_length = 128000
max_subscriptions = 20
```

## Monitoring

Optional monitoring stack with Prometheus and Grafana:

```bash
# Start monitoring
docker-compose --profile monitoring up -d

# Access interfaces
open http://localhost:9090  # Prometheus
open http://localhost:3001  # Grafana (admin/admin123)
```

**Metrics Collected:**
- Request rates and response times
- Upload/download throughput
- Error rates and status codes
- Resource utilization (CPU, memory)
- Active connections and goroutines

## Test Results

All tests generate detailed JSON results and logs:

**File Locations:**
- Integration: `./test_results/integration_test_results_YYYYMMDD_HHMMSS.json`
- Load: `./test_results/load_test_results_YYYYMMDD_HHMMSS.json`
- Compatibility: `./test_results/compatibility_test_results_YYYYMMDD_HHMMSS.json`
- Orchestrator: `./test_results/test_orchestrator_report.json`

**Result Structure:**
```json
{
  "test_run": {
    "timestamp": "2024-01-15T10:30:00Z",
    "gateway_url": "http://localhost:9876",
    "environment": {...}
  },
  "results": {
    "total": 45,
    "passed": 43,
    "failed": 2,
    "success_rate": 95.6
  },
  "performance_metrics": {...}
}
```

## Troubleshooting

### Common Issues

1. **Port Conflicts**
   ```bash
   # Check for conflicting processes
   lsof -i :9876 -i :3000 -i :7777
   
   # Use different ports
   docker-compose -f docker-compose.yml -f docker-compose.override.yml up
   ```

2. **Service Startup Failures**
   ```bash
   # Check service logs
   docker-compose logs gateway
   docker-compose logs blossom-server
   
   # Restart specific service
   docker-compose restart gateway
   ```

3. **Test File Generation Issues**
   ```bash
   # Generate test files manually
   docker-compose --profile setup run test-file-generator
   
   # Check disk space
   df -h
   ```

4. **Network Connectivity**
   ```bash
   # Test internal connectivity
   docker-compose exec gateway ping blossom-server
   
   # Check exposed ports
   docker-compose ps
   ```

### Debug Mode

Enable verbose logging:

```bash
# Docker Compose with debug logs
docker-compose --verbose up

# Individual service logs
docker-compose logs -f gateway

# Test script debug
DEBUG=1 ./integration_test.sh
```

### Performance Tuning

For large-scale testing:

```bash
# Increase resource limits
echo '{"default-ulimits": {"nofile": {"soft": 65536, "hard": 65536}}}' > /etc/docker/daemon.json
sudo systemctl restart docker

# Use faster storage
docker-compose -f docker-compose.yml -f docker-compose.fast-storage.yml up
```

## Continuous Integration

### GitHub Actions Integration

```yaml
name: Gateway Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Tests
        run: |
          cd test
          docker-compose --profile orchestrate up --abort-on-container-exit
```

### Custom CI Pipeline

```bash
#!/bin/bash
set -e

# Start test environment
docker-compose up -d

# Wait for services
./wait-for-services.sh

# Run test suites
./integration_test.sh
go run load_test.go
go run compatibility_test.go

# Collect results
tar -czf test_results_$(date +%Y%m%d_%H%M%S).tar.gz test_results/
```

## Contributing

### Adding New Tests

1. **Integration Tests**: Add test cases to `integration_test.sh`
2. **Load Tests**: Modify parameters in `load_test.go`
3. **Compatibility Tests**: Add format support in `compatibility_test.go`
4. **Docker Services**: Update `docker-compose.yml`

### Test Development Guidelines

- Include clear pass/fail criteria
- Provide detailed error messages
- Generate structured JSON results
- Add comprehensive logging
- Validate cleanup procedures

## License

This testing suite follows the same license as the main Blossom-BitTorrent Gateway project.