An easy-to-host PDS on the ATProtocol, iPhone and MacOS. Maintain control of your keys and data, always.
docs: add human test plan for claim flow frontend
+221
+221
docs/test-plans/2026-03-28-plc-key-management-phase5.md
+221
docs/test-plans/2026-03-28-plc-key-management-phase5.md
···
1
+
# Human Test Plan: Claim Flow Frontend (Import Screens + Multi-Identity)
2
+
3
+
**Implementation plan:** `docs/implementation-plans/2026-03-28-plc-key-management/` (phases 1-5)
4
+
**Generated:** 2026-03-29
5
+
6
+
## Prerequisites
7
+
8
+
- macOS with Xcode installed (latest stable)
9
+
- iOS Simulator available (iPhone target)
10
+
- Nix dev shell active from workspace root: `nix develop --impure --accept-flake-config`
11
+
- Frontend dependencies installed: `cd apps/identity-wallet && pnpm install`
12
+
- Xcode project generated: `cargo tauri ios init` (with PATH patch and sandbox disabling per `apps/identity-wallet/CLAUDE.md`)
13
+
- TypeScript types compiling: `cd apps/identity-wallet && pnpm check`
14
+
- Rust compiling: `cargo build -p identity-wallet --lib`
15
+
- An existing AT Protocol identity on a reachable PDS (e.g., a Bluesky account) for the import flow
16
+
- Access to the email address associated with that identity (for the verification code)
17
+
- App launched via `cd apps/identity-wallet && cargo tauri ios dev`
18
+
19
+
---
20
+
21
+
## Phase 1: Mode Selector and Identity-Aware Routing
22
+
23
+
| Step | Action | Expected |
24
+
|------|--------|----------|
25
+
| 1 | Reset the iOS Simulator: Device > Erase All Content and Settings | Simulator is clean; no Keychain entries |
26
+
| 2 | Launch the app via `cd apps/identity-wallet && cargo tauri ios dev` | App compiles and opens in the Simulator |
27
+
| 3 | Observe the first screen | The mode selector screen is displayed (NOT the relay config screen). Heading reads "Identity Wallet" with tagline "Your self-sovereign identity, in your pocket." |
28
+
| 4 | Verify two buttons are visible | "Create new identity" button (primary/prominent styling) and "I have an identity" button (secondary styling) are both visible |
29
+
| 5 | Tap each button area to confirm interactivity | Both buttons respond to taps (visual feedback on press); neither is disabled or grayed out |
30
+
31
+
**Covers:** plc-key-management.AC5.1
32
+
33
+
---
34
+
35
+
## Phase 2: Identity Input and Resolution
36
+
37
+
| Step | Action | Expected |
38
+
|------|--------|----------|
39
+
| 1 | From the mode selector, tap "I have an identity" | Identity input screen appears with: a text input field, a "Resolve" button, and a "Back" button |
40
+
| 2 | Enter a handle that does not exist: `this-handle-definitely-does-not-exist-12345.test` | Text appears in the input field |
41
+
| 3 | Tap "Resolve" | A loading indicator appears briefly |
42
+
| 4 | Observe the screen after loading | Inline error message: "Handle not found. Check the spelling and try again." The user remains on the identity input screen. No "Continue" button is visible |
43
+
| 5 | Clear the text input completely | Input field is empty |
44
+
| 6 | Enter your valid AT Protocol handle (e.g., `yourname.bsky.social`) | Handle text appears in the input field |
45
+
| 7 | Tap "Resolve" | A loading indicator appears while resolution is in progress |
46
+
| 8 | Observe the resolved identity card | Card displays: Handle (e.g., `@yourname.bsky.social`), DID (truncated `did:plc:...`), PDS URL (e.g., `https://morel.us-east.host.bsky.network`), Rotation key status (either "Your device is the root key" in green or "Device key is not the root key" in neutral styling) |
47
+
| 9 | Verify "Continue" button appeared | A "Continue" button is visible below the identity card |
48
+
| 10 | Verify error message cleared | The previous "Handle not found" error is no longer displayed |
49
+
| 11 | Tap "Back" | Navigation returns to the mode selector screen with both buttons visible |
50
+
51
+
**Covers:** plc-key-management.AC5.3, plc-key-management.AC5.4
52
+
53
+
---
54
+
55
+
## Phase 3: PDS Authentication and Email Verification
56
+
57
+
| Step | Action | Expected |
58
+
|------|--------|----------|
59
+
| 1 | From mode selector, tap "I have an identity", enter your valid handle, tap "Resolve", then tap "Continue" | PDS auth screen appears showing the PDS URL and an "Authenticate with PDS" button. A "Back" button is visible |
60
+
| 2 | Tap "Authenticate with PDS" | A spinner appears with text "Opening browser for PDS authentication..." then Safari opens with the PDS OAuth authorization page |
61
+
| 3 | Complete the OAuth authorization in Safari (approve the request) | Safari redirects back to the app via deep link. The app advances to the email verification screen |
62
+
| 4 | Observe the email verification screen on mount | A spinner appears with "Sending verification email..." |
63
+
| 5 | Wait for the email sending to complete | The screen shows: instruction text ("A verification code has been sent to your email..."), a text input for the token, and a "Verify" button |
64
+
| 6 | Enter an invalid token: `000000` | Text appears in the token input |
65
+
| 7 | Tap "Verify" | An inline error message appears: "Invalid or expired verification code. Check your email and try again." The user remains on the email verification screen. The token input is still editable |
66
+
| 8 | Clear the input and enter the correct verification code from your email | Correct code is in the input field |
67
+
| 9 | Tap "Verify" | The error clears. A loading state appears. On success, the app navigates to the review operation screen |
68
+
69
+
**Covers:** plc-key-management.AC5.5, plc-key-management.AC5.6, plc-key-management.AC5.7
70
+
71
+
---
72
+
73
+
## Phase 4: Review Operation and Claim Submission
74
+
75
+
| Step | Action | Expected |
76
+
|------|--------|----------|
77
+
| 1 | Observe the review operation screen | The screen displays: **Keys section** showing keys being added (green, `+` prefix) and/or keys being removed (red, `-` prefix), or "No key changes". **Services section** showing service changes or "No service changes" |
78
+
| 2 | Verify key display formatting | Key values are in monospace font, truncated for mobile (first 20 characters + "...") |
79
+
| 3 | Verify color coding | Added items use green (`#22c55e`), removed items use red (`#ef4444`), modified items use amber (`#f59e0b`) |
80
+
| 4 | Verify buttons at bottom | "Confirm & Submit" (primary) and "Cancel" (secondary) buttons are visible |
81
+
| 5a | **If warnings are present:** observe warning display | Warning messages appear in amber/yellow highlighted boxes. "Confirm & Submit" button is disabled (grayed out). A checkbox appears: "I understand these warnings and want to proceed" |
82
+
| 5b | **If warnings present:** tap the acknowledgment checkbox | "Confirm & Submit" button becomes enabled/tappable |
83
+
| 5c | **If warnings present:** untap the checkbox | Button becomes disabled again |
84
+
| 5d | **If warnings present:** re-tap checkbox to enable, then tap "Confirm & Submit" | Submission proceeds (see step 6) |
85
+
| 5e | **If no warnings:** verify no warning section or checkbox is shown | "Confirm & Submit" button is enabled by default |
86
+
| 6 | Tap "Confirm & Submit" (with checkbox acknowledged if warnings present) | A loading state appears |
87
+
| 7 | Observe the claim success screen | Screen shows: green checkmark icon/circle, heading "Identity Claimed Successfully", description text about rotation key control, DID document summary card showing DID, handle, and PDS endpoint |
88
+
| 8 | Verify "Done" button | A "Done" button is visible |
89
+
| 9 | Tap "Done" | App navigates to the home screen (IdentityListHome). The claimed identity appears as a card on the home screen |
90
+
91
+
**Covers:** plc-key-management.AC5.8, plc-key-management.AC5.9, plc-key-management.AC5.10
92
+
93
+
---
94
+
95
+
## Phase 5: Multi-Identity Home and Add Identity
96
+
97
+
| Step | Action | Expected |
98
+
|------|--------|----------|
99
+
| 1 | Observe the home screen after completing the import flow | IdentityListHome displays one identity card |
100
+
| 2 | Verify identity card content | Card shows: DID avatar (colored circle), handle (e.g., `@yourname.bsky.social`) or "Unknown handle", truncated DID, PDS endpoint |
101
+
| 3 | Verify rotation key status badge on the card | Green "Root Key" badge if device key is `rotationKeys[0]`, amber "Not Root" if not primary, or gray "Unknown" if undetermined |
102
+
| 4 | Tap the identity card | Navigates to identity detail view (DIDDocumentScreen) showing the full DID document |
103
+
| 5 | Tap "Back" on detail view | Returns to the home screen |
104
+
| 6 | Verify "Add Identity" button | An "Add Identity" button is visible at the bottom of the identity list |
105
+
| 7 | Tap "Add Identity" | The mode selector screen appears with both "Create new identity" and "I have an identity" options |
106
+
107
+
**Covers:** plc-key-management.AC5.11, plc-key-management.AC5.12
108
+
109
+
---
110
+
111
+
## Phase 6: Returning User and Onboarding Regression
112
+
113
+
### AC5.2 -- Returning user skips mode selector
114
+
115
+
| Step | Action | Expected |
116
+
|------|--------|----------|
117
+
| 1 | From the home screen with at least one identity claimed (from Phase 4) | Home screen is visible |
118
+
| 2 | Force-quit the app (swipe up from app switcher, or stop the dev server) | App is terminated |
119
+
| 3 | Relaunch the app via `cargo tauri ios dev` | App opens. The mode selector does NOT appear. The home screen (IdentityListHome) is displayed directly with the previously claimed identity card(s) |
120
+
121
+
**Covers:** plc-key-management.AC5.2
122
+
123
+
### AC5.13 -- Onboarding regression
124
+
125
+
| Step | Action | Expected |
126
+
|------|--------|----------|
127
+
| 1 | Reset the iOS Simulator (Erase All Content and Settings) | Clean state |
128
+
| 2 | Launch the app via `cargo tauri ios dev` | Mode selector screen appears |
129
+
| 3 | Tap "Create new identity" | Relay config screen appears (or is skipped if a relay URL is saved) |
130
+
| 4 | Enter a valid relay URL (e.g., `https://relay.ezpds.com` or `http://localhost:2583`) and tap Connect | Welcome screen appears with "Get Started" button |
131
+
| 5 | Proceed through the full onboarding flow: Welcome > Claim Code > Email > Handle > Password > Loading > DID Ceremony > DID Success > Shamir Backup > Handle Registration > Complete > Authenticating | Each screen renders correctly with proper inputs, buttons, and transitions |
132
+
| 6 | Observe the final screen | Onboarding completes; app arrives at IdentityListHome |
133
+
| 7 | Verify the identity card | The newly created identity appears as a card with correct handle and DID |
134
+
| 8 | Force-quit and relaunch the app | App opens directly to the home screen (mode selector skipped) |
135
+
136
+
**Covers:** plc-key-management.AC5.13
137
+
138
+
---
139
+
140
+
## End-to-End Scenarios
141
+
142
+
### E2E-1: First Launch Import Existing Identity
143
+
144
+
Validates the complete import flow from fresh install through claim submission to home screen.
145
+
146
+
| Step | Action | Expected |
147
+
|------|--------|----------|
148
+
| 1 | Reset the iOS Simulator | Simulator is clean |
149
+
| 2 | Launch the app | Mode selector appears with two options |
150
+
| 3 | Tap "I have an identity" | Identity input screen appears |
151
+
| 4 | Enter a valid handle and tap "Resolve" | Identity info card displays DID, handle, PDS, rotation key status |
152
+
| 5 | Tap "Continue" | PDS auth screen appears with PDS URL |
153
+
| 6 | Tap "Authenticate with PDS" | Safari opens for OAuth |
154
+
| 7 | Complete OAuth in Safari | App returns to email verification screen |
155
+
| 8 | Wait for "Sending verification email..." to complete | Token input form appears |
156
+
| 9 | Enter verification code from email, tap "Verify" | Review operation screen appears with diff |
157
+
| 10 | Tap "Confirm & Submit" (acknowledge warnings if present) | Claim success screen appears with DID doc summary |
158
+
| 11 | Tap "Done" | Home screen shows the claimed identity card with status badge |
159
+
160
+
### E2E-2: Multiple Identities (Create Then Import)
161
+
162
+
Validates that both identity creation paths coexist and multi-identity home correctly displays cards from different flows.
163
+
164
+
| Step | Action | Expected |
165
+
|------|--------|----------|
166
+
| 1 | Reset the iOS Simulator | Simulator is clean |
167
+
| 2 | Launch the app, tap "Create new identity" | Relay config screen appears |
168
+
| 3 | Complete full onboarding (relay config through auth) | Home screen shows one identity card |
169
+
| 4 | Tap "Add Identity" button | Mode selector appears |
170
+
| 5 | Tap "I have an identity" | Identity input screen appears |
171
+
| 6 | Complete import flow (resolve handle, PDS auth, email verification, review, submit) | Claim success screen appears |
172
+
| 7 | Tap "Done" | Home screen shows two identity cards with status badges |
173
+
| 8 | Force-quit and relaunch | Home screen appears directly with both cards |
174
+
175
+
### E2E-3: Import Flow Error Recovery
176
+
177
+
Validates that all error states in the import flow are recoverable.
178
+
179
+
| Step | Action | Expected |
180
+
|------|--------|----------|
181
+
| 1 | From mode selector, tap "I have an identity" | Identity input screen appears |
182
+
| 2 | Enter an invalid handle (`this-handle-definitely-does-not-exist-12345.test`), tap "Resolve" | Inline error: "Handle not found. Check the spelling and try again." |
183
+
| 3 | Clear input, enter a valid handle, tap "Resolve" | Identity card appears; error clears |
184
+
| 4 | Tap "Continue", then tap "Authenticate with PDS" | Safari opens |
185
+
| 5 | Cancel or deny OAuth in Safari | Error message on PDS auth screen |
186
+
| 6 | Tap "Authenticate with PDS" again | Safari reopens for retry |
187
+
| 7 | Complete OAuth successfully | Email verification screen appears |
188
+
| 8 | Enter wrong verification code (`000000`), tap "Verify" | Inline error: "Invalid or expired verification code. Check your email and try again." |
189
+
| 9 | Enter correct code, tap "Verify" | Review operation screen appears; error clears |
190
+
| 10 | Tap "Cancel" on review screen | Returns to identity input screen |
191
+
192
+
### E2E-4: Returning User Skips Mode Selector
193
+
194
+
Validates that Keychain-persisted identity state survives app restart.
195
+
196
+
| Step | Action | Expected |
197
+
|------|--------|----------|
198
+
| 1 | Complete E2E-1 (at least one identity claimed) | Home screen visible |
199
+
| 2 | Force-quit the app completely | App terminated |
200
+
| 3 | Relaunch the app | Home screen appears directly (mode selector skipped) |
201
+
| 4 | Verify identity cards are displayed | All previously claimed identities shown with correct data |
202
+
203
+
---
204
+
205
+
## Traceability
206
+
207
+
| Acceptance Criterion | Automated Test | Manual Step |
208
+
|----------------------|----------------|-------------|
209
+
| plc-key-management.AC5.1 | -- | Phase 1: Mode selector with two buttons on fresh launch |
210
+
| plc-key-management.AC5.2 | `IdentityStore::list_identities()` tests | Phase 6: Relaunch with existing identities skips to home |
211
+
| plc-key-management.AC5.3 | `resolve_identity()` tests | Phase 2: Enter handle, tap Resolve, verify identity card |
212
+
| plc-key-management.AC5.4 | `resolve_identity()` error path tests | Phase 2: Enter bad handle, verify inline error |
213
+
| plc-key-management.AC5.5 | `start_pds_auth()` tests | Phase 3: Tap Authenticate, verify Safari opens, complete OAuth |
214
+
| plc-key-management.AC5.6 | `sign_and_verify_claim()` tests | Phase 3: Enter correct token, verify flow advances |
215
+
| plc-key-management.AC5.7 | `sign_and_verify_claim()` INVALID_TOKEN test | Phase 3: Enter wrong token, verify inline error |
216
+
| plc-key-management.AC5.8 | -- | Phase 4: Inspect diff display with color coding |
217
+
| plc-key-management.AC5.9 | -- | Phase 4: Verify button disabled with warnings, checkbox enables it |
218
+
| plc-key-management.AC5.10 | `submit_claim()` tests | Phase 4: Verify success screen content, tap Done |
219
+
| plc-key-management.AC5.11 | `get_did_doc()` + `get_or_create_device_key()` tests | Phase 5: Verify multi-identity cards with status badges |
220
+
| plc-key-management.AC5.12 | -- | Phase 5: Tap "Add Identity", verify mode selector appears |
221
+
| plc-key-management.AC5.13 | -- | Phase 6: Full onboarding regression |