Testing Overlay Components

How to test context menus, menu bars, and other overlay-based components in browserless tests.

Context Menu
Menu Bar

Some Vaadin components render their content in overlays, which means their child components aren’t part of the normal view component tree. While the overlay is closed, top-level component queries (find()) cannot reach its detached contents. Opening the overlay attaches that content so a top-level query can find it. Instead, use the component-specific testers to interact with overlay content.

ContextMenu renders its items in an overlay outside the main component tree. Use ContextMenuTester to interact with menu items and any custom components inside the menu.

A closed context menu isn’t attached to the UI, so, exactly as in the browser, its items can’t be interacted with. Open the menu before clicking an item or reading its state; clickItem(), isItemChecked(), getItemTexts(), and getItemTooltipText() throw an IllegalStateException on a closed menu.

Source code

JavaContextMenuTester<ContextMenu> menu_ = test(view.contextMenu);

// Simulates the user asking for the menu, for example with a right click
menu_.open();
menu_.clickItem("Edit");
menu_.close();

open() renders no client-side overlay; it simulates the server-side state changes that opening the menu produces in the browser. Both open() and close() are reported as user actions, so the resulting OpenedChangeEvent has isFromClient() returning true. Opening a menu that is already open throws.

Note	Behavior Changed in 25.3 Earlier versions let a test click the items of a closed menu, so a test written against them fails until the `open()` call is added.

Use clickItem() to simulate clicking a menu item by its text or zero-based position.

Source code

JavaContextMenu menu = view.contextMenu;
ContextMenuTester<ContextMenu> menu_ = test(menu);
menu_.open();

// Click a top-level item by text
menu_.clickItem("Edit");

// Click a nested item by text path
menu_.clickItem("Share", "Email");

// Click by position (zero-based, hidden items are skipped)
menu_.clickItem(0);         // first visible item
menu_.clickItem(1, 0);      // first item in second item's submenu

getItemTexts() returns the texts of the items the browser shows, in display order and without the hidden ones, which makes it the way to assert on the contents of a menu that is built dynamically. Pass a path to read the items of a sub-menu:

Source code

Javamenu_.open();

// ["Preview", "Share"] -- a hidden item is left out
Assertions.assertEquals(List.of("Preview", "Share"), menu_.getItemTexts());

// The items of the "Share" sub-menu
Assertions.assertEquals(List.of("Copy link", "Email"),
        menu_.getItemTexts("Share"));

Use isItemChecked() to check whether a checkable item is checked. Clicking a checkable item toggles its checked state automatically.

Source code

Javamenu_.open();

menu_.clickItem("Bold");
Assertions.assertTrue(menu_.isItemChecked("Bold"));

menu_.clickItem("Bold");
Assertions.assertFalse(menu_.isItemChecked("Bold"));

If you’ve added custom components (not only text items) to the menu, use the tester’s find() method on the wrapped component (test(menu).find(…)) instead of the top-level find() query. find() is the one tester method that works on a closed menu, since it queries the menu contents rather than the UI; the components it returns are detached until the menu is opened. Open the menu first to interact with them.

Source code

Java// Find a component inside the menu (detached)
Div div = menu_.find(Div.class).withText("Custom Item").single();

// Open first if you need attached components
menu_.open();
Div div = menu_.find(Div.class).withText("Custom Item").single();
Assertions.assertTrue(div.isAttached());

A GridContextMenu is always about a row, so it has a tester of its own, GridContextMenuTester, which addresses rows. Reach it through the grid’s tester with contextMenu(row), which targets a row without opening the menu, and open it there:

Source code

Javavar menu_ = test(grid).contextMenu(0);

menu_.open();
menu_.clickItem("Delete");

Opening the menu fires a GridContextMenuOpenedEvent reporting the target row, so a handler that builds the items from the row runs as it does in the browser. open(row) opens the menu on a row directly, which is shorter when a test opens it on several rows in turn:

Source code

JavaGridContextMenuTester<GridContextMenu<Person>, Person> menu_ =
        test(view.gridContextMenu);

menu_.open(0);
Assertions.assertEquals(List.of("Edit", "Delete"), menu_.getItemTexts());
menu_.close();

menu_.open(1);

A tester obtained with test(gridContextMenu) targets no row, so it has to be opened with open(row). Everything else — clickItem(), isItemChecked(), getItemTexts(), and find() — behaves as it does on ContextMenuTester.

Note	Behavior Changed in 25.3 `test(gridContextMenu)` previously returned a `ContextMenuTester`, which clicked the items without a row. Code that assigned the result to an explicitly typed variable needs the new type, or `var`.

Common Pitfalls

Using a top-level find() to search inside a closed context menu returns no results because its content is detached. Use test(contextMenu).find() or test(contextMenu).clickItem() instead.

Source code

Java// While the menu is closed, this does not find its items
Button menuButton = find(Button.class).withText("My Action").single(); // throws

// Use the tester's find() method instead
Button menuButton = test(contextMenu).find(Button.class)
        .withText("My Action").single();

MenuBar works similarly to context menu. Use MenuBarTester to click items by text or position.

Source code

JavaMenuBar menuBar = view.menuBar;
MenuBarTester<MenuBar> menuBar_ = test(menuBar);

// Click top-level item
menuBar_.clickItem("File");

// Click nested item
menuBar_.clickItem("File", "Save As");

// The visible top-level items, in display order
List<String> topLevel = menuBar_.getItemTexts();

// The items of the "File" sub-menu
List<String> fileItems = menuBar_.getItemTexts("File");

A MenuBar is always visible, so its items need no opening. getItemTexts() leaves out hidden items, which are also skipped when an item is looked up by text or position.

For a worked example, see Test User Interactions.

E3F7D8A2-9B14-4C6E-A1D0-8F5E2C3B7A91

Docs

Docs

Testing Overlay Components

Context Menu

Opening and Closing the Menu

Clicking Menu Items

Reading Menu Item Texts

Checkable Menu Items

Finding Components in the Menu

Grid Context Menu

Common Pitfalls

Menu Bar