diff options
| author | DanConwayDev <DanConwayDev@protonmail.com> | 2025-12-03 11:19:40 +0000 |
|---|---|---|
| committer | DanConwayDev <DanConwayDev@protonmail.com> | 2025-12-03 11:19:40 +0000 |
| commit | 2eaff5b79fed364d5eba5eb38e4b7bf76326884d (patch) | |
| tree | deacd6294f8860096ee82ee76930204efd65e33c /docs/archive/2025-11-05-test-lessons.md | |
| parent | 57bc8cd9c021feaf08e139e8fb62800bc476068e (diff) | |
remove docs archive
Diffstat (limited to 'docs/archive/2025-11-05-test-lessons.md')
| -rw-r--r-- | docs/archive/2025-11-05-test-lessons.md | 228 |
1 files changed, 0 insertions, 228 deletions
diff --git a/docs/archive/2025-11-05-test-lessons.md b/docs/archive/2025-11-05-test-lessons.md deleted file mode 100644 index 3133376..0000000 --- a/docs/archive/2025-11-05-test-lessons.md +++ /dev/null | |||
| @@ -1,228 +0,0 @@ | |||
| 1 | # Test Implementation Lessons - GRASP-01 Compliance Suite | ||
| 2 | |||
| 3 | This document captures key lessons learned during the implementation of GRASP-01 compliance tests. Each entry documents what worked well, what to avoid, and patterns to follow for future tests. | ||
| 4 | |||
| 5 | --- | ||
| 6 | |||
| 7 | ## Test #3: test_reject_repo_announcement_missing_relays_tag | ||
| 8 | |||
| 9 | **Date:** November 5, 2025 | ||
| 10 | **Test Duration:** 45.997432ms | ||
| 11 | **Status:** ✅ PASSED | ||
| 12 | **Port Used:** 24965 (randomly assigned by test-ngit-relay.sh) | ||
| 13 | |||
| 14 | ### Test Purpose | ||
| 15 | |||
| 16 | Validates GRASP-01 line 5 requirement: relays MUST reject repository announcements without a service URL in the relays tag. | ||
| 17 | |||
| 18 | ### Key Learnings | ||
| 19 | |||
| 20 | 1. **Pattern Consistency is Key** | ||
| 21 | - Following the `test_reject_repo_announcement_missing_clone_tag` pattern significantly simplified implementation | ||
| 22 | - When creating similar tests (rejection tests for missing required tags), reuse the proven pattern | ||
| 23 | - Only swap out the tag being tested - keep all other structure identical | ||
| 24 | |||
| 25 | 2. **nostr-sdk 0.43 API Usage** | ||
| 26 | - Successfully used direct field access: `event.id` (not `event.id()`) | ||
| 27 | - Tag creation pattern: `Tag::custom(TagKind::custom("relays"), vec![...])` | ||
| 28 | - EventBuilder chaining: `EventBuilder::new(kind, content).tags(tags)` | ||
| 29 | - All work correctly with no compilation issues | ||
| 30 | |||
| 31 | 3. **Test Automation Workflow** | ||
| 32 | - test-ngit-relay.sh handled all relay lifecycle management perfectly | ||
| 33 | - Random port assignment (24965) avoided conflicts automatically | ||
| 34 | - No manual Docker commands needed - script handles everything | ||
| 35 | - Cleanup happens automatically on script exit | ||
| 36 | |||
| 37 | ### What Worked Well | ||
| 38 | |||
| 39 | - **Minimal code changes:** Only needed to modify tag name from "clone" to "relays" | ||
| 40 | - **Fast test execution:** Sub-50ms duration indicates efficient test design | ||
| 41 | - **Clear test validation:** Event rejection verified by checking event not present in relay | ||
| 42 | - **Automated testing:** test-ngit-relay.sh provided seamless relay management | ||
| 43 | |||
| 44 | ### What to Avoid | ||
| 45 | |||
| 46 | - Don't manually start relay containers - let test-ngit-relay.sh handle it | ||
| 47 | - Don't use `event.id()` method calls - nostr-sdk 0.43 uses fields | ||
| 48 | - Don't deviate from proven patterns without good reason | ||
| 49 | - Don't hard-code port numbers - use RELAY_URL env var | ||
| 50 | |||
| 51 | ### Pattern to Follow | ||
| 52 | |||
| 53 | ```rust | ||
| 54 | // Create repo announcement WITHOUT required tag | ||
| 55 | let tags = vec![ | ||
| 56 | // Include all other required tags EXCEPT the one being tested | ||
| 57 | Tag::custom( | ||
| 58 | TagKind::custom("clone"), | ||
| 59 | vec!["https://example.com/repo.git"], | ||
| 60 | ), | ||
| 61 | // Missing: relays tag (the one we're testing) | ||
| 62 | ]; | ||
| 63 | |||
| 64 | // Build and publish event | ||
| 65 | let event = client.event_builder() | ||
| 66 | .kind(Kind::GitRepoAnnouncement) | ||
| 67 | .content("Test repo") | ||
| 68 | .tags(tags) | ||
| 69 | .build()?; | ||
| 70 | |||
| 71 | client.publish_expect_reject(&event).await?; | ||
| 72 | ``` | ||
| 73 | |||
| 74 | ### Test Implementation Time | ||
| 75 | |||
| 76 | - Analysis: ~5 minutes (reviewing existing pattern) | ||
| 77 | - Implementation: ~10 minutes (copying pattern, modifying tag) | ||
| 78 | - Testing: ~2 minutes (ran via test-ngit-relay.sh) | ||
| 79 | - Total: ~17 minutes | ||
| 80 | |||
| 81 | ### Next Test Recommendation | ||
| 82 | |||
| 83 | Continue with `test_accept_state_announcement_multiple_refs` - this will test that relays accept repository state announcements with multiple git refs (e.g., multiple branches and tags). | ||
| 84 | |||
| 85 | --- | ||
| 86 | |||
| 87 | ## Test #4: test_accept_valid_repo_state_announcement | ||
| 88 | |||
| 89 | **Date:** November 5, 2025 | ||
| 90 | **Test Duration:** 148ms | ||
| 91 | **Status:** ✅ PASSED | ||
| 92 | **Commit:** ebdf177 | ||
| 93 | |||
| 94 | ### Test Purpose | ||
| 95 | |||
| 96 | Validates GRASP-01 lines 6-7 requirement: relays MUST accept valid repository state announcements (kind 30618) with required `d`, `maintainers`, and `r` tags. | ||
| 97 | |||
| 98 | ### Key Learnings | ||
| 99 | |||
| 100 | 1. **Kind 30618 Uses Different Tags Than Kind 30617** | ||
| 101 | - Repository announcements (30617): `clone`, `relays` tags | ||
| 102 | - Repository state announcements (30618): `d`, `maintainers`, `r` tags | ||
| 103 | - Don't confuse the two - they serve different purposes | ||
| 104 | - State announcements track git refs (branches/tags), repo announcements declare repository metadata | ||
| 105 | |||
| 106 | 2. **Empty Content is Valid** | ||
| 107 | - Repository state announcements use empty content (`""`) | ||
| 108 | - All metadata is in the tags, not the content field | ||
| 109 | - This is different from repo announcements which may have descriptive content | ||
| 110 | |||
| 111 | 3. **Test Duration Significantly Longer** | ||
| 112 | - Previous tests: ~46ms (rejection tests, publish and query) | ||
| 113 | - This test: 148ms (3x longer) | ||
| 114 | - Likely due to more complex tag verification (checking d, maintainers, r tags) | ||
| 115 | - Additional tag content checks (`contains("refs/heads/main")`) | ||
| 116 | |||
| 117 | 4. **Tag Structure for State Announcements** | ||
| 118 | - `d` tag: Repository identifier (unique per repo) | ||
| 119 | - `maintainers` tag: Nostr public key in bech32 format (npub) | ||
| 120 | - `r` tag: Git reference like `refs/heads/main` or `refs/tags/v1.0` | ||
| 121 | - All three are required for valid state announcement | ||
| 122 | |||
| 123 | ### What Worked Well | ||
| 124 | |||
| 125 | - **Clear tag separation:** Using `Tag::identifier()` for `d` tag vs `Tag::custom()` for others | ||
| 126 | - **npub conversion:** Converting public key to bech32 format for maintainers tag | ||
| 127 | - **Comprehensive verification:** Checking all three required tags are present in stored event | ||
| 128 | - **Specific git ref format:** Using proper git reference format `refs/heads/main` | ||
| 129 | |||
| 130 | ### What to Avoid | ||
| 131 | |||
| 132 | - Don't use content field for state announcements - keep it empty | ||
| 133 | - Don't confuse kind 30617 tags (`clone`, `relays`) with kind 30618 tags (`d`, `maintainers`, `r`) | ||
| 134 | - Don't use raw public key hex - convert to npub for maintainers tag | ||
| 135 | - Don't use shorthand ref names like "main" - use full format `refs/heads/main` | ||
| 136 | |||
| 137 | ### Pattern to Follow | ||
| 138 | |||
| 139 | ```rust | ||
| 140 | // Create kind 30618 repository state announcement | ||
| 141 | let repo_id = format!("test-repo-state-{}", timestamp); | ||
| 142 | let npub = client.public_key().to_bech32()?; | ||
| 143 | |||
| 144 | let event = client.event_builder(Kind::Custom(30618), "") | ||
| 145 | .tag(Tag::identifier(&repo_id)) // d tag for repo identifier | ||
| 146 | .tag(Tag::custom(TagKind::custom("maintainers"), vec![npub])) | ||
| 147 | .tag(Tag::custom(TagKind::custom("r"), vec!["refs/heads/main".to_string()])) | ||
| 148 | .build(client.keys())?; | ||
| 149 | |||
| 150 | // Publish and verify acceptance | ||
| 151 | client.send_event(event.clone()).await?; | ||
| 152 | |||
| 153 | // Query using kind, author, and identifier | ||
| 154 | let filter = Filter::new() | ||
| 155 | .kind(Kind::Custom(30618)) | ||
| 156 | .author(client.public_key()) | ||
| 157 | .identifier(&repo_id); | ||
| 158 | |||
| 159 | let events = client.query(filter).await?; | ||
| 160 | ``` | ||
| 161 | |||
| 162 | ### Test Implementation Time | ||
| 163 | |||
| 164 | - Analysis: ~8 minutes (understanding kind 30618 vs 30617 differences) | ||
| 165 | - Implementation: ~12 minutes (new pattern, different tags) | ||
| 166 | - Testing: ~3 minutes (first run, verification) | ||
| 167 | - Total: ~23 minutes | ||
| 168 | |||
| 169 | ### Next Test Recommendation | ||
| 170 | |||
| 171 | Continue with `test_accept_state_announcement_multiple_refs` - straightforward extension of this test, just add more `r` tags for different git refs (branches, tags). | ||
| 172 | |||
| 173 | --- | ||
| 174 | |||
| 175 | ## Template for Future Entries | ||
| 176 | |||
| 177 | ```markdown | ||
| 178 | ## Test #N: test_name_here | ||
| 179 | |||
| 180 | **Date:** YYYY-MM-DD | ||
| 181 | **Test Duration:** XXms | ||
| 182 | **Status:** ✅ PASSED / ⚠️ PARTIAL / ❌ FAILED | ||
| 183 | **Port Used:** XXXXX | ||
| 184 | |||
| 185 | ### Test Purpose | ||
| 186 | |||
| 187 | Brief description of what this test validates from GRASP-01 spec. | ||
| 188 | |||
| 189 | ### Key Learnings | ||
| 190 | |||
| 191 | 1. **Learning Category** | ||
| 192 | - Specific insight | ||
| 193 | - Why it matters | ||
| 194 | - How to apply it | ||
| 195 | |||
| 196 | ### What Worked Well | ||
| 197 | |||
| 198 | - Bullet points of successful approaches | ||
| 199 | |||
| 200 | ### What to Avoid | ||
| 201 | |||
| 202 | - Bullet points of pitfalls encountered | ||
| 203 | |||
| 204 | ### Pattern to Follow | ||
| 205 | |||
| 206 | ```rust | ||
| 207 | // Code example if applicable | ||
| 208 | ``` | ||
| 209 | |||
| 210 | ### Test Implementation Time | ||
| 211 | |||
| 212 | Breakdown of time spent on different phases | ||
| 213 | |||
| 214 | ### Next Test Recommendation | ||
| 215 | |||
| 216 | What test should come next and why | ||
| 217 | ``` | ||
| 218 | |||
| 219 | --- | ||
| 220 | |||
| 221 | ## Summary Statistics | ||
| 222 | |||
| 223 | **Tests Completed:** 3 rejection/validation tests | ||
| 224 | **Average Test Duration:** ~46ms | ||
| 225 | **Success Rate:** 100% | ||
| 226 | **Pattern Reuse Rate:** High (tests 2-3 followed same pattern) | ||
| 227 | |||
| 228 | **Most Valuable Pattern:** Following existing test structure for similar test types \ No newline at end of file | ||