super_ball_thrower/tests/QUICKSTART.md

# Test Suite Quick Start Guide

## Prerequisites

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

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

## Quick Test Run

### 1. Single Test (No Thrower Required)

Test the framework itself:
```bash
cd tests
./test_framework.sh list
```

### 2. Single-Hop Test (1 Thrower)

**Setup Thrower A:**
```bash
# In terminal 1 - Create config
cd ..
cat > config_test_a.json <<EOF
{
  "thrower": {
    "privateKey": "0000000000000000000000000000000000000000000000000000000000000002",
    "name": "Test Thrower A",
    "description": "Test thrower for single-hop tests",
    "maxDelay": 86460,
    "refreshRate": 300,
    "supportedSups": "1,2,3,4,5,6",
    "software": "https://git.laantungir.net/laantungir/super_ball_thrower.git",
    "version": "1.0.0"
  },
  "relays": [
    {
      "url": "wss://relay.laantungir.net",
      "read": true,
      "write": true
    }
  ],
  "daemon": {
    "logLevel": "info",
    "maxQueueSize": 1000
  }
}
EOF

# Start thrower
./superball_thrower config_test_a.json
```

**Run Test:**
```bash
# In terminal 2
cd tests
./test_framework.sh test_single_hop
```

### 3. Multi-Hop Test (3 Throwers)

**Setup Thrower A, B, C:**
```bash
# Terminal 1 - Thrower A
cd ..
./superball_thrower config_test_a.json

# Terminal 2 - Thrower B (create config first)
cat > config_test_b.json <<EOF
{
  "thrower": {
    "privateKey": "0000000000000000000000000000000000000000000000000000000000000003",
    "name": "Test Thrower B",
    "description": "Test thrower B",
    "maxDelay": 86460,
    "refreshRate": 300,
    "supportedSups": "1,2,3,4,5,6",
    "software": "https://git.laantungir.net/laantungir/super_ball_thrower.git",
    "version": "1.0.0"
  },
  "relays": [
    {
      "url": "wss://relay.damus.io",
      "read": true,
      "write": true
    }
  ],
  "daemon": {
    "logLevel": "info",
    "maxQueueSize": 1000
  }
}
EOF
./superball_thrower config_test_b.json

# Terminal 3 - Thrower C (create config first)
cat > config_test_c.json <<EOF
{
  "thrower": {
    "privateKey": "0000000000000000000000000000000000000000000000000000000000000004",
    "name": "Test Thrower C",
    "description": "Test thrower C",
    "maxDelay": 86460,
    "refreshRate": 300,
    "supportedSups": "1,2,3,4,5,6",
    "software": "https://git.laantungir.net/laantungir/super_ball_thrower.git",
    "version": "1.0.0"
  },
  "relays": [
    {
      "url": "wss://nos.lol",
      "read": true,
      "write": true
    }
  ],
  "daemon": {
    "logLevel": "info",
    "maxQueueSize": 1000
  }
}
EOF
./superball_thrower config_test_c.json
```

**Run Tests:**
```bash
# Terminal 4
cd tests
./test_framework.sh test_multi_hop
./test_framework.sh test_padding
./test_framework.sh test_end_to_end
```

### 4. Run All Tests

With all 3 throwers running:
```bash
cd tests
./test_framework.sh all
```

## Test Timing

All tests use 2-second delays for fast execution:
- **test_single_hop**: ~10 seconds
- **test_multi_hop**: ~15 seconds  
- **test_padding**: ~12 seconds
- **test_delays**: ~20 seconds (tests multiple delay values)
- **test_thrower_info**: ~10 seconds
- **test_relay_auth**: ~5 seconds (skipped if no AUTH relay)
- **test_end_to_end**: ~15 seconds

**Total suite runtime**: ~1-2 minutes (with all throwers running)

## Troubleshooting

### "nak command not found"
```bash
go install github.com/fiatjaf/nak@latest
export PATH=$PATH:$(go env GOPATH)/bin
```

### "Event not found on relay"
- Check thrower is running: `ps aux | grep superball_thrower`
- Check thrower logs for errors
- Verify relay connectivity: `nak req --relay wss://relay.laantungir.net -k 1 --limit 1`

### "Event arrived too early"
- Thrower may not be respecting delays
- Check queue processing in logs
- Verify system time is correct

### Tests timeout
- Increase timeout values in test scripts
- Check network connectivity
- Verify relays are responding

## Test Keys

⚠️ **WARNING**: Test keys in `fixtures/test_keys.json` are for testing only!

- Builder: `0000...0001`
- Thrower A: `0000...0002`
- Thrower B: `0000...0003`
- Thrower C: `0000...0004`

**NEVER use these keys in production!**

## Next Steps

1. Run individual tests to verify each SUP
2. Run full suite with `./test_framework.sh all`
3. Check logs in `tests/logs/` for details
4. Review results in `tests/results/summary.txt`

For detailed documentation, see [README.md](README.md).