Alternative Locator API that returns "testing" API instead of raw components

junit6/pom.xml

@@ -153,6 +153,22 @@
                         <goals>
                             <goal>testCompile</goal>
                         </goals>
+                        <configuration>
+                            <!-- End-user-style configuration: run the locator
+                                 processor on junit6's own test sources, with
+                                 a project-specific entry-point FQN so we don't
+                                 collide with shared's GeneratedLocators. -->
+                            <annotationProcessorPaths>
+                                <path>
+                                    <groupId>com.vaadin</groupId>
+                                    <artifactId>browserless-test-locator-processor</artifactId>
+                                    <version>${project.version}</version>
+                                </path>
+                            </annotationProcessorPaths>
+                            <compilerArgs>
+                                <arg>-Alocator.entrypoint.fqn=com.example.locator.AppLocators</arg>
+                            </compilerArgs>
+                        </configuration>
                     </execution>
                 </executions>
             </plugin>

junit6/src/test/java/com/example/locator/LocatorDemoView.java

@@ -0,0 +1,79 @@
+/*
+ * Copyright 2000-2026 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.example.locator;
+
+import java.util.List;
+
+import com.vaadin.flow.component.Composite;
+import com.vaadin.flow.component.button.Button;
+import com.vaadin.flow.component.grid.Grid;
+import com.vaadin.flow.component.html.Span;
+import com.vaadin.flow.component.orderedlayout.VerticalLayout;
+import com.vaadin.flow.component.textfield.TextField;
+import com.vaadin.flow.router.Route;
+
+@Route("locator-demo")
+public class LocatorDemoView extends VerticalLayout {
+
+    public record Person(String name, int age) {
+    }
+
+    public LocatorDemoView() {
+        TextField name = new TextField("Name");
+        name.setId("name");
+
+        Span echo = new Span("");
+        echo.setId("echo");
+
+        Button save = new Button("Save",
+                e -> echo.setText("Saved: " + name.getValue()));
+        save.setId("save");
+
+        Button clear = new Button("Clear", e -> name.setValue(""));
+
+        Grid<Person> people = new Grid<>(Person.class);
+        people.setItems(List.of(new Person("Alice", 30), new Person("Bob", 25),
+                new Person("Carol", 40)));
+        people.addItemClickListener(
+                event -> echo.setText("Clicked: " + event.getItem().name()));
+
+        PersonForm personForm = new PersonForm(echo);
+        personForm.setId("person-form");
+
+        add(name, save, clear, echo, people, personForm);
+    }
+
+    /**
+     * Demo composite mirroring an app-defined widget — exercises the
+     * custom-locator extension point.
+     */
+    public static class PersonForm extends Composite<VerticalLayout> {
+
+        public final TextField nameField = new TextField("Name");
+        public final TextField emailField = new TextField("Email");
+        public final Button submit;
+
+        public PersonForm(Span echo) {
+            nameField.setId("pf-name");
+            emailField.setId("pf-email");
+            submit = new Button("Submit",
+                    e -> echo.setText("Submitted: " + nameField.getValue()
+                            + " <" + emailField.getValue() + ">"));
+            submit.setId("pf-submit");
+            getContent().add(nameField, emailField, submit);
+        }
+    }
+}

junit6/src/test/java/com/example/locator/PersonFormLocator.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2000-2026 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.example.locator;
+
+import com.example.locator.LocatorDemoView.PersonForm;
+
+import com.vaadin.browserless.locator.Locator;
+import com.vaadin.flow.component.button.ButtonLocator;
+import com.vaadin.flow.component.textfield.TextFieldLocator;
+
+/**
+ * App-side locator for a composite. Demonstrates two reuse patterns:
+ *
+ * <ul>
+ * <li>Subclass {@link Locator} with the recursive self-type so filter steps
+ * stay chainable.</li>
+ * <li>Compose built-in locators (TextField, Button) and scope them with
+ * {@code inside(this)} so sub-queries only see descendants of the resolved
+ * composite.</li>
+ * </ul>
+ */
+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();
+    }
+}

junit6/src/test/java/com/vaadin/browserless/BrowserlessBaseClassTest.java

