feat: Add blur simulation and implicit focus tracking

[mstahv]

Summary

Browserless tests now track which component has keyboard focus, so focus and blur listeners fire on their own when a tester clicks a component or sets its value. ComponentTester also gets explicit focus(), blur() and isFocused() methods, and server-side Focusable.focus() / blur() calls are simulated too.

Fixes #163

What changed

Behavior change: interactions made through testers now fire focus and blur events. This affects all users, but only tests whose components have focus or blur listeners:

• click() (the shared Clickable implementation) and setValueAsUser(...) first move focus to the component, which blurs the previously focused one. Blur runs before the click is handled, like in a browser.
• Existing tests that count events, or that expect no focus/blur, may see extra events now.
• If the application has a Focusable.focus() or blur() call pending, the simulation reads the pending JavaScript queue, which consumes it — any other JavaScript queued at the same time is dropped. When no focus or blur call is pending the queue is left untouched, so JavaScript scheduled by the application can still be asserted on. Everything consumed is listed in a debug log under com.vaadin.browserless.FocusTracker. Handling the queue centrally is tracked in #221.

New behaviour:

• New package-private FocusTracker keeps the focused component per UI. It fires focus / blur DOM events as if they came from the client, and mirrors Flow's markers so that a server-initiated focus or blur reports isFromClient() == false.
• Server-side Focusable.focus() / blur() calls are applied at the end of a focus-tracked interaction, on roundTrip(), and when isFocused() is called.
• focus() and blur() fail fast: IllegalArgumentException if the component is not Focusable, IllegalStateException if it is disabled or not attached. Read-only fields can still be focused.
• Only Focusable components take focus. Interacting with anything else blurs the previous component and leaves nothing focused, like focus falling back to the document body.
• Focus is per UI, so it does not survive a page reload, not even in a @PreserveOnRefresh view.
• Testers that fire their events directly (radio button, menu bar, context menu item clicks) do not take part in focus tracking. This is documented in the README together with the other limits.

Use case

A form focuses the next field from a value change listener, and a "save" button validates the amount in a blur listener. The developer wants a test that proves both happen in the right order, without any browser.

TextField amount = new TextField("Amount");
TextField note = new TextField("Note");
amount.addValueChangeListener(e -> note.focus()); // application logic
amount.addBlurListener(e -> validate(amount.getValue()));

// test
test(amount).setValue("100");      // focuses the field, then fires the value change
assertTrue(test(note).isFocused()); // server-side focus() was applied

test(save).click();                 // blurs "note" first, then handles the click
assertFalse(test(note).isFocused());

// explicit control when nothing else is interacted with afterwards
test(amount).focus();
test(amount).blur();

API Changes

com.vaadin.browserless.ComponentTester

// Added
public void focus() // moves simulated keyboard focus to the wrapped component
public void blur() // fires a blur event; no-op if the component is not focused
public boolean isFocused() // true if the component has focus, server-side focus() included

Test summary

Implicit focus on interactions:

• Field focused when a value is set through the tester
• Previously focused field blurred by a click or by setting another field
• Blur listener runs before the click listener
• No blur or re-focus on consecutive edits of the same field
• Click on a non-focusable component blurs the field and focuses nothing

Explicit focus API:

• Blur through the tester fires the blur event as from the client
• Blur on a non-focused component is a no-op
• focus() / blur() fail with a readable message when the component is not Focusable
• Read-only field focusable, disabled or detached field fails

Server-side Focusable calls:

• focus() from a value change listener moves focus and blurs the previous field, not from client
• focus(FocusOption...) detected as well
• blur() fires the blur event and clears focus, not from client
• Focus scheduled outside an interaction applied on roundTrip()
• Field focused in a dialog opened by a click listener

Page reload:

• Focus cleared after a reload, also in a @PreserveOnRefresh view

[mcollovati]

This loop is consuming the while-pending invocation queue but processing only focus and blur. If other testers or testing features need to inspect the invocation as well, they will silently do nothing.
I guess we need a centralized place to handle the JavaScript invocation queue, where testers can register their own handlers for specific expressions.
I wonder if this would need some changes in Flow to simplify things.
Worth creating an issue. @totally-not-ai please create one

[mcollovati]

This loop is consuming the while-pending invocation queue but processing only focus and blur. If other testers or testing features need to inspect the invocation as well, they will silently do nothing.
I guess we need a centralized place to handle the JavaScript invocation queue, where testers can register their own handlers for specific expressions.
I wonder if this would need some changes in Flow to simplify things.
Worth creating an issue. @totally-not-ai please create one

[totally-not-ai]

Created #221 for the central JavaScript invocation dispatch — including the note about possibly needing a supported way in Flow to peek at pending invocations instead of dumping them. @mcollovati

The rest of the review feedback is addressed in d295f4b:

• FocusTracker now implements Serializable
• focused is recorded only after the blur/focus events have been delivered
• blur is no longer fired on a component that does not have focus
• no more UI.getCurrent() fallback: a component not attached to a UI can neither take nor lose focus and fails with an IllegalStateException (@Artur-)
• focus()/blur() fail fast when the component is not Focusable, and use the usability check without the read-only rule, so a read-only field can still be focused while a disabled one cannot
• manual @since tag dropped

