super_ball_thrower/tests/README.md

# Superball Protocol Test Suite

Comprehensive test suite for verifying SUP-01 through SUP-06 compliance in the Superball Thrower daemon.

## Overview

This test suite validates all aspects of the Superball protocol implementation:

- **SUP-01**: Basic single-hop routing
- **SUP-02**: Multi-hop routing (2-5 hops)
- **SUP-03**: Padding payload handling (Type 2 payloads)
- **SUP-04**: Delay and jitter verification
- **SUP-05**: Relay authentication testing
- **SUP-06**: Thrower information publishing

## Prerequisites

### Required Tools

1. **nak** (Nostr Army Knife)
   ```bash
   go install github.com/fiatjaf/nak@latest
   ```

2. **jq** (JSON processor)
   ```bash
   sudo apt-get install jq  # Debian/Ubuntu
   brew install jq          # macOS
   ```

3. **Superball Thrower daemon**
   ```bash
   cd ..
   make
   ```

### Running Throwers

For multi-hop tests, you need multiple thrower instances running. Create separate config files for each:

```bash
# Thrower A
cp config.example.json config_thrower_a.json
# Edit config_thrower_a.json with thrower_a private key

# Thrower B
cp config.example.json config_thrower_b.json
# Edit config_thrower_b.json with thrower_b private key

# Thrower C
cp config.example.json config_thrower_c.json
# Edit config_thrower_c.json with thrower_c private key
```

Start each thrower in a separate terminal:
```bash
./superball_thrower config_thrower_a.json
./superball_thrower config_thrower_b.json
./superball_thrower config_thrower_c.json
```

## Test Structure

```
tests/
├── test_framework.sh          # Main test orchestrator
├── test_single_hop.sh         # SUP-01: Single-hop routing
├── test_multi_hop.sh          # SUP-02: Multi-hop routing
├── test_padding.sh            # SUP-03: Padding payloads
├── test_delays.sh             # SUP-04: Delay verification
├── test_relay_auth.sh         # SUP-05: AUTH relay handling
├── test_thrower_info.sh       # SUP-06: Thrower info publishing
├── test_end_to_end.sh         # Complete workflow test
├── helpers/
│   ├── timing_utils.sh        # Timing and delay utilities
│   └── event_utils.sh         # Event creation utilities
├── fixtures/
│   ├── test_keys.json         # Test keypairs
│   └── test_relays.json       # Test relay configurations
├── logs/                      # Test execution logs
└── results/                   # Test results
```

## Running Tests

### Run All Tests

```bash
cd tests
./test_framework.sh
```

or

```bash
cd tests
./test_framework.sh all
```

### Run Specific Test

```bash
cd tests
./test_framework.sh test_single_hop
./test_framework.sh test_multi_hop
./test_framework.sh test_padding
```

### List Available Tests

```bash
cd tests
./test_framework.sh list
```

### View Help

```bash
cd tests
./test_framework.sh help
```

## Test Descriptions

### test_single_hop.sh (SUP-01)

Tests basic single-hop routing:
- Builder creates encrypted event
- Thrower receives and decrypts
- Thrower waits for delay
- Thrower posts to final relay
- Verifies timing and content

**Duration**: ~10-15 seconds  
**Requirements**: 1 thrower running

### test_multi_hop.sh (SUP-02)

Tests multi-hop routing with 3 hops:
- Creates onion-routed event (3 layers)
- Each thrower unwraps one layer
- Verifies complete routing chain
- Checks cumulative delays

**Duration**: ~30-45 seconds  
**Requirements**: 3 throwers running (A, B, C)

### test_padding.sh (SUP-03)

Tests padding payload handling:
- Thrower A adds padding bytes
- Creates Type 2 payload
- Thrower B performs double decryption
- Verifies padding is discarded
- Confirms content integrity

**Duration**: ~15-20 seconds  
**Requirements**: 2 throwers running (A, B)

### test_delays.sh (SUP-04)

Tests delay constraints with multiple values:
- Tests delays: 0s, 5s, 10s, 30s, 60s
- Verifies minimum delay respected
- Checks jitter application
- Validates timing accuracy

**Duration**: ~2-3 minutes  
**Requirements**: 1 thrower running

