Generally functional. Added upload script
This commit is contained in:
Your Name
376
tests/README.md
Normal file
376
tests/README.md
Normal file
@@ -0,0 +1,376 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user