Documentation versions (currently viewingVaadin 8)

Vaadin 8 reached End of Life on February 21, 2022. Discover how to make your Vaadin 8 app futureproof →

Element Selectors

In addition to the high-level ElementQuery API described in the previous section, Vaadin TestBench includes the lower-level Selenium WebDriver API, with Vaadin extensions. You can find elements also by a plain XPath expression, an element ID, CSS style class, and so on. You can use such selectors together with the element queries. Like the ElementQuery API, it can be considered a domain-specific language (DSL) that is embedded in the TestBenchTestCase class.

The available selectors are defined as static methods in the com.vaadin.testbench.By class. They create and return a By instance, which you can use for the findElement() method in WebDriver.

The ID, CSS class, and Vaadin selectors are described below. For others, we refer to the Selenium WebDriver API documentation.

Some selectors are not applicable to all elements, for example if an element does not have an ID or is outside the Vaadin application.

Finding by ID

Selecting elements by their HTML element id attribute is a robust way to select elements, as noted in "Increasing Selector Robustness". It requires that you component IDs for the UI components with setId().

Button button = new Button("Push Me!");

The button would be rendered as a HTML element: <div id="pushmebutton" ...>...</div>. The element would then be accessible with a low-level WebDriver call:


The selector is equivalent to the statically typed element query $(ButtonElement.class).id("pushmebutton").

Finding by CSS Class

An element with a particular CSS style class name can be selected with the By.className() method. CSS selectors are useful for elements which have no ID, nor can be found easily from the component hierarchy, but do have a particular unique CSS style. Tooltips are one example, as they are floating div elements under the root element of the application. Their v-tooltip style makes it possible to select them as follows:

// Verify that the tooltip contains the expected text
String tooltipText = findElement(

you can find the complete example in TestBench demo.