diff --git a/articles/flow/testing/browserless/component-query.adoc b/articles/flow/testing/browserless/component-query.adoc
index 07f28708f2..137d312abc 100644
--- a/articles/flow/testing/browserless/component-query.adoc
+++ b/articles/flow/testing/browserless/component-query.adoc
@@ -16,28 +16,31 @@ To overcome this limitation, [classname]`BrowserlessTest` provides a component q
 
 == Component Queries
 
-You can get a [classname]`ComponentQuery` object by calling the [methodname]`$()` method, specifying the type of the component you are searching for.
+You can get a [classname]`ComponentQuery` object by calling the [methodname]`find()` method, specifying the type of the component you are searching for.
 
 Once the query is ready with all conditions configured, use a terminal operator to retrieve the components that it found. Examples of terminal operators are [methodname]`single()`, [methodname]`last()`, [methodname]`atIndex()`, [methodname]`all()`, and [methodname]`id()`.
 
 [source,java]
 ----
 // Get the TextField
-TextField nameField = $(TextField.class).single();
+TextField nameField = find(TextField.class).single();
 ----
 
+[NOTE]
+[classname]`BrowserlessTest` retains [methodname]`$()` and [methodname]`$view()` as deprecated aliases for [methodname]`find()` and [methodname]`findInView()`, scheduled for removal in 2.0. The newer composition-based APIs ([classname]`BrowserlessExtension`, [classname]`BrowserlessClassExtension`, and [classname]`BrowserlessUIContext`) only expose [methodname]`find()` and [methodname]`findInView()`.
+
 
 === Scoping Queries
 
-You can also restrict search scope to the children of the current view by using the [methodname]`$view()` method, or even to another component by using [methodname]`$(MyComponent.class, rootComponent)`.
+You can also restrict search scope to the children of the current view by using the [methodname]`findInView()` method, or even to another component by using [methodname]`find(MyComponent.class, rootComponent)`.
 
 [source,java]
 ----
 // Get the TextField in the current view
-TextField nameField = $view(TextField.class).single();
+TextField nameField = findInView(TextField.class).single();
 
 // Get the TextField nested in a container
-TextField nameField = $(TextField.class, view.formLayout).single();
+TextField nameField = find(TextField.class, view.formLayout).single();
 ----
 
 The query object has many filtering methods that can be used to refine the search.
@@ -45,14 +48,14 @@ The query object has many filtering methods that can be used to refine the searc
 [source,java]
 ----
 // Get the TextField with the given label
-TextField nameField = $view(TextField.class)
+TextField nameField = findInView(TextField.class)
         .withPropertyValue(TextField::getLabel, "First name")
         .single();
 
 // Get all TextFields in the view that satisfy the conditions
 Predicate<TextField> fieldHasNotValue = field -> field.getOptionalValue().isEmpty();
 Predicate<TextField> fieldIsInvalid = TextField::isInvalid;
-List<TextField> textField = $view(TextField.class)
+List<TextField> textField = findInView(TextField.class)
         .withCondition(fieldHasNotValue.or(fieldIsInvalid))
         .all();
 ----
@@ -127,13 +130,13 @@ Here are a few examples:
 [source,java]
 ----
 // Find a button by its text
-Button save = $(Button.class).withText("Save").single();
+Button save = find(Button.class).withText("Save").single();
 
 // Find a TextField by CSS class
-TextField styled = $(TextField.class).withClassName("highlighted").single();
+TextField styled = find(TextField.class).withClassName("highlighted").single();
 
 // Find checkboxes with a specific value
-Checkbox checked = $(Checkbox.class).withValue(true).single();
+Checkbox checked = find(Checkbox.class).withValue(true).single();
 ----
 
 
@@ -143,7 +146,7 @@ Use [methodname]`exists()` to check whether a query has results without throwing
 
 [source,java]
 ----
