diff options
| author | DanConwayDev <DanConwayDev@protonmail.com> | 2025-11-05 12:05:38 +0000 |
|---|---|---|
| committer | DanConwayDev <DanConwayDev@protonmail.com> | 2025-11-05 12:05:38 +0000 |
| commit | 1e267c282d07c68dbee4682c66d3933032ed7fec (patch) | |
| tree | 54b24878684ad2a569cb939508d48faaa24c3758 /grasp-audit/README.md | |
| parent | d9c9ef2ff92b687f5ff5585b08b2eead8f139a02 (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.md | 42 |
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 | ||
| 15 | The fastest way to run GRASP-01 compliance tests: | ||
| 16 | |||
| 17 | ```bash | ||
| 18 | # Run the test suite against ngit-relay | ||
| 19 | cd grasp-audit | ||
| 20 | nix develop -c bash test-ngit-relay.sh --mode test | ||
| 21 | ``` | ||
| 22 | |||
| 23 | This 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 | |||
| 30 | For 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 | |||
| 134 | cargo test | 158 | cargo test |
| 135 | ``` | 159 | ``` |
| 136 | 160 | ||
| 137 | ### Integration Tests Against ngit-relay docker image | 161 | ### Integration Tests |
| 138 | 162 | ||
| 139 | Test against the reference GRASP implementation to ensure compatibility. | 163 | The recommended approach is [`test-ngit-relay.sh`](test-ngit-relay.sh), which handles all relay lifecycle management automatically. |
| 140 | 164 | ||
| 141 | **Automated Script (Recommended):** | 165 | See 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 | ||
| 148 | See `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:** | 172 | For 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 | |||
| 160 | RELAY_URL="ws://localhost:18081" cargo test --lib test_grasp01_nostr_relay_against_relay -- --ignored --nocapture | 182 | RELAY_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 | ``` |