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

# 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

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

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

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

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

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

{
  "port": 3000,
  "storage": {
    "type": "filesystem",
    "path": "/data/blobs"
  },
  "limits": {
    "max_blob_size": 104857600,
    "max_total_size": 10737418240
  }
}

Nostr Relay (nostr-relay-config.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:

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

{
  "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

   # 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

   # Check service logs
   docker-compose logs gateway
   docker-compose logs blossom-server
   
   # Restart specific service
   docker-compose restart gateway
   

3. Test File Generation Issues

   # Generate test files manually
   docker-compose --profile setup run test-file-generator
   
   # Check disk space
   df -h
   

4. Network Connectivity

   # Test internal connectivity
   docker-compose exec gateway ping blossom-server
   
   # Check exposed ports
   docker-compose ps
   

Debug Mode

Enable verbose logging:

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

# 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

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

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