Contact us
Create app
com.vaadin.testbench.
Package com.vaadin.testbench

Class ElementQuery<T extends TestBenchElement>

java.lang.Object
com.vaadin.testbench.ElementQuery<T>
public class ElementQuery<T extends TestBenchElement> extends Object

Query class used for finding a given element inside a given search context.

The search context is either a WebDriver instance which searches starting from the root of the current document, or a WebElement instance, which searches both in the light DOM and inside the shadow root of the given element.

When the search context is a WebElement, the shadow root is searched first. E.g. when searching by ID and the same ID is used by a light DOM child of the element and also inside its shadow root, the element from the shadow root is returned.

The element class specified in the constructor defines the tag name which is searched for and also the type of element returned.

  • Constructor Details

    • ElementQuery

      public ElementQuery(Class<T> elementClass)

      Instantiate a new ElementQuery to look for the given type of element.

      Parameters:

      elementClass - the type of element to look for and return

    • ElementQuery

      public ElementQuery(Class<T> elementClass, String tagName)

      Instantiate a new ElementQuery to look for the given type of element.

      Parameters:

      elementClass - the type of element to return

      tagName - the tag name of the element to find

  • Method Details

    • hasAttribute

      @Deprecated(since="9.3") public ElementQuery<T> hasAttribute(String name)
      Deprecated.
      use withAttribute(String)

      Selects on elements having the given attribute.

      Note, this attribute need not have a value.

      Parameters:

      name - the attribute name

      Returns:

      this element query instance for chaining

    • attribute

      @Deprecated(since="9.3") public ElementQuery<T> attribute(String name, String value)
      Deprecated.
      use withAttribute(String, String)

      Selects on elements with the given attribute having the given value.

      For matching a substring of the attribute value, see withAttributeContaining(String, String). For matching a word within the attribute, see withAttributeContainingWord(String, String).

      Parameters:

      name - the attribute name

      value - the attribute value

      Returns:

      this element query instance for chaining

      See Also:

    • attributeContains

      @Deprecated(since="9.3") public ElementQuery<T> attributeContains(String name, String word)
      Deprecated.
      use withAttributeContainingWord(String, String)

      Selects on elements with the given attribute containing the given word.

      Compares with space separated words so that e.g. attributeContains("class", "myclass"); matches class='someclass myclass'.

      For matching the full attribute value, see withAttribute(String, String). For matching a substring of the attribute value, see withAttributeContaining(String, String).

      Parameters:

      name - the attribute name

      word - the word to look for

      Returns:

      this element query instance for chaining

      See Also:

    • withAttribute

      public ElementQuery<T> withAttribute(String attribute)

      Selects on elements having the given attribute.

      Note, the attribute need not have a value--it just needs to exist.

      Parameters:

      attribute - the attribute name

      Returns:

      this element query instance for chaining

    • withAttribute

      public ElementQuery<T> withAttribute(String attribute, String value, ElementQuery.AttributeMatch.Comparison comparison)

      Selects on elements with the given attribute using the given comparison and value.

      The given value must match the attribute value according to the comparison.

      Parameters:

      attribute - the attribute name

      value - the attribute value

      comparison - the comparison to use

      Returns:

      this element query instance for chaining

    • withAttribute

      public ElementQuery<T> withAttribute(String attribute, String value)

      Selects on elements with the given attribute having the given value.

      The given value must match the attribute value exactly.

      For matching a substring of the attribute, see withAttributeContaining(String, String). For matching a word within the attribute, see withAttributeContainingWord(String, String).

      Parameters:

      attribute - the attribute name

      value - the attribute value

      Returns:

      this element query instance for chaining

      See Also:

    • withAttributeContaining

      public ElementQuery<T> withAttributeContaining(String attribute, String text)

      Selects on elements with the given attribute containing the given text.

      The given text must match a substring of the attribute value.

      For matching the full attribute value, see withAttribute(String, String). For matching a word within the attribute, see withAttributeContainingWord(String, String).

      Parameters:

      attribute - the attribute name

      text - the substring to look for

      Returns:

      this element query instance for chaining

      See Also:

    • withAttributeContainingWord

      public ElementQuery<T> withAttributeContainingWord(String attribute, String word)

      Selects on elements with the given attribute containing the given word.

      Compares with space separated words so that e.g. withAttributeContainingWord("class", "myclass"); matches class='someclass myclass'.

      For matching the full attribute value, see withAttribute(String, String). For matching a substring of the attribute value, see withAttributeContaining(String, String).

      Parameters:

      attribute - the attribute name

      word - the word to look for

      Returns:

      this element query instance for chaining

      See Also:

    • withoutAttribute

      public ElementQuery<T> withoutAttribute(String attribute)

      Selects on elements not having the given attribute.

      Note, attributes both with and without values are skipped.

      Parameters:

      attribute - the attribute name

      Returns:

      this element query instance for chaining

    • withoutAttribute

      public ElementQuery<T> withoutAttribute(String attribute, String value)

      Selects on elements not having the given attribute with the given value.

      The given value must match the attribute value exactly in order to be skipped.

      For matching the full attribute value, see withoutAttributeContaining(String, String). For skipping elements having a word within the attribute, see withoutAttributeContainingWord(String, String).

      Parameters:

      attribute - the attribute name

      value - the attribute value

      Returns:

      this element query instance for chaining

      See Also:

    • withoutAttributeContaining

      public ElementQuery<T> withoutAttributeContaining(String attribute, String text)

      Selects on elements not having the given attribute containing the given text.

      The given value must match any substring of the attribute value in order to be skipped.

      For matching the full attribute value, see withoutAttribute(String, String). For skipping elements having a word within the attribute, see withoutAttributeContainingWord(String, String).

      Parameters:

      attribute - the attribute name

      text - the substring to look for

      Returns:

      this element query instance for chaining

      See Also:

    • withoutAttributeContainingWord

      public ElementQuery<T> withoutAttributeContainingWord(String attribute, String word)

      Selects on elements not having the given attribute containing the given word.

      Compares with space separated words so that e.g. withoutAttributeContainingWord("class", "myclass"); skips class='someclass myclass'.

      For matching the full attribute value, see withoutAttribute(String, String). For skipping elements containing a substring of the attribute, see withoutAttributeContaining(String, String).

      Parameters:

      attribute - the attribute name

      word - the word to look for

      Returns:

      this element query instance for chaining

      See Also:

    • withId

      public ElementQuery<T> withId(String id)

      Selects on elements having the given id.

      This selector does not require the id to be unique. To obtain the unique id, chain with single() or use id(String) instead of this selector. If you legitimately have duplicate ids and just want the first one, chain with first().

      Parameters:

      id - the id to look up

      Returns:

      the element with the given id

      See Also:

    • withClassName

      public ElementQuery<T> withClassName(String... classNames)

      Selects on elements having the given class names.

      Parameters:

      classNames - the class names

      Returns:

      this element query instance for chaining

    • withoutClassName

      public ElementQuery<T> withoutClassName(String... classNames)

      Selects on elements not having the given class names.

      Parameters:

      classNames - the class names

      Returns:

      this element query instance for chaining

    • withTheme

      public ElementQuery<T> withTheme(String theme)

      Selects on elements having the given theme.

      Parameters:

      theme - the theme

      Returns:

      this element query instance for chaining

    • withoutTheme

      public ElementQuery<T> withoutTheme(String theme)

      Selects on elements not having the given theme.

      Parameters:

      theme - the theme

      Returns:

      this element query instance for chaining

    • withCondition

      public ElementQuery<T> withCondition(Predicate<T> condition)

      Requires the element to satisfy the given condition.

      For example, to select only enabled elements, you could use
      withCondition(TestBenchElement::isEnabled)
      or to select only those having a non-zero height, you could use
      withCondition(element -> element.getSize().getHeight() != 0)

      Note that conditions are evaluated in order after the element is selected by its attributes.

      Parameters:

      condition - the condition for the element to satisfy; not null

      Returns:

      this element query instance for chaining

    • withPropertyValue

      public <V> ElementQuery<T> withPropertyValue(Function<T,V> getter, V propertyValue, BiPredicate<V,V> comparison)

      Requires the element's given property getter return value to satisfy the given comparison with the supplied value.

      For example, to select TextFieldElements having helper text containing the word "person", you could use 

       withPropertyValue(TextFieldElement::getHelperText, "person", String::contains)

      Type Parameters:

      V - the type of the property values

      Parameters:

      getter - the function to get the value of the property of the element; not null

      propertyValue - value to be compared with the one obtained from the getter function of the element

      comparison - the comparison to use when comparing the getter's property value against the supplied property value (i.e., comparison.test(elementPropertyValue, propertyValue); not null

      Returns:

      this element query instance for chaining

      See Also:

    • withPropertyValue

      public <V> ElementQuery<T> withPropertyValue(Function<T,V> getter, V propertyValue)

      Requires the element's given property getter return value to equal the supplied value.

      Type Parameters:

      V - the type of the property values

      Parameters:

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

      propertyValue - value to be compared with the one obtained from the getter function of the element

      Returns:

      this element query instance for chaining

      See Also:

    • withLabel

      public ElementQuery<T> withLabel(String text, BiPredicate<String,String> comparison)

      Requires the element's label to satisfy the given comparison with the supplied text.

      For matching a label exactly, see withLabel(String), and for matching a label partially, see withLabelContaining(String).

      This method can be used for other label matching needs, such as performing a case-insensitive match: withLabel("name", String::equalsIgnoreCase)
      a label-ending match: withLabel(" Name", String::endsWith)
      or a regular expression match: withLabel("(First|Last) Name", String::matches)

      Parameters:

      text - the text to compare with the label; not null

      comparison - the comparison to use when comparing element's label against the supplied text (i.e., comparison.test(elementLabel, text); not null

      Returns:

      this element query instance for chaining

      See Also:

    • withLabel

      public ElementQuery<T> withLabel(String label)

      Requires the element's label to exactly match the given label value.

      For partially matching text within the label, see withLabelContaining(String).

      Parameters:

      label - the label to match

      Returns:

      this element query instance for chaining

      See Also:

    • withLabelContaining

      public ElementQuery<T> withLabelContaining(String text)

      Requires the element's label to partially match the given text value.

      For exactly matching the label, see withLabel(String).

      Parameters:

      text - the text to match

      Returns:

      this element query instance for chaining

      See Also:

    • withPlaceholder

      public ElementQuery<T> withPlaceholder(String text, BiPredicate<String,String> comparison)

      Requires the element's placeholder to satisfy the given comparison with the supplied text.

      For matching a placeholder exactly, see withPlaceholder(String), and for matching a placeholder partially, see withPlaceholderContaining(String).

      This method can be used for other placeholder matching needs, such as performing a case-insensitive match: withPlaceholder("name", String::equalsIgnoreCase)
      a placeholder-ending match: withPlaceholder(" Name", String::endsWith)
      or a regular expression match: withPlaceholder("(First|Last) Name", String::matches)

      Parameters:

      text - the text to compare with the placeholder; not null

      comparison - the comparison to use when comparing the placeholder against the supplied text (i.e., comparison.test(elementPlaceholder, text); not null

      Returns:

      this element query instance for chaining

      See Also:

    • withPlaceholder

      public ElementQuery<T> withPlaceholder(String placeholder)

      Requires the element's placeholder to exactly match the given placeholder value.

      For partially matching text within the placeholder, see withPlaceholderContaining(String).

      Parameters:

      placeholder - the placeholder to match

      Returns:

      this element query instance for chaining

      See Also:

    • withPlaceholderContaining

      public ElementQuery<T> withPlaceholderContaining(String text)

      Requires the element's placeholder to partially match the given text value.

      For exactly matching the placeholder, see withPlaceholder(String).

      Parameters:

      text - the text to match

      Returns:

      this element query instance for chaining

      See Also:

    • withCaption

      public ElementQuery<T> withCaption(String text, BiPredicate<String,String> comparison)

      Requires the element's caption (i.e., label, placeholder, or text label) to satisfy the given comparison with the supplied text.

      This is a convenience selector method to select an element by its label, placeholder, or text label, as supported by the element. These values are generically considered "captions" as they are used to identify the element to the user.

      The comparison against the values of the element follows this priority:

      1. Label - If the element supports a label and its label is not empty, the element's label value is used in the comparison. If the comparison with the given text is not satisfied by the element's label value, the comparison does not fall through to compare against the placeholder.
      2. Placeholder - Even if an element supports a label, its label value may be empty. In that situation, the element may be using a placeholder in lieu of a label. So in that situation, the comparison falls through to compare against the placeholder if the element supports a placeholder and its placeholder is not empty, the element's placeholder value is used in the comparison.
      3. Text - If the element supports neither labels nor placeholders but does support a caption via its text (such as a button does), the comparison is made against the element's text.
      Note that if the given text is empty, then if the element supports both a label and a placeholder, they must both be empty to be selected.

      For matching a caption exactly, see withCaption(String), and for matching a caption partially, see withCaptionContaining(String).

      This method can be used for other caption matching needs, such as performing a case-insensitive match: withCaption("name", String::equalsIgnoreCase)
      a caption-ending match: withCaption(" Name", String::endsWith)
      or a regular expression match: withCaption("(First|Last) Name", String::matches)

      Parameters:

      text - the text to compare with the caption; not null

      comparison - the comparison to use when comparing the caption against the supplied text (i.e., comparison.test(elementCaption, text); not null

      Returns:

      this element query instance for chaining

      See Also:

    • withCaption

      public ElementQuery<T> withCaption(String caption)

      Requires the element's caption (i.e., label, placeholder, or text label) to exactly match the given caption value.

      For partially matching text within the caption, see withCaptionContaining(String).

      Parameters:

      caption - the caption to match

      Returns:

      this element query instance for chaining

      See Also:

    • withCaptionContaining

      public ElementQuery<T> withCaptionContaining(String text)

      Requires the element's caption (i.e., label, placeholder, or text label) to partially match the given text value.

      For exactly matching the caption, see withCaption(String).

      Parameters:

      text - the text to match

      Returns:

      this element query instance for chaining

      See Also:

    • withText

      public ElementQuery<T> withText(String text, BiPredicate<String,String> comparison)

      Requires the element's text to satisfy the given comparison with the supplied text.

      For matching the element's text exactly, see withText(String), and for matching the element's text partially, see withTextContaining(String).

      This method can be used for other text matching needs, such as performing a case-insensitive match: withText("name", String::equalsIgnoreCase)
      a text-ending match: withText(" Name", String::endsWith)
      or a regular expression match: withText("(First|Last) Name", String::matches)

      Parameters:

      text - the text to compare with the element's text; not null

      comparison - the comparison to use when comparing the element's text against the supplied text (i.e., comparison.test(elementText, text); not null

      Returns:

      this element query instance for chaining

      See Also:

    • withText

      public ElementQuery<T> withText(String text)

      Requires the element's text to exactly match the given text value.

      For partially matching text within the element's text, see withTextContaining(String).

      Parameters:

      text - the text to match

      Returns:

      this element query instance for chaining

      See Also:

    • withTextContaining

      public ElementQuery<T> withTextContaining(String text)

      Requires the element's text to partially match the given text value.

      For exactly matching the text, see withText(String).

      Parameters:

      text - the text to match

      Returns:

      this element query instance for chaining

      See Also:

    • context

      public ElementQuery<T> context(org.openqa.selenium.SearchContext searchContext)

      Sets the context to search inside.

      Parameters:

      searchContext - a SearchContext; either a TestBenchElement or WebDriver (to search from the root) instance

      Returns:

      this element query instance for chaining

    • onPage

      public ElementQuery<T> onPage()

      Defines that the query should start the search from the root of the page, in practice from the <body> tag.

      Returns:

      this element query instance for chaining

    • getContext

      protected org.openqa.selenium.SearchContext getContext()

      Returns the context (element or driver) to search inside.

      Returns:

      a SearchContext instance

    • id

      public T id(String id)

      Executes the search and returns an element having the given unique id.

      This selector expects the id to be unique. If there are duplicate ids, this selector will throw an exception. If you legitimately have duplicate ids, use withId(String).first() instead. (Note, this alternate usage is the former behavior of this selector.)

      Parameters:

      id - the id to look up

      Returns:

      the element with the given id

      Throws:

      org.openqa.selenium.NoSuchElementException - if no unique id element is found

      See Also:

    • single

      public T single()

      Executes the search and returns the sole result.

      Returns:

      The element of the type specified in the constructor

      Throws:

      org.openqa.selenium.NoSuchElementException - if no unique element is found

    • first

      public T first()

      Executes the search and returns the first result.

      Returns:

      The element of the type specified in the constructor

      Throws:

      org.openqa.selenium.NoSuchElementException - if no element is found

    • waitForFirst

      public T waitForFirst()

      Executes the search and returns the first result once at least once result is available.

      This method is identical to first() if at least one element is present. If no element is found, this method will keep searching until an element is found or if 10 seconds has elapsed.

      Returns:

      The element of the type specified in the constructor

      Throws:

      org.openqa.selenium.NoSuchElementException - if no element is found

      See Also:

    • waitForFirst

      public T waitForFirst(long timeOutInSeconds)

      Executes the search and returns the first result once at least once result is available.

      This method is identical to first() if at least one element is present. If no element is found, this method will keep searching until an element is found or timeOutInSeconds seconds has elapsed.

      Parameters:

      timeOutInSeconds - timeout in seconds before this method throws a NoSuchElementException exception

      Returns:

      The element of the type specified in the constructor

      Throws:

      org.openqa.selenium.NoSuchElementException - if no element is found

      See Also:

    • last

      public T last()

      Executes the search and returns the last result.

      Returns:

      The element of the type specified in the constructor

      Throws:

      org.openqa.selenium.NoSuchElementException - if no element is found

    • get

      public T get(int index)

      Executes the search and returns the requested element.

      Parameters:

      index - the index of the element to return

      Returns:

      The element of the type specified in the constructor

      Throws:

      org.openqa.selenium.NoSuchElementException - if no element is found

    • exists

      public boolean exists()

      Checks if this ElementQuery describes existing elements. Same as .all().isEmpty().

      Returns:

      true if elements exists. false if not

    • all

      public List<T> all()

      Search the open Vaadin application for a list of matching components relative to given context.

      Returns:

      Components as a list of corresponding elements

Copyright © 2025. All rights reserved.