fix javadoc

karibu-testing-v10/src/main/java/com/github/mvysny/kaributesting/v10/LocatorJ.java

@@ -1,7 +1,6 @@
 package com.github.mvysny.kaributesting.v10;
 
 import com.vaadin.flow.component.*;
-import com.vaadin.flow.component.button.Button;
 
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -17,6 +16,10 @@
  * @author mavi
  */
 public class LocatorJ {
+    /**
+     * Utility class with static functions only, not meant to be instantiated.
+     */
+    private LocatorJ() {}
     /**
      * Finds a VISIBLE component of given type which matches given class. {@link UI#getCurrent()} all of its descendants are searched.
      *
@@ -32,10 +35,12 @@ public static <T extends Component> T _get(@NotNull Class<T> clazz) {
 
     /**
      * Finds a VISIBLE component in the current UI of given clazz which matches given spec. The {@link UI#getCurrent()} and all of its descendants are searched.
-     * <p>
+     * <br/>
      * Example:
-     * <code>import static com.github.karibu.testing.LocatorJ.*; _get(TextField.class, spec -&gt; spec.withCaption("Name:").withId("name"));</code>
-     * </p>
+     * <pre><code>
+     * import static com.github.karibu.testing.LocatorJ.*;
+     * _get(TextField.class, spec -&gt; spec.withCaption("Name:").withId("name"));
+     * </code></pre>
      *
      * @param clazz the component must be of this class.
      * @param spec  allows you to add search criterion.
@@ -67,9 +72,12 @@ public static <T extends Component> T _get(@NotNull Component receiver, @NotNull
 
     /**
      * Finds a VISIBLE component of given clazz which matches given spec. The receiver and all of its descendants are searched.
-     * <p></p>
+     * <br/>
      * Example:
-     * <code>import static com.github.karibu.testing.LocatorJ.*; _get(layout, TextField.class, spec -&gt; spec.withCaption("Name:").withId("name"));</code>
+     * <pre><code>
+     * import static com.github.karibu.testing.LocatorJ.*;
+     * _get(layout, TextField.class, spec -&gt; spec.withCaption("Name:").withId("name"));
+     * </code></pre>
      *
      * @param receiver the parent layout to search in, not null.
      * @param clazz    the component must be of this class.
@@ -88,17 +96,17 @@ public static <T extends Component> T _get(@NotNull Component receiver, @NotNull
 
     /**
      * Clicks the button, but only if it is actually possible to do so by the user. If the button is read-only or disabled, an exception is thrown.
-     *
+     * @param button button to click.
      * @throws IllegalStateException if the button was not visible or not enabled.
      */
-    public static void _click(@NotNull ClickNotifier<?> receiver) {
-        ButtonKt._click(receiver);
+    public static void _click(@NotNull ClickNotifier<?> button) {
+        ButtonKt._click(button);
     }
 
     /**
      * Sets the value of given component, but only if it is actually possible to do so by the user.
      * If the component is read-only or disabled, an exception is thrown.
-     * <p></p>
+     * <br/>
      * The function fires the value change event; the {@link HasValue.ValueChangeEvent#isFromClient()} will
      * return false indicating that the event came from the server. If this is not desired,
      * depending on your code, it may be
@@ -115,7 +123,7 @@ public static <V> void _setValue(@NotNull HasValue<?, V> receiver, @Nullable V v
     /**
      * Sets the value of given component, but only if it is actually possible to do so by the user.
      * If the component is read-only or disabled, an exception is thrown.
-     * <p></p>
+     * <br/>
      * The function fires the value change event; the {@link HasValue.ValueChangeEvent#isFromClient()} will
      * mirror the <code>fromClient</code> parameter.
      * @throws IllegalStateException if the field was not visible, not enabled or was read-only.
@@ -126,7 +134,7 @@ static <V> void _setValue(@NotNull HasValue<?, V> self, @Nullable V value, boole
 
     /**
      * Fires a value change event which "comes from the client".
-     * <p></p>
+     * <br/>
      * The event is only fired if it is actually possible to do so by the user.
      * If the component is read-only or disabled, an exception is thrown.
      * @param receiver the component, must be
@@ -140,7 +148,7 @@ static <V> void _setValue(@NotNull HasValue<?, V> self, @Nullable V value, boole
 
     /**
      * Fires a value change event which "comes from the client".
-     * <p></p>
+     * <br/>
      * The event is only fired if it is actually possible to do so by the user.
      * If the component is read-only or disabled, an exception is thrown.
      * @param receiver the component, must be
@@ -165,6 +173,7 @@ public static <T extends Component> List<T> _find(@NotNull Class<T> clazz) {
     /**
      * Finds a list of VISIBLE components of given class. {@link UI#getCurrent()} and all of its descendants are searched.
      * @param clazz the requested type of returned components.
+     * @param spec configures the search criteria.
      * @param <T> the type of components being returned.
      * @return the list of matching components, may be empty.
      */
@@ -389,7 +398,7 @@ public static void _assertDisabled(@NotNull Component component) {
      * @throws IllegalStateException if any of the above doesn't hold.
      */
     public static void assertEditableByUser(@NotNull Component component) {
-        BasicUtilsKt.checkEditableByUser(component);
+        BasicUtilsKt._expectEditableByUser(component);
     }
 
     /**

karibu-testing-v10/src/main/java/com/github/mvysny/kaributesting/v10/SearchSpecJ.java

@@ -14,12 +14,17 @@
 
 /**
  * A criterion for matching components. The component must match all of non-null fields.
+ * @param <T> the class of the component we are searching for.
  * @author mavi
  */
 public class SearchSpecJ<T extends Component> {
     @NotNull
     private final SearchSpec<T> spec;
 
+    /**
+     * Creates the criterion. You're not supposed to create instances yourself - they will be created for you by helper methods of the {@link LocatorJ} class.
+     * @param spec configure this delegate
+     */
     public SearchSpecJ(@NotNull SearchSpec<T> spec) {
         this.spec = spec;
     }
@@ -35,11 +40,24 @@ public SearchSpecJ<T> withId(@Nullable String id) {
         return this;
     }
 
+    /**
+     * The required {@link com.github.mvysny.kaributools.ComponentUtilsKt#getLabel(Component)}; if {@code null}, no particular label is matched.
+     * @param label The required {@link com.github.mvysny.kaributools.ComponentUtilsKt#getLabel(Component)}; if {@code null}, no particular label is matched.
+     * @return this
+     */
+    @NotNull
+    public SearchSpecJ<T> withLabel(@Nullable String label) {
+        spec.setLabel(label);
+        return this;
+    }
+
     /**
      * The required {@link com.github.mvysny.kaributools.ComponentUtilsKt#getCaption(Component)}; if {@code null}, no particular caption is matched.
-     * @param caption
+     * @param caption The required {@link com.github.mvysny.kaributools.ComponentUtilsKt#getCaption(Component)}; if {@code null}, no particular caption is matched.
      * @return this
      */
+    @SuppressWarnings("DeprecatedIsStillUsed")
+    @Deprecated(forRemoval = true)
     @NotNull
     public SearchSpecJ<T> withCaption(@Nullable String caption) {
         spec.setCaption(caption);
@@ -160,7 +178,7 @@ public SearchSpecJ<T> withoutThemes(@Nullable String themes) {
 
     /**
      * Adds additional predicate which the component needs to match. Not null.
-     * <p/>
+     * <br/>
      * Please remember to provide a proper {@link Object#toString()} for the predicate,
      * so that you'll get an informative error message on lookup failure.
      * @param predicate the matcher

karibu-testing-v10/src/main/kotlin/com/github/mvysny/kaributesting/v10/Locator.kt

@@ -14,7 +14,6 @@ import com.vaadin.flow.component.littemplate.LitTemplate
 import com.vaadin.flow.component.polymertemplate.PolymerTemplate
 import com.vaadin.flow.router.InternalServerError
 import java.io.PrintStream
-import java.util.*
 import java.util.function.Predicate
 
 /**
@@ -23,6 +22,7 @@ import java.util.function.Predicate
  * You can add more properties, simply by creating a write-only property which will register a new [predicates] on write. See
  * [Adding support for custom search criteria](https://github.com/mvysny/karibu-testing/tree/master/karibu-testing-v10#adding-support-for-custom-search-criteria)
  * for more details.
+ * @param T the class of the component we are searching for.
  * @property clazz the class of the component we are searching for.
  * @property id the required [Component.getId]; if null, no particular id is matched.
  * @property label the required [Component.label]; if null, no particular label is matched.

karibu-testing-v10/src/test/java/com/github/mvysny/kaributesting/v10/LocatorJApiTest.java

@@ -3,7 +3,7 @@
 import com.vaadin.flow.component.UI;
 import com.vaadin.flow.component.button.Button;
 import com.vaadin.flow.component.grid.Grid;
-import com.vaadin.flow.component.html.Label;
+import com.vaadin.flow.component.html.H1;
 import com.vaadin.flow.component.icon.Icon;
 import com.vaadin.flow.component.icon.VaadinIcon;
 import com.vaadin.flow.component.orderedlayout.VerticalLayout;
@@ -17,6 +17,7 @@
  * is hard to use from Java. This is an API test.
  * @author mavi
  */
+@SuppressWarnings("removal")
 public class LocatorJApiTest {
 
     public static class MainView extends VerticalLayout {}
@@ -28,32 +29,32 @@ public LocatorJApiTest() {
         final MainView main = (MainView) UI.getCurrent().getChildren().findFirst().get();
         main.getChildren().count();
 
-        _get(Label.class);
-        _get(Label.class, spec -> spec.withCaption("Name:").withId("foo"));
+        _get(H1.class);
+        _get(H1.class, spec -> spec.withLabel("Name:").withId("foo"));
         _get(new Button(), TextField.class);
-        _get(new VerticalLayout(), TextField.class, spec -> spec.withCaption("Name:").withId("foo").withCount(0));
+        _get(new VerticalLayout(), TextField.class, spec -> spec.withText("Name:").withId("foo").withCount(0));
 
-        _find(Label.class);
-        _find(Label.class, spec -> spec.withCaption("Name:").withId("foo"));
+        _find(H1.class);
+        _find(H1.class, spec -> spec.withCaption("Name:").withId("foo"));
         _find(new Button(), TextField.class);
         _find(new VerticalLayout(), TextField.class, spec -> spec.withCaption("Name:").withId("foo"));
 
-        _assertNone(Label.class);
-        _assertNone(Label.class, spec -> spec.withCaption("Name:").withId("foo"));
+        _assertNone(H1.class);
+        _assertNone(H1.class, spec -> spec.withCaption("Name:").withId("foo"));
         _assertNone(new Button(), TextField.class);
         _assertNone(new VerticalLayout(), TextField.class, spec -> spec.withCaption("Name:").withId("foo"));
 
-        _assertOne(Label.class);
-        _assertOne(Label.class, spec -> spec.withCaption("Name:").withId("foo"));
-        _assertOne(Label.class, spec -> spec.withCaption("Name:").withId("foo").withCount(0));
+        _assertOne(H1.class);
+        _assertOne(H1.class, spec -> spec.withCaption("Name:").withId("foo"));
+        _assertOne(H1.class, spec -> spec.withCaption("Name:").withId("foo").withCount(0));
         _assertOne(new Button(), TextField.class);
         _assertOne(new VerticalLayout(), TextField.class, spec -> spec.withCaption("Name:").withId("foo").withoutClasses("current"));
         _assertOne(new Icon(VaadinIcon.ABACUS), Icon.class, spec -> spec.withIcon(VaadinIcon.ABACUS));
         _assertOne(new Button(VaadinIcon.ABACUS.create()), Button.class, spec -> spec.withIcon(VaadinIcon.ABACUS));
 
-        _assert(Label.class, 2);
-        _assert(Label.class, 3, spec -> spec.withCaption("Name:").withId("foo"));
-        _assert(Label.class, 4, spec -> spec.withCaption("Name:").withId("foo").withCount(0));
+        _assert(H1.class, 2);
+        _assert(H1.class, 3, spec -> spec.withCaption("Name:").withId("foo"));
+        _assert(H1.class, 4, spec -> spec.withCaption("Name:").withId("foo").withCount(0));
         _assert(new Button(), TextField.class, 6);
         _assert(new VerticalLayout(), TextField.class, 3, spec -> spec.withCaption("Name:").withId("foo"));
 

karibu-testing-v10/src/test/java/com/github/mvysny/kaributesting/v10/MockVaadinJApiTest.java

@@ -15,11 +15,11 @@
 public class MockVaadinJApiTest {
 
     public MockVaadinJApiTest() {
-        UtilsKt.getMock(VaadinRequest.getCurrent()).addCookie(new Cookie("foo", "bar"));
-        assertEquals("bar", UtilsKt.getMock(VaadinResponse.getCurrent()).getCookie("foo").getValue());
+        UtilsKt.getFake(VaadinRequest.getCurrent()).addCookie(new Cookie("foo", "bar"));
+        assertEquals("bar", UtilsKt.getFake(VaadinResponse.getCurrent()).getCookie("foo").getValue());
 
         MockVaadin.setup(new Routes(), () -> {
-            UtilsKt.getMock(VaadinRequest.getCurrent()).addCookie(new Cookie("foo", "bar"));
+            UtilsKt.getFake(VaadinRequest.getCurrent()).addCookie(new Cookie("foo", "bar"));
             return new LocatorJApiTest.MyUI();
         });
     }