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-agentbegin 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 tabFix 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
| Claim | Holds 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 updates | updates 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] settles | the effect stopped running after the app settled |
boundaries clean | no error boundary caught during the window or is in an error state at the end |
boundaries clean-at-end | no 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
| Verdict | Exit | Meaning |
|---|---|---|
pass | 0 | the evidence proves every claim |
fail | 1 | the evidence proves at least one claim false |
refused | 4 | the evidence is not good enough to decide |
inconclusive | 5 | complete 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.