upleb.uk

Public git repos — served from a NIP-34 GRASP relay at git.upleb.uk

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