@@ -83,6 +83,7 @@ void extendingBaseClass_runTest_routesAreDiscovered() {
             allViews.add(com.example.multiuser.SharedCounterView.class);
             allViews.add(com.example.multiuser.ExternalNavigationView.class);
             allViews.add(com.example.multiuser.SimpleView.class);
+            allViews.add(com.example.locator.LocatorDemoView.class);
             Assertions.assertEquals(allViews.size(), routes.size());
             Assertions.assertTrue(routes.containsAll(allViews));
         }

junit6/src/test/java/com/vaadin/browserless/GeneratedAggregatorsTest.java

@@ -0,0 +1,112 @@
+/*
+ * Copyright 2000-2026 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.vaadin.browserless;
+
+import java.lang.reflect.Method;
+import java.util.Arrays;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * Reflection assertions pinning structural invariants of the locator
+ * processor's output:
+ * <ul>
+ * <li>{@code GeneratedLocators} is core-only — no commercial entries leak in,
+ * so loading it does not require commercial Vaadin classes on the classpath.
+ * <li>{@code GeneratedCommercialLocators} carries the commercial entries.
+ * <li>{@code CommercialLocators} unions both via interface inheritance.
+ * <li>The end-user-style aggregator emitted by junit6's test-compile
+ * ({@code com.example.locator.AppLocators}) is scoped to this module's own
+ * {@code @Tests}-annotated testers and does not regenerate shared.jar's.
+ * </ul>
+ */
+class GeneratedAggregatorsTest {
+
+    @Test
+    void defaultAggregatorDoesNotContainCommercialEntries() throws Exception {
+        Class<?> agg = Class
+                .forName("com.vaadin.browserless.locator.GeneratedLocators");
+        Set<String> methods = methodNames(agg.getDeclaredMethods());
+        assertTrue(methods.contains("findButton"),
+                "core aggregator should expose findButton, was: " + methods);
+        assertFalse(methods.contains("findChart"),
+                "core aggregator must not expose findChart: " + methods);
+    }
+
+    @Test
+    void commercialAggregatorContainsChartAndNotCoreEntries() throws Exception {
+        Class<?> agg = Class.forName(
+                "com.vaadin.browserless.locator.GeneratedCommercialLocators");
+        Set<String> methods = methodNames(agg.getDeclaredMethods());
+        assertTrue(methods.contains("findChart"),
+                "commercial aggregator should expose findChart, was: "
+                        + methods);
+        assertFalse(methods.contains("findButton"),
+                "commercial aggregator should not duplicate core entries: "
+                        + methods);
+    }
+
+    @Test
+    void commercialLocatorsMixinUnionsCoreAndCommercial() throws Exception {
+        Class<?> mixin = Class
+                .forName("com.vaadin.browserless.locator.CommercialLocators");
+        // getMethods() walks inherited interfaces; getDeclaredMethods()
+        // would only show what's declared on CommercialLocators itself.
+        Set<String> methods = methodNames(mixin.getMethods());
+        assertTrue(methods.contains("findButton"),
+                "CommercialLocators should surface core findButton, was: "
+                        + methods);
+        assertTrue(methods.contains("findChart"),
+                "CommercialLocators should surface commercial findChart, was: "
+                        + methods);
+    }
+
+    @Test
+    void downstreamAggregatorEmittedAtConfiguredFqn() throws Exception {
+        // junit6's test-compile wires the processor with
+        // -Alocator.entrypoint.fqn=com.example.locator.AppLocators
+        // and the processor only scans junit6's own @Tests-annotated test
+        // sources, not shared's testers (which are pre-compiled in
+        // shared.jar). This pins both behaviours.
+        Class<?> downstream = Class.forName("com.example.locator.AppLocators");
+        assertTrue(downstream.isInterface(),
+                "downstream aggregator should be an interface");
+
+        Set<String> methods = methodNames(downstream.getDeclaredMethods());
+        assertTrue(methods.contains("findTestComponent"),
+                "downstream aggregator should include local TestComponent, was: "
+                        + methods);
+        assertTrue(methods.contains("findTestComponentForConcreteTester"),
+                "downstream aggregator should include local TestComponentForConcreteTester, was: "
+                        + methods);
+        assertFalse(methods.contains("findButton"),
+                "downstream aggregator should not regenerate framework entries: "
+                        + methods);
+        assertFalse(methods.contains("findChart"),
+                "downstream aggregator should not regenerate framework entries: "
+                        + methods);
+    }
+
+    private static Set<String> methodNames(Method[] methods) {
+        return Arrays.stream(methods).map(Method::getName)
+                .collect(Collectors.toSet());
+    }
+}