From e6c056023bac4a83930b9c40f4a9513c3680cb67 Mon Sep 17 00:00:00 2001 From: DanConwayDev Date: Mon, 1 Dec 2025 23:21:20 +0000 Subject: better fixtures: update readme --- grasp-audit/README.md | 60 ++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 48 insertions(+), 12 deletions(-) diff --git a/grasp-audit/README.md b/grasp-audit/README.md index 2f4387c..2f07326 100644 --- a/grasp-audit/README.md +++ b/grasp-audit/README.md @@ -242,7 +242,7 @@ pub async fn test_something(client: &AuditClient) -> TestResult { │ Create TestContext, get fixtures, build scenarios, verify │ ├─────────────────────────────────────────────────────────────────┤ │ Layer 2: FixtureKind + TestContext │ -│ ValidRepo, RepoState, MaintainerState, etc. │ +│ ValidRepo, RepoState, OwnerStateDataPushed, etc. │ │ Mode-aware caching within TestContext │ ├─────────────────────────────────────────────────────────────────┤ │ Layer 1: AuditClient │ @@ -252,24 +252,60 @@ pub async fn test_something(client: &AuditClient) -> TestResult { ### Available Fixtures -| FixtureKind | Provides | Use When | -| ------------------------------------ | --------------------------------------- | ------------------------------------- | -| `ValidRepo` | Accepted repo announcement (kind 30617) | Need a repo as prerequisite | -| `RepoState` | Repo + state event (kind 30618) | Testing owner push authorization | -| `RepoWithIssue` | Repo + accepted issue (kind 1621) | Testing issue-dependent events | -| `RepoWithComment` | Repo + issue + comment | Testing comment-dependent events | -| `MaintainerStateDataPushed` | Full maintainer push with git data | Testing maintainer push authorization | -| `RecursiveMaintainerStateDataPushed` | Full recursive maintainer push | Testing recursive maintainer chain | +| FixtureKind | Provides | Use When | +| ----------- | -------- | -------- | +| `ValidRepo` | Accepted repo announcement (kind 30617). Signed by owner keys, lists maintainer in maintainers tag. | Need a repo as prerequisite | +| `RepoWithIssue` | Repo + accepted issue (kind 1621) | Testing issue-dependent events | +| `RepoWithComment` | Repo + issue + comment (kind 1111) | Testing comment-dependent events | +| `RepoState` | Repo + state event (kind 30618). Signed by owner, points to `DETERMINISTIC_COMMIT_HASH`. | Testing owner state events | +| `PREvent` | Repo + PR event (kind 1618). Signed by PR author, points to `PR_TEST_COMMIT_HASH`. | Testing PR-dependent events | +| `PREventGenerated` | PR event built but NOT sent to relay. | Need PR event ID before publishing | +| `PRWrongCommitPushedBeforeEvent` | Wrong commit pushed to `refs/nostr/` before PR event sent. Returns unsent PR event. | Testing pre-event ref cleanup | +| `PREventSentAfterWrongPush` | PR event sent after wrong commit was pushed. Tests cleanup behavior. | Testing post-event ref cleanup | +| `OwnerStateDataPushed` | Full owner push flow: state event + git data pushed. Points to `DETERMINISTIC_COMMIT_HASH`. | Testing owner push authorization | +| `MaintainerStateDataPushed` | Full maintainer push flow: force-pushes over owner's data. Points to `MAINTAINER_DETERMINISTIC_COMMIT_HASH`. | Testing maintainer push authorization | +| `RecursiveMaintainerStateDataPushed` | Full recursive maintainer push flow: Owner → Maintainer → RecursiveMaintainer chain. Points to `RECURSIVE_MAINTAINER_DETERMINISTIC_COMMIT_HASH`. | Testing recursive maintainer authorization | +| `HeadSetToDevelopBranch` | State event with HEAD=refs/heads/develop. Depends on RecursiveMaintainerStateDataPushed. | Testing HEAD branch switching | -### Fixture Lifecycle: Generate → Send → Verify +### Deterministic Commit Hashes -Every fixture follows a 3-step lifecycle: +Fixtures use deterministic commit hashes for reproducible testing: + +| Constant | Hash | Used By | +| -------- | ---- | ------- | +| `DETERMINISTIC_COMMIT_HASH` | `64ea71d79a57a7acb334cd9651f8aec067c0ce5d` | Owner fixtures (RepoState, OwnerStateDataPushed) | +| `MAINTAINER_DETERMINISTIC_COMMIT_HASH` | `1c2d472c9b71ed51968a66500281a3c4a6840464` | MaintainerStateDataPushed | +| `RECURSIVE_MAINTAINER_DETERMINISTIC_COMMIT_HASH` | `05939b82de66fbdb9c077d0a64fc68522f3cb8e0` | RecursiveMaintainerStateDataPushed | +| `PR_TEST_COMMIT_HASH` | `5d40fb1555a0c28bf4d650515a73aaa54d4d9bfb` | PR fixtures (PREvent, PREventGenerated) | + +### Fixture Dependencies + +Fixtures automatically resolve their dependencies: + +``` +ValidRepo (base) +├── RepoWithIssue → RepoWithComment +├── RepoState +├── PREventGenerated → PRWrongCommitPushedBeforeEvent → PREventSentAfterWrongPush +├── PREvent +└── OwnerStateDataPushed + └── MaintainerStateDataPushed + └── RecursiveMaintainerStateDataPushed + └── HeadSetToDevelopBranch +``` + +### Fixture Lifecycle: Generate → Send → Verify → DataPushed + +Every fixture follows a lifecycle (some stop earlier): 1. **GENERATE**: Build event via `AuditClient.event_builder()` (in memory only) 2. **SEND**: `client.send_event(event)` transmits to relay (rate-limited operation) 3. **VERIFY**: Query relay to confirm acceptance/rejection +4. **DATA_PUSHED**: (DataPushed variants only) Clone repo, create commit, push to git server + +Caching happens after the fixture completes - same fixture request returns cached Event. -Caching happens after SEND succeeds - same fixture request returns cached Event. +**Note:** Some fixtures handle their own event sending (e.g., `OwnerStateDataPushed`, `MaintainerStateDataPushed`). These are marked with `sends_own_events() -> true`. ### How TestContext Correlates Events -- cgit v1.2.3