Package com.vaadin.browserless

Class BrowserlessApplicationContext

java.lang.Object
com.vaadin.browserless.BrowserlessApplicationContext
All Implemented Interfaces:
AutoCloseable
Direct Known Subclasses:
SecuredBrowserlessApplicationContext
public class BrowserlessApplicationContext extends Object implements AutoCloseable
Application-level context for multi-user browserless testing.

Manages a shared VaadinServletService and servlet that are shared across all users and their windows. This models the application level of the Vaadin hierarchy: one application contains multiple user sessions, each with multiple UI instances (browser windows).

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; driving the same context from parallel test threads is unsupported.

This base class is unsecured: it has no SecurityContextHandler. For multi-user security isolation, configure a handler via BrowserlessApplicationContext.Builder.withSecurityContextHandler(SecurityContextHandler) ? the builder transitions to SecuredBrowserlessApplicationContext.Builder and build() returns the typed SecuredBrowserlessApplicationContext, which exposes credential-aware newUser(...) overloads. Framework-specific modules (Spring, Quarkus) provide convenience factory methods for both paths. 

 var app = BrowserlessApplicationContext.create(MyView.class);
 var user1 = app.newUser();
 var window1 = user1.newWindow();
 window1.navigate(MyView.class);
 // ...
 app.close();
Since:
1.1
See Also:

  • Method Details

    • create

      public static BrowserlessApplicationContext create(String... viewPackages)
      Creates a plain Java application context, scanning the given packages for @Route-annotated views.
      Parameters:
      viewPackages - package names to scan for views; an empty array falls back to a full classpath scan
      Returns:
      a new application context

    • create

      public static BrowserlessApplicationContext create(Class<?>... viewPackageClasses)
      Creates a plain Java application context, scanning the packages of the given classes for @Route-annotated views.
      Parameters:
      viewPackageClasses - classes whose packages should be scanned for views
      Returns:
      a new application context

    • create

      public static BrowserlessApplicationContext create(UnaryOperator<BrowserlessApplicationContext.Builder> configurer)
      Creates a plain Java application context, applying the given configurer to a fresh builder before building it. The configurer cannot be null; pass UnaryOperator.identity() to accept all defaults.
      Parameters:
      configurer - builder configurer
      Returns:
      a new application context

    • createSecured

      public static <C> SecuredBrowserlessApplicationContext<C> createSecured(Function<BrowserlessApplicationContext.Builder,SecuredBrowserlessApplicationContext.Builder<C>> configurer)
      Creates a credential-typed application context. The configurer must call BrowserlessApplicationContext.Builder.withSecurityContextHandler(SecurityContextHandler) on the supplied builder so that it returns a SecuredBrowserlessApplicationContext.Builder carrying the required handler.

      Using a separate method name rather than an overload of create(UnaryOperator) is intentional: Java overload resolution cannot disambiguate two lambdas whose parameter types share the Function erasure.

      Type Parameters:
      C - the credentials type
      Parameters:
      configurer - builder configurer that installs a security handler and returns the resulting secured builder
      Returns:
      a new credential-aware application context

    • forComponent

      public static BrowserlessApplicationContext forComponent(Supplier<Component> componentFactory)
      Creates a self-contained application context for ad-hoc testing of a single component, without requiring a @Route view. No route discovery is performed (see BrowserlessApplicationContext.Builder.withoutRoutes()), so creation skips the classpath scan and the component is the sole content of each window's UI.

      The given factory is invoked once per window: each newUser().newWindow() call attaches a freshly produced component to that window's UI. 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. Supply a factory that returns a new instance per call if you intend to open more than one window; reusing a single instance across windows re-parents it and leaves the earlier window empty.

      The returned context closes itself when its window's UI is detached, so a single try-with-resources ? on the returned context, or on the window via BrowserlessUIContext.forComponent(Component) ? tears everything down.

      Parameters:
      componentFactory - supplies the component to attach to each window; must not be null
      Returns:
      a new self-closing application context with no routes
      Throws:
      NullPointerException - if componentFactory is null

    • newUser

      public BrowserlessUserContext newUser()
      Creates a new user context representing an anonymous user session.

      When a SecurityContextHandler is configured (on a SecuredBrowserlessApplicationContext), the handler is asked to install its anonymous-equivalent state (e.g. Spring sets an AnonymousAuthenticationToken). On this unsecured base class no security setup is performed.

      Returns:
      the new user context
      Throws:
      IllegalStateException - if this context has been closed

    • close

      public void close()
      Closes this application context and all its user contexts.

      Closes every BrowserlessUserContext created by this application (which in turn closes their windows), fires service destroy listeners, and resets the VaadinService thread-local. This method is idempotent: subsequent invocations have no effect.

      Specified by:
      close in interface AutoCloseable