Package com.vaadin.browserless

Class BrowserlessUIContext

  • All Implemented Interfaces:
    com.vaadin.browserless.TesterWrappers , com.vaadin.browserless.locator.GeneratedLocators , com.vaadin.browserless.locator.Locators , java.lang.AutoCloseable 
    
public class BrowserlessUIContext
 implements TesterWrappers, Locators, AutoCloseable

    UI-level context for multi-user browserless testing.

    Represents a single browser window (one UI instance). All DSL methods (navigate, find, findInView, test) 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
    Since:

    1.1

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description

    • Constructor Summary

      Constructors 
      Constructor Description

    • Enum Constant Summary

      Enum Constants 
      Enum Constant Description

    • Method Summary

      Modifier and Type Method Description
      BrowserlessUserContext getUser() Returns the user context that owns this window.
      UI getUI() Returns the UI managed by this context.
      void activate() Activates this UI context on the current thread.
      <T extends Component> T navigate(Class<T> navigationTarget) Navigates this window to the given view class.
      <C, T extends Component, HasUrlParameter<C>> T navigate(Class<T> navigationTarget, C parameter) Navigates this window to the given view class with a URL parameter.
      <T extends Component> T navigate(Class<T> navigationTarget, Map<String, String> parameters) Navigates this window to the given view class with route parameters.
      <T extends Component> T navigate(String location, Class<T> expectedTarget) Navigates this window to the given location and validates the resulting view.
      static BrowserlessUIContext forComponent(Component component) Shorthand for ad-hoc component testing of a single component — no @Route view required.
      static BrowserlessUIContext forComponent(Supplier<Component> componentFactory) Shorthand for ad-hoc component testing of a single component, taking a factory rather than a ready instance — no @Route view required.
      <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.
      <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.
      <T extends Component> ComponentQuery<T> findInView(Class<T> componentType) Gets a query object for finding components of the given type inside the current view.
      <T extends ComponentTester<Y>, Y extends Component> T test(Y component) Wraps a component with the best matching ComponentTester.
      <T extends ComponentTester<Y>, Y extends Component> T test(Class<T> tester, Y component) Wraps a component in the given ComponentTester.
      HasElement getCurrentView() Gets the current view displayed in this window.
      void roundTrip() Simulates a server round-trip, flushing pending component changes.
      void fireShortcut(Key key, Array<KeyModifier> modifiers) Simulates a keyboard shortcut performed on the browser.
      boolean runPendingSignalsTasks() Processes all pending Signals tasks with a default max wait time of 100 milliseconds.
      boolean runPendingSignalsTasks(long maxWaitTime, TimeUnit unit) Processes all pending Signals tasks, waiting up to the specified timeout for the first task to arrive.
      String getExternalNavigationURL() Returns the URL from the last external navigation triggered by setLocation or open.
      String getExternalNavigationURL(String windowName) Returns the last URL opened with the given window name.
      Map<String, List<String>> getOpenedWindows() Returns a map of all windows opened via open or open, excluding navigations that target the current window (_self, _parent, _top, empty, or null).
      void activateLocatorContext() Hook for context-bound implementations to install Vaadin thread-locals before a locator is built.
      void close() Closes this UI context and detaches the UI.

      • Methods inherited from class com.vaadin.browserless.TesterWrappers

        popoverFor, popoverFor, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test, test

      • Methods inherited from class com.vaadin.browserless.locator.Locators

        find

      • Methods inherited from class com.vaadin.browserless.locator.GeneratedLocators

        activateLocatorContext, findAccordion, findAnchor, findBigDecimalField, findBreadcrumbs, findButton, findCheckbox, findCheckboxGroup, findComboBox, findConfirmDialog, findContextMenu, findDatePicker, findDateTimePicker, findDecimalRangeSlider, findDecimalSlider, findDescriptionList, findDetails, findDialog, findDiv, findEmailField, findEmphasis, findGrid, findH1, findH2, findH3, findH4, findH5, findH6, findHr, findImage, findInput, findIntegerField, findIntegerRangeSlider, findIntegerSlider, findListBox, findListItem, findLoginForm, findLoginOverlay, findMarkdown, findMasterDetailLayout, findMenuBar, findMessageInput, findMessageList, findMultiSelectComboBox, findMultiSelectListBox, findNativeButton, findNativeDetails, findNativeLabel, findNotification, findNumberField, findOrderedList, findParagraph, findPasswordField, findPopover, findPre, findRadioButton, findRadioButtonGroup, findRangeInput, findRouterLink, findSelect, findSideNav, findSpan, findTabSheet, findTabs, findTextArea, findTextField, findTimePicker, findUnorderedList, findUpload, findVirtualList, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use, use

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

    • Method Detail

      • getUI

         UI getUI()

        Returns the UI managed by this context.

        Returns:

        the UI instance

      • activate

         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()).

      • navigate

         <T extends Component> T navigate(Class<T> navigationTarget)

        Navigates this window to the given view class.

        Parameters:
        navigationTarget - the view class to navigate to
        Returns:

        the instantiated view

      • navigate

         <C, T extends Component, HasUrlParameter<C>> T navigate(Class<T> navigationTarget, C parameter)

        Navigates this window to the given view class with a URL parameter.

        Parameters:
        navigationTarget - the view class to navigate to
        parameter - the URL parameter
        Returns:

        the instantiated view

      • navigate

         <T extends Component> T navigate(Class<T> navigationTarget, Map<String, String> parameters)

        Navigates this window to the given view class with route parameters.

        Parameters:
        navigationTarget - the view class to navigate to
        parameters - the route parameters
        Returns:

        the instantiated view

      • navigate

         <T extends Component> T navigate(String location, Class<T> expectedTarget)

        Navigates this window to the given location and validates the resulting view.

        Parameters:
        location - the navigation location string
        expectedTarget - the expected view class
        Returns:

        the instantiated view

      • forComponent

         static BrowserlessUIContext forComponent(Component component)

        Shorthand for ad-hoc component testing of a single component — no @Route view required. Builds a self-contained, route-free application context via forComponent, opens one user and one window, and attaches the given component to that window's UI. The returned window owns its bundled BrowserlessApplicationContext, which is torn down when the window's UI detaches, so a single try-with-resources is enough: 

        try (var window = BrowserlessUIContext.forComponent(new MyForm())) {
    window.findButton().withCaption("Save").click();
}
        This is a single-window shorthand: it captures the given instance, so opening further windows on the underlying context would re-parent the same component. It also constructs the component before any UI exists — if the component's constructor needs UI.getCurrent() or the session, use forComponent instead. For multi-window, multi-user, or routed tests use forComponent with a fresh-instance factory, or the standard BrowserlessApplicationContext.create(...) + newUser().newWindow() chain.
        Parameters:
        component - the component to attach; must not be null
        Returns:

        a window with the component attached

      • forComponent

         static BrowserlessUIContext forComponent(Supplier<Component> componentFactory)

        Shorthand for ad-hoc component testing of a single component, taking a factory rather than a ready instance — no @Route view required. Builds a self-contained, route-free application context via forComponent, opens one user and one window, and attaches the produced component to that window's UI: 

        try (var window = BrowserlessUIContext.forComponent(MyForm::new)) {
    window.findButton().withCaption("Save").click();
}
        The factory runs from UI.init(), after the Vaadin thread-locals (UI, session, security context) are installed, so a component whose constructor reads UI.getCurrent() observes the live environment — unlike forComponent, which receives an already-constructed instance. The returned window owns its bundled BrowserlessApplicationContext, which is torn down when the window's UI detaches.
        Parameters:
        componentFactory - supplies the component to attach; must not be null
        Returns:

        a window with the produced component attached

      • find

         <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.

        Parameters:
        componentType - the type of component to search for
        Returns:

        a query object

      • find

         <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.

        Parameters:
        componentType - the type of component to search for
        fromThis - the component to search within
        Returns:

        a query object

      • findInView

         <T extends Component> ComponentQuery<T> findInView(Class<T> componentType)

        Gets a query object for finding components of the given type inside the current view.

        Parameters:
        componentType - the type of component to search for
        Returns:

        a query object

      • test

         <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.

        Parameters:
        component - the component to wrap
        Returns:

        the component wrapped in a tester

      • test

         <T extends ComponentTester<Y>, Y extends Component> T test(Class<T> tester, Y component)

        Wraps a component in the given ComponentTester.

        Parameters:
        tester - test wrapper to use
        component - component to wrap
        Returns:

        the initialized tester for the component

      • getCurrentView

         HasElement getCurrentView()

        Gets the current view displayed in this window.

        Returns:

        the current view

      • roundTrip

         void roundTrip()

        Simulates a server round-trip, flushing pending component changes.

      • fireShortcut

         void fireShortcut(Key key, Array<KeyModifier> modifiers)

        Simulates a keyboard shortcut performed on the browser.

        Parameters:
        key - primary key of the shortcut.
        modifiers - key modifiers.

      • runPendingSignalsTasks

         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

      • runPendingSignalsTasks

         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.
        unit - the time unit of the timeout value
        Returns:

        true if any pending Signals tasks were processed

      • getExternalNavigationURL

         String getExternalNavigationURL()

        Returns the URL from the last external navigation triggered by setLocation or open.

        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 or getOpenedWindows.

        Returns:

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

      • getExternalNavigationURL

         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

         Map<String, List<String>> getOpenedWindows()

        Returns a map of all windows opened via open or open, 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

         void activateLocatorContext()

        Hook for context-bound implementations to install Vaadin thread-locals before a locator is built. Default is a no-op.

      • close

         void close()

        Closes this UI context and detaches the UI.