Five tests in BlurSimulationTest cover the new edge cases (blur without focus, non-focusable component, read-only, disabled, detached). Full build green.

[Artur-]

What's the status of this, are there unresolved questions? We should not block this on the Flow JS mechanism - we can adopt that the day it is available

[totally-not-ai]

@Artur- Status: no open questions from my side, and nothing here waits for Flow.

All review comments are addressed:

• FocusTracker implements Serializable, the focused component is recorded only after the blur/focus events have been delivered, and blur is no longer fired on a component that does not have focus
• no UI.getCurrent() fallback: a component that is not attached to a UI can neither take nor lose focus and fails with an IllegalStateException
• focus()/blur() fail fast for components that are not Focusable and use the usability check without the read-only rule, so a read-only field can still be focused while a disabled one cannot
• FocusTracker is package-private, so the only new public API is ComponentTester.focus(), blur() and isFocused()
• the README now documents the simulation and its limitations

On the JavaScript mechanism: agreed, it is not a blocker. Detection matches the JS that Focusable generates today and is covered by tests for focus(), focus(FocusOption...) and blur(), so a change on the Flow side fails the build immediately instead of silently. The pending queue is now only consumed when a focus or blur call is actually pending, so JavaScript scheduled by the application survives an ordinary interaction. #221 tracks handling the queue centrally; adopting it later is an internal change behind the same tester API.

Ready for another look.

[mcollovati]

This error message looks a bit cryptic. Make it easier to read like <component class> is not Focusable

[mcollovati]

The pending JavaScript invocation check before purge does not resolve the problem of vanishing simulations, but it is better than nothing.
Let's keep it that way until a proper handling is implemented.

[totally-not-ai]

@mcollovati Agreed, the pre-check only narrows the window — it is kept as is.

One thing added so the remaining gap is at least diagnosable: the expressions that are consumed together with a focus or blur call are now listed in a debug log under com.vaadin.browserless.FocusTracker, so a JavaScript simulation vanishing from the queue can be traced instead of looking like a framework bug. The README limitation note points at that log too.

Why re-queueing the untouched invocations is not an option is recorded in #221, together with the current state: dumpPendingJavaScriptInvocations() marks every invocation as sent, and PendingJavaScriptInvocation.setSentToBrowser() asserts it is called only once, so a re-added invocation fails on the next dump. A proper fix needs either a non-destructive read of the queue (UIInternals.getPendingJavaScriptInvocations() is package-private today) or a dispatcher owning the queue for the whole test.

[mcollovati]

@totally-not-ai merge main and resolve the conflicts

[totally-not-ai]

@mcollovati Merged main. The only conflict was in the README feature list, where the new page reload bullet and the focus and blur bullet landed in the same place — both are kept.

The merge brought in the reload() DSL, which recreates the UI. Focus is tracked per UI, so nothing is focused after a reload; added reload_clearsFocus to ReloadPreserveOnRefreshTest to pin that, using a @PreserveOnRefresh view where the component instances are reused, so the assertion is about focus state rather than about the component being gone.

Full build green.

[mcollovati]

@Artur- what should we do with this PR, after the changes introduced by vaadin/flow#25749? Ship it as it is with the problem of draining the queue? Or should we revise it after implementing vaadin/flow#221?

[Artur-]

If the current implementation implements focus tracking without breaking anything else, let's ship it and make a follow-up PR. The current version could be backported to 25.3 as far as I understand, an updated version could not

[totally-not-ai]

@Artur- Agreed — nothing else is pending here, so no further changes in this PR.

On not breaking anything: the full suite is green, and the only behaviour outside the focus paths is that the pending JavaScript queue is read when a server-side focus or blur call is actually queued. That case is narrowed by a containsPendingJavascript pre-check, and what the simulation takes off the queue is listed in a debug log under com.vaadin.browserless.FocusTracker.

On the backport: labelled target/25.3. The code only relies on public Flow API that is present there (containsPendingJavascript, dumpPendingJavaScriptInvocations), and the JavaScript it matches is what Focusable generates in 25.3 as well, so nothing in the detection is specific to the newer branch. Verified by building and running the whole junit6 suite, focus tests included, against the 25.3 Vaadin artifacts — all green. (The CDI regression module could not resolve vaadin-cdi for that version in this environment; it does not exercise focus.)

Follow-up work — a central place to handle the pending JavaScript queue, so other testers can react to scheduled JavaScript instead of it being consumed here — is tracked in #221, including why re-queueing the untouched invocations is not viable today.

[vaadin-bot]

Hi @mstahv and @mcollovati, when i performed cherry-pick to this commit to 25.3, i have encountered the following issue. Can you take a look and pick it manually?
Error Message:
Error: Command failed: git cherry-pick 33e025f
error: could not apply 33e025f... feat: Add blur simulation and implicit focus tracking (#164)
hint: After resolving the conflicts, mark them with
hint: "git add/rm ", then run
hint: "git cherry-pick --continue".
hint: You can instead skip this commit with "git cherry-pick --skip".
hint: To abort and get back to the state before "git cherry-pick",
hint: run "git cherry-pick --abort".

[mcollovati]

@totally-not-ai look at #164 (comment) and make the cherry-pick