Constructor Detail

• ComponentQuery

  ComponentQuery(Class<T> componentType)

  Creates a new instance of ComponentQuery to search for components of given type.

  Parameters:

  componentType - the type of the component(s) to search for

Method Detail

• withPropertyValue

   <V> ComponentQuery<T> withPropertyValue(Function<T, V> getter, V expectedValue)

  Requires the given property to have expected value.

  Parameters:

  getter - the function to get the value of the property of the field, not null

  expectedValue - value to be compared with the one obtained by applying the getter function to a component instance

  Returns:

  this element query instance for chaining

• withValue

   <V> ComponentQuery<T> withValue(V expectedValue)

  Requires the component to be an implementation of com.vaadin.flow.component.HasValue interface and to have exactly the given value. Providing a null value as expectedValue has no effects since the filter will not be applied.

  Parameters:

  expectedValue - value to be compared with the one obtained by getValue

  Returns:

  this element query instance for chaining

• withId

   ComponentQuery<T> withId(String id)

  Requires the component to have the given id

  Parameters:

  id - the id to look up

  Returns:

  this element query instance for chaining

• withTestId

   ComponentQuery<T> withTestId(String testId)

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

  Test ids are expected to be unique within the UI, so a match always resolves to at most one component (just like withId).

  Parameters:

  testId - the test id to look up

  Returns:

  this element query instance for chaining

  Since:

  1.1

• withCondition

   ComponentQuery<T> withCondition(Predicate<T> condition)

  Requires the components to satisfy the given condition.

  Parameters:

  condition - the condition to check against the components.

  Returns:

  this element query instance for chaining

• withClassName

   ComponentQuery<T> withClassName(Array<String> className)

  Requires the components to have all the given CSS class names

  Parameters:

  className - required CSS class names, not null

  Returns:

  this element query instance for chaining

• withoutClassName

   ComponentQuery<T> withoutClassName(Array<String> className)

  Requires the components to have none of the given CSS class names

  Parameters:

  className - CSS class names that component should not have, not null

  Returns:

  this element query instance for chaining

• withTheme

   ComponentQuery<T> withTheme(ThemeVariant variant)

  Add a theme variant that should be set on the target component. Prefer this over the raw-string withTheme so the IDE can autocomplete the variant and a typo becomes a compile error.

  
  ui.find(Button.class).withTheme(ButtonVariant.LUMO_PRIMARY).all();
  

  Parameters:

  variant - the variant to require on the component

  Returns:

  this element query instance for chaining

  Since:

  1.1

• withTheme

  @Deprecated() ComponentQuery<T> withTheme(String theme)

  Add theme that should be set on the target component.

  Parameters:

  theme - theme that should exist on the component.

  Returns:

  this element query instance for chaining

• withoutTheme

   ComponentQuery<T> withoutTheme(ThemeVariant variant)

  Add a theme variant that should not be set on the target component. Prefer this over the raw-string withoutTheme for the same reasons as withTheme.

  Parameters:

  variant - the variant that should not be present on the component

  Returns:

  this element query instance for chaining

  Since:

  1.1

• withoutTheme

  @Deprecated() ComponentQuery<T> withoutTheme(String theme)

  Add theme that should not be available on the target component.

  Parameters:

  theme - theme that should not exist on the component.

  Returns:

  this element query instance for chaining

• withCaption

   ComponentQuery<T> withCaption(String caption)

  Requires the component to have a caption equal to the given text Concept of caption vary based on the component type. The check is usually made against the com.vaadin.flow.dom.Elementlabel property, but for some component (e.g. Button) the text content may be used.

  Parameters:

  caption - the text the component is expected to have as its caption

  Returns:

  this element query instance for chaining

• withCaptionContaining

   ComponentQuery<T> withCaptionContaining(String text)

  Requires the component to have a caption containing the given text Concept of caption vary based on the component type. The check is usually made against the com.vaadin.flow.dom.Elementlabel property, but for some component (e.g. Button) the text content may be used.

  Parameters:

  text - the text the component is expected to have as its caption

  Returns:

  this element query instance for chaining

• withLabel

   ComponentQuery<T> withLabel(String label)

  Requires the component's 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.

  Parameters:

  label - the expected label, not null

  Returns:

  this element query instance for chaining

  Since:

  1.1

• withLabelContaining

   ComponentQuery<T> withLabelContaining(String text)

  Requires the component's label property to contain the given text.

  Parameters:

  text - substring to find in the label, not null

  Returns:

  this element query instance for chaining

  Since:

  1.1

• withPlaceholder

   ComponentQuery<T> withPlaceholder(String placeholder)

  Requires the component's placeholder to be exactly the given value. Useful for toolbar / search fields that intentionally omit a stacked label and identify themselves to the user via placeholder text instead.

  Parameters:

  placeholder - the expected placeholder, not null

  Returns:

  this element query instance for chaining

  Since:

  1.1

• withPlaceholderContaining

   ComponentQuery<T> withPlaceholderContaining(String text)

  Requires the component's placeholder to contain the given text. Comparison is case-sensitive. Read in the same way as withPlaceholder.

  Parameters:

  text - substring to find in the placeholder, not null

  Returns:

  this element query instance for chaining

  Since:

  1.1

• withAriaLabel

   ComponentQuery<T> withAriaLabel(String ariaLabel)

  Requires the component's aria-label attribute to be exactly the given value. Useful for components like Button that don't carry a visible label property but identify themselves to assistive technology via aria-label.

  Parameters:

  ariaLabel - the expected aria-label, not null

  Returns:

  this element query instance for chaining

  Since:

  1.1