-if ($(Notification.class).exists()) {
+if (find(Notification.class).exists()) {
     // A notification is open
 }
 ----
@@ -156,13 +159,13 @@ You can assert the number of results directly in the query chain:
 [source,java]
 ----
 // Expect exactly 3 text fields
-List<TextField> fields = $(TextField.class).withResultsSize(3).all();
+List<TextField> fields = find(TextField.class).withResultsSize(3).all();
 
 // Expect between 1 and 5 results
-List<Button> buttons = $(Button.class).withResultsSize(1, 5).all();
+List<Button> buttons = find(Button.class).withResultsSize(1, 5).all();
 
 // Expect at least 1 result
-List<Grid> grids = $(Grid.class).withMinResults(1).all();
+List<Grid> grids = find(Grid.class).withMinResults(1).all();
 ----
 
 
@@ -175,7 +178,7 @@ You may sometimes need to do a query for components nested inside the UI, in a h
 ----
 
 // Search for all 'VerticalLayout's in the view
-TextField textField = $view(VerticalLayout.class)
+TextField textField = findInView(VerticalLayout.class)
         // take the second one and start searching for 'TextField's
         .thenOn(2, TextField.class)
         // filter for disabled 'TextField's
diff --git a/articles/flow/testing/browserless/extensions.adoc b/articles/flow/testing/browserless/extensions.adoc
new file mode 100644
index 0000000000..406b28b08f
--- /dev/null
+++ b/articles/flow/testing/browserless/extensions.adoc
@@ -0,0 +1,130 @@
+---
+title: JUnit 6 Extensions
+page-title: Composition-based browserless testing with JUnit 6 extensions
+description: Use BrowserlessExtension and BrowserlessClassExtension as an alternative to extending BrowserlessTest.
+meta-description: Set up Vaadin browserless tests with JUnit 6 @RegisterExtension when extending a base class is not an option.
+order: 45
+---
+
+
+= JUnit 6 Extensions
+
+[since:com.vaadin:vaadin@V25.2]
+
+Extending [classname]`BrowserlessTest` is the most compact way to write browserless tests, but it requires your test class to use inheritance for the Vaadin setup. When a project already has its own test base class, or you prefer composition over inheritance, the [classname]`BrowserlessExtension` and [classname]`BrowserlessClassExtension` JUnit 6 extensions provide the same functionality without requiring a specific superclass.
+
+[NOTE]
+These extensions are part of the `browserless-test-junit6` artifact. They don't replace [classname]`SpringBrowserlessTest` or [classname]`QuarkusBrowserlessTest` -- for Spring and Quarkus projects, continue to extend those base classes.
+
+
+== When to Use an Extension
+
+Use an extension when any of the following applies:
+
+- The test class already extends another base class that can't be changed.
+- The project standardizes on composition-based JUnit 6 extensions.
+
+
+== Per-Method Lifecycle
+
+[classname]`BrowserlessExtension` creates a fresh Vaadin environment before each test method and tears it down after. Register it as an instance field with [annotationname]`@RegisterExtension`:
+
+[source,java]
+----
+@ViewPackages(classes = CartView.class)
+class CartViewTest {
+
+    @RegisterExtension
+    BrowserlessExtension ext = new BrowserlessExtension();
+
+    @Test
+    void addItemToCart() {
+        CartView view = ext.navigate(CartView.class);
+        ext.test(view.getAddButton()).click();
+
+        Assertions.assertEquals(1, view.getCartSize());
+    }
+}
+----
+
+Navigation, queries, and tester interactions are available as methods on the extension instance -- [methodname]`ext.navigate()`, [methodname]`ext.find()`, [methodname]`ext.findInView()`, [methodname]`ext.test()`, [methodname]`ext.getCurrentView()`, [methodname]`ext.fireShortcut()`, [methodname]`ext.roundTrip()`, and [methodname]`ext.runPendingSignalsTasks()`.
+
+
+== Per-Class Lifecycle
+
+[classname]`BrowserlessClassExtension` initializes the Vaadin environment once in [annotationname]`@BeforeAll` and shares it across all tests in the class. Register it as a `static` field:
+
+[source,java]
+----
+@ViewPackages(classes = CartView.class)
+class CartViewSharedTest {
+
+    @RegisterExtension
+    static BrowserlessClassExtension ext = new BrowserlessClassExtension();
+
+    @BeforeAll
+    static void setup() {
+        ext.navigate(CartView.class);
+    }
+
+    @Test
+    void addItem() {
+        // same UI instance as removeItem
+        ext.test(ext.find(Button.class).withText("Add").single()).click();
+    }
+
+    @Test
+    void removeItem() {
+        // state from addItem is preserved
+    }
+}
+----
+
+The same trade-offs as <<optimizing-tests#sharing-the-vaadin-environment-across-tests, per-class lifecycle with `BrowserlessTest`>> apply: state leaks between tests, so write tests that tolerate leftover state or reset it explicitly.
+
+
+== Configuring the Extension
+
+Both extensions support a builder-style API for configuration, used as an alternative or in addition to annotations.
+
+.Builder API
+[cols="1,2"]
+|===
+| Method | Description
+
+| [methodname]`withViewPackages(Class<?>...)`
+| Adds the packages of the given classes to the route scan. Equivalent to [annotationname]`@ViewPackages(classes = ...)`.
+
+| [methodname]`withViewPackages(String...)`
+| Adds package names (as strings) to the route scan. Equivalent to [annotationname]`@ViewPackages(packages = ...)`.
+
+| [methodname]`withServices(Class<?>...)`
+| Registers custom implementations with the Vaadin [classname]`Lookup` SPI.
+
+| [methodname]`withComponentTesterPackages(String...)`
+| Adds packages to scan for custom [classname]`ComponentTester` implementations. Equivalent to [annotationname]`@ComponentTesterPackages`.
+|===
+
+The [annotationname]`@ViewPackages` annotation still works when placed on the test class; programmatic configuration adds to what the annotation declares.
+
+.Extension with Programmatic Configuration
+[source,java]
+----
+class AdminViewTest {
+
+    @RegisterExtension
+    BrowserlessExtension ext = new BrowserlessExtension()
+            .withViewPackages("com.example.views", "com.example.admin")
+            .withServices(CustomInstantiatorFactory.class)
+            .withComponentTesterPackages("com.example.testers");
+
+    @Test
+    void adminDashboardLoads() {
+        AdminDashboardView view = ext.navigate(AdminDashboardView.class);
+        Assertions.assertNotNull(view);
+    }
+}
+----
+
+
+[discussion-id]`B51F9D4A-2E73-4B18-8C6F-9A3D7E2B1C04`
diff --git a/articles/flow/testing/browserless/getting-started.adoc b/articles/flow/testing/browserless/getting-started.adoc
index 8b236c69b1..0098a67f48 100644
--- a/articles/flow/testing/browserless/getting-started.adoc
+++ b/articles/flow/testing/browserless/getting-started.adoc
@@ -71,7 +71,7 @@ class HelloWorldViewTest extends SpringBrowserlessTest {
         test(helloView.name).setValue("Test");
         test(helloView.sayHello).click();
 
-        Notification notification = $(Notification.class).single();
+        Notification notification = find(Notification.class).single();
         Assertions.assertEquals("Hello Test", test(notification).getText());
     }
 
@@ -127,12 +127,12 @@ Each Vaadin component has a tester tailored to its behavior. For example, a [cla
 
 === Finding Components
 
-Not every component is stored in a view field. For example, the [classname]`Notification` in the test above is created inside a click listener and isn't referenced anywhere in the view. Use the [methodname]`$()` query method to find components in the UI by their type:
+Not every component is stored in a view field. For example, the [classname]`Notification` in the test above is created inside a click listener and isn't referenced anywhere in the view. Use the [methodname]`find()` query method to find components in the UI by their type:
 
 [source,java]
 ----
 // Find the single Notification currently open
-Notification notification = $(Notification.class).single();
+Notification notification = find(Notification.class).single();
 ----
 
 The query API supports filtering by properties, predicates, and scoping to specific parts of the component tree. See <<component-query#, Querying Components>> for details.
@@ -215,4 +215,9 @@ fireShortcut(Key.KEY_S, KeyModifier.CONTROL);
 ----
 
 
+.Multiple Users or Windows?
+[TIP]
+This setup drives a single user with a single window. For tests that need several concurrent users or multiple windows of the same user, see <<multi-user#, Multi-User and Multi-Window Testing>>.
+
+
 [discussion-id]`7F423DA0-1C41-44BA-B832-55C269FA9311`
diff --git a/articles/flow/testing/browserless/locators.adoc b/articles/flow/testing/browserless/locators.adoc
new file mode 100644
index 0000000000..d90cb6a22c
--- /dev/null
+++ b/articles/flow/testing/browserless/locators.adoc
@@ -0,0 +1,180 @@
+---
+title: Component Locators
+page-title: Using locators in Vaadin browserless tests
+description: Drive components with a fluent locator that combines a query filter chain and tester actions.
+meta-description: Use the Vaadin browserless locator API to assert and act on components in a single fluent expression -- replacing find().single() plus test() boilerplate.
+order: 22
+---
+
+
+= Component Locators
+
+[since:com.vaadin:vaadin@V25.2]
+
+A *locator* is a fluent object that combines a [classname]`ComponentQuery` filter chain with the actions of a [classname]`ComponentTester`. A single expression replaces the common [methodname]`test(find(...).single())` pattern and the locator is reusable across UI changes -- its resolution cache rewinds automatically when filters are reapplied, or explicitly via [methodname]`invalidate()`.
+
+[NOTE]
+Locator entry points are currently available on [classname]`BrowserlessUIContext` (the multi-user/multi-window API). For tests that extend [classname]`BrowserlessTest` or use the JUnit 6 extensions, continue to use <<component-query#, component queries>> with [methodname]`test()`.
+
+
+== Generated Entry Points
+
+For every built-in Vaadin component tester, a typed [methodname]`find&lt;Component&gt;()` method is available on the window. The method name mirrors the component type, and the returned locator exposes both the filter chain and the tester's action methods:
+
+[source,java]
+----
+var window = app.newUser().newWindow();
+window.navigate(CartView.class);
+
+window.findTextField().withId("name").setValue("World");
+window.findButton().withCaption("Save").click();
+
+Assertions.assertEquals("Saved: World",
+        window.findSpan().withId("echo").getText());
+----
+
+For testers whose value type isn't pinned by the component (typically [classname]`Grid` and [classname]`ComboBox`), the entry point takes a witness:
+
+[source,java]
+----
+Person first = window.findGrid(Person.class).getRow(0);
+int rows = window.findGrid(Person.class).size();
+----
+
+
+== Filter Chain
+
+Locators share their filter vocabulary with [classname]`ComponentQuery`:
+
+[cols="1,2"]
+|===
+| Method | Description
+
+| [methodname]`withId(String)`
+| Matches the component with the given `id`.
+
+| [methodname]`withCaption(String)` / [methodname]`withCaptionContaining(String)`
+| Matches by exact caption or by caption substring.
+
+| [methodname]`withText(String)` / [methodname]`withTextContaining(String)`
+| Matches by exact text content or by substring.
+
+| [methodname]`withClassName(String...)` / [methodname]`withoutClassName(String...)`
+| Matches components carrying all (or none) of the given CSS class names.
+
+| [methodname]`withTheme(String)` / [methodname]`withoutTheme(String)`
+| Matches components with (or without) the given theme value.
+
+| [methodname]`withAttribute(String)` / [methodname]`withAttribute(String, String)` / [methodname]`withoutAttribute(...)`
+| Matches by attribute presence and value.
+
+| [methodname]`withValue(V)`
+| Matches [interfacename]`HasValue` components whose value equals the given value.
+
+| [methodname]`withCondition(Predicate<C>)`
+| Matches components satisfying a custom predicate.
+
+| [methodname]`inside(Component)` / [methodname]`inside(Locator)`
+| Scopes the search to descendants of the given component (or of the component matched by the given locator -- resolved lazily on first action).
+
+| [methodname]`atIndex(int)`
+| Picks the n-th match (1-based) when the filter chain yields more than one.
+
+| [methodname]`with(UnaryOperator<ComponentQuery<C>>)`
+| Escape hatch for filters not exposed on the locator (for example, [methodname]`withPropertyValue` or [methodname]`withResultsSize`).
+|===
+
+[source,java]
+----
+window.findButton()
+        .with(q -> q.withPropertyValue(Button::getText, "Save"))
+        .click();
+----
+
+
+== Resolution
+
+Most locator chains end in a tester action ([methodname]`click()`, [methodname]`setValue()`, ...), which resolves the locator to a single component and caches the result for the rest of the chain. The base locator also exposes resolution methods directly:
+
+[cols="1,2"]
+|===
+| Method | Description
+
+| [methodname]`component()`
+| Resolves to a single matching component (or the [methodname]`atIndex(n)` pick). Caches the result; subsequent calls return the same instance until the cache is cleared.
+
+| [methodname]`components()`
+| Returns all matching components. Bypasses the cache.
+
+| [methodname]`exists()`
+| Returns [code]`true` if the filter chain matches at least one component.
+
+| [methodname]`invalidate()`
+| Rewinds the cache and clears any [methodname]`atIndex(n)` pick. Use after a UI change that may have replaced or detached the resolved component.
+|===
+
+Filter methods themselves clear only the resolution cache, so a locator can be re-used safely across UI mutations without re-applying its filters. [methodname]`atIndex(n)` is sticky -- it is part of the filter chain -- so only [methodname]`invalidate()` resets the pick.
+
+[source,java]
+----
+var save = window.findButton().withCaption("Save");
+
+window.findTextField().withId("name").setValue("first");
+save.click();
+
+// Same locator instance, fresh resolution after the UI changed
+window.findTextField().withId("name").setValue("second");
+save.invalidate().click();
+----
+
+
+== Seeding a Locator with a Direct Reference
+
+When the test already holds a reference to a specific component (for example, an exposed field of a composite), [methodname]`use(component)` returns a locator pinned to that instance. The locator skips the type-based search and applies any further filter on top of the identity match:
+
+[source,java]
+----
+PersonForm form = window.find(PersonForm.class).single();
+
+window.use(form.nameField).setValue("Ada");
+window.use(form.emailField).setValue("ada@example.com");
+window.use(form.submit).click();
+----
+
+
+== Custom Locators
+
+For composites, page objects, or domain-specific widgets, subclass [classname]`Locator` with the recursive self-type so filter steps stay chainable, and expose the actions you want the test to see. Scope inner queries with [methodname]`inside(this)` so they only match descendants of the resolved composite:
+
+[source,java]
+----
+public class PersonFormLocator
+        extends Locator<PersonForm, PersonFormLocator> {
+
+    public PersonFormLocator() {
+        super(PersonForm.class);
+    }
+
+    public PersonFormLocator fillIn(String name, String email) {
+        new TextFieldLocator().withId("pf-name").inside(this).setValue(name);
+        new TextFieldLocator().withId("pf-email").inside(this).setValue(email);
+        return this;
+    }
+
+    public void submit() {
+        new ButtonLocator().withId("pf-submit").inside(this).click();
+    }
+}
+----
+
+Tests reach the custom locator through [methodname]`find(Supplier&lt;L&gt;)`:
+
+[source,java]
+----
+window.find(PersonFormLocator::new)
+        .fillIn("Ada", "ada@example.com")
+        .submit();
+----
+
+
+[discussion-id]`2E7A4F31-6B98-4D2A-9C18-5F3E8A7B1C04`
diff --git a/articles/flow/testing/browserless/migration.adoc b/articles/flow/testing/browserless/migration.adoc
index 2fe83c182b..42313b7685 100644
--- a/articles/flow/testing/browserless/migration.adoc
+++ b/articles/flow/testing/browserless/migration.adoc
@@ -70,7 +70,7 @@ Rename the test base classes as follows:
 | [classname]`QuarkusBrowserlessTest`
 |===
 
-If you're migrating from JUnit 5 (`vaadin-testbench-unit-junit5`), no other code changes are needed. The test API -- including [methodname]`navigate()`, [methodname]`test()`, and the [methodname]`$()` query methods -- remains the same.
+If you're migrating from JUnit 5 (`vaadin-testbench-unit-junit5`), no other code changes are needed. The test API -- including [methodname]`navigate()`, [methodname]`test()`, and the component query methods ([methodname]`find()` and [methodname]`findInView()`, previously [methodname]`$()` and [methodname]`$view()`) -- remains the same.
 
 If you're migrating from JUnit 4 (`vaadin-testbench-unit`), you also need to update JUnit annotations and imports (e.g., `@Before` → `@BeforeEach`, `Assert` → `Assertions`). See the https://docs.junit.org/current/user-guide/migrating-from-junit4.html[JUnit 5 migration guide] for details.
 
diff --git a/articles/flow/testing/browserless/multi-user.adoc b/articles/flow/testing/browserless/multi-user.adoc
new file mode 100644
index 0000000000..fbd0943c77
--- /dev/null
+++ b/articles/flow/testing/browserless/multi-user.adoc
@@ -0,0 +1,346 @@
+---
+title: Multi-User and Multi-Window Testing
+page-title: Browserless testing for multi-user and multi-window scenarios in Vaadin
+description: Drive multiple concurrent user sessions and multiple browser windows in a single browserless test.
+meta-description: Test Vaadin features that depend on multiple users or multiple windows -- shared state, security isolation, and per-window UI state -- without a browser.
+order: 32
+---
+
+
+= Multi-User and Multi-Window Testing
+
+[since:com.vaadin:vaadin@V25.2]
+
+[classname]`BrowserlessTest` and the JUnit 6 extensions cover the most common scenario: one user, one window. Some features can only be exercised with multiple participants in the same test -- application-wide singletons observed by two users, per-window UI state of the same user, or security context isolation when switching between authenticated users.
+
+The [classname]`BrowserlessApplicationContext` API models this directly. It is a composition-based, lower-level alternative that lets the test create as many user sessions and UI instances as needed, then drive them independently.
+
+
+== When to Use This API
+
+Reach for [classname]`BrowserlessApplicationContext` when:
+
+- Two or more users must be active at the same time -- for example, asserting that a shared service exposes the same state to both, or that one user's mutation does not leak into another user's session.
+- A single user has multiple browser windows open and per-window UI state must remain isolated while session state is shared.
+- A test switches between authenticated users and needs the Spring Security or Quarkus security context to follow the active window.
+
+For tests with a single user and a single window, prefer <<getting-started#, `SpringBrowserlessTest`>>, <<non-spring#, `BrowserlessTest`>>, <<quarkus#, `QuarkusBrowserlessTest`>>, or the <<extensions#, JUnit 6 extensions>>.
+
+
+== Application, User, and Window
+
+The API exposes three nested contexts that mirror Vaadin's runtime hierarchy:
+
+[cols="1,3"]
+|===
+| [classname]`BrowserlessApplicationContext`
+| One [classname]`VaadinService` and one servlet, shared across every user and window the test creates.
+
+| [classname]`BrowserlessUserContext`
+| One [classname]`VaadinSession` and the security state of a single logical user. A user can own many windows.
+
+| [classname]`BrowserlessUIContext`
+| One [classname]`UI` instance -- a single browser window. Provides the testing DSL ([methodname]`navigate`, [methodname]`find`, [methodname]`test`, ...).
+|===
+
+[NOTE]
+All three contexts are *thread-affine*: they must be created, used, and closed on the same thread. Driving the same context from parallel test threads is not supported.
+
+When the test calls a DSL method on any [classname]`BrowserlessUIContext`, the API automatically switches the thread-local Vaadin state -- [classname]`VaadinService`, [classname]`VaadinSession`, [classname]`UI`, request, response, and the security context -- to that window's user. Interleaving calls on different windows is therefore safe without any explicit context switch.
+
+
+== Setting Up the Application Context
+
+The application context is built once per test, typically in [annotationname]`@BeforeEach`, and closed in [annotationname]`@AfterEach`. Use try-with-resources or call [methodname]`close()` explicitly: closing the application context cascades to every user and window it created.
+
+[methodname]`create()` accepts the packages that contain [annotationname]`@Route`-annotated views, either as package names or as classes whose packages should be scanned. Passing classes plays well with IDE refactoring and is the preferred form.
+
+.Plain Java
+[source,java]
+----
+try (var app = BrowserlessApplicationContext.create(CartView.class)) {
+    var user = app.newUser();
+    var window = user.newWindow();
+    window.navigate(CartView.class);
+    // assertions...
+}
+----
+
+For Spring and Quarkus, dedicated factories pre-wire the framework-specific servlet and lookup initializer:
+
+.Spring
+[source,java]
+----
+@ExtendWith(SpringExtension.class)
+@ContextConfiguration(classes = ShopTestConfig.class)
+class CartViewMultiUserTest {
+
+    @Autowired
+    private ApplicationContext applicationContext;
+
+    private BrowserlessApplicationContext app;
+
+    @BeforeEach
+    void setUp() {
+        app = SpringBrowserlessApplicationContext.create(applicationContext,
+                CartView.class);
+    }
+
+    @AfterEach
+    void tearDown() {
+        app.close();
+    }
+}
+----
+
+.Quarkus
+[source,java]
+----
+@QuarkusTest
+class CartViewMultiUserTest {
+
+    private BrowserlessApplicationContext app;
+
+    @BeforeEach
+    void setUp() {
+        app = QuarkusBrowserlessApplicationContext.create(CartView.class);
+    }
+
+    @AfterEach
+    void tearDown() {
+        app.close();
+    }
+}
+----
+
+
+== Creating Users and Windows
+
+[methodname]`newUser()` returns a fresh [classname]`BrowserlessUserContext` with its own [classname]`VaadinSession`. [methodname]`newWindow()` creates a new [classname]`UI` for that user. Different users have independent sessions; different windows of the same user share a session but have independent [classname]`UI` instances.
+
+.Two Users, Independent Sessions
+[source,java]
+----
+var alice = app.newUser();
+var aliceWindow = alice.newWindow();
+
+var bob = app.newUser();
+var bobWindow = bob.newWindow();
+
+Assertions.assertNotSame(alice.getSession(), bob.getSession());
+Assertions.assertNotSame(aliceWindow.getUI(), bobWindow.getUI());
+----
+
+Every window exposes the same testing DSL as [classname]`BrowserlessTest`, scoped to that window -- no explicit activation is required:
+
+- [methodname]`window.navigate(...)` -- navigate the window to a view.
+- [methodname]`window.findButton()`, [methodname]`window.findTextField()`, [methodname]`window.findGrid(Class<V>)`, ... -- typed locator entry points that combine a filter chain with the component's tester actions in one fluent expression; see <<locators#, Component Locators>>.
+- [methodname]`window.find(Class)` and [methodname]`window.findInView(Class)` -- locate components in this window. Returns a [classname]`ComponentQuery`; see <<component-query#, Querying Components>>.
+- [methodname]`window.test(component)` -- wrap a component in a tester that simulates user actions like [methodname]`click()` and [methodname]`setValue()`. Returns a typed tester matched to the component's type; see <<component-testers#, Component Testers>>.
+- [methodname]`window.getCurrentView()` and [methodname]`window.roundTrip()` -- convenience accessors that mirror their [classname]`BrowserlessTest` counterparts.
+
+.Two Users Sharing Application-Level State
+[source,java]
+----
+var w1 = app.newUser().newWindow();
+w1.navigate(SharedCounterView.class);
+
+var w2 = app.newUser().newWindow();
+w2.navigate(SharedCounterView.class);
+
+// w1 mutates a shared static counter
+w1.findButton().withText("Increment").click();
+Assertions.assertEquals("Count: 1", w1.findParagraph().getText());
+
+// w2 still shows its own UI state until it refreshes
+Assertions.assertEquals("Count: 0", w2.findParagraph().getText());
+
+w2.findButton().withText("Refresh").click();
+Assertions.assertEquals("Count: 1", w2.findParagraph().getText());
+----
+
+.Same User, Two Windows, Independent UI State
+[source,java]
+----
+var user = app.newUser();
+var w1 = user.newWindow();
+var w2 = user.newWindow();
+
+w1.navigate(CartView.class);
+w2.navigate(CheckoutView.class);
+
+// Each window holds its own current view
+Assertions.assertInstanceOf(CartView.class, w1.getCurrentView());
+Assertions.assertInstanceOf(CheckoutView.class, w2.getCurrentView());
+
+// Session is the same; UIs are not
+Assertions.assertSame(user.getSession(), w1.getUI().getSession());
+Assertions.assertNotSame(w1.getUI(), w2.getUI());
+----
+
+
+== Authenticated Users with Spring Security
+
+When Spring Security is on the classpath, [methodname]`SpringBrowserlessApplicationContext.createSecured()` returns a [classname]`SecuredBrowserlessApplicationContext<Authentication>` that exposes credential-aware [methodname]`newUser(...)` overloads. The handler installs the user's [classname]`Authentication` on the calling thread before [classname]`SessionInit` listeners fire, mirroring the order of operations in a real Vaadin + Spring Security request.
+
+When the test switches between windows belonging to different users, the outgoing user's [classname]`SecurityContext` is saved and the incoming user's snapshot is restored automatically.
+
+.Multi-User Security Isolation
+[source,java]
+----
+@ExtendWith(SpringExtension.class)
+@ContextConfiguration(classes = SecurityTestConfig.class)
+class MultiUserSecurityTest {
+
+    @Autowired
+    private ApplicationContext applicationContext;
+
+    private SecuredBrowserlessApplicationContext<Authentication> app;
+
+    @BeforeEach
+    void setUp() {
+        app = SpringBrowserlessApplicationContext.createSecured(
+                applicationContext, ProtectedView.class);
+    }
+
+    @AfterEach
+    void tearDown() {
+        app.close();
+    }
+
+    @Test
+    void switchingUsers_securityContextFollowsActiveWindow() {
+        var admin = app.newUser("john", "ADMIN").newWindow();
+        var anon = app.newUser().newWindow();
+
+        admin.navigate(ProtectedView.class);
+        Assertions.assertInstanceOf(ProtectedView.class,
+                admin.getCurrentView());
+
+        // Switching to the anonymous user restores their (empty) context;
+        // the protected view redirects to login.
+        Assertions.assertThrows(IllegalArgumentException.class,
+                () -> anon.navigate(ProtectedView.class));
+        Assertions.assertInstanceOf(LoginView.class, anon.getCurrentView());
+
+        // Switching back restores admin's authentication.
+        admin.navigate(ProtectedView.class);
+        Assertions.assertInstanceOf(ProtectedView.class,
+                admin.getCurrentView());
+    }
+}
+----
+
+[methodname]`newUser(String username, String... roles)` is a convenience that produces an [classname]`Authentication` with the conventions of [annotationname]`@WithMockUser`. To install a custom [classname]`Authentication` directly, pass it to [methodname]`newUser(Authentication)`. Calling [methodname]`newUser()` without arguments creates an anonymous user; the handler installs Spring's [classname]`AnonymousAuthenticationToken`.
+
+
+== Authenticated Users with Quarkus Security
+
+The Quarkus factory follows the same pattern with [classname]`SecurityIdentity` as the credential type:
+
+.Quarkus Multi-User Test
+[source,java]
+----
+@QuarkusTest
+@TestProfile(SecurityTestConfig.class)
+class MultiUserSecurityTest {
+
+    private SecuredBrowserlessApplicationContext<SecurityIdentity> app;
+
+    @BeforeEach
+    void setUp() {
+        app = QuarkusBrowserlessApplicationContext
+                .createSecured(ProtectedView.class);
+    }
+
+    @AfterEach
+    void tearDown() {
+        app.close();
+    }
+
+    @Test
+    void authenticatedUser_byUsernameAndRoles_seesProtectedView() {
+        var window = app.newUser("john", "USER").newWindow();
+
+        window.navigate(ProtectedView.class);
+        Assertions.assertInstanceOf(ProtectedView.class,
+                window.getCurrentView());
+    }
+
+    @Test
+    void authenticatedUser_byIdentity_seesProtectedView() {
+        SecurityIdentity identity = QuarkusSecurityIdentity.builder()
+                .setPrincipal(new QuarkusPrincipal("john"))
+                .addRoles(Set.of("USER"))
+                .setAnonymous(false)
+                .build();
+
+        var window = app.newUser(identity).newWindow();
+
+        window.navigate(ProtectedView.class);
+        Assertions.assertInstanceOf(ProtectedView.class,
+                window.getCurrentView());
+    }
+}
+----
+
+As with the Spring factory, [methodname]`newUser()` without arguments creates an anonymous user, and cross-user window switches save and restore the active [classname]`SecurityIdentity` automatically.
+
+
+== Customizing the Application Context
+
+For advanced setups, [classname]`BrowserlessApplicationContext.Builder` exposes the same configuration knobs as the framework-specific factories. Construct one directly and call [methodname]`build()` for an unsecured context, or chain [methodname]`withSecurityContextHandler(...)` to transition to a typed [classname]`SecuredBrowserlessApplicationContext.Builder<C>` whose [methodname]`build()` returns the credential-aware variant.
+
+.Builder Configuration
+[cols="1,2"]
+|===
+| Method | Purpose
+
+| [methodname]`withViewPackages(String...)` / [methodname]`withViewPackages(Class<?>...)`
+| Adds packages to scan for [annotationname]`@Route`-annotated views. Successive calls accumulate.
+
+| [methodname]`withComponentTesterPackages(String...)` / [methodname]`withComponentTesterPackages(Class<?>...)`
+| Adds packages to scan for custom [classname]`ComponentTester` implementations.
+
+| [methodname]`withSecurityContextHandler(SecurityContextHandler<C>)`
+| Enables credential-aware [methodname]`newUser(...)` overloads. Transitions to the typed [classname]`SecuredBrowserlessApplicationContext.Builder<C>`.
+
+| [methodname]`withServletFactory(...)`
+| Replaces the default mock servlet -- for example, to plug in a framework-specific servlet.
+
+| [methodname]`withUIFactory(UIFactory)`
+| Provides a custom [classname]`UI` subclass for every window created by the context.
+
+| [methodname]`withLookupServices(Class<?>...)`
+| Registers Vaadin [classname]`Lookup` service implementations.
+
+| [methodname]`withCloseHook(Runnable)`
+| Registers a callback to run after the context tears down -- intended for releasing framework-specific state.
+|===
+
+For one-off tweaks without holding on to a builder reference, [methodname]`BrowserlessApplicationContext.create(UnaryOperator<Builder>)` and the corresponding [methodname]`createSecured(Function<Builder, SecuredBuilder<C>>)` accept a configurer:
+
+[source,java]
+----
+try (var app = BrowserlessApplicationContext.create(b -> b
+        .withViewPackages(CartView.class)
+        .withCloseHook(() -> testFixtures.reset()))) {
+    // ...
+}
+----
+
+The Spring and Quarkus factories expose [methodname]`builder(...)` overloads that return a pre-wired builder for projects that need to add further customizations on top of the framework defaults.
+
+
+== Pitfalls and Guarantees
+
+Common gotchas worth keeping in mind:
+
+- *Always close the application context.* Use try-with-resources or call [methodname]`close()` in [annotationname]`@AfterEach`. Closing the application cascades to every user and window. Leaking a context across tests leaves Vaadin thread-locals pointing at torn-down state.
+- *No parallel access.* Every context is thread-affine. Driving the same [classname]`BrowserlessApplicationContext` from multiple threads in the same test is unsupported.
+- *Security snapshot is per user, not per window.* Two windows of the same user share one snapshot; a security mutation made while one window is active is visible to the user's other windows. The snapshot is re-captured only on cross-user switches.
+- *Calling Vaadin APIs directly.* DSL methods on [classname]`BrowserlessUIContext` activate the window automatically. If the test reaches for [methodname]`UI.getCurrent()`, [methodname]`VaadinSession.getCurrent()`, or [classname]`SecurityContextHolder` between DSL calls, call [methodname]`window.activate()` first to make sure the thread-locals reflect the intended window.
+- *Anonymous users still go through the handler.* On a secured context, [methodname]`newUser()` with no arguments delegates to the handler, which installs its anonymous-equivalent state (for example, Spring's [classname]`AnonymousAuthenticationToken`).
+
+
+[discussion-id]`9C4E8A2D-6F31-4B72-9A8F-5D7E1C3B4F60`
diff --git a/articles/flow/testing/browserless/non-spring.adoc b/articles/flow/testing/browserless/non-spring.adoc
index 8c16203bf9..e075861609 100644
--- a/articles/flow/testing/browserless/non-spring.adoc
+++ b/articles/flow/testing/browserless/non-spring.adoc
@@ -43,7 +43,7 @@ class HelloWorldViewTest extends BrowserlessTest {
         test(helloView.name).setValue("Test");
         test(helloView.sayHello).click();
 
-        Notification notification = $(Notification.class).single();
+        Notification notification = find(Notification.class).single();
         Assertions.assertEquals("Hello Test", test(notification).getText());
     }
 
@@ -52,6 +52,14 @@ class HelloWorldViewTest extends BrowserlessTest {
 
 All the features described in the <<getting-started#, Getting Started>> guide — package scanning, navigation, component testing, and component queries — work the same way with [classname]`BrowserlessTest`. Replace [classname]`SpringBrowserlessTest` with [classname]`BrowserlessTest` and remove the [annotationname]`@SpringBootTest` annotation.
 
+.Already Have a Test Base Class?
+[TIP]
+If your project already has its own test base class, you can still get the Vaadin environment without extending [classname]`BrowserlessTest`. See <<extensions#, JUnit 6 Extensions>> for the composition-based setup.
+
+.Multiple Users or Windows?
+[TIP]
+This setup drives a single user with a single window. For tests that need several concurrent users or multiple windows of the same user, see <<multi-user#, Multi-User and Multi-Window Testing>>.
+
 
 == Running Tests
 
diff --git a/articles/flow/testing/browserless/optimizing-tests.adoc b/articles/flow/testing/browserless/optimizing-tests.adoc
index a7a151af83..98afba6ead 100644
--- a/articles/flow/testing/browserless/optimizing-tests.adoc
+++ b/articles/flow/testing/browserless/optimizing-tests.adoc
@@ -65,7 +65,7 @@ class ViewTest extends SpringBrowserlessTest {
         test(helloView.name).setValue("Test");
         test(helloView.sayHello).click();
 
-        Notification notification = $(Notification.class).single();
+        Notification notification = find(Notification.class).single();
         Assertions.assertEquals("Hello Test", test(notification).getText());
     }
 }
@@ -81,4 +81,44 @@ class ViewTestConfig {
 ----
 
 
+== Sharing the Vaadin Environment Across Tests
+
+[since:com.vaadin:vaadin@V25.2]
+
+By default, the Vaadin environment -- the session, the UI, and all routes -- is created before every test method and torn down after. For classes with many tests that navigate to views sharing the same [classname]`MainLayout`, this setup cost can dominate the test runtime.
+
+Annotating the test class with [annotationname]`@TestInstance(Lifecycle.PER_CLASS)` initializes the environment once in [annotationname]`@BeforeAll` and shares the same [classname]`UI` instance across all test methods in the class. This can significantly reduce runtime for suites with hundreds of tests on the same view.
+
+.Per-Class Lifecycle Example
+[source,java]
+----
+@ViewPackages(classes = CartView.class)
+@TestInstance(TestInstance.Lifecycle.PER_CLASS)
+class CartViewTest extends BrowserlessTest {
+
+    @BeforeAll
+    void setup() {
+        navigate(CartView.class);
+    }
+
+    @Test
+    void addItem_increasesCartSize() {
+        // same UI instance as the other tests
+        test(find(Button.class).withText("Add").single()).click();
+    }
+
+    @Test
+    void removeItem_decreasesCartSize() {
+        // state from the previous test is preserved
+    }
+}
+----
+
+[WARNING]
+With a shared environment, state leaks between tests. Tests must either tolerate leftover state or reset it explicitly -- for example, by re-navigating to the view in a [annotationname]`@BeforeEach` method. Prefer per-class lifecycle for read-only or independent interactions; stick with the default per-method lifecycle when tests mutate shared state in conflicting ways.
+
+[NOTE]
+This optimization applies only to [classname]`BrowserlessTest`. [classname]`SpringBrowserlessTest` and [classname]`QuarkusBrowserlessTest` still reinitialize the Vaadin environment before each test method, so [annotationname]`@TestInstance(PER_CLASS)` on those classes doesn't share the Vaadin environment -- though it can still be useful for sharing other per-class state.
+
+
 [discussion-id]`A3B7E2F1-5D89-4C6A-9E12-7F4A8B3C6D50`
diff --git a/articles/flow/testing/browserless/overlay-components.adoc b/articles/flow/testing/browserless/overlay-components.adoc
index a047cd96a8..47fff1064c 100644
--- a/articles/flow/testing/browserless/overlay-components.adoc
+++ b/articles/flow/testing/browserless/overlay-components.adoc
@@ -9,7 +9,7 @@ order: 25
 
 = Testing Overlay Components
 
-Some Vaadin components render their content in overlays, which means their child components aren't part of the normal view component tree. Standard component queries using [methodname]`$()` can't find components inside these overlays. Instead, use the component-specific testers to interact with overlay content.
+Some Vaadin components render their content in overlays, which means their child components aren't part of the normal view component tree. Standard top-level component queries ([methodname]`find()`) can't reach components inside these overlays. Instead, use the component-specific testers to interact with overlay content.
 
 
 == Context Menu
@@ -54,7 +54,7 @@ Assertions.assertFalse(menu_.isItemChecked("Bold"));
 
 === Finding Components in the Menu
 
-If you've added custom components (not just text items) to the menu, use the tester's [methodname]`find()` method instead of the standard [methodname]`$()` query. Call [methodname]`open()` first if you need the components to be in an attached state.
+If you've added custom components (not just text items) to the menu, use the tester's [methodname]`find()` method on the wrapped component (e.g., [methodname]`test(menu).find(...)`) instead of the top-level [methodname]`find()` query. Call [methodname]`open()` first if you need the components to be in an attached state.
 
 [source,java]
 ----
@@ -83,12 +83,12 @@ gridMenu_.clickItem("Delete");
 
 === Common Pitfalls
 
-Using [methodname]`$()` to search for components inside a context menu doesn't work because the overlay content isn't part of the main component tree. Use [methodname]`test(contextMenu).find()` or [methodname]`test(contextMenu).clickItem()` instead.
+Using a top-level [methodname]`find()` to search for components inside a context menu doesn't work because the overlay content isn't part of the main component tree. Use [methodname]`test(contextMenu).find()` or [methodname]`test(contextMenu).clickItem()` instead.
 
 [source,java]
 ----
 // This does NOT work -- won't find items inside the context menu
-Button menuButton = $(Button.class).withText("My Action").single(); // throws
+Button menuButton = find(Button.class).withText("My Action").single(); // throws
 
 // Use the tester's find() method instead
 Button menuButton = test(contextMenu).find(Button.class)
diff --git a/articles/flow/testing/browserless/quarkus.adoc b/articles/flow/testing/browserless/quarkus.adoc
index cbe2831579..f533bf5078 100644
--- a/articles/flow/testing/browserless/quarkus.adoc
+++ b/articles/flow/testing/browserless/quarkus.adoc
@@ -24,7 +24,7 @@ class ViewTest extends QuarkusBrowserlessTest {
         test(helloView.name).setValue("Test");
         test(helloView.sayHello).click();
 
-        Notification notification = $(Notification.class).single();
+        Notification notification = find(Notification.class).single();
         Assertions.assertEquals("Hello Test", test(notification).getText());
     }
 }
@@ -154,7 +154,7 @@ class ViewSecurityTest extends QuarkusBrowserlessTest {
         // public view is default page
         Assertions.assertInstanceOf(PublicView.class, getCurrentView());
 
-        Anchor anchor = $(Anchor.class).withText("Sign in").single();
+        Anchor anchor = find(Anchor.class).withText("Sign in").single();
         Assertions.assertTrue(
                 test(anchor).isUsable(),
                 "Sign in link should be available for anonymous user");
@@ -166,7 +166,7 @@ class ViewSecurityTest extends QuarkusBrowserlessTest {
         navigate(AdminRoleView.class);
 
         Assertions.assertTrue(
-                $(Avatar.class).single().isVisible(),
+                find(Avatar.class).single().isVisible(),
                 "Avatar should be visible for logged users");
     }
 }
@@ -174,4 +174,10 @@ class ViewSecurityTest extends QuarkusBrowserlessTest {
 <1> Sets a profile to activate Vaadin access control feature.
 <2> Uses Quarkus test security annotations.
 
+
+.Multiple Users or Windows?
+[TIP]
+This setup drives a single user with a single window. For tests that need several concurrent users or multiple windows of the same user, see <<multi-user#, Multi-User and Multi-Window Testing>>.
+
+
 [discussion-id]`61B2F8E5-448E-4C36-82E3-D492712ECE67`
diff --git a/articles/flow/testing/browserless/snapshots.adoc b/articles/flow/testing/browserless/snapshots.adoc
index 464f076fdf..7a19fcddbd 100644
--- a/articles/flow/testing/browserless/snapshots.adoc
+++ b/articles/flow/testing/browserless/snapshots.adoc
@@ -79,7 +79,7 @@ And a test for it:
 public void clickSayHello_showsGreeting() {
     HelloWorldView view = navigate(HelloWorldView.class);
     test(view.sayHello).click();
-    Notification notification = $(Notification.class).single();
+    Notification notification = find(Notification.class).single();
     assertEquals("Hello World", test(notification).getText());
 }
 ----
@@ -104,10 +104,10 @@ Without the snapshot, you'd have to guess. With it, the empty `value=''` points
 
 == Tips
 
-- **Look for what's missing.** If a query like `$(Notification.class).single()` fails, the snapshot shows you that the component simply isn't there. Check the tree for clues about why it wasn't created.
+- **Look for what's missing.** If a query like `find(Notification.class).single()` fails, the snapshot shows you that the component simply isn't there. Check the tree for clues about why it wasn't created.
 - **Check property values.** When an assertion on a component's text or value fails, find that component in the tree and compare its actual properties to what you expected.
-- **Watch for unexpected components.** If `$(Button.class).single()` fails because multiple buttons were found, the snapshot shows you all of them so you can narrow your query.
-- **Inspect the layout hierarchy.** If a component appears in the tree but a scoped query like `$view(TextField.class)` can't find it, the snapshot helps you see whether the component is nested inside the expected parent.
+- **Watch for unexpected components.** If `find(Button.class).single()` fails because multiple buttons were found, the snapshot shows you all of them so you can narrow your query.
+- **Inspect the layout hierarchy.** If a component appears in the tree but a scoped query like `findInView(TextField.class)` can't find it, the snapshot helps you see whether the component is nested inside the expected parent.
 
 
 [discussion-id]`99487CB3-54AB-4C0A-8A46-926A527EB381`
diff --git a/articles/flow/testing/browserless/spring-security.adoc b/articles/flow/testing/browserless/spring-security.adoc
index 429c46b46e..cc1f7b3964 100644
--- a/articles/flow/testing/browserless/spring-security.adoc
+++ b/articles/flow/testing/browserless/spring-security.adoc
@@ -86,7 +86,7 @@ public class ViewSecurityTest extends SpringBrowserlessTest {
         // public view is default page
         Assertions.assertInstanceOf(PublicView.class, getCurrentView());
 
-        Anchor anchor = $(Anchor.class).withText("Sign in").single();
+        Anchor anchor = find(Anchor.class).withText("Sign in").single();
         Assertions.assertTrue(
                 test(anchor).isUsable(),
                 "Sign in link should be available for anonymous user");
@@ -98,7 +98,7 @@ public class ViewSecurityTest extends SpringBrowserlessTest {
         navigate(AdminRoleView.class);
 
         Assertions.assertTrue(
-                $(Avatar.class).single().isVisible(),
+                find(Avatar.class).single().isVisible(),
                 "Avatar should be visible for logged users");
     }
 }
@@ -118,7 +118,7 @@ class SpringUnitSecurityTest extends SpringBrowserlessTest {
         navigate(AdminRoleView.class);
 
         Assertions.assertTrue(
-                $(Avatar.class).single().isVisible(),
+                find(Avatar.class).single().isVisible(),
                 "Avatar should be visible for logged users");
     }
 
@@ -169,4 +169,9 @@ class SecurityTestConfig {
 ----
 
 
+.Multiple Users or Windows?
+[TIP]
+This setup drives a single user with a single window. For tests that need several concurrent users or multiple windows of the same user, see <<multi-user#, Multi-User and Multi-Window Testing>>.
+
+
 [discussion-id]`2A8B3F1E-9C47-4D5A-B621-8E3F2A7C9D10`