From 51f84b5abe3fa689228843bd73f48038b9cd554f Mon Sep 17 00:00:00 2001
From: Matti Tahvonen <matti@vaadin.com>
Date: Thu, 21 May 2026 11:27:42 +0000
Subject: [PATCH 01/10] feat: add withLabel and withAriaLabel filters (closes
 #42)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Common Playwright pattern — selecting form fields by their visible label
or buttons by their assistive-tech label — wasn't expressible directly
in the locator/query API. withCaption() exists but is intentionally
broader (it matches label, text, or placeholder depending on component)
and that ambiguity can surprise users.

Adds four new filters at both the ComponentQuery and Locator layers:

  - withLabel(text)            — exact match on the "label" property
  - withLabelContaining(text)  — substring match on the "label" property
  - withAriaLabel(text)        — exact match on the "aria-label" attribute
  - withAriaLabelContaining(text) — substring match on "aria-label"

Backed by new predicates in ElementConditions (hasLabel, labelContains,
hasAriaLabel, ariaLabelContains) so the same checks are reusable from
withCondition. Unit-tested at the query layer and integration-tested at
the locator layer; LocatorDemoView grows an aria-label on Clear and the
inner PersonForm uses distinct labels so withLabel matches resolve to
single elements.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../com/example/locator/LocatorDemoView.java  |  5 +-
 .../browserless/ComponentQueryTest.java       | 91 +++++++++++++++++++
 .../vaadin/browserless/LocatorApiTest.java    | 43 +++++++++
 .../vaadin/browserless/ComponentQuery.java    | 56 ++++++++++++
 .../vaadin/browserless/ElementConditions.java | 61 +++++++++++++
 .../vaadin/browserless/locator/Locator.java   | 41 +++++++++
 6 files changed, 295 insertions(+), 2 deletions(-)

diff --git a/junit6/src/test/java/com/example/locator/LocatorDemoView.java b/junit6/src/test/java/com/example/locator/LocatorDemoView.java
index 5540430a..635eb33d 100644
--- a/junit6/src/test/java/com/example/locator/LocatorDemoView.java
+++ b/junit6/src/test/java/com/example/locator/LocatorDemoView.java
@@ -43,6 +43,7 @@ public LocatorDemoView() {
         save.setId("save");
 
         Button clear = new Button("Clear", e -> name.setValue(""));
+        clear.setAriaLabel("Reset form");
 
         Grid<Person> people = new Grid<>(Person.class);
         people.setItems(List.of(new Person("Alice", 30), new Person("Bob", 25),
@@ -62,8 +63,8 @@ public LocatorDemoView() {
      */
     public static class PersonForm extends Composite<VerticalLayout> {
 
-        public final TextField nameField = new TextField("Name");
-        public final TextField emailField = new TextField("Email");
+        public final TextField nameField = new TextField("Full name");
+        public final TextField emailField = new TextField("Email address");
         public final Button submit;
 
         public PersonForm(Span echo) {
diff --git a/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java b/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java
index e486b317..5e9d2f1f 100644
--- a/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java
+++ b/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java
@@ -617,6 +617,97 @@ void withCaptionContaining_null_throws() {
                 () -> query.withCaptionContaining(null));
     }
 
+    @Test
+    void withLabel_exactMatch_getsCorrectComponent() {
+        TestComponent labelled = new TestComponent();
+        labelled.getElement().setProperty("label", "Full name");
+
+        TestComponent other = new TestComponent();
+        other.getElement().setProperty("label", "Email");
+
+        TestComponent noLabel = new TestComponent();
+
+        UI.getCurrent().getElement().appendChild(labelled.getElement(),
+                other.getElement(), noLabel.getElement());
+
+        Assertions.assertSame(labelled, find(TestComponent.class)
+                .withLabel("Full name").single());
+        Assertions.assertSame(other,
+                find(TestComponent.class).withLabel("Email").single());
+        Assertions.assertTrue(
+                find(TestComponent.class).withLabel("Missing").all().isEmpty());
+    }
+
+    @Test
+    void withLabelContaining_substringMatch() {
+        TestComponent fullName = new TestComponent();
+        fullName.getElement().setProperty("label", "Full name");
+
+        TestComponent firstName = new TestComponent();
+        firstName.getElement().setProperty("label", "First name");
+
+        TestComponent noLabel = new TestComponent();
+
+        UI.getCurrent().getElement().appendChild(fullName.getElement(),
+                firstName.getElement(), noLabel.getElement());
+
+        Assertions.assertIterableEquals(List.of(fullName, firstName),
+                find(TestComponent.class).withLabelContaining("name").all());
+    }
+
+    @Test
+    void withAriaLabel_exactMatch_getsCorrectComponent() {
+        TestComponent reset = new TestComponent();
+        reset.getElement().setAttribute("aria-label", "Reset form");
+
+        TestComponent other = new TestComponent();
+        other.getElement().setAttribute("aria-label", "Submit form");
+
+        TestComponent noAria = new TestComponent();
+
+        UI.getCurrent().getElement().appendChild(reset.getElement(),
+                other.getElement(), noAria.getElement());
+
+        Assertions.assertSame(reset, find(TestComponent.class)
+                .withAriaLabel("Reset form").single());
+        Assertions.assertSame(other, find(TestComponent.class)
+                .withAriaLabel("Submit form").single());
+        Assertions.assertTrue(find(TestComponent.class)
+                .withAriaLabel("Missing").all().isEmpty());
+    }
+
+    @Test
+    void withAriaLabelContaining_substringMatch() {
+        TestComponent reset = new TestComponent();
+        reset.getElement().setAttribute("aria-label", "Reset form");
+
+        TestComponent submit = new TestComponent();
+        submit.getElement().setAttribute("aria-label", "Submit form");
+
+        TestComponent noAria = new TestComponent();
+
+        UI.getCurrent().getElement().appendChild(reset.getElement(),
+                submit.getElement(), noAria.getElement());
+
+        Assertions.assertIterableEquals(List.of(reset, submit),
+                find(TestComponent.class).withAriaLabelContaining("form")
+                        .all());
+    }
+
+    @Test
+    void withLabel_null_throws() {
+        ComponentQuery<TestComponent> query = find(TestComponent.class);
+        Assertions.assertThrows(NullPointerException.class,
+                () -> query.withLabel(null));
+    }
+
+    @Test
+    void withAriaLabel_null_throws() {
+        ComponentQuery<TestComponent> query = find(TestComponent.class);
+        Assertions.assertThrows(NullPointerException.class,
+                () -> query.withAriaLabel(null));
+    }
+
     @Test
     void withText_exactMatch_getsCorrectComponent() {
         TextComponent span1 = new TextComponent("sample text");
diff --git a/junit6/src/test/java/com/vaadin/browserless/LocatorApiTest.java b/junit6/src/test/java/com/vaadin/browserless/LocatorApiTest.java
index 09fc6233..67dba814 100644
--- a/junit6/src/test/java/com/vaadin/browserless/LocatorApiTest.java
+++ b/junit6/src/test/java/com/vaadin/browserless/LocatorApiTest.java
@@ -143,6 +143,49 @@ void customLocator_viaGetSupplier_composesBuiltins() {
         }
     }
 
+    @Test
+    void filterChain_withLabel_selectsField() {
+        try (var app = BrowserlessApplicationContext.create(routes())) {
+            var window = app.newUser().newWindow();
+            window.navigate(LocatorDemoView.class);
+
+            // Outer TextField has label "Name"; inner PersonForm has
+            // "Full name" / "Email address" — labels are unique at the top
+            // level so withLabel resolves to exactly one match.
+            window.findTextField().withLabel("Name").setValue("via label");
+            Assertions.assertEquals("via label", window.findTextField()
+                    .withId("name").component().getValue());
+
+            // Substring match against the inner form's label.
+            window.findTextField().withLabelContaining("Full")
+                    .setValue("inner");
+            Assertions.assertEquals("inner", window.findTextField()
+                    .withId("pf-name").component().getValue());
+        }
+    }
+
+    @Test
+    void filterChain_withAriaLabel_selectsButton() {
+        try (var app = BrowserlessApplicationContext.create(routes())) {
+            var window = app.newUser().newWindow();
+            window.navigate(LocatorDemoView.class);
+
+            window.findTextField().withId("name").setValue("X");
+
+            // The Clear button identifies itself to screen readers via
+            // aria-label="Reset form".
+            window.findButton().withAriaLabel("Reset form").click();
+            Assertions.assertEquals("", window.findTextField().withId("name")
+                    .component().getValue());
+
+            // Substring match against the same attribute.
+            window.findTextField().withId("name").setValue("X");
+            window.findButton().withAriaLabelContaining("Reset").click();
+            Assertions.assertEquals("", window.findTextField().withId("name")
+                    .component().getValue());
+        }
+    }
+
     @Test
     void filterChain_expandedSurface() {
         try (var app = BrowserlessApplicationContext.create(routes())) {
diff --git a/shared/src/main/java/com/vaadin/browserless/ComponentQuery.java b/shared/src/main/java/com/vaadin/browserless/ComponentQuery.java
index d01460bd..111c0abc 100644
--- a/shared/src/main/java/com/vaadin/browserless/ComponentQuery.java
+++ b/shared/src/main/java/com/vaadin/browserless/ComponentQuery.java
@@ -243,6 +243,62 @@ public ComponentQuery<T> withCaptionContaining(String text) {
         return this;
     }
 
+    /**
+     * Requires the component's {@code label} property to be exactly the given
+     * value. Use this for form fields (TextField, ComboBox, etc.) where the
+     * end user identifies a field by its label.
+     *
+     * @param label
+     *            the expected label, not {@literal null}
+     * @return this element query instance for chaining
+     * @see com.vaadin.flow.component.HasLabel#getLabel()
+     */
+    public ComponentQuery<T> withLabel(String label) {
+        locatorSpec.predicates.add(ElementConditions.hasLabel(label));
+        return this;
+    }
+
+    /**
+     * Requires the component's {@code label} property to contain the given
+     * text.
+     *
+     * @param text
+     *            substring to find in the label, not {@literal null}
+     * @return this element query instance for chaining
+     */
+    public ComponentQuery<T> withLabelContaining(String text) {
+        locatorSpec.predicates.add(ElementConditions.labelContains(text));
+        return this;
+    }
+
+    /**
+     * Requires the component's {@code aria-label} attribute to be exactly the
+     * given value. Useful for components like {@code Button} that don't carry
+     * a visible label property but identify themselves to assistive
+     * technology via {@code aria-label}.
+     *
+     * @param ariaLabel
+     *            the expected aria-label, not {@literal null}
+     * @return this element query instance for chaining
+     */
+    public ComponentQuery<T> withAriaLabel(String ariaLabel) {
+        locatorSpec.predicates.add(ElementConditions.hasAriaLabel(ariaLabel));
+        return this;
+    }
+
+    /**
+     * Requires the component's {@code aria-label} attribute to contain the
+     * given text.
+     *
+     * @param text
+     *            substring to find in the aria-label, not {@literal null}
+     * @return this element query instance for chaining
+     */
+    public ComponentQuery<T> withAriaLabelContaining(String text) {
+        locatorSpec.predicates.add(ElementConditions.ariaLabelContains(text));
+        return this;
+    }
+
     /**
      * Requires the text content of the component to be equal to the given text
      *
diff --git a/shared/src/main/java/com/vaadin/browserless/ElementConditions.java b/shared/src/main/java/com/vaadin/browserless/ElementConditions.java
index 6beb9a3f..68fe87d9 100644
--- a/shared/src/main/java/com/vaadin/browserless/ElementConditions.java
+++ b/shared/src/main/java/com/vaadin/browserless/ElementConditions.java
@@ -196,6 +196,67 @@ public static <T extends Component> Predicate<T> hasNotAttribute(
                 .equals(component.getElement().getAttribute(attribute), value);
     }
 
+    /**
+     * Checks if the component has its {@code label} property set to exactly
+     * the given value. The {@code label} property is what
+     * {@link com.vaadin.flow.component.HasLabel#getLabel()} reads.
+     *
+     * @param label
+     *            the expected label, not {@literal null}
+     */
+    public static <T extends Component> Predicate<T> hasLabel(String label) {
+        Objects.requireNonNull(label, "label must not be null");
+        return component -> label
+                .equals(component.getElement().getProperty("label"));
+    }
+
+    /**
+     * Checks if the component's {@code label} property contains the given
+     * text. Comparison is case-sensitive.
+     *
+     * @param text
+     *            substring to find in the label, not {@literal null}
+     */
+    public static <T extends Component> Predicate<T> labelContains(String text) {
+        Objects.requireNonNull(text, "text must not be null");
+        return component -> {
+            String label = component.getElement().getProperty("label");
+            return label != null && label.contains(text);
+        };
+    }
+
+    /**
+     * Checks if the component has its {@code aria-label} attribute set to
+     * exactly the given value. Useful for components like {@code Button} that
+     * don't expose a {@code label} property but identify themselves to
+     * assistive technology via {@code aria-label}.
+     *
+     * @param ariaLabel
+     *            the expected aria-label, not {@literal null}
+     */
+    public static <T extends Component> Predicate<T> hasAriaLabel(
+            String ariaLabel) {
+        Objects.requireNonNull(ariaLabel, "ariaLabel must not be null");
+        return component -> ariaLabel
+                .equals(component.getElement().getAttribute("aria-label"));
+    }
+
+    /**
+     * Checks if the component's {@code aria-label} attribute contains the
+     * given text. Comparison is case-sensitive.
+     *
+     * @param text
+     *            substring to find in the aria-label, not {@literal null}
+     */
+    public static <T extends Component> Predicate<T> ariaLabelContains(
+            String text) {
+        Objects.requireNonNull(text, "text must not be null");
+        return component -> {
+            String label = component.getElement().getAttribute("aria-label");
+            return label != null && label.contains(text);
+        };
+    }
+
     private static class TextContainsPredicate<T extends Component>
             implements Predicate<T> {
 
diff --git a/shared/src/main/java/com/vaadin/browserless/locator/Locator.java b/shared/src/main/java/com/vaadin/browserless/locator/Locator.java
index 9844ac08..a6843c24 100644
--- a/shared/src/main/java/com/vaadin/browserless/locator/Locator.java
+++ b/shared/src/main/java/com/vaadin/browserless/locator/Locator.java
@@ -124,6 +124,47 @@ public SELF withCaptionContaining(String text) {
         return self();
     }
 
+    /**
+     * Requires the matched component's {@code label} property to be exactly
+     * the given value. Use this for form fields where the end user
+     * identifies a field by its label.
+     */
+    public SELF withLabel(String label) {
+        resetCache();
+        query.withLabel(label);
+        return self();
+    }
+
+    /**
+     * Requires the matched component's {@code label} property to contain the
+     * given text.
+     */
+    public SELF withLabelContaining(String text) {
+        resetCache();
+        query.withLabelContaining(text);
+        return self();
+    }
+
+    /**
+     * Requires the matched component's {@code aria-label} attribute to be
+     * exactly the given value.
+     */
+    public SELF withAriaLabel(String ariaLabel) {
+        resetCache();
+        query.withAriaLabel(ariaLabel);
+        return self();
+    }
+
+    /**
+     * Requires the matched component's {@code aria-label} attribute to
+     * contain the given text.
+     */
+    public SELF withAriaLabelContaining(String text) {
+        resetCache();
+        query.withAriaLabelContaining(text);
+        return self();
+    }
+
     /** Requires the text content of the component to equal the given text. */
     public SELF withText(String text) {
         resetCache();

From 9556e3d5369c3788a7f92552a741795e60c601af Mon Sep 17 00:00:00 2001
From: Matti Tahvonen <matti@vaadin.com>
Date: Thu, 21 May 2026 12:17:39 +0000
Subject: [PATCH 02/10] feat: withLabel matches separate <label for="...">
 elements
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When a component is labelled by an external <label for="componentId">
element (the HTML pattern, exposed in Flow via NativeLabel.setFor), its
"label" property is empty — so the previous withLabel implementation
missed it. Now also walks the UI for a <label> element whose "for"
attribute matches the component's id, and reads the label's text
content.

Adds a reusable ElementTreeWalker static helper for depth-first Element
traversal — kind of a Flow-level querySelectorAll. ElementConditions
uses it for the new fallback path; other future searches that need to
look at the raw element tree (e.g. by tag or attribute) can reuse it.

ComponentQueryTest covers both exact and substring forms across the
direct-property and for-attribute paths.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../browserless/ComponentQueryTest.java       | 31 +++++++--
 .../vaadin/browserless/ElementConditions.java | 64 +++++++++++++++----
 .../vaadin/browserless/ElementTreeWalker.java | 53 +++++++++++++++
 3 files changed, 133 insertions(+), 15 deletions(-)
 create mode 100644 shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java

diff --git a/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java b/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java
index 5e9d2f1f..61f39b7f 100644
--- a/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java
+++ b/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java
@@ -21,6 +21,7 @@
 import java.util.stream.Collectors;
 import java.util.stream.IntStream;
 
+import com.vaadin.flow.component.html.NativeLabel;
 import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Test;
 
@@ -625,15 +626,25 @@ void withLabel_exactMatch_getsCorrectComponent() {
         TestComponent other = new TestComponent();
         other.getElement().setProperty("label", "Email");
 
+        TestComponent withLabelComponent = new TestComponent();
+        // TODO why don't we set id implicitly, #FFS
+        withLabelComponent.setId("random123");
+        NativeLabel labelComponent = new NativeLabel("Native");
+        labelComponent.setFor(withLabelComponent);
+
         TestComponent noLabel = new TestComponent();
 
         UI.getCurrent().getElement().appendChild(labelled.getElement(),
-                other.getElement(), noLabel.getElement());
+                other.getElement(), noLabel.getElement(), withLabelComponent.getElement(), labelComponent.getElement());
 
         Assertions.assertSame(labelled, find(TestComponent.class)
                 .withLabel("Full name").single());
         Assertions.assertSame(other,
                 find(TestComponent.class).withLabel("Email").single());
+        // A separate <label for="random123"> targets withLabelComponent —
+        // withLabel resolves the relationship via the for attribute.
+        Assertions.assertSame(withLabelComponent,
+                find(TestComponent.class).withLabel("Native").single());
         Assertions.assertTrue(
                 find(TestComponent.class).withLabel("Missing").all().isEmpty());
     }
@@ -648,11 +659,23 @@ void withLabelContaining_substringMatch() {
 
         TestComponent noLabel = new TestComponent();
 
+        TextField textFieldWithLabel = new TextField("First name");
+
+        // Component labelled via a separate <label for="..."> — substring
+        // match must traverse the same path as exact match.
+        TestComponent viaForAttr = new TestComponent();
+        viaForAttr.setId("via-for");
+        NativeLabel forLabel = new NativeLabel("Display name");
+        forLabel.setFor(viaForAttr);
+
         UI.getCurrent().getElement().appendChild(fullName.getElement(),
-                firstName.getElement(), noLabel.getElement());
+                firstName.getElement(), noLabel.getElement(),
+                textFieldWithLabel.getElement(), viaForAttr.getElement(),
+                forLabel.getElement());
 
-        Assertions.assertIterableEquals(List.of(fullName, firstName),
-                find(TestComponent.class).withLabelContaining("name").all());
+        Assertions.assertIterableEquals(
+                List.of(fullName, firstName, textFieldWithLabel, viaForAttr),
+                find(Component.class).withLabelContaining("name").all());
     }
 
     @Test
diff --git a/shared/src/main/java/com/vaadin/browserless/ElementConditions.java b/shared/src/main/java/com/vaadin/browserless/ElementConditions.java
index 68fe87d9..65307882 100644
--- a/shared/src/main/java/com/vaadin/browserless/ElementConditions.java
+++ b/shared/src/main/java/com/vaadin/browserless/ElementConditions.java
@@ -25,6 +25,7 @@
 import com.vaadin.flow.component.HasText;
 import com.vaadin.flow.component.Html;
 import com.vaadin.flow.component.HtmlComponent;
+import com.vaadin.flow.component.UI;
 import com.vaadin.flow.dom.Element;
 
 /**
@@ -197,32 +198,73 @@ public static <T extends Component> Predicate<T> hasNotAttribute(
     }
 
     /**
-     * Checks if the component has its {@code label} property set to exactly
-     * the given value. The {@code label} property is what
-     * {@link com.vaadin.flow.component.HasLabel#getLabel()} reads.
+     * Checks if the component is labelled by exactly the given text. A
+     * component is considered labelled by a text when either:
+     *
+     * <ul>
+     * <li>its {@code label} property (read by
+     * {@link com.vaadin.flow.component.HasLabel#getLabel()}) equals the
+     * text, or</li>
+     * <li>some {@code <label for="componentId">} element elsewhere in the UI
+     * has that text as its (recursive) content.</li>
+     * </ul>
+     *
+     * The second form covers the HTML pattern where a separate
+     * {@link com.vaadin.flow.component.html.NativeLabel} (or any
+     * {@code <label>} element) targets an input via the {@code for}
+     * attribute.
      *
      * @param label
      *            the expected label, not {@literal null}
      */
     public static <T extends Component> Predicate<T> hasLabel(String label) {
         Objects.requireNonNull(label, "label must not be null");
-        return component -> label
-                .equals(component.getElement().getProperty("label"));
+        return component -> matchesLabel(component, label, false);
     }
 
     /**
-     * Checks if the component's {@code label} property contains the given
-     * text. Comparison is case-sensitive.
+     * Checks if the component's label contains the given text. The label is
+     * read in the same way as {@link #hasLabel(String)} (component's
+     * {@code label} property or a referring {@code <label for="...">}
+     * element). Comparison is case-sensitive.
      *
      * @param text
      *            substring to find in the label, not {@literal null}
      */
     public static <T extends Component> Predicate<T> labelContains(String text) {
         Objects.requireNonNull(text, "text must not be null");
-        return component -> {
-            String label = component.getElement().getProperty("label");
-            return label != null && label.contains(text);
-        };
+        return component -> matchesLabel(component, text, true);
+    }
+
+    private static boolean matchesLabel(Component component, String expected,
+            boolean substring) {
+        String own = component.getElement().getProperty("label");
+        if (matches(own, expected, substring)) {
+            return true;
+        }
+        return component.getId()
+                .map(ElementConditions::referringLabelText)
+                .filter(text -> matches(text, expected, substring))
+                .isPresent();
+    }
+
+    private static boolean matches(String actual, String expected,
+            boolean substring) {
+        if (actual == null) {
+            return false;
+        }
+        return substring ? actual.contains(expected) : actual.equals(expected);
+    }
+
+    private static String referringLabelText(String id) {
+        UI ui = UI.getCurrent();
+        if (ui == null) {
+            return null;
+        }
+        return ElementTreeWalker.walk(ui.getElement())
+                .filter(e -> "label".equalsIgnoreCase(e.getTag()))
+                .filter(e -> id.equals(e.getAttribute("for")))
+                .map(Element::getTextRecursively).findFirst().orElse(null);
     }
 
     /**
diff --git a/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java b/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java
new file mode 100644
index 00000000..658f761e
--- /dev/null
+++ b/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java
@@ -0,0 +1,53 @@
+/*
+ * 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.util.function.Predicate;
+import java.util.stream.Stream;
+
+import com.vaadin.flow.dom.Element;
+
+/**
+ * Static helpers for walking and selecting nodes in an
+ * {@link com.vaadin.flow.dom.Element} subtree.
+ * <p>
+ * Think {@code document.querySelectorAll} at the Flow element level: handy
+ * whenever a search needs to look beyond the component graph (e.g. matching
+ * by tag, attribute, or any predicate over the raw element tree).
+ */
+public final class ElementTreeWalker {
+
+    private ElementTreeWalker() {
+        throw new AssertionError("Must not be instantiated");
+    }
+
+    /**
+     * Depth-first stream containing {@code root} and all of its descendants.
+     */
+    public static Stream<Element> walk(Element root) {
+        return Stream.concat(Stream.of(root),
+                root.getChildren().flatMap(ElementTreeWalker::walk));
+    }
+
+    /**
+     * Elements in the subtree rooted at {@code root} (including {@code root}
+     * itself) that match the given predicate, in depth-first order.
+     */
+    public static Stream<Element> select(Element root,
+            Predicate<Element> predicate) {
+        return walk(root).filter(predicate);
+    }
+}

From f358ef82ca110853c8205d546d600965bc7f0a67 Mon Sep 17 00:00:00 2001
From: Matti Tahvonen <matti@vaadin.com>
Date: Thu, 21 May 2026 15:22:10 +0300
Subject: [PATCH 03/10] spotless

---
 .../browserless/ComponentQueryTest.java       | 17 ++++++-------
 .../vaadin/browserless/ComponentQuery.java    | 10 ++++----
 .../vaadin/browserless/ElementConditions.java | 24 +++++++++----------
 .../vaadin/browserless/ElementTreeWalker.java |  4 ++--
 .../vaadin/browserless/locator/Locator.java   | 10 ++++----
 5 files changed, 32 insertions(+), 33 deletions(-)

diff --git a/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java b/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java
index 61f39b7f..485dc675 100644
--- a/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java
+++ b/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java
@@ -21,7 +21,6 @@
 import java.util.stream.Collectors;
 import java.util.stream.IntStream;
 
-import com.vaadin.flow.component.html.NativeLabel;
 import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Test;
 
@@ -34,6 +33,7 @@
 import com.vaadin.flow.component.UI;
 import com.vaadin.flow.component.button.Button;
 import com.vaadin.flow.component.html.Div;
+import com.vaadin.flow.component.html.NativeLabel;
 import com.vaadin.flow.component.textfield.IntegerField;
 import com.vaadin.flow.component.textfield.TextField;
 import com.vaadin.flow.component.textfield.TextFieldBase;
@@ -635,10 +635,11 @@ void withLabel_exactMatch_getsCorrectComponent() {
         TestComponent noLabel = new TestComponent();
 
         UI.getCurrent().getElement().appendChild(labelled.getElement(),
-                other.getElement(), noLabel.getElement(), withLabelComponent.getElement(), labelComponent.getElement());
+                other.getElement(), noLabel.getElement(),
+                withLabelComponent.getElement(), labelComponent.getElement());
 
-        Assertions.assertSame(labelled, find(TestComponent.class)
-                .withLabel("Full name").single());
+        Assertions.assertSame(labelled,
+                find(TestComponent.class).withLabel("Full name").single());
         Assertions.assertSame(other,
                 find(TestComponent.class).withLabel("Email").single());
         // A separate <label for="random123"> targets withLabelComponent —
@@ -691,12 +692,12 @@ void withAriaLabel_exactMatch_getsCorrectComponent() {
         UI.getCurrent().getElement().appendChild(reset.getElement(),
                 other.getElement(), noAria.getElement());
 
-        Assertions.assertSame(reset, find(TestComponent.class)
-                .withAriaLabel("Reset form").single());
+        Assertions.assertSame(reset,
+                find(TestComponent.class).withAriaLabel("Reset form").single());
         Assertions.assertSame(other, find(TestComponent.class)
                 .withAriaLabel("Submit form").single());
-        Assertions.assertTrue(find(TestComponent.class)
-                .withAriaLabel("Missing").all().isEmpty());
+        Assertions.assertTrue(find(TestComponent.class).withAriaLabel("Missing")
+                .all().isEmpty());
     }
 
     @Test
diff --git a/shared/src/main/java/com/vaadin/browserless/ComponentQuery.java b/shared/src/main/java/com/vaadin/browserless/ComponentQuery.java
index 111c0abc..a8800dbc 100644
--- a/shared/src/main/java/com/vaadin/browserless/ComponentQuery.java
+++ b/shared/src/main/java/com/vaadin/browserless/ComponentQuery.java
@@ -245,8 +245,8 @@ public ComponentQuery<T> withCaptionContaining(String text) {
 
     /**
      * Requires the component's {@code label} property to be exactly the given
-     * value. Use this for form fields (TextField, ComboBox, etc.) where the
-     * end user identifies a field by its label.
+     * value. Use this for form fields (TextField, ComboBox, etc.) where the end
+     * user identifies a field by its label.
      *
      * @param label
      *            the expected label, not {@literal null}
@@ -273,9 +273,9 @@ public ComponentQuery<T> withLabelContaining(String text) {
 
     /**
      * Requires the component's {@code aria-label} attribute to be exactly the
-     * given value. Useful for components like {@code Button} that don't carry
-     * a visible label property but identify themselves to assistive
-     * technology via {@code aria-label}.
+     * given value. Useful for components like {@code Button} that don't carry a
+     * visible label property but identify themselves to assistive technology
+     * via {@code aria-label}.
      *
      * @param ariaLabel
      *            the expected aria-label, not {@literal null}
diff --git a/shared/src/main/java/com/vaadin/browserless/ElementConditions.java b/shared/src/main/java/com/vaadin/browserless/ElementConditions.java
index 65307882..95a67603 100644
--- a/shared/src/main/java/com/vaadin/browserless/ElementConditions.java
+++ b/shared/src/main/java/com/vaadin/browserless/ElementConditions.java
@@ -203,16 +203,15 @@ public static <T extends Component> Predicate<T> hasNotAttribute(
      *
      * <ul>
      * <li>its {@code label} property (read by
-     * {@link com.vaadin.flow.component.HasLabel#getLabel()}) equals the
-     * text, or</li>
+     * {@link com.vaadin.flow.component.HasLabel#getLabel()}) equals the text,
+     * or</li>
      * <li>some {@code <label for="componentId">} element elsewhere in the UI
      * has that text as its (recursive) content.</li>
      * </ul>
      *
      * The second form covers the HTML pattern where a separate
      * {@link com.vaadin.flow.component.html.NativeLabel} (or any
-     * {@code <label>} element) targets an input via the {@code for}
-     * attribute.
+     * {@code <label>} element) targets an input via the {@code for} attribute.
      *
      * @param label
      *            the expected label, not {@literal null}
@@ -225,13 +224,14 @@ public static <T extends Component> Predicate<T> hasLabel(String label) {
     /**
      * Checks if the component's label contains the given text. The label is
      * read in the same way as {@link #hasLabel(String)} (component's
-     * {@code label} property or a referring {@code <label for="...">}
-     * element). Comparison is case-sensitive.
+     * {@code label} property or a referring {@code <label for="...">} element).
+     * Comparison is case-sensitive.
      *
      * @param text
      *            substring to find in the label, not {@literal null}
      */
-    public static <T extends Component> Predicate<T> labelContains(String text) {
+    public static <T extends Component> Predicate<T> labelContains(
+            String text) {
         Objects.requireNonNull(text, "text must not be null");
         return component -> matchesLabel(component, text, true);
     }
@@ -242,10 +242,8 @@ private static boolean matchesLabel(Component component, String expected,
         if (matches(own, expected, substring)) {
             return true;
         }
-        return component.getId()
-                .map(ElementConditions::referringLabelText)
-                .filter(text -> matches(text, expected, substring))
-                .isPresent();
+        return component.getId().map(ElementConditions::referringLabelText)
+                .filter(text -> matches(text, expected, substring)).isPresent();
     }
 
     private static boolean matches(String actual, String expected,
@@ -284,8 +282,8 @@ public static <T extends Component> Predicate<T> hasAriaLabel(
     }
 
     /**
-     * Checks if the component's {@code aria-label} attribute contains the
-     * given text. Comparison is case-sensitive.
+     * Checks if the component's {@code aria-label} attribute contains the given
+     * text. Comparison is case-sensitive.
      *
      * @param text
      *            substring to find in the aria-label, not {@literal null}
diff --git a/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java b/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java
index 658f761e..204d1abc 100644
--- a/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java
+++ b/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java
@@ -25,8 +25,8 @@
  * {@link com.vaadin.flow.dom.Element} subtree.
  * <p>
  * Think {@code document.querySelectorAll} at the Flow element level: handy
- * whenever a search needs to look beyond the component graph (e.g. matching
- * by tag, attribute, or any predicate over the raw element tree).
+ * whenever a search needs to look beyond the component graph (e.g. matching by
+ * tag, attribute, or any predicate over the raw element tree).
  */
 public final class ElementTreeWalker {
 
diff --git a/shared/src/main/java/com/vaadin/browserless/locator/Locator.java b/shared/src/main/java/com/vaadin/browserless/locator/Locator.java
index a6843c24..1a846d9d 100644
--- a/shared/src/main/java/com/vaadin/browserless/locator/Locator.java
+++ b/shared/src/main/java/com/vaadin/browserless/locator/Locator.java
@@ -125,9 +125,9 @@ public SELF withCaptionContaining(String text) {
     }
 
     /**
-     * Requires the matched component's {@code label} property to be exactly
-     * the given value. Use this for form fields where the end user
-     * identifies a field by its label.
+     * Requires the matched component's {@code label} property to be exactly the
+     * given value. Use this for form fields where the end user identifies a
+     * field by its label.
      */
     public SELF withLabel(String label) {
         resetCache();
@@ -156,8 +156,8 @@ public SELF withAriaLabel(String ariaLabel) {
     }
 
     /**
-     * Requires the matched component's {@code aria-label} attribute to
-     * contain the given text.
+     * Requires the matched component's {@code aria-label} attribute to contain
+     * the given text.
      */
     public SELF withAriaLabelContaining(String text) {
         resetCache();

From f933c05c6616a37a3e72aeb0ece8bfd281b260eb Mon Sep 17 00:00:00 2001
From: Matti Tahvonen <matti@vaadin.com>
Date: Thu, 21 May 2026 20:26:23 +0300
Subject: [PATCH 04/10] avoid using UI.getCurrent()

---
 .../com/vaadin/browserless/ElementConditions.java   | 13 +++++--------
 1 file changed, 5 insertions(+), 8 deletions(-)

diff --git a/shared/src/main/java/com/vaadin/browserless/ElementConditions.java b/shared/src/main/java/com/vaadin/browserless/ElementConditions.java
index 95a67603..cc7fa302 100644
--- a/shared/src/main/java/com/vaadin/browserless/ElementConditions.java
+++ b/shared/src/main/java/com/vaadin/browserless/ElementConditions.java
@@ -25,7 +25,6 @@
 import com.vaadin.flow.component.HasText;
 import com.vaadin.flow.component.Html;
 import com.vaadin.flow.component.HtmlComponent;
-import com.vaadin.flow.component.UI;
 import com.vaadin.flow.dom.Element;
 
 /**
@@ -242,7 +241,9 @@ private static boolean matchesLabel(Component component, String expected,
         if (matches(own, expected, substring)) {
             return true;
         }
-        return component.getId().map(ElementConditions::referringLabelText)
+        return component.getId()
+                .map(id -> referringLabelText(
+                        component.getUI().get().getElement(), id))
                 .filter(text -> matches(text, expected, substring)).isPresent();
     }
 
@@ -254,12 +255,8 @@ private static boolean matches(String actual, String expected,
         return substring ? actual.contains(expected) : actual.equals(expected);
     }
 
-    private static String referringLabelText(String id) {
-        UI ui = UI.getCurrent();
-        if (ui == null) {
-            return null;
-        }
-        return ElementTreeWalker.walk(ui.getElement())
+    private static String referringLabelText(Element root, String id) {
+        return ElementTreeWalker.walk(root)
                 .filter(e -> "label".equalsIgnoreCase(e.getTag()))
                 .filter(e -> id.equals(e.getAttribute("for")))
                 .map(Element::getTextRecursively).findFirst().orElse(null);

From 813fdfab90f4a0d628bc8214792ad4d0772eee92 Mon Sep 17 00:00:00 2001
From: Matti Tahvonen <matti@vaadin.com>
Date: Fri, 22 May 2026 08:06:47 +0300
Subject: [PATCH 05/10] hide helper at this point from public API

---
 .../vaadin/browserless/ElementTreeWalker.java   | 17 ++++-------------
 1 file changed, 4 insertions(+), 13 deletions(-)

diff --git a/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java b/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java
index 204d1abc..cabc0ada 100644
--- a/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java
+++ b/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java
@@ -15,11 +15,10 @@
  */
 package com.vaadin.browserless;
 
-import java.util.function.Predicate;
-import java.util.stream.Stream;
-
 import com.vaadin.flow.dom.Element;
 
+import java.util.stream.Stream;
+
 /**
  * Static helpers for walking and selecting nodes in an
  * {@link com.vaadin.flow.dom.Element} subtree.
@@ -28,7 +27,7 @@
  * whenever a search needs to look beyond the component graph (e.g. matching by
  * tag, attribute, or any predicate over the raw element tree).
  */
-public final class ElementTreeWalker {
+final class ElementTreeWalker {
 
     private ElementTreeWalker() {
         throw new AssertionError("Must not be instantiated");
@@ -37,17 +36,9 @@ private ElementTreeWalker() {
     /**
      * Depth-first stream containing {@code root} and all of its descendants.
      */
-    public static Stream<Element> walk(Element root) {
+    static Stream<Element> walk(Element root) {
         return Stream.concat(Stream.of(root),
                 root.getChildren().flatMap(ElementTreeWalker::walk));
     }
 
-    /**
-     * Elements in the subtree rooted at {@code root} (including {@code root}
-     * itself) that match the given predicate, in depth-first order.
-     */
-    public static Stream<Element> select(Element root,
-            Predicate<Element> predicate) {
-        return walk(root).filter(predicate);
-    }
 }

From 869122f6c5b9971aba27128777d78a6f5afacb71 Mon Sep 17 00:00:00 2001
From: Matti Tahvonen <matti@vaadin.com>
Date: Fri, 22 May 2026 08:33:25 +0300
Subject: [PATCH 06/10] formatter

---
 .../main/java/com/vaadin/browserless/ElementTreeWalker.java   | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java b/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java
index cabc0ada..33e8ac12 100644
--- a/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java
+++ b/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java
@@ -15,10 +15,10 @@
  */
 package com.vaadin.browserless;
 
-import com.vaadin.flow.dom.Element;
-
 import java.util.stream.Stream;
 
+import com.vaadin.flow.dom.Element;
+
 /**
  * Static helpers for walking and selecting nodes in an
  * {@link com.vaadin.flow.dom.Element} subtree.

From f13dc63dd949bb5d501674863ebbb33d7d8d9f7d Mon Sep 17 00:00:00 2001
From: Matti Tahvonen <matti@vaadin.com>
Date: Fri, 22 May 2026 05:47:02 +0000
Subject: [PATCH 07/10] test: withLabel resolves a for-mapped label inside a
 Dialog
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Verifies that the <label for="..."> resolution path also fires when the
NativeLabel and its targeted TextField live inside an opened Dialog —
i.e. the walker reaches into the dialog overlay content and finds the
referring label even though it's not a direct child of the UI element.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../vaadin/browserless/ComponentQueryTest.java | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java b/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java
index 485dc675..a4e4a5b7 100644
--- a/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java
+++ b/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java
@@ -679,6 +679,24 @@ void withLabelContaining_substringMatch() {
                 find(Component.class).withLabelContaining("name").all());
     }
 
+    @Test
+    void withLabel_componentInsideDialog_isFound() {
+        TextField field = new TextField();
+        field.setId("dlg-field");
+        NativeLabel label = new NativeLabel("Inside dialog");
+        label.setFor(field);
+
+        com.vaadin.flow.component.dialog.Dialog dialog = new com.vaadin.flow.component.dialog.Dialog();
+        dialog.add(label, field);
+        dialog.open();
+
+        // The <label for="dlg-field"> sits inside the dialog overlay; the
+        // query must walk into the dialog content to resolve the for
+        // relationship.
+        Assertions.assertSame(field,
+                find(TextField.class).withLabel("Inside dialog").single());
+    }
+
     @Test
     void withAriaLabel_exactMatch_getsCorrectComponent() {
         TestComponent reset = new TestComponent();

From 6130343b3c0fa0260105015eefa7188e1427e79b Mon Sep 17 00:00:00 2001
From: Matti Tahvonen <matti@vaadin.com>
Date: Fri, 22 May 2026 05:54:34 +0000
Subject: [PATCH 08/10] feat: ElementTreeWalker traverses virtual children too
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

MasterDetailLayout attaches its detail content via Element.appendVirtualChild
(same mechanism several Vaadin overlays use). The previous walk()
implementation only traversed regular children, so a <label for="id">
inside such virtual content was invisible to the withLabel resolver.

walk() now interleaves virtual children with regular ones, matching the
behavior of the existing Kotlin Element.getVirtualChildren() helper.

Also tightens referringLabelText to skip text-node elements before
calling getTag() — text nodes throw UnsupportedOperationException on
that call, which masked failures before this fix.

Regression test (ComponentQueryTest#withLabel_componentInsideMasterDetailLayout_isFound)
fails on the old walker and passes after the change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../browserless/ComponentQueryTest.java       | 20 +++++++++++++++
 .../vaadin/browserless/ElementConditions.java |  2 ++
 .../vaadin/browserless/ElementTreeWalker.java | 25 +++++++++++++++++--
 3 files changed, 45 insertions(+), 2 deletions(-)

diff --git a/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java b/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java
index a4e4a5b7..728664cc 100644
--- a/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java
+++ b/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java
@@ -697,6 +697,26 @@ void withLabel_componentInsideDialog_isFound() {
                 find(TextField.class).withLabel("Inside dialog").single());
     }
 
+    @Test
+    void withLabel_componentInsideMasterDetailLayout_isFound() {
+        TextField field = new TextField();
+        field.setId("mdl-field");
+        NativeLabel label = new NativeLabel("MDL label");
+        label.setFor(field);
+
+        com.vaadin.flow.component.masterdetaillayout.MasterDetailLayout layout =
+                new com.vaadin.flow.component.masterdetaillayout.MasterDetailLayout();
+        layout.setMaster(new com.vaadin.flow.component.html.Span("master"));
+        layout.setDetail(new Div(label, field));
+
+        UI.getCurrent().getElement().appendChild(layout.getElement());
+
+        // MasterDetailLayout attaches its detail content via virtual children;
+        // the walker has to traverse those to find the referring <label>.
+        Assertions.assertSame(field,
+                find(TextField.class).withLabel("MDL label").single());
+    }
+
     @Test
     void withAriaLabel_exactMatch_getsCorrectComponent() {
         TestComponent reset = new TestComponent();
diff --git a/shared/src/main/java/com/vaadin/browserless/ElementConditions.java b/shared/src/main/java/com/vaadin/browserless/ElementConditions.java
index cc7fa302..ec30b6aa 100644
--- a/shared/src/main/java/com/vaadin/browserless/ElementConditions.java
+++ b/shared/src/main/java/com/vaadin/browserless/ElementConditions.java
@@ -257,6 +257,8 @@ private static boolean matches(String actual, String expected,
 
     private static String referringLabelText(Element root, String id) {
         return ElementTreeWalker.walk(root)
+                // Element.getTag() throws on text nodes; skip them first.
+                .filter(e -> !e.isTextNode())
                 .filter(e -> "label".equalsIgnoreCase(e.getTag()))
                 .filter(e -> id.equals(e.getAttribute("for")))
                 .map(Element::getTextRecursively).findFirst().orElse(null);
diff --git a/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java b/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java
index 33e8ac12..3140f4fb 100644
--- a/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java
+++ b/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java
@@ -16,8 +16,11 @@
 package com.vaadin.browserless;
 
 import java.util.stream.Stream;
+import java.util.stream.StreamSupport;
 
 import com.vaadin.flow.dom.Element;
+import com.vaadin.flow.internal.StateNode;
+import com.vaadin.flow.internal.nodefeature.VirtualChildrenList;
 
 /**
  * Static helpers for walking and selecting nodes in an
@@ -26,6 +29,10 @@
  * Think {@code document.querySelectorAll} at the Flow element level: handy
  * whenever a search needs to look beyond the component graph (e.g. matching by
  * tag, attribute, or any predicate over the raw element tree).
+ * <p>
+ * Traversal includes both regular and virtual children, so components that
+ * attach content via {@code Element.appendVirtualChild(...)} (Dialog overlay,
+ * MasterDetailLayout detail slot, etc.) are still reachable.
  */
 final class ElementTreeWalker {
 
@@ -34,11 +41,25 @@ private ElementTreeWalker() {
     }
 
     /**
-     * Depth-first stream containing {@code root} and all of its descendants.
+     * Depth-first stream containing {@code root} and all of its descendants,
+     * including elements attached as virtual children.
      */
     static Stream<Element> walk(Element root) {
         return Stream.concat(Stream.of(root),
-                root.getChildren().flatMap(ElementTreeWalker::walk));
+                Stream.concat(root.getChildren(), virtualChildren(root))
+                        .flatMap(ElementTreeWalker::walk));
     }
 
+    private static Stream<Element> virtualChildren(Element element) {
+        if (!element.getNode().hasFeature(VirtualChildrenList.class)) {
+            return Stream.empty();
+        }
+        return element.getNode()
+                .getFeatureIfInitialized(VirtualChildrenList.class)
+                .map(list -> StreamSupport
+                        .stream(((Iterable<StateNode>) list::iterator)
+                                .spliterator(), false)
+                        .map(Element::get))
+                .orElseGet(Stream::empty);
+    }
 }

From 5ea88c107973df09aabdb07fd71a421829c048e4 Mon Sep 17 00:00:00 2001
From: Matti Tahvonen <matti@vaadin.com>
Date: Fri, 22 May 2026 08:57:13 +0300
Subject: [PATCH 09/10] formatiformat

---
 .../java/com/vaadin/browserless/ComponentQueryTest.java    | 3 +--
 .../java/com/vaadin/browserless/ElementTreeWalker.java     | 7 +++----
 2 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java b/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java
index 728664cc..4a1c79fa 100644
--- a/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java
+++ b/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java
@@ -704,8 +704,7 @@ void withLabel_componentInsideMasterDetailLayout_isFound() {
         NativeLabel label = new NativeLabel("MDL label");
         label.setFor(field);
 
-        com.vaadin.flow.component.masterdetaillayout.MasterDetailLayout layout =
-                new com.vaadin.flow.component.masterdetaillayout.MasterDetailLayout();
+        com.vaadin.flow.component.masterdetaillayout.MasterDetailLayout layout = new com.vaadin.flow.component.masterdetaillayout.MasterDetailLayout();
         layout.setMaster(new com.vaadin.flow.component.html.Span("master"));
         layout.setDetail(new Div(label, field));
 
diff --git a/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java b/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java
index 3140f4fb..7e6c89af 100644
--- a/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java
+++ b/shared/src/main/java/com/vaadin/browserless/ElementTreeWalker.java
@@ -56,10 +56,9 @@ private static Stream<Element> virtualChildren(Element element) {
         }
         return element.getNode()
                 .getFeatureIfInitialized(VirtualChildrenList.class)
-                .map(list -> StreamSupport
-                        .stream(((Iterable<StateNode>) list::iterator)
-                                .spliterator(), false)
-                        .map(Element::get))
+                .map(list -> StreamSupport.stream(
+                        ((Iterable<StateNode>) list::iterator).spliterator(),
+                        false).map(Element::get))
                 .orElseGet(Stream::empty);
     }
 }

From b80faac50d2d6b47aeda3ba0a929092f27acbf81 Mon Sep 17 00:00:00 2001
From: Matti Tahvonen <matti@vaadin.com>
Date: Fri, 22 May 2026 13:28:35 +0000
Subject: [PATCH 10/10] fix: address PR #71 review comments from mcollovati

ElementConditions: hasLabel, labelContains, hasAriaLabel and
ariaLabelContains now throw IllegalArgumentException on null inputs,
consistent with the existing containsText / hasAttribute style.

ComponentQueryTest:
- Drop the temporary "why don't we set id implicitly" TODO comment;
  if it becomes a real concern, it'll get a Flow ticket instead of
  living as inline noise.
- Expand withLabelContaining_substringMatch with both a non-matching
  label-property component and a non-matching <label for=...>
  component, so the assertion proves filtering rather than just
  matching.
- Expand withAriaLabelContaining_substringMatch with a non-matching
  aria-label component for the same reason.
- Use imports for Dialog and MasterDetailLayout instead of
  fully-qualified names.
- withLabel_null_throws / withAriaLabel_null_throws now assert
  IllegalArgumentException to match the new contract.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../browserless/ComponentQueryTest.java       | 34 ++++++++++++++-----
 .../vaadin/browserless/ElementConditions.java | 16 ++++++---
 2 files changed, 38 insertions(+), 12 deletions(-)

diff --git a/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java b/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java
index 4a1c79fa..4330a149 100644
--- a/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java
+++ b/junit6/src/test/java/com/vaadin/browserless/ComponentQueryTest.java
@@ -32,8 +32,10 @@
 import com.vaadin.flow.component.Text;
 import com.vaadin.flow.component.UI;
 import com.vaadin.flow.component.button.Button;
+import com.vaadin.flow.component.dialog.Dialog;
 import com.vaadin.flow.component.html.Div;
 import com.vaadin.flow.component.html.NativeLabel;
+import com.vaadin.flow.component.masterdetaillayout.MasterDetailLayout;
 import com.vaadin.flow.component.textfield.IntegerField;
 import com.vaadin.flow.component.textfield.TextField;
 import com.vaadin.flow.component.textfield.TextFieldBase;
@@ -627,7 +629,6 @@ void withLabel_exactMatch_getsCorrectComponent() {
         other.getElement().setProperty("label", "Email");
 
         TestComponent withLabelComponent = new TestComponent();
-        // TODO why don't we set id implicitly, #FFS
         withLabelComponent.setId("random123");
         NativeLabel labelComponent = new NativeLabel("Native");
         labelComponent.setFor(withLabelComponent);
@@ -660,6 +661,10 @@ void withLabelContaining_substringMatch() {
 
         TestComponent noLabel = new TestComponent();
 
+        // Non-matching label property — must be excluded from the result.
+        TestComponent unrelatedLabel = new TestComponent();
+        unrelatedLabel.getElement().setProperty("label", "Address");
+
         TextField textFieldWithLabel = new TextField("First name");
 
         // Component labelled via a separate <label for="..."> — substring
@@ -669,10 +674,18 @@ void withLabelContaining_substringMatch() {
         NativeLabel forLabel = new NativeLabel("Display name");
         forLabel.setFor(viaForAttr);
 
+        // Non-matching <label for="..."> — must be excluded from the result.
+        TestComponent viaForAttrUnrelated = new TestComponent();
+        viaForAttrUnrelated.setId("via-for-unrelated");
+        NativeLabel forLabelUnrelated = new NativeLabel("Country");
+        forLabelUnrelated.setFor(viaForAttrUnrelated);
+
         UI.getCurrent().getElement().appendChild(fullName.getElement(),
                 firstName.getElement(), noLabel.getElement(),
-                textFieldWithLabel.getElement(), viaForAttr.getElement(),
-                forLabel.getElement());
+                unrelatedLabel.getElement(), textFieldWithLabel.getElement(),
+                viaForAttr.getElement(), forLabel.getElement(),
+                viaForAttrUnrelated.getElement(),
+                forLabelUnrelated.getElement());
 
         Assertions.assertIterableEquals(
                 List.of(fullName, firstName, textFieldWithLabel, viaForAttr),
@@ -686,7 +699,7 @@ void withLabel_componentInsideDialog_isFound() {
         NativeLabel label = new NativeLabel("Inside dialog");
         label.setFor(field);
 
-        com.vaadin.flow.component.dialog.Dialog dialog = new com.vaadin.flow.component.dialog.Dialog();
+        Dialog dialog = new Dialog();
         dialog.add(label, field);
         dialog.open();
 
@@ -704,7 +717,7 @@ void withLabel_componentInsideMasterDetailLayout_isFound() {
         NativeLabel label = new NativeLabel("MDL label");
         label.setFor(field);
 
-        com.vaadin.flow.component.masterdetaillayout.MasterDetailLayout layout = new com.vaadin.flow.component.masterdetaillayout.MasterDetailLayout();
+        MasterDetailLayout layout = new MasterDetailLayout();
         layout.setMaster(new com.vaadin.flow.component.html.Span("master"));
         layout.setDetail(new Div(label, field));
 
@@ -747,8 +760,13 @@ void withAriaLabelContaining_substringMatch() {
 
         TestComponent noAria = new TestComponent();
 
+        // Non-matching aria-label — must be excluded from the result.
+        TestComponent unrelated = new TestComponent();
+        unrelated.getElement().setAttribute("aria-label", "Close dialog");
+
         UI.getCurrent().getElement().appendChild(reset.getElement(),
-                submit.getElement(), noAria.getElement());
+                submit.getElement(), noAria.getElement(),
+                unrelated.getElement());
 
         Assertions.assertIterableEquals(List.of(reset, submit),
                 find(TestComponent.class).withAriaLabelContaining("form")
@@ -758,14 +776,14 @@ void withAriaLabelContaining_substringMatch() {
     @Test
     void withLabel_null_throws() {
         ComponentQuery<TestComponent> query = find(TestComponent.class);
-        Assertions.assertThrows(NullPointerException.class,
+        Assertions.assertThrows(IllegalArgumentException.class,
                 () -> query.withLabel(null));
     }
 
     @Test
     void withAriaLabel_null_throws() {
         ComponentQuery<TestComponent> query = find(TestComponent.class);
-        Assertions.assertThrows(NullPointerException.class,
+        Assertions.assertThrows(IllegalArgumentException.class,
                 () -> query.withAriaLabel(null));
     }
 
diff --git a/shared/src/main/java/com/vaadin/browserless/ElementConditions.java b/shared/src/main/java/com/vaadin/browserless/ElementConditions.java
index ec30b6aa..96c2329e 100644
--- a/shared/src/main/java/com/vaadin/browserless/ElementConditions.java
+++ b/shared/src/main/java/com/vaadin/browserless/ElementConditions.java
@@ -216,7 +216,9 @@ public static <T extends Component> Predicate<T> hasNotAttribute(
      *            the expected label, not {@literal null}
      */
     public static <T extends Component> Predicate<T> hasLabel(String label) {
-        Objects.requireNonNull(label, "label must not be null");
+        if (label == null) {
+            throw new IllegalArgumentException("label cannot be null");
+        }
         return component -> matchesLabel(component, label, false);
     }
 
@@ -231,7 +233,9 @@ public static <T extends Component> Predicate<T> hasLabel(String label) {
      */
     public static <T extends Component> Predicate<T> labelContains(
             String text) {
-        Objects.requireNonNull(text, "text must not be null");
+        if (text == null) {
+            throw new IllegalArgumentException("text cannot be null");
+        }
         return component -> matchesLabel(component, text, true);
     }
 
@@ -275,7 +279,9 @@ private static String referringLabelText(Element root, String id) {
      */
     public static <T extends Component> Predicate<T> hasAriaLabel(
             String ariaLabel) {
-        Objects.requireNonNull(ariaLabel, "ariaLabel must not be null");
+        if (ariaLabel == null) {
+            throw new IllegalArgumentException("ariaLabel cannot be null");
+        }
         return component -> ariaLabel
                 .equals(component.getElement().getAttribute("aria-label"));
     }
@@ -289,7 +295,9 @@ public static <T extends Component> Predicate<T> hasAriaLabel(
      */
     public static <T extends Component> Predicate<T> ariaLabelContains(
             String text) {
-        Objects.requireNonNull(text, "text must not be null");
+        if (text == null) {
+            throw new IllegalArgumentException("text cannot be null");
+        }
         return component -> {
             String label = component.getElement().getAttribute("aria-label");
             return label != null && label.contains(text);