Docs

Docs

Test User Interactions

Find components, simulate navigation and keyboard shortcuts, and test menu actions in browserless tests.

Start with the setup for your application framework. The interaction methods in this guide are shared, but retain your framework-specific test base class and initialization. For Java EE/CDI, extend AbstractCdiViewTest and register each tested view and its dependencies as described in the CDI guide. Each example below is a pattern to adapt to your view; it belongs inside a test method unless shown otherwise.

Find the Component to Exercise

Use a label or visible text when it identifies the component unambiguously. Scope the query when the same field appears more than once:

Source code
Java
TextField name = findInView(TextField.class)
        .withLabel("First name").single();
test(name).setValue("Ada");
Assertions.assertEquals("Ada", name.getValue());

Use find(Type.class, container) to restrict a query to a particular container. A component inside a Grid renderer may need to be obtained through test(grid).getCellComponent(…​) before it can be exercised. An empty top-level query does not necessarily mean that the application failed to create the component. See Query Boundaries and Component Queries for the full behavior.

Test IDs

Use Component.setTestId() to assign a stable identifier to a component for use in tests. This sets the data-testid HTML attribute on the component’s element, which can also be used by browser-based testing frameworks:

Source code
Java
Button submitButton = new Button("Submit");
submitButton.setTestId("submit-button");

// Later, retrieve the test ID
String testId = submitButton.getTestId(); // "submit-button"

Use a test ID when a label or visible text would be ambiguous or would change with translations. Keep the identifier independent of styling and layout.

Browserless tests can use the same identifier: the testId() terminal operator and the withTestId() filter look up components by their test ID:

Source code
Java
Button submit = find(Button.class).testId("submit-button");

See Querying Components for details.

Use Locators for Repeated Interactions

In a base-class test, implement Locators to combine lookup and interaction. The class below uses the plain Java setup. In a CDI test, add implements Locators to your AbstractCdiViewTest subclass instead; retain its CDI configuration.

Source code
Java
class CartViewTest extends BrowserlessTest implements Locators {
    @Test
    void addItem_increasesCartSize() {
        navigate(CartView.class);
        findButton().withText("Add to cart").click();
        Assertions.assertEquals("1 item",
                findSpan().withId("cart-size").getText());
    }
}

This example assumes that the cart view updates the span after adding an item. For locator reuse and invalidation rules, see Locator Resolution.

Test Navigation and Shortcuts

Navigate by location when the outcome may be a redirect, and pass the expected view class:

Source code
Java
navigate("protected", LoginView.class);

A location can also carry a query string and fragment; for example, navigate("orders/123?tab=history#details", OrderView.class). Assert the state selected by those parameters after navigation.

For route parameters and other navigation forms, see Navigation.

To exercise a save shortcut, invoke it after changing the form and then assert the same outcome as clicking Save:

Source code
Java
fireShortcut(Key.KEY_S, KeyModifier.CONTROL);
// Assert the saved state or the confirmation shown by your view.

Test Menu Actions

Use a menu tester to reach overlay content. For a view exposing a contextMenu field:

Source code
Java
var view = navigate(EditorView.class);
var menu = test(view.contextMenu);
menu.open();
menu.clickItem("Bold");
Assertions.assertTrue(menu.isItemChecked("Bold"));

For nested actions, pass a text path such as clickItem("Share", "Email"). For a menu containing custom components, call test(menuComponent).find(…​). Open the menu before clicking items or reading their state. Only the menu tester’s find() query works while it is closed; returned components remain detached until it opens. See Overlay Component Testers for indexing and attachment semantics.

BDC6250E-E9D6-44DD-9B67-777C0F7E98AA

Updated –