super_ball_thrower/tests/QUICKSTART.md

Test Suite Quick Start Guide

Prerequisites

1. Install nak (Nostr Army Knife):

   go install github.com/fiatjaf/nak@latest
   

2. Build the daemon:

   cd ..
   make
   

Quick Test Run

1. Single Test (No Thrower Required)

Test the framework itself:

cd tests
./test_framework.sh list

2. Single-Hop Test (1 Thrower)

Setup Thrower A:

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

# In terminal 2
cd tests
./test_framework.sh test_single_hop

3. Multi-Hop Test (3 Throwers)

Setup Thrower A, B, C:

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

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

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"

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.