Genie React

Verify a fix

Declare what the fix must make true, drive the interaction, and get a verdict with an exit code.

Declare claims, drive the UI, and end the window. Genie waits for the app to settle, then decides each claim. Settling means React stopped committing, Query and Router work finished, and every fetch or XMLHttpRequest call the app started during the window got its response. A request still in flight when --timeout-ms runs out refuses the claims it could change, naming the request; the $ fix raises the timeout. --domains limits the wait to a list such as react,network. A domain the app does not report refuses at begin and names the collector to add, such as requestWatchCollector() for network.

Run one verification

npx @genie-react/cli verify begin --session my-agent --name "click the counter" \
  --claim 'render MemoChild max 0' \
  --claim 'render App min 1' \
  --claim 'boundaries clean'
agent-browser --session my-agent click button.counter
npx @genie-react/cli verify end <id> --session my-agent

begin prints the ID and the end command. end prints one line per claim. This is apps/vite-demo before the fix, trimmed:

fail vfy_… "click the counter"  1 commit, quiet after 616 ms (react, query, network)
  1 fail render MemoChild max 0  {renders:1,mounts:0,updates:1,remounts:0,semantics:exact,…}
  2 pass render App min 1  {renders:1,mounts:0,updates:1,remounts:0,semantics:exact,…}
  3 pass boundaries clean  {caughtDuringWindow:0,caughtAtEnd:0}
! ui-outcome-not-observed: Genie does not check the screen; confirm it with the UI driver
attempt 1 for these claims on this tab

Fix the code and run all three again. The last line tracks attempts:

attempt 2 for these claims on this tab; previous fail vfy_…; code changed since (Fast Refresh)

verify show <id> --claim 1 prints the evidence that decided a claim. The evidence: line under a verdict names the first claim whose verdict is the run's, so a fail points at the failed claim even when a refused claim comes before it.

Write claims

ClaimHolds when
render <Name> max <N>matched instances rendered at most N times
render <Name> min <N>they rendered at least N times
render <Name> max <N> counting updatesupdates only; a remount still fails unless you add allow-remount
render <Name> only <cause>[,<cause>]every render had only listed causes: mount, children, router, props.<name>, a state hook such as state[<n>], reducer[<n>] or this.state.<field>, context.<Name>, query.<hash>
effect <Name>[#index] max <N>each effect ran at most N times
effect <Name>[#index] settlesthe effect stopped running after the app settled
boundaries cleanno error boundary caught during the window or is in an error state at the end
boundaries clean-at-endno boundary is in an error state at the end
suspense <Name> hidden max <N>a Suspense fallback replaced matched instances in at most N commits

Names are exact component names. Narrow one with @src/file.tsx or [key=value]. Add a positive control, such as min 1 on a component the action must change, so a run that never reached the app fails. --claims <file> takes claims as JSON.

only treats a first mount as a cause like any other, so a component that mounts during the window fails only props.order. List mount when the action can mount instances, as a virtualized list does when rows below the fold mount: render OrderRow only props.order,mount. Allowing mount also accepts a remount from a changed key; a max <N> counting updates claim on the same component fails on one.

A component hidden behind a Suspense fallback does not render, so render TopBar max 0 passes while a fallback blanks the top bar. To prove a layout stays on screen while a lazy route or data loads, claim suspense TopBar hidden max 0. It counts every fallback above TopBar that replaced content already on screen, including fallbacks that resolved before end. A boundary that mounts in its fallback hid nothing and does not count.

A class component without shouldComponentUpdate renders whenever its parent does, so each of its renders also carries an inferred parent cause. only can still pass on a class wrapped in connect() or memo(): when the parent is that wrapper and the wrapper rendered only for exact causes you listed, such as props.issue, Genie counts the parent cause as settled.

verify lists up to 2,000 mounted instances of each target. With more, it refuses to pass the claim (evidence_truncated) instead of judging only the instances it listed.

Read the verdict

VerdictExitMeaning
pass0the evidence proves every claim
fail1the evidence proves at least one claim false
refused4the evidence is not good enough to decide
inconclusive5complete evidence that does not decide, such as an excess only StrictMode explains

A refusal names its reason and the fix. When the window holds no React commit at all, claims that hold when nothing renders, such as max 0, refuse with no_activity:

refused vfy_… "nothing"  0 commits, quiet after 609 ms (react, query, network)
  1 refused render MemoChild max 0  no_activity: No React commit happened in the window; the interaction did not reach this tab or did not change React state.

The guard counts every commit in the tab, from any component. On a page whose own timer or poll sets state, such as a clock or a sync status, a window with no interaction still has commits, so it passes with exit code 0. Only a min 1 claim on a component the interaction must change catches an action that never reached the app.

Read evidence lists every refusal.

A count graded semantics:lower-bound can still decide a claim: 37 renders already break max 0. When the lower bound comes from an analysis budget that ran out, such as the target reserve on a board with hundreds of instances, the claim prints the budget that would make the count exact and the command that begins the same run with it:

  1 fail render FeatureGate max 0  {renders:37,…,semantics:lower-bound,instances:840,activeInstances:840}
      budgetAdvice: {exhaustedLimits:[targetOperationReserve],suggestedBudget:{…,targetOperationReserve:92000,targetTimeReserveMs:92}}
      exact: $ npx genie-react verify begin … --budget '{…,"targetOperationReserve":92000,"targetTimeReserveMs":92}'

While a window is open

Genie refuses tools that would skew the evidence on that tab, such as react_clear_renders and the override tools, with reason conflict and hubCode: "VERIFICATION_ACTIVE"; its next ends the verification. verify abort <id> releases the window, and unended windows expire after five minutes. Genie does not check the screen, so confirm the result with the UI driver.

On this page