Documentation versions (currently viewingVaadin 24)

Low-Level Element Interactions

A list and description of helpers to use when a high-level API isn’t available for interacting with components.

Typically, you would use the provided high-level element API to interact with components. For situations in which a high-level API isn’t available or doesn’t offer the methods you need, a few helpers are provided.

Getting or Setting Properties

Many interactions with web components can be performed by reading or modifying element properties. For this, the following helpers are provided in TestBenchElement:

String getPropertyString(String... propertyNames)
Boolean getPropertyBoolean(String... propertyNames)
Integer getPropertyInteger(String... propertyNames)
Double getPropertyDouble(String... propertyNames)
Object getProperty(String... propertyNames)
TestBenchElement getPropertyElement(String... propertyNames)
List<TestBenchElement> getPropertyElements(String... propertyNames)

These methods are typically meant for creating page objects or TestBench elements, but can also be handy as a workaround when a needed method isn’t available.

Typically, you should use the correct getPropertyXYZ() depending on the type of the property in JavaScript. If you use another type, the value is converted using standard JavaScript rules, which may or may not give the result you desire.

Calling Functions

If you need to call a function on an element, you can use Object callFunction(String methodName, Object…​ args), available in TestBenchElement. Below is an example of this:

divElement.callFunction("setAttribute", "title", "Hello");

Executing JavaScript

Sometimes the available API doesn’t offer what you want to execute a JavaScript snippet to accomplish your task. You can execute any JavaScript snippet using the executeScript() method available in TestBenchTestCase and TestBenchElement and add references to elements and other parameters using the Object…​ args parameter. All arguments passed to the method are available through the arguments array in JavaScript.

For example, to return the offsetHeight property of an element, you could do this:

TestBenchElement element = ...; // find the element somehow
Long offsetHeight = (Long)executeScript("return arguments[0].offsetHeight", element);
The above executeScript() call would be the same as using element.getPropertyInteger("offsetHeight");.

The argument array and the return type support a limited set of types:

  • HTML elements are converted to TestBenchElement instances;

  • Decimal numbers are converted to Double;

  • Non-decimal numbers are converted to Integer;

  • Booleans are converted to Boolean;

  • All other values except arrays are converted to String; and

  • Returned arrays are converted to List<Object>, containing types described above.

As there is no way to know what type the JavaScript function returns, you always need to cast the return value.