# 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

```java
// 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](https://raw.githubusercontent.com/parttio/dramafinder/master/skills/vaadin-playwright-test/api-reference.md)

**Do not decompile the DramaFinder jar to find its API — read the file above
(one request) instead.** It is regenerated on every release and cannot drift
from the shipped code.

**No network?** The same file ships inside the jar, which is already in `~/.m2`
once the dependency resolves:

```
JAR=$(ls ~/.m2/repository/org/vaadin/addons/dramafinder/*/dramafinder-*.jar | tail -1)
unzip -p "$JAR" META-INF/dramafinder/START-HERE.md    # short guide, ~4 KB
unzip -p "$JAR" META-INF/dramafinder/api-reference.md # every signature, ~100 KB
```

Start with `START-HERE.md`: it has a working test skeleton, the tag-to-wrapper
naming rule, and the handful of things that are easy to get wrong.

## Documentation

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

## Element Specifications

Signatures for **every** element live in the auto-generated
[api-reference.md](https://raw.githubusercontent.com/parttio/dramafinder/master/skills/vaadin-playwright-test/api-reference.md).
The files below are hand-written prose docs, kept only for components whose
behaviour isn't obvious from the signatures:

- [VaadinElement](docs/specifications/VaadinElement.md) - Base class + how to extend it
- [BadgeElement](docs/specifications/BadgeElement.md) - Text vs number vs icon, theme-variant assertions
- [BreadcrumbsElement](docs/specifications/BreadcrumbsElement.md) - Overflow overlay model, experimental feature flag
- [GridElement](docs/specifications/GridElement.md) - Auto-scroll & stale-element caveats, renderer/lazy examples
- [TreeGridElement](docs/specifications/TreeGridElement.md) - Tree-state reading, hierarchy-column location
- [VirtualListElement](docs/specifications/VirtualListElement.md) - Debouncer flush, typed component queries
- [ComboBoxElement](docs/specifications/ComboBoxElement.md) - Lazy data providers, filter-and-select
- [DatePickerElement](docs/specifications/DatePickerElement.md) - String vs LocalDate value formats
- [TimePickerElement](docs/specifications/TimePickerElement.md) - String vs LocalTime value formats
- [DateTimePickerElement](docs/specifications/DateTimePickerElement.md) - Composite enabled/aria semantics
- [AvatarGroupElement](docs/specifications/AvatarGroupElement.md) - Overflow model, xpath scoping, maxItemsVisible budget
- [MessageInputElement](docs/specifications/MessageInputElement.md) - Submit behaviour
- [LoginElement](docs/specifications/LoginElement.md) - Login form/overlay lookups, i18n-driven assertions
- [MarkdownElement](docs/specifications/MarkdownElement.md) - Rendered-output assertions, not Markdown source
- [NotificationElement](docs/specifications/NotificationElement.md) - Open-card scoping
- [CheckboxGroupElement](docs/specifications/CheckboxGroupElement.md) - Label-based selection, exhaustive assertSelected
- [RadioButtonElement](docs/specifications/RadioButtonElement.md) - Internal use via group
- [SliderElement](docs/specifications/SliderElement.md) - Keyboard-driven value changes, step snapping
- [TextAreaElement](docs/specifications/TextAreaElement.md) - Input-locator override
- [UploadElement](docs/specifications/UploadElement.md) - Hidden-file-input pattern
- [TooltipElement](docs/specifications/TooltipElement.md) - Opened state without visibility, hover delay, position on the overlay

## Key Patterns

### Element Lookup
Elements are found using accessible names via ARIA roles:
```java
// 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`
- Switches: `AriaRole.SWITCH`
- Checkbox groups / radio groups: `AriaRole.GROUP`, `AriaRole.RADIOGROUP`
- Radio buttons: `AriaRole.RADIO`
- Dialogs: `AriaRole.DIALOG`
- List boxes: `AriaRole.LISTBOX`
- Menus: `AriaRole.MENU`, `AriaRole.MENUITEM`
- Sliders: `AriaRole.SLIDER`

### Assertion Methods
Each element provides assertion methods that auto-retry:
```java
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

```bash
# 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`