ui/_docs/02_document/tests/resilience-tests.md

Resilience Tests

Failure / recovery scenarios at the SPA's observable boundary: bearer expiry, refresh cookie loss, upstream 5xx, network partition, oversized uploads, SSE drop. Every fault injection is at the network / browser layer; the UI is observed for graceful behavior and recovery.

NFT-RES-01: 401 → refresh → retry recovery is transparent

Summary: An authenticated request that returns 401 mid-session is refreshed and retried without unmounting the routed view. Traces to: AC-01, AC-23

Preconditions:

• Active session on /flights.

Fault injection:

• Force a 401 on the next outbound authenticated request.

Steps:

Step	Action	Expected Behavior
1	Stub the next request to return 401 once	first response 401
2	Observe the SPA's reaction	POST /api/admin/auth/refresh with credentials:'include'; on 200, original request retried with new bearer
3	Inspect <ProtectedRoute> children	not unmounted; re-render delta ≤ 1

Pass criteria: row 03 sequence; row 11 re-render bound (≤ 1); row 12 refresh count == 1 — all hold simultaneously. Expected result source: results_report.md rows 03, 11, 12.

---

NFT-RES-02: SSE bearer-rotation — both streams reconnect within 5 s

Summary: A bearer rotation during open SSE streams (live-GPS + annotation-status) tears them down and reopens them with the new token. Traces to: AC-24

Preconditions:

• Two EventSources open.

Fault injection:

• Trigger a server-driven rotation of the bearer (force a refresh).

Steps:

Step	Action	Expected Behavior
1	Rotate bearer	new token in memory
2	Observe each EventSource	closes, then reopens with new ?token=
3	Measure max reconnect time	≤ 5 000 ms

Pass criteria: both streams close+open exactly once; max reconnect ≤ 5 000 ms (results_report.md row 13). Status: quarantined until SSE reconnect-on-rotation ships (Step 8 hardening). Expected result source: results_report.md row 13.

---

NFT-RES-03: Network offline at boot — error state, no offline mode

Summary: With network disabled, app boot results in a user-visible error state — NOT a service worker-served cached UI. Traces to: AC-N3

Preconditions:

• Browser network disabled (or all /api/* stubs respond with offline error).

Fault injection:

• All outbound requests fail with net::ERR_INTERNET_DISCONNECTED (or equivalent).

Steps:

Step	Action	Expected Behavior
1	Load the SPA	static assets served by nginx OK; API calls fail
2	Observe DOM	login or general error surface present
3	Inspect navigator.serviceWorker.controller	null

Pass criteria: row 93 — error/login-failed state present; no service worker controller. Expected result source: results_report.md row 93.

---

NFT-RES-04: ProtectedRoute loading timeout fallback after 10 s

Summary: The <ProtectedRoute> spinner has a bounded loading window; a stalled auth bootstrap surfaces a retry CTA / error. Traces to: AC-17

Preconditions:

• Bootstrap refresh stubbed to never resolve.

Fault injection:

• POST /api/admin/auth/refresh hangs (no response).

Steps:

Step	Action	Expected Behavior
1	Mount <ProtectedRoute>	spinner rendered
2	Advance fake time to 10 s	timeout fires
3	Inspect DOM	retry CTA or error message present; spinner unmounted

Pass criteria: row 59 — fallback present, spinner absent. Status: quarantined until timeout fix lands (Step 4). Expected result source: results_report.md row 59.

---

NFT-RES-05: Settings save with upstream 500 — UI state recovers

Summary: A 500 on settings save surfaces an error and resets the saving flag. Traces to: AC-27

Preconditions:

• Form filled in valid state on /settings.

Fault injection:

• Upstream PUT /api/annotations/settings/system returns 500 after T ms.

Steps:

Step	Action	Expected Behavior
1	Click Save	PUT issued
2	Stub responds 500 within 2 s	failure
3	Inspect within 2 s	toast / inline error; saving === false; no route navigation

Pass criteria: row 68. Status: quarantined until Step 4 try/finally fix. Expected result source: results_report.md row 68.

---

NFT-RES-06: Settings save with network drop — try/finally state reset

Summary: When the underlying fetch throws (network drop), saving resets and the user sees an error. Traces to: AC-27

Preconditions:

• Form filled in valid state.

Fault injection:

• Network drop mid-PUT (fetch rejects).

Steps:

Step	Action	Expected Behavior
1	Click Save	PUT issued
2	Stub throws	rejection delivered
3	Inspect	saving === false; error surfaced

Pass criteria: row 69. Status: quarantined. Expected result source: results_report.md row 69.

---

NFT-RES-07: nginx 413 on oversized upload surfaces user-visible error

Summary: An upload that exceeds client_max_body_size 500M returns 413; the UI presents a user-facing message (no silent failure, no alert()). Traces to: AC-10

Preconditions:

• Authenticated; <MediaList> open.

Fault injection:

• Drop a 501 MB synthetic file.

Steps:

Step	Action	Expected Behavior
1	Upload 501 MB	upload starts
2	nginx rejects	413 delivered
3	Inspect UI	error containing the i18n "file too large" string; no alert() invoked

Pass criteria: row 39. Expected result source: results_report.md row 39.

---

NFT-RES-08: Refresh cookie expired — redirect to /login

Summary: When the refresh cookie is gone (or expired) and a 401 occurs, the SPA redirects the user to /login rather than silently looping refresh. Traces to: AC-01, AC-22

Preconditions:

• Cookie cleared from the browser jar.

Fault injection:

• 401 on any authenticated call; subsequent POST /api/admin/auth/refresh returns 401.

Steps:

Step	Action	Expected Behavior
1	Issue authenticated call	401
2	Refresh attempted	401 (no cookie)
3	Observe routing	redirect to /login

Pass criteria: final URL /login; no infinite refresh loop (single refresh attempt). Derived from AC-01 + AC-22; no specific results_report row binds the loop bound — Phase 3 flags this and the loop bound is added to row 03 if accepted.

---

NFT-RES-09: Annotation download tainted-canvas fallback

Summary: When <canvas>.toBlob() raises a tainted-canvas exception (cross-origin video frame), the user sees an error rather than a silent no-op. Traces to: NFR (04_verification_log.md finding on handleDownload tainted-canvas risk)

Preconditions:

• An annotation is loaded from a video sourced with CORS that taints the canvas.

Fault injection:

• Cross-origin video source taints the canvas; toBlob throws.

Steps:

Step	Action	Expected Behavior
1	Click Download	export attempted
2	toBlob throws	error handled
3	Inspect UI	user-visible error; no alert(); no silent swallow

Pass criteria: row 96 — error surfaced; no silent swallow; no fabricated blob; no alert(). Expected result source: results_report.md row 96.

---

NFT-RES-10: SSE server disconnect — UI surfaces a connection-lost indicator

Summary: When the suite server closes a live-GPS or status-events SSE without rotation, the UI does NOT show stale data and DOES indicate the connection lost. Traces to: AC-08, AC-09, AC-24

Preconditions:

• One SSE stream open.

Fault injection:

• Server force-closes the stream (no rotation).

Steps:

Step	Action	Expected Behavior
1	Drop the stream from the server	error fires on EventSource
2	Observe DOM	a connection-lost indicator is rendered (or stale-data badge)
3	Observe reconnect behavior	EventSource auto-retries per browser default; if the SPA re-creates it, exactly one new instance

Pass criteria: row 97 — connection-lost indicator OR reconnect attempt within 10 s; stale data NOT rendered as live; reconnect attempts ≤ 1 in the 10 s window. Expected result source: results_report.md row 97.

---

NFT-RES-11: Tile endpoint 401/503 does NOT crash the map

Summary: When the satellite-provider /tiles/{z}/{x}/{y} endpoint returns 401 (cookie-auth failure) or 503 (Google Maps upstream down), the SPA renders a broken-tile placeholder for the failing tile(s) and the rest of the application keeps working. No React error boundary fires; no full-page crash. Traces to: AC-41 (AZ-498 NFR-Reliability)

Preconditions:

• <FlightMap> mounted with a valid VITE_SATELLITE_TILE_URL.
• Tile endpoint configured to return 401 (auth failure) OR 503 (upstream provider down) for one or more tile coordinates.

Fault injection:

• (auth-failure variant) Strip / invalidate the satellite-provider auth cookie before the SPA attempts a tile fetch; tile endpoint responds 401.
• (upstream-down variant) Configure the test stub to return 503 for GET /tiles/{z}/{x}/{y}.

Steps:

Step	Action	Expected Behavior
1	Mount <FlightMap>; trigger a tile load that fails per the fault	Leaflet emits a tileerror event for the affected coordinate
2	Observe the rendered map	broken-tile placeholder shown in the failing cell; surrounding tiles continue rendering normally
3	Observe the rest of the SPA (header, side panels, navigation)	remains interactive; no React error boundary fires; no console error of category Uncaught
4	Observe a recovery path (auth restored OR upstream back)	next pan/zoom successfully fetches the tile; the placeholder is replaced with the imagery

Pass criteria:

• 401 response on a tile request MUST NOT crash the map; broken-tile placeholder rendered in the failing cell, rest of SPA interactive.
• 503 response treated identically to 404/transient failure (fault budget — recovery path works after the upstream returns).
• No new uncaught error in the console attributable to the failed tile.

Expected result source: AZ-498 NFR-Reliability (no results_report.md row needed — observable through DOM state and console). Note on follow-up: AZ-498 risk #5 flags an optional tileerror listener on <MapContainer> that surfaces a structured warning + an optional inline banner ("Imagery unavailable; please re-sign-in"). If/when that lands, this scenario gains a Step 5 asserting the banner appears within 2 s of the first tile error.