diff options
| author | DanConwayDev <DanConwayDev@protonmail.com> | 2025-12-02 21:20:17 +0000 |
|---|---|---|
| committer | DanConwayDev <DanConwayDev@protonmail.com> | 2025-12-02 21:20:17 +0000 |
| commit | 72683beea066d066637e747c40dc859fb709babf (patch) | |
| tree | 2db3462ebbcb7501e56491148cc3ffa7aa294071 /grasp-audit/README.md | |
| parent | 5c10ca008413744b09136618eaa85275c997704c (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.md | 60 |
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] |
| 43 | async fn main() -> Result<()> { | 43 | async 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 |
| 64 | cargo install --path . | 64 | cargo install --path . |
| 65 | 65 | ||
| 66 | # Run smoke tests against local relay | 66 | # Run smoke tests against local relay (shared fixtures - default) |
| 67 | grasp-audit audit --relay ws://localhost:7000 --mode ci --spec nip01-smoke | 67 | grasp-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) |
| 70 | grasp-audit audit --relay wss://grasp.example.com --mode production --spec all | 70 | grasp-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) | 128 | The 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 | 132 | Fixtures 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 |
| 137 | let config = AuditConfig::ci(); | 138 | let 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) | 143 | Each 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 |
| 147 | let config = AuditConfig::production(); | 149 | let config = AuditConfig::isolated(); |
| 150 | ``` | ||
| 151 | |||
| 152 | ### CLI Usage | ||
| 153 | |||
| 154 | ```bash | ||
| 155 | # Default: shared fixtures (efficient for sequential CLI runs) | ||
| 156 | grasp-audit audit --relay ws://localhost:7000 --spec all | ||
| 157 | |||
| 158 | # Isolated fixtures (for testing) | ||
| 159 | grasp-audit audit --relay ws://localhost:7000 --mode isolated --spec all | ||
| 148 | ``` | 160 | ``` |
| 149 | 161 | ||
| 150 | ## Examples | 162 | ## Examples |