Genie React

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: true

The 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 main
ok: 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-f

Trimmed 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 since

Forcing 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 pending or error looks like a query that never loaded, with no data and dataUpdatedAt at 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":true with "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.
  • verify does not read the screen. A suspense claim 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.

On this page