upleb.uk

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

summaryrefslogtreecommitdiff
path: root/grasp-audit/README.md
diff options
context:
space:
mode:
authorDanConwayDev <DanConwayDev@protonmail.com>2025-11-05 12:05:38 +0000
committerDanConwayDev <DanConwayDev@protonmail.com>2025-11-05 12:05:38 +0000
commit1e267c282d07c68dbee4682c66d3933032ed7fec (patch)
tree54b24878684ad2a569cb939508d48faaa24c3758 /grasp-audit/README.md
parentd9c9ef2ff92b687f5ff5585b08b2eead8f139a02 (diff)
feat(grasp-audit): standardize testing with test-ngit-relay.sh
Establish test-ngit-relay.sh as the canonical testing approach for GRASP-01 compliance tests, eliminating manual relay setup and ensuring consistent, reproducible test environments. **Enhanced test-ngit-relay.sh:** - Add command-line argument parsing (--mode, --spec, --help) - Support both audit and test execution modes - Comprehensive inline documentation - Backward compatible (default behavior unchanged) **Documentation updates:** - AGENTS.md: Add "Standard Testing Process" section - AGENTS.md: Update Quick Reference to prioritize test-ngit-relay.sh - AGENTS.md: Add Critical Gotcha #7 about using the test script - grasp-audit/README.md: Add prominent Quick Start section - grasp-audit/README.md: Reorganize testing documentation **Benefits:** - Automatic relay lifecycle management (start, cleanup) - Random port selection prevents conflicts - Isolated temporary directories per run - Guaranteed cleanup on success or failure - Consistent test environment across all developers All changes tested and verified working.
Diffstat (limited to 'grasp-audit/README.md')
-rw-r--r--grasp-audit/README.md42
1 files changed, 33 insertions, 9 deletions
diff --git a/grasp-audit/README.md b/grasp-audit/README.md
index 3787fee..97a6429 100644
--- a/grasp-audit/README.md
+++ b/grasp-audit/README.md
@@ -12,6 +12,28 @@ A reusable audit and compliance testing tool for GRASP protocol implementations.
12 12
13## Quick Start 13## Quick Start
14 14
15The fastest way to run GRASP-01 compliance tests:
16
17```bash
18# Run the test suite against ngit-relay
19cd grasp-audit
20nix develop -c bash test-ngit-relay.sh --mode test
21```
22
23This automatically:
24- ✅ Starts ngit-relay in an isolated Docker container
25- ✅ Runs all GRASP-01 compliance tests
26- ✅ Cleans up resources when finished
27
28**Currently Passing:** 4/18 tests (14 tests stubbed with "Not implemented yet")
29
30For more options:
31```bash
32./test-ngit-relay.sh --help
33```
34
35## Usage Examples
36
15### As a Library 37### As a Library
16 38
17```rust 39```rust
@@ -124,6 +146,8 @@ cargo run --example simple_audit
124 146
125## Testing 147## Testing
126 148
149> **TL;DR:** See the [Quick Start](#quick-start) section for the fastest way to run tests.
150
127### Unit Tests 151### Unit Tests
128 152
129```bash 153```bash
@@ -134,20 +158,18 @@ nix develop
134cargo test 158cargo test
135``` 159```
136 160
137### Integration Tests Against ngit-relay docker image 161### Integration Tests
138 162
139Test against the reference GRASP implementation to ensure compatibility. 163The recommended approach is [`test-ngit-relay.sh`](test-ngit-relay.sh), which handles all relay lifecycle management automatically.
140 164
141**Automated Script (Recommended):** 165See the [Quick Start](#quick-start) section for common usage patterns.
142 166
143```bash 167**Advanced: Manual Relay Setup**
144# Handles setup, testing, and cleanup automatically
145./test-ngit-relay.sh
146```
147 168
148See `test-ngit-relay.sh` for full setup/cleanup details. 169<details>
170<summary>Click to expand manual testing instructions</summary>
149 171
150**Manual Testing:** 172For advanced use cases where you need direct control over the relay:
151 173
152```bash 174```bash
153# Start relay on a specific port (example uses 18081) 175# Start relay on a specific port (example uses 18081)
@@ -160,6 +182,8 @@ grasp-audit audit --relay ws://localhost:18081 --mode ci
160RELAY_URL="ws://localhost:18081" cargo test --lib test_grasp01_nostr_relay_against_relay -- --ignored --nocapture 182RELAY_URL="ws://localhost:18081" cargo test --lib test_grasp01_nostr_relay_against_relay -- --ignored --nocapture
161``` 183```
162 184
185</details>
186
163## Architecture 187## Architecture
164 188
165``` 189```