• Home
• com.github.mvysny.kaributesting
• karibu-testing-v10
• 2.2.0
• source code
• LocatorJ.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

com.github.mvysny.kaributesting.v10.LocatorJ Maven / Gradle / Ivy

package com.github.mvysny.kaributesting.v10;

import com.vaadin.flow.component.*;

import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

import java.util.List;
import java.util.function.Consumer;

import kotlin.Unit;

/**
 * To use this class, don't forget to add import static com.github.karibu.testing.LocatorJ.*; to your test class.
 *
 * @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.
     *
     * @param clazz the component class
     * @param  the component type
     * @return the only matching component, never null.
     * @throws IllegalArgumentException if no component matched, or if more than one component matches.
     */
    @NotNull
    public static  T _get(@NotNull Class clazz) {
        return LocatorKt._get(clazz, searchSpec -> Unit.INSTANCE);
    }

    /**
     * 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.
     * 

     * Example:
     * 

     * import static com.github.karibu.testing.LocatorJ.*;
     * _get(TextField.class, spec -> spec.withCaption("Name:").withId("name"));
     * 
     *
     * @param clazz the component must be of this class.
     * @param spec  allows you to add search criterion.
     * @param  the component type
     * @return the only matching component, never null.
     * @throws IllegalArgumentException if no component matched, or if more than one component matches.
     */
    @NotNull
    public static  T _get(@NotNull Class clazz, @NotNull Consumer> spec) {
        return LocatorKt._get(clazz, ss -> {
            spec.accept(new SearchSpecJ<>(ss));
            return Unit.INSTANCE;
        });
    }

    /**
     * Finds a VISIBLE component of given type which matches given class. The receiver and all of its descendants are searched.
     *
     * @param receiver the parent layout to search in, not null.
     * @param clazz    the component class
     * @param  the component type
     * @return the only matching component, never null.
     * @throws IllegalArgumentException if no component matched, or if more than one component matches.
     */
    @NotNull
    public static  T _get(@NotNull Component receiver, @NotNull Class clazz) {
        return LocatorKt._get(receiver, clazz, searchSpec -> Unit.INSTANCE);
    }

    /**
     * Finds a VISIBLE component of given clazz which matches given spec. The receiver and all of its descendants are searched.
     * 

     * Example:
     * 

     * import static com.github.karibu.testing.LocatorJ.*;
     * _get(layout, TextField.class, spec -> spec.withCaption("Name:").withId("name"));
     * 
     *
     * @param receiver the parent layout to search in, not null.
     * @param clazz    the component must be of this class.
     * @param spec     allows you to add search criterion.
     * @param  the component type
     * @return the only matching component, never null.
     * @throws IllegalArgumentException if no component matched, or if more than one component matches.
     */
    @NotNull
    public static  T _get(@NotNull Component receiver, @NotNull Class clazz, @NotNull Consumer> spec) {
        return LocatorKt._get(receiver, clazz, ss -> {
            spec.accept(new SearchSpecJ<>(ss));
            return Unit.INSTANCE;
        });
    }

    /**
     * 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 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.
     * 

     * 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
     * possible to call {@link #_fireValueChange(AbstractField, boolean)} with fromClient=true instead.
     * @param receiver the component
     * @param value the new value
     * @param  the value type
     * @throws IllegalStateException if the field was not visible, not enabled or was read-only.
     */
    public static  void _setValue(@NotNull HasValue receiver, @Nullable V value) {
        HasValueUtilsKt.set_value(receiver, value);
    }

    /**
     * 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.
     * 

     * The function fires the value change event; the {@link HasValue.ValueChangeEvent#isFromClient()} will
     * mirror the fromClient parameter.
     * @throws IllegalStateException if the field was not visible, not enabled or was read-only.
     */
    static  void _setValue(@NotNull HasValue self, @Nullable V value, boolean fromClient) {
        HasValueUtilsKt._setValue(self, value, fromClient);
    }

    /**
     * Fires a value change event which "comes from the client".
     * 

     * 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
     * @param fromClient whether the event comes from the client or not.
     * @param  the type of the component
     * @throws IllegalStateException if the field was not visible, not enabled or was read-only.
     */
    public static > void _fireValueChange(@NotNull C receiver, boolean fromClient) {
        HasValueUtilsKt._fireValueChange(receiver, fromClient);
    }

    /**
     * Fires a value change event which "comes from the client".
     * 

     * 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
     * @param  the type of the component
     * @throws IllegalStateException if the field was not visible, not enabled or was read-only.
     */
    public static > void _fireValueChange(@NotNull C receiver) {
        _fireValueChange(receiver, true);
    }

    /**
     * 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  the type of components being returned.
     * @return the list of matching components, may be empty.
     */
    @NotNull
    public static  List _find(@NotNull Class clazz) {
        return LocatorKt._find(clazz, spec -> Unit.INSTANCE);
    }

    /**
     * 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  the type of components being returned.
     * @return the list of matching components, may be empty.
     */
    @NotNull
    public static  List _find(@NotNull Class clazz, @NotNull Consumer> spec) {
        return LocatorKt._find(clazz, ss -> {
            spec.accept(new SearchSpecJ<>(ss));
            return Unit.INSTANCE;
        });
    }

    /**
     * Finds a list of VISIBLE components of given class. Given component and all of its descendants are searched.
     * @param receiver search this component and all of its descendants.
     * @param clazz the requested type of returned components.
     * @param  the type of components being returned.
     * @return the list of matching components, may be empty.
     */
    @NotNull
    public static  List _find(@NotNull Component receiver, @NotNull Class clazz) {
        return LocatorKt._find(receiver, clazz, spec -> Unit.INSTANCE);
    }

    /**
     * Finds a list of VISIBLE components of given class which matches given spec. Given component and all of its descendants are searched.
     * @param receiver search this component and all of its descendants.
     * @param clazz the requested type of returned components.
     * @param spec configures the search criteria.
     * @param  the type of components being returned.
     * @return the list of matching components, may be empty.
     */
    @NotNull
    public static  List _find(@NotNull Component receiver, @NotNull Class clazz, @NotNull Consumer> spec) {
        return LocatorKt._find(receiver, clazz, ss -> {
            spec.accept(new SearchSpecJ<>(ss));
            return Unit.INSTANCE;
        });
    }

    /**
     * Expects that there are no VISIBLE components in the current UI of given class. The {@link UI#getCurrent()} and all of its descendants are searched.
     * @param clazz the requested type of matched components.
     * @throws IllegalArgumentException if one or more components matched.
     */
    public static void _assertNone(@NotNull Class clazz) {
        LocatorKt._expectNone(clazz, spec -> Unit.INSTANCE);
    }

    /**
     * Expects that there are no VISIBLE components in the current UI of given class which matches spec. The {@link UI#getCurrent()} and all of its descendants are searched.
     * @param clazz the type of the matching component.
     * @param spec configures the search criteria.
     * @param  the type of the matching component.
     * @throws IllegalArgumentException if one or more components matched.
     */
    public static  void _assertNone(@NotNull Class clazz, @NotNull Consumer> spec) {
        LocatorKt._expectNone(clazz, ss -> {
            spec.accept(new SearchSpecJ<>(ss));
            return Unit.INSTANCE;
        });
    }

    /**
     * Expects that there are no VISIBLE components of given class. The receiver component and all of its descendants are searched.
     * @param receiver search this component and all of its descendants.
     * @param clazz the type of the matching component.
     * @throws IllegalArgumentException if one or more components matched.
     */
    public static void _assertNone(@NotNull Component receiver, @NotNull Class clazz) {
        LocatorKt._expectNone(receiver, clazz, ss -> Unit.INSTANCE);
    }

    /**
     * Expects that there are no VISIBLE components of given class matching given spec. The receiver component and all of its descendants are searched.
     * @param receiver search this component and all of its descendants.
     * @param clazz the type of the matching component.
     * @param spec configures the search criteria.
     * @param  the type of the matching component.
     * @throws IllegalArgumentException if one or more components matched.
     */
    public static  void _assertNone(@NotNull Component receiver, @NotNull Class clazz, @NotNull Consumer> spec) {
        LocatorKt._expectNone(receiver, clazz, ss -> {
            spec.accept(new SearchSpecJ<>(ss));
            return Unit.INSTANCE;
        });
    }

    /**
     * Expects that there is exactly ono VISIBLE components in the current UI of given class. The {@link UI#getCurrent()} and all of its descendants are searched.
     * @param clazz    the component must be of this class.
     * @throws AssertionError if none, or more than one component matched.
     */
    public static void _assertOne(@NotNull Class clazz) {
        LocatorKt._expectOne(clazz, spec -> Unit.INSTANCE);
    }

    /**
     * Expects that there is exactly one VISIBLE components in the current UI of given class which matches spec. The {@link UI#getCurrent()} and all of its descendants are searched.
     * @param clazz    the component must be of this class.
     * @param spec     allows you to add search criterion.
     * @param  the component must be of this type.
     * @throws AssertionError if none, or more than one component matched.
     */
    public static  void _assertOne(@NotNull Class clazz, @NotNull Consumer> spec) {
        LocatorKt._expectOne(clazz, ss -> {
            spec.accept(new SearchSpecJ<>(ss));
            return Unit.INSTANCE;
        });
    }

    /**
     * Expects that there is exactly one VISIBLE components of given class. The receiver component and all of its descendants are searched.
     * @param receiver the parent layout to search in, not null.
     * @param clazz    the component must be of this class.
     * @throws AssertionError if none, or more than one component matched.
     */
    public static void _assertOne(@NotNull Component receiver, @NotNull Class clazz) {
        LocatorKt._expectOne(receiver, clazz, ss -> Unit.INSTANCE);
    }

    /**
     * Expects that there is exactly one VISIBLE components of given class matching given spec. The receiver component and all of its descendants are searched.
     * @param receiver the parent layout to search in, not null.
     * @param clazz    the component must be of this class.
     * @param spec     allows you to add search criterion.
     * @param  the component must be of this type.
     * @throws AssertionError if none, or more than one component matched.
     */
    public static  void _assertOne(@NotNull Component receiver, @NotNull Class clazz, @NotNull Consumer> spec) {
        LocatorKt._expectOne(receiver, clazz, ss -> {
            spec.accept(new SearchSpecJ<>(ss));
            return Unit.INSTANCE;
        });
    }

    /**
     * Expects that there are exactly {@code count} VISIBLE components in the current UI match {@code block}. The {@link UI#getCurrent} and all of its descendants are searched.
     * @param clazz the component must be of this class.
     * @param count this count of components must match
     * @throws AssertionError if incorrect count of component matched.
     */
    public static void _assert(@NotNull Class clazz, int count) {
        LocatorKt._expect(clazz, count, spec -> Unit.INSTANCE);
    }

    /**
     * Expects that there are exactly {@code count} VISIBLE components in the current UI of given class which matches spec. The {@link UI#getCurrent()} and all of its descendants are searched.
     * @param clazz    the component must be of this class.
     * @param count this count of components must match
     * @param spec     allows you to add search criterion.
     * @param  the component must be of this type.
     * @throws AssertionError if incorrect count of component matched.
     */
    public static  void _assert(@NotNull Class clazz, int count, @NotNull Consumer> spec) {
        LocatorKt._expect(clazz, count, ss -> {
            spec.accept(new SearchSpecJ<>(ss));
            return Unit.INSTANCE;
        });
    }

    /**
     * Expects that there are exactly {@code count} VISIBLE components of given class. The receiver component and all of its descendants are searched.
     * @param receiver the parent layout to search in, not null.
     * @param clazz    the component must be of this class.
     * @param count this count of components must match
     * @throws AssertionError if incorrect count of component matched.
     */
    public static void _assert(@NotNull Component receiver, @NotNull Class clazz, int count) {
        LocatorKt._expect(receiver, clazz, count, ss -> Unit.INSTANCE);
    }

    /**
     * Expects that there are exactly {@code count} VISIBLE components of given class matching given spec. The receiver component and all of its descendants are searched.
     * @param receiver the parent layout to search in, not null.
     * @param clazz    the component must be of this class.
     * @param count this count of components must match
     * @param spec     allows you to add search criterion.
     * @param  the component must be of this type.
     * @throws AssertionError if incorrect count of component matched.
     */
    public static  void _assert(@NotNull Component receiver, @NotNull Class clazz, int count, @NotNull Consumer> spec) {
        LocatorKt._expect(receiver, clazz, count, ss -> {
            spec.accept(new SearchSpecJ<>(ss));
            return Unit.INSTANCE;
        });
    }

    /**
     * Expects that there are no dialogs shown.
     */
    public static void _assertNoDialogs() {
        LocatorKt._expectNoDialogs();
    }

    /**
     * Fails if given component is not {@link HasEnabled#isEnabled()}.
     * May succeed when the parent is disabled.
     * @param component the component to check
     */
    public static void _assertEnabled(@NotNull Component component) {
        BasicUtilsKt._expectEnabled(component);
    }

    /**
     * Fails if given component is {@link HasEnabled#isEnabled()}.
     * May succeed when the parent is disabled.
     * @param component the component to check
     */
    public static void _assertDisabled(@NotNull Component component) {
        BasicUtilsKt._expectDisabled(component);
    }

    /**
     * Checks that a component is actually editable by the user:
     * 
The component must be effectively visible: it itself must be visible, its parent must be visible and all of its ascendants must be visible.
     *   For the purpose of testing individual components not attached to the UI, a component may be considered visible even though it's not
     *   currently nested in a UI.
     * 
The component must be effectively enabled: it itself must be enabled, its parent must be enabled and all of its ascendants must be enabled.
     * 
If the component is HasValue, it must not be HasValue.isReadOnly.
     * 
     * @param component the component to check
     * @throws IllegalStateException if any of the above doesn't hold.
     */
    public static void assertEditableByUser(@NotNull Component component) {
        BasicUtilsKt._expectEditableByUser(component);
    }

    /**
     * Fails if given component is not {@link HasValue#isReadOnly() read-only}.
     * @param component the component to check
     */
    public static void _assertReadOnly(@NotNull HasValue component) {
        BasicUtilsKt._expectReadOnly(component);
    }

    /**
     * Fails if given component is {@link HasValue#isReadOnly() read-only}.
     * @param component the component to check
     */
    public static void _assertNotReadOnly(@NotNull HasValue component) {
        BasicUtilsKt._expectNotReadOnly(component);
    }

    /**
     * Pretty-prints the Vaadin component tree to the stdout, for example:
     * 

     * └── MockedUI[]
     *     └── Button[text='Hello!']
     * 
     */
    public static void _dump() {
        LocatorKt._dump();
    }
}