Skip to content

fix(browser): make scoped UI assertions and keyboard actions reliable - #240

Closed
ibacalu wants to merge 1 commit into
tomatool:mainfrom
ibacalu:codex/ui-assertion-contracts
Closed

ibacalu wants to merge 1 commit into
tomatool:mainfrom
ibacalu:codex/ui-assertion-contracts

Conversation

@ibacalu

@ibacalu ibacalu commented Nov 4, 2026 •

Copy link
Copy Markdown

Summary

Browser assertions can confuse rendered text with control names, miss a state change that occurs just after lookup, or match text behind a dialog. presses Enter can also open a dialog and immediately activate its newly focused close button because a separate synthetic character event bypasses the prevented keydown.

 presses(key)
-  keydown → unconditional char → keyup
+  keydown with text → Chromium handles cancellation → keyup

 assert control state
-  wait for lookup → check state once
+  retry lookup and expected state together

+ sees a "dialog" named "Review" within "3s"
+ sees "Ready" in the "dialog" named "Review" within "3s"
+ does not see "Saving…" in the "dialog" named "Review"
+ no longer sees a "dialog" named "Review" within "3s"

Named-role assertions use computed accessibility roles/names, require unique visible matches and scope content/field values to that element. Existing page-wide text assertions retain their semantics. State assertions also follow labels to their controls when the visible label is transformed by CSS. No element handles are cached across retries or navigation.

Documentation explains assertion intent, bounded waits, redundant readiness checks and measuring setup/reset/scenario costs. Generated step documentation and native integration scenarios cover every new step.

Evidence

  • Before: real-Chrome regressions failed when a prevented Enter moved focus into a dialog, when Apply became enabled after lookup, and when a control became disabled asynchronously.
    After: those regressions pass, including Enter/Space, prevented printable keys, replacement controls, uppercase labels, implicit roles, hidden/ambiguous duplicates, background-text exclusion, field values and dialog disappearance.
  • Passed go test -short ./..., go test ./command ./internal/resource/browser, focused browser regressions with -race, go build ./..., go vet ./internal/resource/browser, and git diff --check.
  • Application-level replay of the original table-to-dialog Enter/Space flow also passes against the real product component with explicit focus-return outcome waits (4 scenarios / 72 steps), using these actual browser handlers.
  • Step coverage: 339/339 overall and 22/22 browser steps; no unmatched integration steps.
  • Docker-backed integration execution was unavailable locally. The added native browser integration scenario is included for CI. Scoped lookup improves precision; no per-step speedup is claimed.

Merge Danger

Door: two-way

Reversible implementation and additive step syntax; no existing text step changes meaning.

Blast Radius: browser

Keyboard dispatch changes all presses actions. Enabled/disabled assertions now wait for the expected state, so an incorrect state can take the configured timeout to fail. Successful conditions return immediately.

@ibacalu
ibacalu requested a review from alileza as a code owner November 4, 2026 19:08
@ibacalu
ibacalu marked this pull request as draft November 4, 2026 19:15
@ibacalu ibacalu closed this Nov 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant