Test every loading, empty, and error state without clicking through your app. One was a blank page
Genie held a real customer screen in its loading, error, empty and Suspense states, then put it back. The forced fallback exposed a tab that blanks the whole page.
You force each state with one Genie call, read it with your driver's snapshot, and undo it with
query_restore_state or react_reset_overrides. On the customer screens of the dashboard demo, this
found one real bug. The loading state of the Recent orders tab is an empty page.
Every command and output below comes from one run of Genie 1.1.0 on 2026-11-19 against
apps/realworld-dashboard.
Snapshots are trimmed to the changed region. The
raw evidence
has every command in order with untrimmed output.
Sign in and pick a query
The app registers its own Genie tools, so you sign in without the form:
agent-browser --session upd-f open "http://127.0.0.1:5242/login"
npx genie-react call app_login_as --session upd-f '{"role":"manager"}'
agent-browser --session upd-f open "http://127.0.0.1:5242/customers"
npx genie-react call query_list --session upd-f '{}' --fields queryHash,status,observerCount[2]:
- {queryHash:"[\"customers\",\"list\",{\"page\":1,\"pageSize\":25,\"q\":\"\"}]",status:success,observerCount:1}
- {queryHash:"[\"notifications\"]",status:success,observerCount:1}The Customers page reads the first query. Its header says 1,200 accounts and Updated 8 seconds ago,
and the table shows 25 rows.
Loading
Hold the list query in pending:
npx genie-react call query_simulate_state --session upd-f \
'{"queryKey":["customers","list",{"page":1,"pageSize":25,"q":""}],"state":"pending"}'
agent-browser --session upd-f snapshot -c -s main- main
- sectionheader
- heading "Customers" [level=1, ref=e13]
- paragraph
- StaticText "Loading accounts…"
- StaticText "Not synced yet"
- button "Refresh customers" [ref=e14]
…
- status "Loading page"The table is gone and a spinner with the label "Loading page" replaces it. The header reads
"Loading accounts…" and "Not synced yet", as on a real first load. query_get shows why:
- {status:pending,fetchStatus:fetching,dataUpdatedAt:0,dataUpdateCount:0,simulatedState:pending}SyncStatus prints "Not synced yet" when updatedAt === 0, and the simulation sets
dataUpdatedAt to 0. Genie 1.0.2 kept the real dataUpdatedAt, so this header read "Updated 12
seconds ago" beside the spinner, and 1.1.0 fixed that.
Error
Switch the same query to error with a message of your choice:
npx genie-react call query_simulate_state --session upd-f \
'{"queryKey":["customers","list",{"page":1,"pageSize":25,"q":""}],"state":"error","errorMessage":"GET /api/customers failed with 503"}'
agent-browser --session upd-f snapshot -c -s main - paragraph
- StaticText "Loading accounts…"
- StaticText "Not synced yet"
…
- alert
- paragraph
- StaticText "Customers could not be loaded"
- paragraph
- StaticText "GET /api/customers failed with 503"
- button "Retry" [ref=e230]The error panel renders your message and a Retry button. The default error simulates a failed
first load, so the query has no data ("hasData":false in query_get). The header says "Loading
accounts…", because the page builds that line from customers.data alone.
A failed refresh is different. The cached data stays, and only the request fails. Add
"keepData":true to simulate that:
npx genie-react call query_simulate_state --session upd-f \
'{"queryKey":["customers","list",{"page":1,"pageSize":25,"q":""}],"state":"error","keepData":true,"errorMessage":"GET /api/customers failed with 503"}'
agent-browser --session upd-f snapshot -c -s main -d 4 - paragraph
- StaticText "1,200 accounts"
- StaticText "Updated 17 seconds ago"
…
- alert
- paragraph
- StaticText "Customers could not be loaded"
- paragraph
- StaticText "GET /api/customers failed with 503"query_get now reports "hasData":true, the original dataUpdatedAt, and isRefetchError: true on
the page's observer. The header keeps the cached count above the error panel.
Which of the two do your users reach? Check each against a real failure. The app's
app_inject_fault tool makes the mock backend return 503. Run query_restore_state with
{"all":true} first, then inject the fault and click Refresh customers:
npx genie-react call app_inject_fault --session upd-f \
'{"path":"/api/customers","method":"GET","status":503}' --fields faults
agent-browser --session upd-f find label 'Refresh customers' click
agent-browser --session upd-f wait --text 'Customers could not be loaded'
agent-browser --session upd-f snapshot -c -s main -d 4 - paragraph
- StaticText "1,200 accounts"
- StaticText "Updated 31 seconds ago"
…
- alert
- paragraph
- StaticText "Customers could not be loaded"
- paragraph
- StaticText "Injected 503 for GET /api/customers"The real failed refresh looks like the keepData simulation. The header keeps the cached count and
the sync time, and the error panel sits below it. query_get reports the same hasData:true and
isRefetchError:true. A fault on the first load never reaches this panel.
Reload /customers with the fault in place, and the route loader fails first. The router's
RouteError page shows "This page could not be loaded" instead. So the "Loading accounts…" header
beside the panel is a state no user reaches on this route, and there is nothing to file.
Empty
The list is empty only when a search matches nothing. You can reach that through component state instead of the cache. Find the page and its stateful hooks:
npx genie-react call react_find_components --session upd-f '{"query":"CustomersPage","exact":true}'
npx genie-react call react_inspect_component --session upd-f '{"id":2418486018335}' - {index:9,kind:state,hook:useState,stateful:true,stateIndex:0,value:""}stateIndex 0 is the search box's term. Set it to a term no account contains:
npx genie-react call react_override_hook_state --session upd-f \
'{"id":2418486018335,"stateIndex":0,"value":"zzqx"}'
agent-browser --session upd-f snapshot -c -s main - paragraph
- StaticText "0 accounts"
…
- textbox "Search customers" [ref=e15]: zzqx
…
- paragraph
- StaticText "No customers match"
- paragraph
- StaticText "Try a different name or clear the tier filter."The page debounced the term, moved the URL to ?page=1&q=zzqx and ran a real search. This empty
state came from the server, so the header and the body agree. Undo it:
npx genie-react call react_reset_overrides --session upd-f '{}'ok: true
cleared: [{kind:hook,componentName:CustomersPage,outcome:restored}]
remaining: 0
commitObserved: trueThe URL returns to ?page=1&q= and the header to 1,200 accounts.
The orders tab blanks the whole page
A customer page has a Recent orders tab. CustomerOrdersPanel loads it with useSuspenseQuery.
Open /customers/c-0042, click the tab once so the panel mounts, then hold its nearest Suspense
boundary in the fallback:
npx genie-react call react_find_components --session upd-f '{"query":"CustomerOrdersPanel","exact":true}' \
--json | jq -c '.matches[] | {id,name,path}'
npx genie-react call react_toggle_suspense_fallback --session upd-f '{"id":11958380134513,"showFallback":true}'
agent-browser --session upd-f snapshot -c -s mainok: true
boundaryId: 11958380134450
showingFallback: true
activeOverrides: 1
(empty page)The customer name, the Edit account button and the tabs all vanished. main has no visible
content and no spinner. The sidebar and top bar stay. react_suspense names the boundary:
- {id:11958380134450,parentBoundaryId:11958380134436,state:fallback,forced:true,…,source:{file:/node_modules/.pnpm/@tanstack+react-router@1.170.41_…/node_modules/@tanstack/react-router/dist/esm/Match.js,line:70,column:48,functionName:MatchView},sourceOwnership:library}The nearest boundary belongs to TanStack Router's MatchView, above the whole page. The page
itself has no boundary around the panel.
A forced state shows what could happen. To prove it does happen, reload the page, slow the orders
request with the app's app_set_latency tool, and click the tab for real:
npx genie-react call app_set_latency --session upd-f \
'{"rules":[{"path":"/api/customers/c-0042/orders","ms":3000}]}'
agent-browser --session upd-f find role tab click --name 'Recent orders'
agent-browser --session upd-f snapshot -c -s main(empty page)A user who clicks Recent orders sees a blank page for as long as the orders take. React's Suspense reference describes this. When content that is already shown suspends again outside a transition, the closest boundary shows its fallback again.
Turn the blank page into a failing check
That real click ran inside verify. The claim suspense CustomerDetailPage hidden max 0 fails
when any Suspense boundary above the page replaces it with a fallback during the window:
npx genie-react verify begin --session upd-f --name 'open Recent orders' \
--claim 'render CustomerOrdersPanel min 1' --claim 'boundaries clean' \
--claim 'suspense CustomerDetailPage hidden max 0'
agent-browser --session upd-f find role tab click --name 'Recent orders'
npx genie-react verify end vfy_b7e44950-b3a7-4c52-b0c2-ca4806ff231c --session upd-fTrimmed to the verdict and claim lines, it exits 1:
fail vfy_b7e44950-b3a7-4c52-b0c2-ca4806ff231c "open Recent orders" 4 commits, quiet after 3506 ms (react, query, router, network)
1 pass render CustomerOrdersPanel min 1 {renders:2,mounts:1,updates:1,remounts:0,semantics:exact,instances:1,activeInstances:1}
2 pass boundaries clean {caughtDuringWindow:0,caughtAtEnd:0}
3 fail suspense CustomerDetailPage hidden max 0 {hidden:1,hidesInWindow:1}The panel rendered and no boundary caught an error, so claims 1 and 2 pass. Claim 3 catches the
blank page. Genie 1.0.2 had no suspense claim, and the same click passed verify there. Claim 1
stays as the control that proves the click reached the app.
The fix
Give the panel its own boundary inside the page:
-import { useEffect, useState } from 'react'
+import { Suspense, useEffect, useState } from 'react'
import { PermissionGate } from '../../app/permissions'
import { Button } from '../../components/ui/button'
+import { Skeleton } from '../../components/ui/feedback'
…
) : (
- <CustomerOrdersPanel customerId={customer.id} />
+ <Suspense fallback={<Skeleton className="h-64" />}>
+ <CustomerOrdersPanel customerId={customer.id} />
+ </Suspense>
)}After the fix, the same real click with the same 3,000 ms delay shows the page during the load:
- main
- link "All customers" [ref=e801]
- sectionheader
- heading "Quarry Retail" [level=1, ref=e810]
…
- button "Edit account" [ref=e811]
- tablist "Customer sections"
- tab "Profile" [ref=e812]
- tab "Recent orders" [selected, ref=e813]The same three claims pass, and the command exits 0:
pass vfy_7c6d1cff-15f4-438c-9b22-af86ef34ed1e "open Recent orders" 3 commits, quiet after 3377 ms (react, query, router, network)
1 pass render CustomerOrdersPanel min 1 {renders:1,mounts:1,updates:0,remounts:0,semantics:exact,instances:1,activeInstances:1}
2 pass boundaries clean {caughtDuringWindow:0,caughtAtEnd:0}
3 pass suspense CustomerDetailPage hidden max 0 {hidden:0,hidesInWindow:0}
attempt 2 for these claims on this tab; previous fail vfy_b7e44950-b3a7-4c52-b0c2-ca4806ff231c; document reloaded sinceForcing the fallback again now holds a boundary that the page owns:
{"id":5353374744693,"state":"fallback","forced":true,"source":"CustomerDetailPage","file":"/src/features/customers/customer-detail-page.tsx"}Both runs also printed ui-outcome-not-observed. verify proves that no Suspense fallback hid the
page. The driver snapshot proves what the user saw.
Put everything back
Release every override and simulation, clear the backend rules, and check the result:
npx genie-react call app_set_latency --session upd-f '{}' --fields latency
npx genie-react call app_clear_faults --session upd-f '{}' --fields faults
npx genie-react call query_restore_state --session upd-f '{"all":true}'
npx genie-react call react_reset_overrides --session upd-f '{}'Require remaining: 0 from react_reset_overrides. query_restore_state reports restored for
each query it put back.
When forcing states misleads you
- A simulated
pendingorerrorlooks like a query that never loaded, with no data anddataUpdatedAtat 0. Pages that read cached data can show a pair your users never see, as the Customers header did beside the error panel. Use"keepData":truewith"state":"error"when the state you care about is a failed refresh. - Forcing tells you what a state looks like, not whether users reach it. Confirm a suspected bug with a real fault or delay through the app's own tools, as above.
- A hook override lasts until the component's own next
setState. Component IDs change after a reload, so find them again. verifydoes not read the screen. Asuspenseclaim proves React did not hide a component. For everything else the user sees, the driver snapshot is the evidence.
The Validate UI states guide covers the same tools on the Vite demo, and Verify a fix lists the claims verify can decide.
The mutation succeeded and the list didn't update. One query key was off by one letter
A task form said Saved while the list kept two rows. Genie showed the invalidation matched 0 queries because the key said task, not tasks.
Your error boundary caught the error and rendered nothing
An empty card with no error message can be a TypeError that an error boundary swallowed. Genie's react_error_state names the boundary, the thrower and the line.