### test_relay_auth.sh (SUP-05)

Tests AUTH-required relay handling:
- Detects AUTH requirement
- Verifies relay marked as "auth-required"
- Confirms events skip AUTH relay
- Checks appropriate logging

**Duration**: ~5 seconds  
**Requirements**: AUTH-required relay (optional)

### test_thrower_info.sh (SUP-06)

Tests thrower information publishing:
- Queries for kind 12222 events
- Verifies all required fields
- Checks relay configurations
- Validates event structure

**Duration**: ~10-15 seconds  
**Requirements**: 1 thrower running with auto-publish

### test_end_to_end.sh

Complete workflow test combining all features:
- 3-hop routing chain
- Padding at first hop
- Delays at each hop
- Full protocol compliance
- Performance metrics

**Duration**: ~30-45 seconds  
**Requirements**: 3 throwers running (A, B, C)

## Test Configuration

### Test Keys

Test keypairs are defined in `fixtures/test_keys.json`:
- **builder**: Creates initial Superball events
- **thrower_a**: First hop
- **thrower_b**: Second hop
- **thrower_c**: Third hop
- **thrower_d**: Fourth hop (for 4-hop tests)
- **thrower_e**: Fifth hop (for 5-hop tests)

⚠️ **WARNING**: These are test keys only. NEVER use in production!

### Test Relays

Relay configurations are in `fixtures/test_relays.json`:
- **primary**: wss://relay.laantungir.net
- **secondary**: wss://relay.damus.io
- **tertiary**: wss://nos.lol
- **final**: wss://relay.nostr.band

You can modify these to use your preferred relays.

## Interpreting Results

### Success Output

```
=== Superball Protocol Test Suite ===
Starting at Mon Dec 10 14:00:00 UTC 2025

Running: test_single_hop
✓ PASSED: test_single_hop (12s)

Running: test_multi_hop
✓ PASSED: test_multi_hop (38s)

...

=== Test Summary ===
Passed:  7
Failed:  0
Skipped: 0
Total:   7
```

### Failure Output

When a test fails, the last 20 lines of the log are displayed:

```
Running: test_single_hop
✗ FAILED: test_single_hop (15s)
  See log: logs/test_single_hop.log
  Last 20 lines of log:
    ERROR: Inner event not found on final relay within 30s
    This could indicate:
      - Thrower is not running
      - Network connectivity issues
```

### Logs

Detailed logs for each test are saved in `logs/`:
- `logs/test_single_hop.log`
- `logs/test_multi_hop.log`
- etc.

Results summary is saved in `results/summary.txt`.

## Troubleshooting

### Test Fails: "nak command not found"

Install nak:
```bash
go install github.com/fiatjaf/nak@latest
```

### Test Fails: "superball_thrower binary not found"

Build the daemon:
```bash
cd ..
make
```

### Test Fails: "Event not found on relay"

Possible causes:
1. Thrower not running
2. Wrong private key in config
3. Relay connectivity issues
4. Firewall blocking WebSocket connections

Check thrower logs:
```bash
tail -f /tmp/superball_thrower.log
```

### Test Fails: "Event arrived too early"

The thrower may not be respecting delay constraints. Check:
1. Queue processing is working
2. Delays are being applied
3. System time is correct

### Multi-hop Tests Fail

Ensure all required throwers are running:
```bash
ps aux | grep superball_thrower
```

Each thrower needs its own config file with the correct private key.

## CI/CD Integration

### GitHub Actions

Example workflow:

```yaml
name: Superball Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: recursive
      
      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y jq libsecp256k1-dev libsodium-dev
          go install github.com/fiatjaf/nak@latest
      
      - name: Build
        run: make
      
      - name: Run tests
        run: |
          cd tests
          ./test_framework.sh all
      
      - name: Upload results
        if: always()
        uses: actions/upload-artifact@v2
        with:
          name: test-results
          path: tests/results/
```

## Contributing

When adding new tests:

1. Create test script in `tests/`
2. Follow naming convention: `test_<feature>.sh`
3. Add to `TESTS` array in `test_framework.sh`
4. Include clear documentation
5. Add expected duration and requirements
6. Provide troubleshooting guidance

## License

Same as parent project.