Package com.vaadin.browserless.locator

Class Locator

  • All Implemented Interfaces:
    
public abstract class Locator<C extends Component, SELF extends Locator<C, SELF>>

    Base class for the find* tester API. A locator is a fluent combination of a ComponentQuery filter chain and a tester: the subclass exposes both the filter methods inherited from this class and the action methods specific to the component type.

    Resolution is deferred to the first action call (component) and cached. Every filter method on this class clears the resolution cache before mutating the underlying query, so the next action re-resolves and callers never have to call invalidate between fluent steps. Filter steps keep the locator's atIndex pick sticky — it is part of the filter chain — so a single locator instance can be reused across an asynchronous boundary (e.g. roundTrip()) without holding on to a stale component reference. invalidate is the explicit rewind hatch and additionally clears the pick.

    Filters that this class does not expose directly (for example withPropertyValue or withResultsSize) are reachable through the with escape hatch, which lets callers compose any filter the underlying ComponentQuery supports without subclassing.

    Construction modes. The default constructor (Locator) seeds an empty query that searches the active UI. Tests that already hold a direct reference to the component they want to act on can instead use the seeded-query constructor (Locator), which pre-filters the query with an identity predicate. Both modes share the same filter/resolution machinery — additional filters compose on top of the identity predicate, and a filter that excludes the seeded component just makes exists return false and component throw. Custom locator subclasses can opt in by declaring a second constructor that forwards to super(Class, component).

    Since:

    1.1

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description

    • Field Summary

      Fields 
      Modifier and Type Field Description

    • Constructor Summary

      Constructors 
      Constructor Description

    • Enum Constant Summary

      Enum Constants 
      Enum Constant Description

    • Method Summary

      Modifier and Type Method Description
      SELF withId(String id) Requires the matched component to have the given id.
      SELF withTestId(String testId) Requires the matched component to have the given data-testid attribute, as set by setTestId.
      SELF withClassName(Array<String> className) Requires the matched component to have all the given CSS class names.
      SELF withoutClassName(Array<String> className) Requires the matched component to have none of the given CSS class names.
      SELF withAttribute(String attribute) Requires the matched component to have the given attribute set.
      SELF withAttribute(String attribute, String value) Requires the matched component to have the given attribute with the expected value.
      SELF withoutAttribute(String attribute) Requires the matched component not to have the given attribute.
      SELF withoutAttribute(String attribute, String value) Requires the matched component not to have the given attribute value (or not to have the attribute at all).
      SELF withCondition(Predicate<C> condition) Requires the matched component to satisfy the given predicate.
      SELF with(UnaryOperator<ComponentQuery<C>> op) Escape hatch for filters not directly exposed on Locator.
      SELF inside(Component parent) Scopes the search to descendants of the given component.
      SELF inside(Locator<out Object, out Object> parent) Scopes the search to descendants of the component matched by the given locator.
      SELF atIndex(int index) Picks the n-th match (1-based) when the filter chain yields multiple matches.
      C component() Resolves the locator to a single matching component, caching the result.
      List<C> components() Returns all matching components, bypassing the cache.
      boolean exists() Returns true if the filter chain matches at least one component.
      SELF invalidate() Rewinds picker state: discards any cached resolution and clears the atIndex pick.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

    • Method Detail

      • withId

         SELF withId(String id)

        Requires the matched component to have the given id.

      • withTestId

         SELF withTestId(String testId)

        Requires the matched component to have the given data-testid attribute, as set by setTestId.

      • withAttribute

         SELF withAttribute(String attribute)

        Requires the matched component to have the given attribute set.

      • withAttribute

         SELF withAttribute(String attribute, String value)

        Requires the matched component to have the given attribute with the expected value.

      • withoutAttribute

         SELF withoutAttribute(String attribute, String value)

        Requires the matched component not to have the given attribute value (or not to have the attribute at all).

      • with

         SELF with(UnaryOperator<ComponentQuery<C>> op)

        Escape hatch for filters not directly exposed on Locator. Applies the given operator to the underlying ComponentQuery, letting users compose any filter the query supports without subclassing. 

        findButton().with(q -> q.withPropertyValue(Button::getText, "Save"))
        .click();
        Honors the UnaryOperator contract: whatever the operator returns becomes the locator's new underlying query. ComponentQuery's built-in filter methods all return this, so a fluent chain just re-installs the same instance; an operator that builds and returns a fresh query replaces the prior one wholesale.

      • inside

         SELF inside(Component parent)

        Scopes the search to descendants of the given component. Replaces any lazy parent previously installed by inside with a fixed reference.

      • inside

         SELF inside(Locator<out Object, out Object> parent)

        Scopes the search to descendants of the component matched by the given locator.

        The parent is resolved lazily, at child-resolution time: each call to component, components, or exists first invokes parent.component() and installs the result as this locator's search context. A later invalidate on parent therefore propagates — the next child action re-resolves both. Calling inside afterwards replaces this lazy parent with a fixed reference; calling inside(Locator) again replaces the lazy parent.

      • atIndex

         SELF atIndex(int index)

        Picks the n-th match (1-based) when the filter chain yields multiple matches. Without this, the default expectation is exactly one match.

      • component

         C component()

        Resolves the locator to a single matching component, caching the result. Subclasses call this from action methods (e.g. click).

        Returns:

        the matched component

      • components

         List<C> components()

        Returns all matching components, bypassing the cache. Useful for assertions on counts without committing to a single match.

      • exists

         boolean exists()

        Returns true if the filter chain matches at least one component.

      • invalidate

         SELF invalidate()

        Rewinds picker state: discards any cached resolution and clears the atIndex pick. Filter methods on this class call a private cache-only reset internally, so they keep the locator's atIndex(n) sticky as part of the filter chain. invalidate() is the explicit "rewind" hatch: after a UI change that replaces or detaches the resolved component, calling it forces the next action to re-resolve, and also drops the pick so the next resolution defaults back to "single match expected" until the caller re-applies atIndex.