Package com.vaadin.browserless

Class BrowserlessUIContext

java.lang.Object
com.vaadin.browserless.BrowserlessUIContext
All Implemented Interfaces:
GeneratedLocators, Locators, TesterWrappers, AutoCloseable
public class BrowserlessUIContext extends Object implements TesterWrappers, Locators, AutoCloseable
UI-level context for multi-user browserless testing.

Represents a single browser window (one UI instance). All DSL methods (navigate(java.lang.Class<T>), find(java.lang.Class<T>), findInView(java.lang.Class<T>), test(Y)) automatically call activate() before executing, which transparently switches the thread-local Vaadin state and security context to this window's user.

Instances of this class are thread-affine: they must be created, used, and closed on the same thread. The active context is held in a ThreadLocal and is not visible to other threads. This class is not safe for concurrent access from multiple threads.

This means you can freely interleave calls on different windows without explicit context switching: 

 window1.navigate(ViewA.class);
 window2.navigate(ViewB.class); // auto-switches to window2's user
 window1.find(Button.class).first(); // auto-switches back to window1's user
See Also:

  • Method Details

    • activate

      public void activate()
      Activates this UI context on the current thread.

      Sets all Vaadin thread-locals (VaadinService, VaadinSession, UI, VaadinRequest, VaadinResponse) to this window's values. If a SecurityContextHandler is configured and the previous active context belonged to a different user, the outgoing user's security context is automatically saved and this user's context is restored.

      The security context is a per-user snapshot, not per-window: switching between windows of the same user does not save or restore security state, so mutations made by one window are observed by sibling windows.

      This method is called automatically by all DSL methods. You only need to call it explicitly if you are accessing Vaadin APIs directly (e.g. UI.getCurrent()).

    • find

      public <T extends Component> ComponentQuery<T> find(Class<T> componentType)
      Gets a query object for finding components of the given type in this window's UI.
      Type Parameters:
      T - the component type
      Parameters:
      componentType - the type of component to search for
      Returns:
      a query object

    • find

      public <T extends Component> ComponentQuery<T> find(Class<T> componentType, Component fromThis)
      Gets a query object for finding components of the given type nested inside the specified component.
      Type Parameters:
      T - the component type
      Parameters:
      componentType - the type of component to search for
      fromThis - the component to search within
      Returns:
      a query object

    • findInView

      public <T extends Component> ComponentQuery<T> findInView(Class<T> componentType)
      Gets a query object for finding components of the given type inside the current view.
      Type Parameters:
      T - the component type
      Parameters:
      componentType - the type of component to search for
      Returns:
      a query object

    • test

      public <T extends ComponentTester<Y>, Y extends Component> T test(Y component)
      Wraps a component with the best matching ComponentTester. This generic fallback is used for component types not covered by the specific TesterWrappers defaults.
      Type Parameters:
      T - the tester type
      Y - the component type
      Parameters:
      component - the component to wrap
      Returns:
      the component wrapped in a tester

    • test

      public <T extends ComponentTester<Y>, Y extends Component> T test(Class<T> tester, Y component)
      Wraps a component in the given ComponentTester.
      Type Parameters:
      T - the tester type
      Y - the component type
      Parameters:
      tester - test wrapper to use
      component - component to wrap
      Returns:
      the initialized tester for the component

    • getCurrentView

      public HasElement getCurrentView()
      Gets the current view displayed in this window.
      Returns:
      the current view

    • roundTrip

      public void roundTrip()
      Simulates a server round-trip, flushing pending component changes.

    • fireShortcut

      public void fireShortcut(Key key, KeyModifier... modifiers)
      Simulates a keyboard shortcut performed on the browser.
      Parameters:
      key - primary key of the shortcut. This must not be a KeyModifier.
      modifiers - key modifiers. Can be empty.

    • runPendingSignalsTasks

      public boolean runPendingSignalsTasks()
      Processes all pending Signals tasks with a default max wait time of 100 milliseconds. Convenience for tests that need to wait for asynchronous Signal effects triggered from background threads or non-UI contexts.

      If this window's VaadinSession lock is held by the current thread, it is temporarily released during the wait to allow background threads to acquire the lock and enqueue tasks.

      Returns:
      true if any pending Signals tasks were processed
      See Also:

    • runPendingSignalsTasks

      public boolean runPendingSignalsTasks(long maxWaitTime, TimeUnit unit)
      Processes all pending Signals tasks, waiting up to the specified timeout for the first task to arrive. Once the first task is found, all remaining tasks in the queue are processed immediately without additional waiting.
      Parameters:
      maxWaitTime - the maximum time to wait for the first task to arrive in the given time unit. If <= 0, returns immediately if no tasks are available.
      unit - the time unit of the timeout value
      Returns:
      true if any pending Signals tasks were processed

    • getExternalNavigationURL

      public String getExternalNavigationURL()
      Returns the URL from the last external navigation triggered by Page.setLocation(String) or Page.open(String).

      This captures URLs where the window name is _self, _parent, _top, empty, or null (all of which navigate the current window). To query URLs opened in other windows, use getExternalNavigationURL(String) or getOpenedWindows().

      Returns:
      the external navigation URL, or null if no external navigation has occurred

    • getExternalNavigationURL

      public String getExternalNavigationURL(String windowName)
      Returns the last URL opened with the given window name.

      For _blank, returns the URL from the most recent call. For named windows, returns the last URL that targeted that name.

      Parameters:
      windowName - the window name to look up
      Returns:
      the last URL for the given window name, or null if none

    • getOpenedWindows

      public Map<String,List<String>> getOpenedWindows()
      Returns a map of all windows opened via Page.open(String) or Page.open(String, String), excluding navigations that target the current window (_self, _parent, _top, empty, or null).

      The map keys are window names, and values are lists of URLs opened under that name. For _blank, the list contains all URLs (each call opens a new window). For named windows, the list typically contains a single entry (the last URL).

      Returns:
      an unmodifiable map of window names to URL lists

    • activateLocatorContext

      public void activateLocatorContext()
      Description copied from interface: Locators
      Hook for context-bound implementations to install Vaadin thread-locals before a locator is built. Default is a no-op.
      Specified by:
      activateLocatorContext in interface GeneratedLocators
      Specified by:
      activateLocatorContext in interface Locators

    • getUI

      public UI getUI()
      Returns the UI managed by this context.
      Returns:
      the UI instance

    • getUser

      public BrowserlessUserContext getUser()
      Returns the user context that owns this window.
      Returns:
      the parent user context

    • close

      public void close()
      Closes this UI context and detaches the UI.
      Specified by:
      close in interface AutoCloseable