blob: cb6d8a79a2c02af93a9bc6117ee784d2e0deccfc (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
|
# GRASP Audit - Quick Start Guide
## Prerequisites
- Rust 1.75 or later
- C compiler (gcc or clang)
- A Nostr relay for testing (optional for unit tests)
## Setup on NixOS
```bash
# Enter development shell
cd grasp-audit
nix develop
# Build the project
cargo build
# Run unit tests (no relay needed)
cargo test --lib
```
## Setup on Other Systems
```bash
cd grasp-audit
# Install Rust (if needed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Build
cargo build
# Run unit tests
cargo test --lib
```
## Running Smoke Tests (Requires Relay)
### Option 1: Use a Public Relay
```bash
# Run against a public relay
cargo run --example simple_audit
# Edit the example to use: wss://relay.damus.io or similar
```
### Option 2: Run Local Relay
```bash
# Terminal 1: Start a test relay
# Option A: Using nostr-relay-builder
git clone https://github.com/rust-nostr/nostr
cd nostr/crates/nostr-relay-builder
cargo run --example basic
# Option B: Using docker
docker run -p 7000:7000 scsibug/nostr-rs-relay
# Terminal 2: Run smoke tests
cd grasp-audit
cargo run --example simple_audit
```
### Option 3: Use the CLI
```bash
# Build the CLI
cargo build --release
# Run smoke tests
./target/release/grasp-audit audit \
--relay ws://localhost:7000 \
--mode ci \
--spec nip01-smoke
```
## Running Tests
```bash
# Unit tests only (no relay needed)
cargo test --lib
# Integration tests (needs relay at ws://localhost:7000)
cargo test --ignored
# All tests
cargo test --all
# With output
cargo test -- --nocapture
```
## Using as a Library
Add to your `Cargo.toml`:
```toml
[dependencies]
grasp-audit = { path = "../grasp-audit" }
```
Example code:
```rust
use grasp_audit::*;
#[tokio::main]
async fn main() -> Result<()> {
// Create audit client
let config = AuditConfig::isolated();
let client = AuditClient::new("ws://localhost:7000", config).await?;
// Run smoke tests
let results = specs::Nip01SmokeTests::run_all(&client).await;
// Print results
results.print_report();
// Check if passed
if !results.all_passed() {
eprintln!("Some tests failed!");
std::process::exit(1);
}
Ok(())
}
```
## Troubleshooting
### Build Errors
**Error:** `linker 'cc' not found`
**Solution (NixOS):**
```bash
nix develop # Use the provided flake.nix
```
**Solution (Other Linux):**
```bash
sudo apt-get install build-essential # Debian/Ubuntu
sudo yum install gcc # RedHat/CentOS
```
**Solution (macOS):**
```bash
xcode-select --install
```
### Connection Errors
**Error:** `Failed to connect to relay`
**Solutions:**
1. Make sure a relay is running at the specified URL
2. Check firewall settings
3. Try a different relay URL
4. Use `ws://` for local, `wss://` for remote
### Test Failures
**Error:** Tests fail with timeout
**Solutions:**
1. Increase timeout in test code
2. Check relay is responding (try with `websocat`)
3. Check network connectivity
## Examples
### CI Mode (Isolated Testing)
```bash
# Each run is isolated with unique ID
./target/release/grasp-audit audit \
--relay ws://localhost:7000 \
--mode ci \
--spec nip01-smoke
# Run ID: ci-a1b2c3d4-e5f6-7890-abcd-ef1234567890
# Tests only see events from this run
```
### Production Mode (Audit Live Service)
```bash
# Read-only audit of production relay
./target/release/grasp-audit audit \
--relay wss://relay.example.com \
--mode production \
--spec nip01-smoke
# Run ID: prod-audit-1699027200
# Tests see all events (including real ones)
# Minimal writes (read-only by default)
```
## What's Next?
1. ✅ Run unit tests
2. ✅ Run smoke tests against a relay
3. ✅ Check the report output
4. 🚧 Implement GRASP-01 compliance tests
5. 🚧 Set up CI/CD integration
6. 🚧 Test against ngit-grasp relay
## Resources
- **README.md** - Full documentation
- **SMOKE_TEST_REPORT.md** - Implementation details
- **examples/simple_audit.rs** - Example usage
- **GRASP_AUDIT_PLAN.md** - Original plan
## Support
For issues or questions:
1. Check the documentation in this directory
2. Review the examples
3. Check the test code for usage patterns
4. Open an issue on the project repository
|