198 lines
5.6 KiB
Markdown
198 lines
5.6 KiB
Markdown
# Superball Protocol Test Suite - Summary
|
|
|
|
## Overview
|
|
|
|
Comprehensive test suite for validating SUP-01 through SUP-06 compliance in the C implementation of the Superball Thrower daemon.
|
|
|
|
## Test Coverage
|
|
|
|
| Test | SUP | Feature | Duration | Throwers Required |
|
|
|------|-----|---------|----------|-------------------|
|
|
| `test_single_hop.sh` | SUP-01 | Basic routing | ~10s | 1 (A) |
|
|
| `test_multi_hop.sh` | SUP-02 | Multi-hop (3 hops) | ~15s | 3 (A, B, C) |
|
|
| `test_padding.sh` | SUP-03 | Padding payloads | ~12s | 2 (A, B) |
|
|
| `test_delays.sh` | SUP-04 | Delay verification | ~20s | 1 (A) |
|
|
| `test_relay_auth.sh` | SUP-05 | AUTH handling | ~5s | Optional |
|
|
| `test_thrower_info.sh` | SUP-06 | Thrower info | ~10s | 1 (A) |
|
|
| `test_end_to_end.sh` | All | Complete workflow | ~15s | 3 (A, B, C) |
|
|
|
|
**Total Runtime**: ~1-2 minutes (with all throwers running)
|
|
|
|
## File Structure
|
|
|
|
```
|
|
tests/
|
|
├── test_framework.sh # Main orchestrator (300 lines)
|
|
├── test_single_hop.sh # SUP-01 test (100 lines)
|
|
├── test_multi_hop.sh # SUP-02 test (150 lines)
|
|
├── test_padding.sh # SUP-03 test (140 lines)
|
|
├── test_delays.sh # SUP-04 test (100 lines)
|
|
├── test_relay_auth.sh # SUP-05 test (80 lines)
|
|
├── test_thrower_info.sh # SUP-06 test (150 lines)
|
|
├── test_end_to_end.sh # Integration test (200 lines)
|
|
├── helpers/
|
|
│ ├── timing_utils.sh # Timing utilities (60 lines)
|
|
│ └── event_utils.sh # Event utilities (120 lines)
|
|
├── fixtures/
|
|
│ ├── test_keys.json # Test keypairs
|
|
│ └── test_relays.json # Test relay configs
|
|
├── logs/ # Test execution logs (generated)
|
|
├── results/ # Test results (generated)
|
|
├── README.md # Full documentation
|
|
├── QUICKSTART.md # Quick start guide
|
|
└── TEST_SUITE_SUMMARY.md # This file
|
|
```
|
|
|
|
**Total Lines of Code**: ~1,400 lines
|
|
|
|
## Quick Commands
|
|
|
|
```bash
|
|
# List all tests
|
|
./test_framework.sh list
|
|
|
|
# Run all tests
|
|
./test_framework.sh all
|
|
|
|
# Run specific test
|
|
./test_framework.sh test_single_hop
|
|
|
|
# View help
|
|
./test_framework.sh help
|
|
```
|
|
|
|
## Test Parameters
|
|
|
|
All tests use **2-second delays** for fast execution:
|
|
- Single-hop: 2s delay
|
|
- Multi-hop: 2s per hop (6s total for 3 hops)
|
|
- Padding: 2s per hop
|
|
- End-to-end: 2s per hop (6s total)
|
|
|
|
## Success Criteria
|
|
|
|
Each test verifies:
|
|
1. ✓ Event routing completes successfully
|
|
2. ✓ Timing constraints respected (delay >= specified)
|
|
3. ✓ Content integrity maintained
|
|
4. ✓ Event structure valid
|
|
5. ✓ Protocol compliance (SUP-specific)
|
|
|
|
## Test Keys (fixtures/test_keys.json)
|
|
|
|
⚠️ **FOR TESTING ONLY - DO NOT USE IN PRODUCTION**
|
|
|
|
| Role | Private Key | Public Key |
|
|
|------|-------------|------------|
|
|
| Builder | `0000...0001` | `79be667e...` |
|
|
| Thrower A | `0000...0002` | `c6047f94...` |
|
|
| Thrower B | `0000...0003` | `f9308a01...` |
|
|
| Thrower C | `0000...0004` | `e493dbf1...` |
|
|
| Thrower D | `0000...0005` | `2f8bde4d...` |
|
|
| Thrower E | `0000...0006` | `fff97bd5...` |
|
|
|
|
## Test Relays (fixtures/test_relays.json)
|
|
|
|
Default test relays:
|
|
- **Primary**: wss://relay.laantungir.net
|
|
- **Secondary**: wss://relay.damus.io
|
|
- **Tertiary**: wss://nos.lol
|
|
- **Final**: wss://relay.nostr.band
|
|
|
|
## Dependencies
|
|
|
|
1. **nak** (Nostr Army Knife) - Event creation and relay interaction
|
|
2. **jq** - JSON processing
|
|
3. **bash** - Shell scripting
|
|
4. **superball_thrower** - The daemon being tested
|
|
|
|
## Output Examples
|
|
|
|
### Successful Test
|
|
```
|
|
=== SUP-01: Single-Hop Routing Test ===
|
|
Builder: 79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798
|
|
Thrower A: c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5
|
|
...
|
|
=== TEST PASSED ===
|
|
✓ Single-hop routing successful
|
|
✓ Delay constraint respected (3s >= 2s)
|
|
✓ Event content preserved
|
|
✓ Event published to correct relay
|
|
```
|
|
|
|
### Failed Test
|
|
```
|
|
=== SUP-01: Single-Hop Routing Test ===
|
|
...
|
|
ERROR: Inner event not found on final relay within 30s
|
|
This could indicate:
|
|
- Thrower is not running
|
|
- Network connectivity issues
|
|
```
|
|
|
|
## Integration with CI/CD
|
|
|
|
The test suite is designed for easy CI/CD integration:
|
|
|
|
```yaml
|
|
# .github/workflows/test.yml
|
|
- name: Run Superball Tests
|
|
run: |
|
|
cd tests
|
|
./test_framework.sh all
|
|
```
|
|
|
|
## Troubleshooting Guide
|
|
|
|
| Issue | Solution |
|
|
|-------|----------|
|
|
| "nak not found" | `go install github.com/fiatjaf/nak@latest` |
|
|
| "Event not found" | Check thrower is running, verify relay connectivity |
|
|
| "Event too early" | Check delay implementation in daemon |
|
|
| "Timeout" | Increase timeout values, check network |
|
|
|
|
## Future Enhancements
|
|
|
|
Potential additions:
|
|
- [ ] 4-hop and 5-hop routing tests
|
|
- [ ] Stress testing (high volume)
|
|
- [ ] Performance benchmarking
|
|
- [ ] Failure injection tests
|
|
- [ ] Network partition simulation
|
|
- [ ] Concurrent routing tests
|
|
- [ ] Memory leak detection
|
|
- [ ] Relay failover testing
|
|
|
|
## Metrics
|
|
|
|
Test suite provides:
|
|
- **Coverage**: All 6 SUPs tested
|
|
- **Execution Time**: < 2 minutes
|
|
- **Automation**: Fully automated
|
|
- **Reporting**: Detailed logs and summaries
|
|
- **Reliability**: Deterministic results
|
|
|
|
## Documentation
|
|
|
|
- **README.md**: Complete documentation
|
|
- **QUICKSTART.md**: Quick start guide
|
|
- **TEST_SUITE_SUMMARY.md**: This summary
|
|
|
|
## Maintenance
|
|
|
|
Test suite is self-contained and requires minimal maintenance:
|
|
- Update relay URLs if relays change
|
|
- Adjust timeouts if network conditions change
|
|
- Add new tests for new SUPs
|
|
- Update test keys if needed (testing only)
|
|
|
|
## License
|
|
|
|
Same as parent project.
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-12-10
|
|
**Version**: 1.0
|
|
**Author**: Roo (Code Mode) |