• withAriaLabelContaining

   ComponentQuery<T> withAriaLabelContaining(String text)

  Requires the component's aria-label attribute to contain the given text.

  Parameters:

  text - substring to find in the aria-label, not null

  Returns:

  this element query instance for chaining

  Since:

  1.1

• withText

   ComponentQuery<T> withText(String text)

  Requires the text content of the component to be equal to the given text

  Parameters:

  text - the text the component is expected to have as its content

  Returns:

  this element query instance for chaining

• withTextContaining

   ComponentQuery<T> withTextContaining(String text)

  Requires the text content of the component to contain the given text

  Parameters:

  text - the text the component is expected to have as its caption

  Returns:

  this element query instance for chaining

• withResultsSize

   ComponentQuery<T> withResultsSize(int count)

  Requires the search to find exactly the given number of components

  Parameters:

  count - the expected number of component retrieved by the search

  Returns:

  this element query instance for chaining

• withResultsSize

   ComponentQuery<T> withResultsSize(int min, int max)

  Requires the search to find a number of components within given range

  Parameters:

  min - minimum number of components that should be found (inclusive)

  max - maximum number of components that should be found (inclusive)

  Returns:

  this element query instance for chaining

• withMinResults

   ComponentQuery<T> withMinResults(int min)

  Requires the search to find at least the given number of components

  Parameters:

  min - minimum number of components that should be found (inclusive)

  Returns:

  this element query instance for chaining

• withMaxResults

   ComponentQuery<T> withMaxResults(int max)

  Requires the search to find at most the given number of components

  Parameters:

  max - maximum number of components that should be found (inclusive)

  Returns:

  this element query instance for chaining

• withAttribute

   ComponentQuery<T> withAttribute(String attribute)

  Requires the search to find components with the given attribute set, independently of its value.

  Parameters:

  attribute - the name of the attribute, not null

  Returns:

  this element query instance for chaining

• withAttribute

   ComponentQuery<T> withAttribute(String attribute, String value)

  Requires the search to find components having the given attribute with exactly the expected value.

  Parameters:

  attribute - the name of the attribute, not null

  value - value expected to be set on attribute, not null

  Returns:

  this element query instance for chaining

• withoutAttribute

   ComponentQuery<T> withoutAttribute(String attribute)

  Requires the search to find components without the given attribute.

  Parameters:

  attribute - the name of the attribute, not null

  Returns:

  this element query instance for chaining

• withoutAttribute

   ComponentQuery<T> withoutAttribute(String attribute, String value)

  Requires the search to find components having the given attribute value different from the provided one, or to not have the attribute at all.

  Parameters:

  attribute - the name of the attribute, not null

  value - value expected not to be set on attribute, not null

  Returns:

  this element query instance for chaining

• thenOnFirst

   <E extends Component> ComponentQuery<E> thenOnFirst(Class<E> componentType)

  Gets a new ComponentQuery to search for given component type on the context of first matching component for current query.

  Parameters:

  componentType - the type of the component(s) to search for

  Returns:

  a new query object, to search for nested components.

• thenOn

   <E extends Component> ComponentQuery<E> thenOn(int index, Class<E> componentType)

  Gets a new ComponentQuery to search for given component type on the context of the matching component at given index for current query. Index is 1-based. Given a zero or negative index or an index higher than the actual number of components found results in an IndexOutOfBoundsException.

  Parameters:

  componentType - the type of the component(s) to search for

  Returns:

  a new query object, to search for nested components.

• single

   T single()

  Executes the search against current context and returns the component, expecting to find exactly one. Exceptions are thrown if the search produces zero or more than one result.

  Returns:

  the component of the type specified in the constructor.

• first

  @Deprecated(since = "10.0", forRemoval = true) T first()

  Executes the search against current context and returns the first result.

  Warning: This method can lead to flaky tests when multiple matching components exist, as it arbitrarily selects the first one without validation. Consider using single instead, which asserts that exactly one component matches and fails immediately if multiple components are found, making tests more reliable and failures easier to diagnose.

  Returns:

  a component of the type specified in the constructor.

• last

   T last()

  Executes the search against current context and returns the last result.

  Returns:

  a component of the type specified in the constructor.

• atIndex

   T atIndex(int index)

  Executes the search against current context and returns the component at given index. Index is 1-based. Given a zero or negative index or an index higher than the actual number of components found results in an IndexOutOfBoundsException.

  Returns:

  the component of the type specified in the constructor.

• id

   T id(String id)

  Executes a search for a component with the given id.

  Parameters:

  id - the id to look up

  Returns:

  the component with the given id

• testId

   T testId(String testId)

  Executes a search for a component with the given data-testid attribute, as set by setTestId.

  Parameters:

  testId - the test id to look up

  Returns:

  the component with the given test id

  Since:

  1.1

• exists

   boolean exists()

  Checks if this ComponentQuery describes existing components.

  Returns:

  true if components are found, otherwise false.

• all

   List<T> all()

  Executes the search against current context and returns a list of matching components.

  Returns:

  a list of found components, or an empty list if search does not produce results. Never null.

• from

   ComponentQuery<T> from(Component context)

  Sets the context to search inside. If a null value is given, the search will be performed againt the UI.

  Parameters:

  context - a component used as starting element for search.

  Returns:

  this component query instance for chaining.