AGENTS.md

1# Scripts
2 
3## e2e-share.sh
4 
5End-to-end integration tests for the crit CLI to crit-web share flow. Tests the full round-trip: sharing reviews, fetching web comments, re-sharing without duplicates, and unpublishing.
6 
7### Prerequisites
8 
9- A local crit-web checkout as a sibling directory (`../crit-web` relative to the crit repo root, or set `CRIT_WEB_DIR`)
10- PostgreSQL running locally (the script creates a `crit_e2e` database)
11- mise (for Go and Elixir toolchain management)
12 
13### Usage
14 
15```bash
16# Full run: build crit, start crit-web on :4001, run tests, tear down
17make e2e-share
18# or directly:
19./scripts/e2e-share.sh
20 
21# Start crit-web for manual testing (Ctrl+C to stop)
22./scripts/e2e-share.sh --serve
23 
24# Run tests against an already-running crit-web
25./scripts/e2e-share.sh --skip-web
26 
27# Run a specific test
28./scripts/e2e-share.sh -run TestShareSyncFullLifecycle
29```
30 
31### Environment variables
32 
33| Variable | Default | Description |
34|---|---|---|
35| `CRIT_WEB_PORT` | `4001` | Port for the test crit-web instance |
36| `CRIT_WEB_DIR` | `../crit-web` | Path to crit-web checkout |
37| `DB_NAME` | `crit_e2e` | PostgreSQL database name (separate from dev) |
38 
39### What the script does
40 
411. Builds crit via `make build`
422. Creates/resets the `crit_e2e` database
433. Starts crit-web with `SELFHOSTED=true` on the test port (no OAuth)
444. Waits for `GET /health` to return 200
455. Runs all `TestShareSync*` integration tests with `CRIT_AUTH_TOKEN=""` to bypass any local auth config
466. Tears down crit-web on exit
47 
48### Test file: `share_integration_test.go`
49 
50Build tag: `//go:build integration` — these tests are excluded from `go test ./...` and only run via `go test -tags integration`.
51 
52Tests use `--output <dir>` to write `.crit.json` to a temp directory (not `~/.crit/reviews/`), and `--share-url` to point at the local crit-web instance.
53 
54Every test logs its review URL (`t.Logf("  -> Review: ...")`) so you can open them in a browser for visual inspection. Reviews persist on crit-web after tests run (except the unpublish test).
55 
56#### Test cases
57 
58| Test | What it covers |
59|---|---|
60| `TestShareSyncIntegration` | Original: share, seed web comment, re-share, verify content + export |
61| `TestShareSyncNoComments` | Share with zero comments, verify document on web |
62| `TestShareSyncLineComments` | Line-scoped comments: body, position, scope verified on web |
63| `TestShareSyncFileComment` | File-scoped comment: body, scope, file_path verified on web |
64| `TestShareSyncReviewLevelComments` | Review-level comments shared (tests #297 fix for CLI path) |
65| `TestShareSyncMixedCommentTypes` | All 3 scopes together, each verified on web |
66| `TestShareSyncResolvedExcluded` | Resolved comments filtered out of share payload |
67| `TestShareSyncReshareNoDuplicates` | Re-share preserves comments without duplication |
68| `TestShareSyncReshareNoChanges` | No-op when content unchanged (round stays same) |
69| `TestShareSyncFetchWebComments` | Web-authored comments pulled into local .crit.json |
70| `TestShareSyncFetchWebCommentsNoDuplicates` | Repeated syncs don't duplicate web comments |
71| `TestShareSyncMultipleFiles` | Multi-file share with per-file comment association |
72| `TestShareSyncMultipleRounds` | Round progression across 3 share cycles, content verified |
73| `TestShareSyncCommentWithReplies` | Threaded replies included in share |
74| `TestShareSyncUnpublish` | Full unpublish: web deletion + local state cleared |
75| `TestShareSyncExport` | Export endpoint returns .crit.json-compatible shape |
76| `TestShareSyncFetchReviewLevelWebComment` | Review-level web comments merged into local ReviewComments |
77| `TestShareSyncFullLifecycle` | Complete round-trip: local comments with threads, share, web comments added, fetch, re-share (preserved), fetch again (no duplicates) |
78 
79#### Adding new tests
80 
81- Name test functions `TestShareSync*` so they're picked up by the `-run TestShareSync` filter
82- Use the helpers: `critShareCmd`, `critUnpublishCmd`, `writeTestCritJSON`, `readCritJSON`, `commentsFromAPI`, `documentFromAPI`, `seedComment`, `seedCommentAt`, `seedReviewComment`, `logReview`, `extractToken`
83- Always call `logReview(t, output)` after sharing so the URL is visible in test output
84- Use `writeTestCritJSON` (not `writeCritJSON` — that name conflicts with `github.go`)
85 
86## e2e-roundtrip.sh and e2e-gitlab-roundtrip.sh
87 
88These are the provider-specific runners for one live roundtrip suite in `internal/session`. GitHub uses the `e2e_github` tag, `CRIT_ROUNDTRIP_REPO`, and authenticated `gh`; GitLab uses the `e2e_gitlab` tag, `CRIT_GITLAB_ROUNDTRIP_PROJECT`, and authenticated `glab` (plus optional `CRIT_GITLAB_ROUNDTRIP_HOST` for self-managed instances). Both create and clean up a temporary change request and branch. See `test/roundtrip/README.md` for shared setup and authoring guidance.
89