A community based topic aggregation platform built on atproto
bretton.dev
1# End-to-End Testing Guide
2
3## Overview
4
5Coves supports full E2E testing with a local atProto stack:
6
7```
8Third-party Client → Coves XRPC → PDS → Jetstream → Coves AppView → PostgreSQL
9```
10
11**Why Jetstream?**
12- PDS emits raw CBOR-encoded firehose (binary, hard to parse)
13- Jetstream converts CBOR → clean JSON (same format as production)
14- Tests exactly match production behavior
15
16---
17
18## Quick Start
19
20### 1. Start Development Stack
21
22```bash
23make dev-up
24```
25
26This starts:
27- **PostgreSQL** (port 5433) - Coves database
28- **PDS** (port 3001) - Local atProto server
29- **Jetstream** (port 6008) - CBOR → JSON converter (always runs for read-forward)
30
31> **Note:** Jetstream is now part of `dev-up` since read-forward architecture requires it
32
33### 2. Start AppView
34
35```bash
36# In another terminal
37make run # Starts AppView (auto-runs migrations)
38```
39
40AppView will connect to `ws://localhost:6008/subscribe` (configured in `.env.dev`)
41
42### 3. Run Automated E2E Tests
43
44```bash
45make e2e-test
46```
47
48This runs the full test suite:
49- Creates accounts via XRPC endpoint
50- Verifies PDS account creation
51- Validates Jetstream indexing
52- Confirms database storage
53
54### 4. Manual Testing (Optional)
55
56#### Create User via Coves XRPC
57
58```bash
59curl -X POST http://localhost:8081/xrpc/social.coves.actor.signup \
60 -H "Content-Type: application/json" \
61 -d '{
62 "handle": "alice.local.coves.dev",
63 "email": "alice@test.com",
64 "password": "test1234"
65 }'
66```
67
68**Response:**
69```json
70{
71 "did": "did:plc:xyz123...",
72 "handle": "alice.local.coves.dev",
73 "accessJwt": "eyJ...",
74 "refreshJwt": "eyJ..."
75}
76```
77
78**What happens:**
791. Coves XRPC handler receives signup request
802. Calls PDS `com.atproto.server.createAccount`
813. PDS creates account → emits to firehose
824. Jetstream converts event → JSON
835. AppView receives JSON → indexes user
846. User appears in PostgreSQL `users` table
85
86### 5. Verify Indexing
87
88Check AppView logs:
89```
902025/01/15 12:00:00 Identity event: did:plc:xyz123 → alice.local.coves.dev
912025/01/15 12:00:00 Indexed new user: alice.local.coves.dev (did:plc:xyz123)
92```
93
94Query via API:
95```bash
96curl "http://localhost:8081/xrpc/social.coves.actor.getprofile?actor=alice.local.coves.dev"
97```
98
99Expected response:
100```json
101{
102 "did": "did:plc:xyz123...",
103 "profile": {
104 "handle": "alice.local.coves.dev",
105 "createdAt": "2025-01-15T12:00:00Z"
106 }
107}
108```
109
110---
111
112## Workflow Summary
113
114### Daily Development
115```bash
116make dev-up # Start PDS + PostgreSQL + Jetstream (once)
117make run # Start AppView (in another terminal)
118make test # Run fast tests during development
119```
120
121### Before Commits/PRs
122```bash
123make e2e-test # Run full E2E test suite
124```
125
126### Reset Everything
127```bash
128make dev-reset # Nuclear option - deletes all data
129make dev-up # Start fresh
130```
131
132---
133
134## Testing Scenarios
135
136### Automated E2E Test Suite
137
138```bash
139make e2e-test
140```
141
142This tests:
143- ✅ Single account creation via XRPC
144- ✅ Idempotent duplicate event handling
145- ✅ Multiple concurrent user indexing
146
147### Manual: User Registration via XRPC
148
149```bash
150curl -X POST http://localhost:8081/xrpc/social.coves.actor.signup \
151 -H "Content-Type: application/json" \
152 -d '{"handle":"bob.local.coves.dev","email":"bob@test.com","password":"pass1234"}'
153```
154
155### Manual: Federated User (Direct PDS)
156
157```bash
158# Simulates a user on another PDS
159curl -X POST http://localhost:3001/xrpc/com.atproto.server.createAccount \
160 -H "Content-Type: application/json" \
161 -d '{"handle":"charlie.local.coves.dev","email":"charlie@test.com","password":"pass1234"}'
162
163# Coves AppView will still index via Jetstream (read-forward)
164```
165
166---
167
168## Next Steps
169
1701. ✅ E2E testing infrastructure complete
1712. ✅ Automated E2E test suite implemented
1723. ✅ XRPC signup endpoint for third-party clients
1734. 🔨 TODO: Add handle update support
1745. 🔨 TODO: Add CI/CD E2E tests