TooltipElement

Full API (methods, signatures, descriptions): see api-reference.md. This note covers only behaviour that isn't obvious from the signatures.

A tooltip is always reached through the component it describes

Flow's com.vaadin.flow.component.shared.Tooltip has no constructor: a tooltip is created for a component, and the resulting <vaadin-tooltip slot="tooltip"> is a light-DOM child of that component. So there is no "id of the tooltip" to look it up by — scope the lookup to the target instead, or go through the HasTooltipElement mixin:

// through the mixin — the usual way
ButtonElement save = ButtonElement.getByText(page, "Save");
save.getTooltip().assertText("Saves the current draft");

// scoped to the target component
TooltipElement tooltip = TooltipElement.get(page.locator("#save-button"));

// by the tooltip's own text, when the target is not the interesting part
TooltipElement.getByText(page, "Saves the current draft");

HasTooltipElement is a thin facade over TooltipElement: assertTooltipHasText(...) is getTooltip().assertText(...). Use the mixin for the text, and getTooltip() as soon as the test cares about the opened state, the position, or triggering the tooltip.

Assert the opened state, not visibility

<vaadin-tooltip> is display: contents and renders nothing of its own — what appears on screen is the <vaadin-tooltip-overlay> in its shadow DOM. So the open/closed assertions read the opened attribute the component reflects, which flips exactly when the tooltip opens and closes:

tooltip.assertOpened();   // opened attribute present
tooltip.assertClosed();   // opened attribute absent
tooltip.isOpened();

When a test genuinely needs the rendered box — a screenshot, a bounding-box assertion — reach for the overlay instead of the host:

assertThat(tooltip.getOverlayLocator()).isVisible();

The text is readable while the tooltip is closed

The tooltip content lives in a role="tooltip" element that stays in the DOM whether the tooltip is open or not, so text assertions need no interaction:

// no hover needed
field.assertTooltipHasText("Tooltip for the field");

assertText(null) asserts that the tooltip shows nothing. A tooltip with empty text keeps its overlay hidden, so absence is asserted on the content's visibility rather than on the element being gone.

Opening a tooltip is delayed

hoverTarget() moves the pointer to the centre of the element the tooltip describes — the live target element reference, which no selector can express — after scrolling it into view. Vaadin then waits out the tooltip's hover delay, 500 ms by default, before opening. Follow it with a retrying assertion, never with the plain getter:

tooltip.hoverTarget();
tooltip.assertOpened();          // absorbs the hover delay
// tooltip.isOpened()            // would read false, too early

tooltip.closeWithEscape();
tooltip.assertClosed();

closeWithEscape() presses Escape on the page, because the component listens for the key on the document and the tooltip host cannot be focused. A tooltip in manual mode ignores both hover and Escape; drive it from the server side and assert the result:

// tooltip.setManual(true) on the server
ButtonElement.getByText(page, "Show tooltip").click();
tooltip.assertOpened();

The position is read from the overlay

Tooltip.setPosition(...) sets a DOM property on the host and nothing else; it is the overlay that reflects the effective position as an attribute. getPosition() and assertPosition(...) read it there, so they answer with the configured position, or with bottom when none was configured:

// no position configured
tooltip.assertPosition("bottom");

// Tooltip.TooltipPosition.TOP_START
tooltip.assertPosition("top-start");

There is no "absent" case, so assertPosition(null) is not supported.