DramaFinder

Playwright element wrappers for Vaadin web components

DramaFinder provides typed Java wrappers around Vaadin web components for use with Playwright testing. Each wrapper exposes component-specific APIs for interaction and assertion, following accessibility-first lookup patterns using ARIA roles.

Quick Start

// Find elements by accessible label
TextFieldElement username = TextFieldElement.getByLabel(page, "Username");
ButtonElement submit = ButtonElement.getByText(page, "Submit");

// Interact and assert
username.setValue("john.doe");
username.assertValue("john.doe");
submit.click();

API Reference

The complete public API of every element wrapper (methods, signatures, one-line descriptions) is auto-generated from source into a single file:

• api-reference.md

Do not download or unzip the DramaFinder jar/sources to find its API — fetch the file above (one request) instead. It is regenerated on every release and cannot drift from the shipped code.

Documentation

• AGENTS.md - Repository guidelines, coding conventions, pitfalls & patterns
• TESTING.md - Testing guide and instructions
• README.md - Project overview and setup

Element Specifications

Signatures for every element live in the auto-generated api-reference.md. The files below are hand-written prose docs, kept only for components whose behaviour isn't obvious from the signatures:

• VaadinElement - Base class + how to extend it
• GridElement - Auto-scroll & stale-element caveats, renderer/lazy examples
• TreeGridElement - Tree-state reading, hierarchy-column location
• VirtualListElement - Debouncer flush, typed component queries
• ComboBoxElement - Lazy data providers, filter-and-select
• DatePickerElement - String vs LocalDate value formats
• TimePickerElement - String vs LocalTime value formats
• DateTimePickerElement - Composite enabled/aria semantics
• MessageInputElement - Submit behaviour
• NotificationElement - Open-card scoping
• RadioButtonElement - Internal use via group
• TextAreaElement - Input-locator override
• UploadElement - Hidden-file-input pattern

Key Patterns

Element Lookup

Elements are found using accessible names via ARIA roles:

// By label (most common)
TextFieldElement.getByLabel(page, "Email")
ButtonElement.getByText(page, "Save")
SelectElement.getByLabel(page, "Country")

// Scoped lookup within container
TextFieldElement.getByLabel(formLocator, "Name")

ARIA Roles by Component

• Text fields: AriaRole.TEXTBOX
• Number fields: AriaRole.SPINBUTTON
• Date/time pickers: AriaRole.COMBOBOX
• Buttons: AriaRole.BUTTON
• Checkboxes: AriaRole.CHECKBOX
• Radio buttons: AriaRole.RADIO
• Dialogs: AriaRole.DIALOG
• List boxes: AriaRole.LISTBOX
• Menus: AriaRole.MENU, AriaRole.MENUITEM

Assertion Methods

Each element provides assertion methods that auto-retry:

field.assertValue("expected");
field.assertEnabled();
field.assertDisabled();
field.assertRequired();
field.assertInvalid();
dialog.assertOpen();
dialog.assertClosed();

Mixin Interfaces

Common behaviors are provided via interfaces:

• HasInputFieldElement - value get/set
• HasValidationPropertiesElement - required, invalid, error message
• HasEnabledElement - enabled/disabled state
• FocusableElement - focus/blur operations
• HasThemeElement - theme variant assertions
• HasClearButtonElement - clear button click
• HasPlaceholderElement - placeholder text
• HasTooltipElement - tooltip content
• HasLabelElement - label text
• HasHelperElement - helper text

Build Commands

# Build with tests
./mvnw clean install

# Run integration tests
./mvnw -B verify --file pom.xml

# Run single IT test
./mvnw -Dit.test=MyViewIT -Pit verify

Source Code

• Main elements: src/main/java/org/vaadin/addons/dramafinder/element/
• Shared mixins: src/main/java/org/vaadin/addons/dramafinder/element/shared/
• Integration tests: src/test/java/**/*IT.java