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-12-02 21:20:17 +0000
committerDanConwayDev <DanConwayDev@protonmail.com>2025-12-02 21:20:17 +0000
commit72683beea066d066637e747c40dc859fb709babf (patch)
tree2db3462ebbcb7501e56491148cc3ffa7aa294071 /grasp-audit/README.md
parent5c10ca008413744b09136618eaa85275c997704c (diff)
refactor: rename AuditMode variants and change CLI default to shared
Breaking change: Renamed AuditMode enum variants for clarity: - AuditMode::CI -> AuditMode::Isolated (fresh fixtures per test) - AuditMode::Production -> AuditMode::Shared (reuse fixtures across tests) Config constructors renamed (with deprecated aliases): - AuditConfig::ci() -> AuditConfig::isolated() - AuditConfig::production() -> AuditConfig::shared() CLI default changed from 'ci' to 'shared' mode, which enables fixture caching across tests. This fixes the issue where fixtures were being re-created for every test in CLI mode. Fixture caching behavior: - Shared mode (CLI default): Uses client's cache, fixtures reused - Isolated mode (for cargo test): Local cache per TestContext
Diffstat (limited to 'grasp-audit/README.md')
-rw-r--r--grasp-audit/README.md60
1 files changed, 36 insertions, 24 deletions
diff --git a/grasp-audit/README.md b/grasp-audit/README.md
index 2f07326..0ff3d71 100644
--- a/grasp-audit/README.md
+++ b/grasp-audit/README.md
@@ -4,8 +4,8 @@ A reusable audit and compliance testing tool for GRASP protocol implementations.
4 4
5## Features 5## Features
6 6
7- ✅ **Isolated Testing**: Tests run in parallel with unique audit IDs 7- ✅ **Shared Fixtures**: Fixtures cached and reused across tests (default for CLI)
8- ✅ **Production Audit**: Test live services with minimal impact 8- ✅ **Isolated Testing**: Fresh fixtures per test for parallel test isolation
9- ✅ **Clean Audit Events**: Special tags for easy cleanup (no deletion trails) 9- ✅ **Clean Audit Events**: Special tags for easy cleanup (no deletion trails)
10- ✅ **Spec-Mirrored Tests**: Test structure matches GRASP protocol exactly 10- ✅ **Spec-Mirrored Tests**: Test structure matches GRASP protocol exactly
11- ✅ **Reusable**: Can test any GRASP implementation (Rust, Go, Python, etc.) 11- ✅ **Reusable**: Can test any GRASP implementation (Rust, Go, Python, etc.)
@@ -41,8 +41,8 @@ use grasp_audit::*;
41 41
42#[tokio::main] 42#[tokio::main]
43async fn main() -> Result<()> { 43async fn main() -> Result<()> {
44 // Create audit client for CI testing 44 // Create audit client with shared fixtures (default for CLI)
45 let config = AuditConfig::ci(); 45 let config = AuditConfig::shared();
46 let client = AuditClient::new("ws://localhost:7000", config).await?; 46 let client = AuditClient::new("ws://localhost:7000", config).await?;
47 47
48 // Run NIP-01 smoke tests 48 // Run NIP-01 smoke tests
@@ -63,11 +63,11 @@ async fn main() -> Result<()> {
63# Install 63# Install
64cargo install --path . 64cargo install --path .
65 65
66# Run smoke tests against local relay 66# Run smoke tests against local relay (shared fixtures - default)
67grasp-audit audit --relay ws://localhost:7000 --mode ci --spec nip01-smoke 67grasp-audit audit --relay ws://localhost:7000 --spec nip01-smoke
68 68
69# Audit production server 69# Run with isolated fixtures (each test gets fresh fixtures)
70grasp-audit audit --relay wss://grasp.example.com --mode production --spec all 70grasp-audit audit --relay ws://localhost:7000 --mode isolated --spec all
71``` 71```
72 72
73## Test Specifications 73## Test Specifications
@@ -110,11 +110,10 @@ All audit events automatically include special tags for isolation and cleanup:
110 110
111- `["t", "grasp-audit-test-event"]` - Identifies all audit-related events 111- `["t", "grasp-audit-test-event"]` - Identifies all audit-related events
112- `["t", "audit-{run_id}"]` - Unique identifier for each audit run 112- `["t", "audit-{run_id}"]` - Unique identifier for each audit run
113 - CI mode: `audit-ci-{uuid}` 113 - Shared mode: `audit-audit-{uuid}`
114 - Production mode: `audit-prod-audit-{timestamp}` 114 - Isolated mode: `audit-isolated-{uuid}`
115- `["t", "audit-cleanup-after-{unix_timestamp}"]` - Cleanup scheduling 115- `["t", "audit-cleanup-after-{unix_timestamp}"]` - Cleanup scheduling
116 - CI mode: Current time + 3600 seconds (1 hour) 116 - Default: Current time + 3600 seconds (1 hour)
117 - Production mode: Current time + 300 seconds (5 minutes)
118 117
119**Benefits:** 118**Benefits:**
120 119
@@ -124,27 +123,40 @@ All audit events automatically include special tags for isolation and cleanup:
124- **No deletion trails**: No NIP-09 deletion events needed 123- **No deletion trails**: No NIP-09 deletion events needed
125- **Discovery**: Easy to query all audit events via hashtag 124- **Discovery**: Easy to query all audit events via hashtag
126 125
127## Modes 126## Fixture Modes
128 127
129### CI Mode (Default) 128The audit tool supports two fixture caching modes that control how test prerequisites are managed.
130 129
131- Tests are isolated by unique run ID 130### Shared Mode (Default for CLI)
132- Tests only see their own events 131
133- Full read/write access 132Fixtures are cached and reused across all tests. Use this when:
134- Cleanup after 1 hour 133- Running the CLI audit tool sequentially
134- Tests build on each other's fixtures
135- You want efficient resource usage
135 136
136```rust 137```rust
137let config = AuditConfig::ci(); 138let config = AuditConfig::shared();
138``` 139```
139 140
140### Production Mode 141### Isolated Mode (For Parallel Tests)
141 142
142- Tests see all events (including real ones) 143Each test creates fresh fixtures for complete isolation. Use this when:
143- Read-only by default (minimal impact) 144- Running `cargo test` in parallel
144- Cleanup after 5 minutes 145- Tests must not interfere with each other
146- Testing the fixture system itself
145 147
146```rust 148```rust
147let config = AuditConfig::production(); 149let config = AuditConfig::isolated();
150```
151
152### CLI Usage
153
154```bash
155# Default: shared fixtures (efficient for sequential CLI runs)
156grasp-audit audit --relay ws://localhost:7000 --spec all
157
158# Isolated fixtures (for testing)
159grasp-audit audit --relay ws://localhost:7000 --mode isolated --spec all
148``` 160```
149 161
150## Examples 162## Examples