diff --git a/.github/workflows/api-reference.yml b/.github/workflows/api-reference.yml new file mode 100644 index 0000000..4b66637 --- /dev/null +++ b/.github/workflows/api-reference.yml @@ -0,0 +1,83 @@ +name: API Reference + +# Keeps skills/vaadin-playwright-test/api-reference.md in lock-step with the code. +# +# - On push (master / issue branches): regenerate and commit the result back to +# the branch, so the reference updates itself with no manual step. +# - On pull_request: regenerate and FAIL if the committed file is stale. Push +# events from a fork have a read-only token and cannot auto-commit, so this +# verify-only job is what catches an out-of-date reference in a fork PR. +# +# The push path filter excludes api-reference.md itself, so the bot's own commit +# does not re-trigger the workflow (no loop). + +on: + push: + branches: + - master + - 'issue-**' + paths: + - 'src/main/java/org/vaadin/addons/dramafinder/element/**' + - 'tools/generate-api-reference.java' + - '.github/workflows/api-reference.yml' + pull_request: + branches: [ master ] + paths: + - 'src/main/java/org/vaadin/addons/dramafinder/element/**' + - 'tools/generate-api-reference.java' + - '.github/workflows/api-reference.yml' + +permissions: + contents: write + +jobs: + update-api-reference: + # Auto-commit path — only on push (needs write access to the branch). + if: github.event_name == 'push' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ github.ref_name }} + - name: Set up JDK 21 + uses: actions/setup-java@v4 + with: + java-version: '21' + distribution: 'temurin' + - name: Set up JBang + uses: jbangdev/setup-jbang@main + - name: Regenerate API reference + run: jbang tools/generate-api-reference.java + - name: Commit the regenerated reference if it changed + run: | + if git diff --quiet skills/vaadin-playwright-test/api-reference.md; then + echo "api-reference.md is already up to date." + else + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git add skills/vaadin-playwright-test/api-reference.md + git commit -m "Regenerate api-reference.md [skip ci]" + git push origin HEAD:${{ github.ref_name }} + fi + + verify-api-reference: + # Verify-only path — for pull requests (incl. forks, whose token is read-only). + if: github.event_name == 'pull_request' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up JDK 21 + uses: actions/setup-java@v4 + with: + java-version: '21' + distribution: 'temurin' + - name: Set up JBang + uses: jbangdev/setup-jbang@main + - name: Regenerate API reference + run: jbang tools/generate-api-reference.java + - name: Fail if the committed reference is out of date + run: | + if ! git diff --exit-code skills/vaadin-playwright-test/api-reference.md; then + echo "::error::api-reference.md is stale. Run 'jbang tools/generate-api-reference.java' and commit the result." + exit 1 + fi diff --git a/AGENTS.md b/AGENTS.md index 1897aca..593b4cf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -245,4 +245,16 @@ public static ButtonElement getByText(Locator locator, String text) { ... } - Follow this file's conventions for any edits. Keep patches minimal and focused. - Use `*IT.java` only for end-to-end tests executed by Failsafe. -- Refer to `docs/specifications/` for detailed element API documentation. +- **Never download or unzip the DramaFinder jar/sources to discover its API.** + The complete public API (every element, signatures, one-line descriptions) is + in `skills/vaadin-playwright-test/api-reference.md`, auto-generated from source + by `tools/generate-api-reference.java`. To look something up, **grep that file + for the element name and read only its `### Element` section** — don't + read the whole file. In a consumer project where it isn't checked out, fetch + it (one request) from + `https://raw.githubusercontent.com/parttio/dramafinder/master/skills/vaadin-playwright-test/api-reference.md`. +- `api-reference.md` is generated — never edit it by hand. After changing any + element's public API, regenerate it (`jbang tools/generate-api-reference.java`) + and commit the result; CI fails if it is stale. +- Refer to `docs/specifications/` for the prose docs on components with + non-obvious behaviour (Grid, TreeGrid, VirtualList, and extension guidance). diff --git a/GEMINI.md b/GEMINI.md index 142c7b4..a39442c 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -49,6 +49,14 @@ mvn -Pit verify ## Available Element Classes +> **Never download or unzip the DramaFinder jar/sources to discover its API.** +> The complete, always-current public API (every element, its methods, +> signatures and one-line descriptions) is in +> `skills/vaadin-playwright-test/api-reference.md`, auto-generated from source. +> Read that file — in a consumer project, fetch it from +> `https://raw.githubusercontent.com/parttio/dramafinder/master/skills/vaadin-playwright-test/api-reference.md`. +> The table below is a component→class overview only. + Each element class wraps a Playwright `Locator` and provides typed helpers (getters, actions, assertions) for a specific Vaadin component. They all extend `VaadinElement` and are annotated with `@PlaywrightElement`. | Element | Vaadin Component | Tag | diff --git a/docs/specifications/AbstractNumberFieldElement.md b/docs/specifications/AbstractNumberFieldElement.md deleted file mode 100644 index 69dd4bb..0000000 --- a/docs/specifications/AbstractNumberFieldElement.md +++ /dev/null @@ -1,70 +0,0 @@ -# AbstractNumberFieldElement Specification - -## Overview - -`AbstractNumberFieldElement` is an abstract base class for Vaadin number-like fields. It provides shared behavior for numeric inputs, including access to step controls (increase/decrease buttons) and common mixins for validation, input handling, theming, accessibility, and focus. - -## Class Hierarchy - -``` -VaadinElement - └── AbstractNumberFieldElement (abstract) - ├── IntegerFieldElement - └── NumberFieldElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `HasValidationPropertiesElement` | Validation properties support | -| `HasInputFieldElement` | Input field operations | -| `HasPrefixElement` | Prefix slot support | -| `HasSuffixElement` | Suffix slot support | -| `HasClearButtonElement` | Clear button functionality | -| `HasPlaceholderElement` | Placeholder text support | -| `HasAllowedCharPatternElement` | Character pattern restrictions | -| `HasThemeElement` | Theme variants support | -| `FocusableElement` | Focus operations | -| `HasAriaLabelElement` | ARIA label accessibility | -| `HasEnabledElement` | Enabled/disabled state | -| `HasTooltipElement` | Tooltip support | - -## API Methods - -### Constructor - -```java -AbstractNumberFieldElement(Locator locator) -``` - -Creates a new `AbstractNumberFieldElement` from a Playwright locator. - -### Step Controls - -| Method | Description | -|--------|-------------| -| `getHasControls()` | Returns `true` if step buttons are visible | -| `assertHasControls(boolean hasControls)` | Asserts step buttons visibility | -| `clickIncreaseButton()` | Clicks the increase (+) button | -| `clickDecreaseButton()` | Clicks the decrease (-) button | - -## Usage Examples - -### Using Step Controls - -```java -IntegerFieldElement quantity = IntegerFieldElement.getByLabel(page, "Quantity"); - -// Check if controls are visible -quantity.assertHasControls(true); - -// Use increase/decrease buttons -quantity.clickIncreaseButton(); -quantity.clickDecreaseButton(); -``` - -## Subclasses - -- `IntegerFieldElement` - For integer values with `Integer` type helpers -- `NumberFieldElement` - For decimal values with `Double` type helpers diff --git a/docs/specifications/AccordionElement.md b/docs/specifications/AccordionElement.md deleted file mode 100644 index c7fabf2..0000000 --- a/docs/specifications/AccordionElement.md +++ /dev/null @@ -1,83 +0,0 @@ -# AccordionElement Specification - -## Overview - -`AccordionElement` is a Playwright element wrapper for the `` web component. It provides helpers to access panels by their summary text and to assert open/closed state and panel count. - -## Tag Name - -``` -vaadin-accordion -``` - -## Class Hierarchy - -``` -VaadinElement - └── AccordionElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `HasStyleElement` | Style attribute support | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-accordion"` | HTML tag name | - -## API Methods - -### Constructor - -```java -AccordionElement(Locator locator) -``` - -Creates a new `AccordionElement` from a Playwright locator. - -### Panel Management - -| Method | Description | -|--------|-------------| -| `getPanel(String summary)` | Get a panel by its summary text | -| `openPanel(String summary)` | Open a panel by its summary text | -| `closePanel(String summary)` | Close a panel by its summary text | -| `getOpenedPanel()` | Get the currently opened panel | -| `isPanelOpened(String summary)` | Check if a panel is open | - -### Assertions - -| Method | Description | -|--------|-------------| -| `assertPanelCount(int count)` | Assert the number of panels | -| `assertPanelOpened(String summary)` | Assert that a panel is open | -| `assertPanelClosed(String summary)` | Assert that a panel is closed | - -## Usage Examples - -### Basic Usage - -```java -AccordionElement accordion = new AccordionElement(page.locator("vaadin-accordion")); - -// Assert panel count -accordion.assertPanelCount(3); - -// Open and close panels -accordion.openPanel("Personal Information"); -accordion.assertPanelOpened("Personal Information"); - -accordion.closePanel("Personal Information"); -accordion.assertPanelClosed("Personal Information"); - -// Get the currently opened panel -AccordionPanelElement openedPanel = accordion.getOpenedPanel(); -``` - -## Related Elements - -- `AccordionPanelElement` - Individual accordion panel diff --git a/docs/specifications/AccordionPanelElement.md b/docs/specifications/AccordionPanelElement.md deleted file mode 100644 index db33f0b..0000000 --- a/docs/specifications/AccordionPanelElement.md +++ /dev/null @@ -1,94 +0,0 @@ -# AccordionPanelElement Specification - -## Overview - -`AccordionPanelElement` is a Playwright element wrapper for the `` web component. It offers utilities to toggle open state, read summary and access content. - -## Tag Name - -``` -vaadin-accordion-panel -``` - -## Class Hierarchy - -``` -VaadinElement - └── AccordionPanelElement -``` - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-accordion-panel"` | HTML tag name | -| `FIELD_HEADING_TAG_NAME` | `"vaadin-accordion-heading"` | Heading tag name | - -## API Methods - -### Constructor - -```java -AccordionPanelElement(Locator locator) -``` - -Creates a new `AccordionPanelElement` from a Playwright locator. - -### Static Factory Methods - -#### getAccordionPanelBySummary(Locator locator, String summary) - -Get an accordion panel by its summary text within a scope. - -#### getOpenedAccordionPanel(Locator locator) - -Get the currently opened accordion panel within a scope. - -### State Methods - -| Method | Description | -|--------|-------------| -| `isOpen()` | Whether the panel is open | -| `setOpen(boolean open)` | Set the open state by clicking summary | -| `getSummaryText()` | Get the text content of the summary | - -### Locator Methods - -| Method | Description | -|--------|-------------| -| `getSummaryLocator()` | Locator for the summary heading | -| `getContentLocator()` | Locator for the content element | - -### Assertions - -| Method | Description | -|--------|-------------| -| `assertOpened()` | Assert that the panel is opened | -| `assertClosed()` | Assert that the panel is closed | -| `assertEnabled()` | Assert that the panel is enabled | -| `assertDisabled()` | Assert that the panel is disabled | -| `assertContentVisible()` | Assert that content is visible | -| `assertContentNotVisible()` | Assert that content is hidden | - -## Usage Examples - -### Basic Usage - -```java -AccordionPanelElement panel = AccordionPanelElement.getAccordionPanelBySummary( - page.locator("vaadin-accordion"), "Details"); - -// Check and toggle state -if (!panel.isOpen()) { - panel.setOpen(true); -} -panel.assertOpened(); - -// Access content -String summary = panel.getSummaryText(); -Locator content = panel.getContentLocator(); -``` - -## Related Elements - -- `AccordionElement` - Parent accordion container diff --git a/docs/specifications/BigDecimalFieldElement.md b/docs/specifications/BigDecimalFieldElement.md deleted file mode 100644 index 600fe42..0000000 --- a/docs/specifications/BigDecimalFieldElement.md +++ /dev/null @@ -1,91 +0,0 @@ -# BigDecimalFieldElement Specification - -## Overview - -`BigDecimalFieldElement` is a Playwright element wrapper for the `` web component. - -## Tag Name - -``` -vaadin-big-decimal-field -``` - -## Class Hierarchy - -``` -VaadinElement - └── BigDecimalFieldElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `HasValidationPropertiesElement` | Validation properties support | -| `HasInputFieldElement` | Input field operations | -| `HasPrefixElement` | Prefix slot support | -| `HasSuffixElement` | Suffix slot support | -| `HasClearButtonElement` | Clear button functionality | -| `HasPlaceholderElement` | Placeholder text support | -| `HasAllowedCharPatternElement` | Character pattern restrictions | -| `HasThemeElement` | Theme variants support | -| `FocusableElement` | Focus operations | -| `HasAriaLabelElement` | ARIA label accessibility | -| `HasEnabledElement` | Enabled/disabled state | -| `HasTooltipElement` | Tooltip support | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-big-decimal-field"` | HTML tag name | - -## API Methods - -### Constructor - -```java -BigDecimalFieldElement(Locator locator) -``` - -Creates a new `BigDecimalFieldElement` from a Playwright locator. - -### Static Factory Methods - -#### getByLabel(Page page, String label) - -Locates a big decimal field by its label on a page. - -```java -BigDecimalFieldElement field = BigDecimalFieldElement.getByLabel(page, "Price"); -``` - -#### getByLabel(Locator locator, String label) - -Locates a big decimal field by its label within a specific locator context. - -```java -BigDecimalFieldElement field = BigDecimalFieldElement.getByLabel(formLocator, "Amount"); -``` - -## Usage Examples - -### Basic Usage - -```java -BigDecimalFieldElement price = BigDecimalFieldElement.getByLabel(page, "Price"); - -// Set value (inherited from HasInputFieldElement) -price.setValue("123.45"); - -// Assert value -price.assertValue("123.45"); - -// Clear field -price.clickClearButton(); -``` - -## Related Elements - -- `NumberFieldElement` - For double precision numbers -- `IntegerFieldElement` - For integer numbers diff --git a/docs/specifications/ButtonElement.md b/docs/specifications/ButtonElement.md deleted file mode 100644 index 36c9685..0000000 --- a/docs/specifications/ButtonElement.md +++ /dev/null @@ -1,116 +0,0 @@ -# ButtonElement Specification - -## Overview - -`ButtonElement` is a Playwright element wrapper for the `` web component. It provides lookup helpers based on accessible name or visible text and exposes common focus, aria-label, enablement, prefix/suffix and theming mixins. - -## Tag Name - -``` -vaadin-button -``` - -## Class Hierarchy - -``` -VaadinElement - └── ButtonElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `FocusableElement` | Focus operations | -| `HasAriaLabelElement` | ARIA label accessibility | -| `HasEnabledElement` | Enabled/disabled state | -| `HasPrefixElement` | Prefix slot support | -| `HasStyleElement` | Style attribute support | -| `HasSuffixElement` | Suffix slot support | -| `HasThemeElement` | Theme variants support | -| `HasTooltipElement` | Tooltip support | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-button"` | HTML tag name | - -## API Methods - -### Constructor - -```java -ButtonElement(Locator locator) -``` - -Creates a new `ButtonElement` from a Playwright locator. - -### Static Factory Methods - -#### getByText(Page page, String text) - -Get a button by its accessible name or visible text. - -```java -ButtonElement btn = ButtonElement.getByText(page, "Save"); -``` - -#### getByText(Page page, Page.GetByRoleOptions options) - -Get a button with custom role options. - -```java -ButtonElement btn = ButtonElement.getByText(page, - new Page.GetByRoleOptions().setName("Submit").setExact(true)); -``` - -#### getByText(Locator locator, String text) - -Get a button by text within a scope. - -```java -ButtonElement btn = ButtonElement.getByText(formLocator, "Cancel"); -``` - -#### getByText(Locator locator, Locator.GetByRoleOptions options) - -Get a button with custom options within a scope. - -#### getByLabel(Page page, String text) - -Alias for `getByText(Page, String)`. - -## Usage Examples - -### Basic Usage - -```java -// Find button by text -ButtonElement saveBtn = ButtonElement.getByText(page, "Save"); - -// Click the button -saveBtn.click(); - -// Check enabled state -saveBtn.assertEnabled(); -saveBtn.assertDisabled(); - -// Focus operations -saveBtn.focus(); -saveBtn.blur(); -``` - -### With Theme Assertions - -```java -ButtonElement primaryBtn = ButtonElement.getByText(page, "Submit"); - -// Assert theme variant -primaryBtn.assertHasTheme("primary"); -primaryBtn.assertHasTheme("error"); -``` - -## Related Elements - -- `MenuItemElement` - For menu bar buttons diff --git a/docs/specifications/CardElement.md b/docs/specifications/CardElement.md deleted file mode 100644 index a86e81a..0000000 --- a/docs/specifications/CardElement.md +++ /dev/null @@ -1,106 +0,0 @@ -# CardElement Specification - -## Overview - -`CardElement` is a Playwright element wrapper for the `` web component. It exposes slot-aware accessors (title, subtitle, header/footer, media) and lookup helpers based on the Card's ARIA region name (title). - -## Tag Name - -``` -vaadin-card -``` - -## Class Hierarchy - -``` -VaadinElement - └── CardElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `HasThemeElement` | Theme variants support | -| `HasStyleElement` | Style attribute support | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-card"` | HTML tag name | - -## API Methods - -### Constructor - -```java -CardElement(Locator locator) -``` - -Creates a new `CardElement` from a Playwright locator. - -### Static Factory Methods - -#### getByTitle(Page page, String title) - -Get a card by its title. - -```java -CardElement card = CardElement.getByTitle(page, "User Profile"); -``` - -#### getByTitle(Locator locator, String title) - -Get a card by title within a scope. - -```java -CardElement card = CardElement.getByTitle(containerLocator, "Settings"); -``` - -### Slot Locators - -| Method | Description | -|--------|-------------| -| `getTitleLocator()` | Locator for the title slot | -| `getSubtitleLocator()` | Locator for the subtitle slot | -| `getHeaderLocator()` | Locator for the header slot | -| `getHeaderPrefixLocator()` | Locator for the header-prefix slot | -| `getHeaderSuffixLocator()` | Locator for the header-suffix slot | -| `getMediaLocator()` | Locator for the media slot | -| `getFooterLocator()` | Locator for the footer slot | -| `getContentLocator()` | Locator for the default content slot | - -### Assertions - -| Method | Description | -|--------|-------------| -| `assertTitle(String title)` | Assert card title or absence when `null` | -| `assertSubtitle(String subtitle)` | Assert card subtitle or absence when `null` | - -## Usage Examples - -### Basic Usage - -```java -CardElement card = CardElement.getByTitle(page, "Product Details"); - -// Assert title and subtitle -card.assertTitle("Product Details"); -card.assertSubtitle("Premium Edition"); - -// Access card sections -Locator header = card.getHeaderLocator(); -Locator content = card.getContentLocator(); -Locator footer = card.getFooterLocator(); - -// Access media slot -Locator media = card.getMediaLocator(); -``` - -### Theme Variants - -```java -CardElement card = CardElement.getByTitle(page, "Alert"); -card.assertHasTheme("error"); -``` diff --git a/docs/specifications/CheckboxElement.md b/docs/specifications/CheckboxElement.md deleted file mode 100644 index eb47f4d..0000000 --- a/docs/specifications/CheckboxElement.md +++ /dev/null @@ -1,126 +0,0 @@ -# CheckboxElement Specification - -## Overview - -`CheckboxElement` is a Playwright element wrapper for the `` web component. It provides helpers to read and modify checked/indeterminate state and access common mixins for label, helper, validation and enablement. - -## Tag Name - -``` -vaadin-checkbox -``` - -## Class Hierarchy - -``` -VaadinElement - └── CheckboxElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `FocusableElement` | Focus operations | -| `HasAriaLabelElement` | ARIA label accessibility | -| `HasEnabledElement` | Enabled/disabled state | -| `HasHelperElement` | Helper text support | -| `HasValueElement` | Value operations | -| `HasStyleElement` | Style attribute support | -| `HasLabelElement` | Label support | -| `HasValidationPropertiesElement` | Validation properties | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-checkbox"` | HTML tag name | - -## API Methods - -### Constructor - -```java -CheckboxElement(Locator locator) -``` - -Creates a new `CheckboxElement` from a Playwright locator. - -### Static Factory Methods - -#### getByLabel(Page page, String label) - -Get a checkbox by its accessible label. - -```java -CheckboxElement checkbox = CheckboxElement.getByLabel(page, "Accept Terms"); -``` - -### Checked State - -| Method | Description | -|--------|-------------| -| `isChecked()` | Whether the checkbox is checked | -| `check()` | Check the checkbox | -| `uncheck()` | Uncheck the checkbox | -| `assertChecked()` | Assert that checkbox is checked | -| `assertNotChecked()` | Assert that checkbox is not checked | - -### Indeterminate State - -| Method | Description | -|--------|-------------| -| `isIndeterminate()` | Whether checkbox is indeterminate | -| `setIndeterminate(boolean)` | Set the indeterminate state | -| `assertIndeterminate()` | Assert indeterminate state | -| `assertNotIndeterminate()` | Assert not indeterminate | - -### Locator Methods - -| Method | Description | -|--------|-------------| -| `getEnabledLocator()` | Returns input locator for enabled state | -| `getAriaLabelLocator()` | Returns input locator for ARIA label | -| `getFocusLocator()` | Returns input locator for focus | - -## Usage Examples - -### Basic Usage - -```java -CheckboxElement terms = CheckboxElement.getByLabel(page, "I accept the terms"); - -// Check/uncheck -terms.check(); -terms.assertChecked(); - -terms.uncheck(); -terms.assertNotChecked(); -``` - -### Indeterminate State - -```java -CheckboxElement selectAll = CheckboxElement.getByLabel(page, "Select All"); - -// Set indeterminate -selectAll.setIndeterminate(true); -selectAll.assertIndeterminate(); - -// Clear indeterminate by checking -selectAll.check(); -selectAll.assertNotIndeterminate(); -``` - -### Validation - -```java -CheckboxElement required = CheckboxElement.getByLabel(page, "Required Field"); -required.assertRequired(); -required.assertInvalid(); -``` - -## Related Elements - -- `RadioButtonElement` - Single selection from group -- `RadioButtonGroupElement` - Group of radio buttons diff --git a/docs/specifications/ComboBoxElement.md b/docs/specifications/ComboBoxElement.md index 19a4ff2..31388ae 100644 --- a/docs/specifications/ComboBoxElement.md +++ b/docs/specifications/ComboBoxElement.md @@ -1,259 +1,22 @@ -# ComboBoxElement Specification +# ComboBoxElement -## Overview +> Full API (methods, signatures, descriptions): see [api-reference.md](../../skills/vaadin-playwright-test/api-reference.md). This note covers only behaviour that isn't obvious from the signatures. -`ComboBoxElement` is a Playwright element wrapper for the `` web component. It provides helpers to open the overlay, filter items, and pick items by visible text, along with aria/placeholder/validation mixins. It supports both in-memory and lazy-loaded data providers. +## Lazy data providers behave identically -## Tag Name +ComboBox supports both in-memory and lazy-loaded (server-side) data providers. The element API works the same way regardless of the loading strategy — `filterAndSelectItem` and `setFilter` narrow results from the server exactly as they do for in-memory data. -``` -vaadin-combo-box -``` - -## Class Hierarchy - -``` -VaadinElement - └── ComboBoxElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `FocusableElement` | Focus operations | -| `HasAriaLabelElement` | ARIA label accessibility | -| `HasInputFieldElement` | Input field operations (value, helper, label, style) | -| `HasPrefixElement` | Prefix slot support | -| `HasThemeElement` | Theme variants support | -| `HasPlaceholderElement` | Placeholder text support | -| `HasEnabledElement` | Enabled/disabled state | -| `HasTooltipElement` | Tooltip support | -| `HasValidationPropertiesElement` | Validation properties | -| `HasClearButtonElement` | Clear button functionality | -| `HasAllowedCharPatternElement` | Character pattern restrictions | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-combo-box"` | HTML tag name | -| `FIELD_ITEM_TAG_NAME` | `"vaadin-combo-box-item"` | Item tag name | - -## API Methods - -### Constructor - -```java -ComboBoxElement(Locator locator) -``` - -Creates a new `ComboBoxElement` from a Playwright locator. - -### Static Factory Methods - -#### getByLabel(Page page, String label) - -Locates a combo box by its accessible label on a page. Uses `AriaRole.COMBOBOX` for matching. - -```java -ComboBoxElement comboBox = ComboBoxElement.getByLabel(page, "Country"); -``` - -#### getByLabel(Locator locator, String label) - -Locates a combo box by its label within a specific locator scope. - -```java -ComboBoxElement comboBox = ComboBoxElement.getByLabel(formLocator, "Country"); -``` - -### Selection Methods - -| Method | Description | -|--------|-------------| -| `selectItem(String item)` | Open the overlay and click the matching item by visible label | -| `filterAndSelectItem(String filter, String item)` | Type filter text into the input, then click the matching item | - -### Filter Methods - -| Method | Description | -|--------|-------------| -| `setFilter(String filter)` | Open the overlay and type into the input to trigger filtering | -| `getFilter()` | Get the current filter value from the DOM property | - -### Overlay Methods - -| Method | Description | -|--------|-------------| -| `open()` | Open the combo box overlay | -| `close()` | Close the combo box overlay | -| `isOpened()` | Whether the overlay is currently open | -| `clickToggleButton()` | Click the dropdown toggle button | -| `getOverlayItemCount()` | Count visible overlay items | - -### Value Methods - -| Method | Description | -|--------|-------------| -| `getValue()` | Get the displayed value from the input element | -| `assertValue(String expected)` | Assert the displayed value equals the expected string | - -### Read-Only Methods - -| Method | Description | -|--------|-------------| -| `isReadOnly()` | Whether the combo box is read-only | -| `assertReadOnly()` | Assert the combo box is read-only | -| `assertNotReadOnly()` | Assert the combo box is not read-only | - -### Locator Methods - -| Method | Description | -|--------|-------------| -| `getFocusLocator()` | Returns the input locator | -| `getAriaLabelLocator()` | Returns the input locator | -| `getEnabledLocator()` | Returns the input locator | -| `getToggleButtonLocator()` | Returns the toggle button part locator | - -### Assertions - -| Method | Description | -|--------|-------------| -| `assertValue(String expected)` | Assert the displayed value | -| `assertOpened()` | Assert the overlay is open | -| `assertClosed()` | Assert the overlay is closed | -| `assertReadOnly()` | Assert read-only state | -| `assertNotReadOnly()` | Assert not read-only state | -| `assertItemCount(int expected)` | Assert the overlay contains exactly the expected number of visible items | - -## Usage Examples - -### Basic Usage - -```java -ComboBoxElement comboBox = ComboBoxElement.getByLabel(page, "Sort by"); - -// Select an item -comboBox.selectItem("Rating: high to low"); - -// Get selected value -String selected = comboBox.getValue(); // "Rating: high to low" - -// Assert selection -comboBox.assertValue("Rating: high to low"); -``` +## Filter-then-select pattern -### Filtering and Selection +`filterAndSelectItem` types filter text into the input (triggering server/in-memory filtering) and then clicks the matching item in one step. Use `setFilter` + `assertItemCount` when you want to verify how many items a filter narrows to before selecting. ```java -ComboBoxElement comboBox = ComboBoxElement.getByLabel(page, "Fruit"); - // Filter and select in one step comboBox.filterAndSelectItem("Apr", "Apricot"); comboBox.assertValue("Apricot"); -// Or filter manually +// Or filter manually and inspect the narrowed list comboBox.setFilter("Ban"); comboBox.assertItemCount(1); comboBox.close(); ``` - -### Lazy Loading - -ComboBox supports lazy data providers for large datasets. The element API works the same way regardless of the data loading strategy. - -```java -ComboBoxElement comboBox = ComboBoxElement.getByLabel(page, "Lazy ComboBox"); - -// Filter narrows results from the server -comboBox.filterAndSelectItem("Item 250", "Item 250"); -comboBox.assertValue("Item 250"); - -// Verify filtered item count -comboBox.setFilter("Item 500"); -comboBox.assertItemCount(1); -comboBox.close(); -``` - -### Overlay State - -```java -ComboBoxElement comboBox = ComboBoxElement.getByLabel(page, "Country"); - -// Assert initial state -comboBox.assertClosed(); - -// Open and verify -comboBox.open(); -comboBox.assertOpened(); - -// Close and verify -comboBox.close(); -comboBox.assertClosed(); -``` - -### Clear Button - -```java -ComboBoxElement comboBox = ComboBoxElement.getByLabel(page, "Category"); - -comboBox.selectItem("Electronics"); -comboBox.assertValue("Electronics"); - -comboBox.clickClearButton(); -comboBox.assertValue(""); -``` - -### Read-Only - -```java -ComboBoxElement comboBox = ComboBoxElement.getByLabel(page, "Read-only ComboBox"); - -comboBox.assertReadOnly(); -comboBox.assertValue("Banana"); -``` - -### Validation - -```java -ComboBoxElement comboBox = ComboBoxElement.getByLabel(page, "Required Field"); - -comboBox.assertValid(); - -// Trigger validation -ButtonElement.getByText(page, "Validate").click(); -comboBox.assertInvalid(); -``` - -### Prefix and Helper - -```java -ComboBoxElement comboBox = ComboBoxElement.getByLabel(page, "Sort by"); - -// Prefix -comboBox.assertPrefixHasText("Prefix"); - -// Helper text -comboBox.assertHelperHasText("Helper text"); -``` - -### Focus and Accessibility - -```java -ComboBoxElement comboBox = ComboBoxElement.getByLabel(page, "Sort by"); - -// Focus -comboBox.focus(); -comboBox.assertIsFocused(); - -// ARIA label -ComboBoxElement ariaCombo = ComboBoxElement.getByLabel(page, "Invisible label"); -ariaCombo.assertAriaLabel("Invisible label"); -``` - -## Related Elements - -- `SelectElement` - Simpler overlay selection without filtering or lazy loading -- `ListBoxElement` - Scrollable inline list of options -- `RadioButtonGroupElement` - Radio-based selection with all options visible diff --git a/docs/specifications/ContextMenuElement.md b/docs/specifications/ContextMenuElement.md deleted file mode 100644 index 601fe86..0000000 --- a/docs/specifications/ContextMenuElement.md +++ /dev/null @@ -1,117 +0,0 @@ -# ContextMenuElement Specification - -## Overview - -`ContextMenuElement` is a Playwright element wrapper for context menu overlays ``. It provides helpers to open a menu via a context-click on the target, inspect the overlay list box, and pick menu items by their accessible label using the `menu` role. - -## Tag Name - -``` -vaadin-context-menu -``` - -## Class Hierarchy - -``` -VaadinElement - └── ContextMenuElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `HasStyleElement` | Style attribute support | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-context-menu"` | HTML tag name | -| `FIELD_LIST_BOX_TAG_NAME` | `"vaadin-context-menu-list-box"` | List box tag name | - -## API Methods - -### Constructors - -```java -ContextMenuElement(Page page) -``` - -Creates a `ContextMenuElement` from the first opened context menu on the page. - -```java -ContextMenuElement(Locator locator) -``` - -Creates a `ContextMenuElement` from an existing locator. - -### Static Methods - -#### openOn(Locator target) - -Open the context menu by right-clicking on the provided target. - -```java -ContextMenuElement.openOn(page.locator(".my-element")); -``` - -### Menu Operations - -| Method | Description | -|--------|-------------| -| `selectItem(String itemLabel)` | Select a menu item by label | -| `openSubMenu(String itemLabel)` | Open a submenu and return its overlay | -| `getListBoxLocator()` | Locator for the menu list box | - -### Assertions - -| Method | Description | -|--------|-------------| -| `assertOpen()` | Assert that menu is open | -| `assertClosed()` | Assert that menu is closed | -| `assertItemEnabled(String itemLabel)` | Assert menu item is enabled | -| `assertItemDisabled(String itemLabel)` | Assert menu item is disabled | -| `assertItemChecked(String itemLabel)` | Assert checkable item is checked | -| `assertItemNotChecked(String itemLabel)` | Assert checkable item is not checked | - -## Usage Examples - -### Basic Usage - -```java -// Right-click to open context menu -ContextMenuElement.openOn(page.locator(".target-element")); - -// Get the context menu -ContextMenuElement menu = new ContextMenuElement(page); -menu.assertOpen(); - -// Select an item -menu.selectItem("Copy"); -``` - -### Submenus - -```java -ContextMenuElement.openOn(page.locator(".target")); -ContextMenuElement menu = new ContextMenuElement(page); - -// Open a submenu -ContextMenuElement submenu = menu.openSubMenu("More Options"); -submenu.selectItem("Advanced Settings"); -``` - -### Checkable Items - -```java -ContextMenuElement menu = new ContextMenuElement(page); -menu.assertItemChecked("Show Grid"); -menu.selectItem("Show Grid"); // Toggle -menu.assertItemNotChecked("Show Grid"); -``` - -## Related Elements - -- `MenuBarElement` - For menu bar navigation -- `MenuElement` - For menu bar dropdowns diff --git a/docs/specifications/DatePickerElement.md b/docs/specifications/DatePickerElement.md index 884d06b..b6b9d96 100644 --- a/docs/specifications/DatePickerElement.md +++ b/docs/specifications/DatePickerElement.md @@ -1,130 +1,16 @@ -# DatePickerElement Specification +# DatePickerElement -## Overview +> Full API (methods, signatures, descriptions): see [api-reference.md](../../skills/vaadin-playwright-test/api-reference.md). This note covers only behaviour that isn't obvious from the signatures. -`DatePickerElement` is a Playwright element wrapper for the `` web component. It adds convenience methods for `LocalDate` values and lookup by label. +## String values use the localized format, LocalDate uses ISO -## Tag Name +`setValue(String)` / `assertValue(String)` expect the localized display format `dd/mm/yyyy` (e.g. `"15/05/2023"`), whereas `setValue(LocalDate)` uses ISO-8601. Pick the overload that matches the format you're working with. -``` -vaadin-date-picker -``` - -## Class Hierarchy - -``` -VaadinElement - └── DatePickerElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `HasInputFieldElement` | Input field operations | -| `HasValidationPropertiesElement` | Validation properties | -| `HasClearButtonElement` | Clear button functionality | -| `HasPlaceholderElement` | Placeholder text support | -| `HasThemeElement` | Theme variants support | -| `FocusableElement` | Focus operations | -| `HasAriaLabelElement` | ARIA label accessibility | -| `HasEnabledElement` | Enabled/disabled state | -| `HasTooltipElement` | Tooltip support | -| `HasLabelElement` | Label support | -| `HasHelperElement` | Helper text support | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-date-picker"` | HTML tag name | - -## API Methods - -### Constructor - -```java -DatePickerElement(Locator locator) -``` - -Creates a new `DatePickerElement` from a Playwright locator. - -### Static Factory Methods - -#### getByLabel(Page page, String label) - -Locates a date picker by its label. - -```java -DatePickerElement datePicker = DatePickerElement.getByLabel(page, "Birth Date"); -``` - -#### getByLabel(Locator locator, String label) +## Asserting a cleared value -Locates a date picker by label within a scope. - -### Value Methods - -| Method | Description | -|--------|-------------| -| `setValue(LocalDate date)` | Set value using LocalDate (ISO-8601 format) | -| `setValue(String value)` | Set value as string (dd/mm/yyyy format) | -| `getValueAsLocalDate()` | Get value as LocalDate or null | - -### Assertions - -| Method | Description | -|--------|-------------| -| `assertValue(String value)` | Assert value as string (dd/mm/yyyy) | -| `assertValue(LocalDate value)` | Assert value as LocalDate | - -### Locator Methods - -| Method | Description | -|--------|-------------| -| `getAriaLabelLocator()` | Returns input locator | -| `getFocusLocator()` | Returns input locator | -| `getEnabledLocator()` | Returns input locator | - -## Usage Examples - -### Basic Usage +After clearing, assert emptiness with the `LocalDate` overload passing an explicit null cast to disambiguate: ```java -DatePickerElement birthDate = DatePickerElement.getByLabel(page, "Birth Date"); - -// Set value with LocalDate -birthDate.setValue(LocalDate.of(1990, 5, 15)); - -// Get value -LocalDate date = birthDate.getValueAsLocalDate(); - -// Assert value -birthDate.assertValue(LocalDate.of(1990, 5, 15)); -``` - -### String Format - -```java -DatePickerElement startDate = DatePickerElement.getByLabel(page, "Start Date"); - -// Set value as formatted string -startDate.setValue("15/05/2023"); -startDate.assertValue("15/05/2023"); -``` - -### Clear and Validation - -```java -DatePickerElement date = DatePickerElement.getByLabel(page, "Date"); date.clickClearButton(); date.assertValue((LocalDate) null); - -date.assertRequired(); -date.assertInvalid(); ``` - -## Related Elements - -- `TimePickerElement` - For time selection -- `DateTimePickerElement` - Combined date and time picker diff --git a/docs/specifications/DateTimePickerElement.md b/docs/specifications/DateTimePickerElement.md index 9d76a98..ad0ea87 100644 --- a/docs/specifications/DateTimePickerElement.md +++ b/docs/specifications/DateTimePickerElement.md @@ -1,147 +1,21 @@ -# DateTimePickerElement Specification +# DateTimePickerElement -## Overview +> Full API (methods, signatures, descriptions): see [api-reference.md](../../skills/vaadin-playwright-test/api-reference.md). This note covers only behaviour that isn't obvious from the signatures. -`DateTimePickerElement` is a Playwright element wrapper for the `` web component. It composes a `DatePickerElement` and `TimePickerElement` and exposes helpers to interact using `LocalDateTime`. +## Composite of two sub-fields -## Tag Name +`DateTimePickerElement` internally composes a `DatePickerElement` and a `TimePickerElement`. This changes several inherited behaviours: -``` -vaadin-date-time-picker -``` - -## Class Hierarchy - -``` -VaadinElement - └── DateTimePickerElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `HasInputFieldElement` | Input field operations | -| `HasValidationPropertiesElement` | Validation properties | -| `HasClearButtonElement` | Clear button functionality | -| `HasPlaceholderElement` | Placeholder text support | -| `HasThemeElement` | Theme variants support | -| `FocusableElement` | Focus operations | -| `HasAriaLabelElement` | ARIA label accessibility | -| `HasEnabledElement` | Enabled/disabled state | -| `HasTooltipElement` | Tooltip support | -| `HasLabelElement` | Label support | -| `HasHelperElement` | Helper text support | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-date-time-picker"` | HTML tag name | -| `ISO_LOCAL_DATE_TIME` | DateTimeFormatter | ISO format with custom time | - -## API Methods - -### Constructor - -```java -DateTimePickerElement(Locator locator) -``` - -Creates a new `DateTimePickerElement` from a Playwright locator. Internally creates `DatePickerElement` and `TimePickerElement` children. - -### Static Factory Methods - -#### getByLabel(Page page, String label) - -Locates a date-time picker by its label. - -```java -DateTimePickerElement picker = DateTimePickerElement.getByLabel(page, "Appointment"); -``` - -#### getByLabel(Locator locator, String label) - -Locates a date-time picker by label within a scope. - -### Value Methods +- **`getAriaLabel()`** returns the *date* picker's ARIA label; `assertAriaLabel(String)` asserts it on *both* sub-fields. +- **`isEnabled()` / `assertEnabled()` / `assertDisabled()`** require *both* sub-fields to be in that state. +- You can set/assert each part independently via `setDate` / `setTime` and `assertDateValue` / `assertTimeValue`. -| Method | Description | -|--------|-------------| -| `setValue(LocalDateTime date)` | Set value using LocalDateTime | -| `setValue(String value)` | Set value as string (dd/mm/yyyy hh:mm) | -| `getValueAsLocalDateTime()` | Get value as LocalDateTime or null | - -### Partial Value Methods - -| Method | Description | -|--------|-------------| -| `setDate(String date)` | Set only the date part | -| `setTime(String time)` | Set only the time part | -| `assertDateValue(String date)` | Assert date sub-field value | -| `assertTimeValue(String time)` | Assert time sub-field value | - -### Assertions - -| Method | Description | -|--------|-------------| -| `assertValue(String value)` | Assert value as string | -| `assertValue(LocalDateTime value)` | Assert value as LocalDateTime | - -### Overridden Methods - -| Method | Description | -|--------|-------------| -| `getAriaLabel()` | Returns date picker's ARIA label | -| `assertAriaLabel(String)` | Asserts both date and time ARIA labels | -| `isEnabled()` | Returns true if both sub-fields enabled | -| `assertEnabled()` | Asserts both sub-fields enabled | -| `assertDisabled()` | Asserts both sub-fields disabled | - -## Usage Examples - -### Basic Usage +The `String` value format is `dd/mm/yyyy hh:mm`. ```java -DateTimePickerElement appointment = DateTimePickerElement.getByLabel(page, "Appointment"); - -// Set value with LocalDateTime -appointment.setValue(LocalDateTime.of(2023, 5, 15, 14, 30)); - -// Get value -LocalDateTime dateTime = appointment.getValueAsLocalDateTime(); - -// Assert value -appointment.assertValue(LocalDateTime.of(2023, 5, 15, 14, 30)); -``` - -### Partial Updates - -```java -DateTimePickerElement meeting = DateTimePickerElement.getByLabel(page, "Meeting"); - -// Set date and time separately +// Set date and time separately, then assert each part meeting.setDate("15/05/2023"); meeting.setTime("14:30"); - -// Assert individual parts meeting.assertDateValue("15/05/2023"); meeting.assertTimeValue("14:30"); ``` - -### Enabled State - -```java -DateTimePickerElement picker = DateTimePickerElement.getByLabel(page, "Schedule"); - -// Both date and time must be enabled -picker.assertEnabled(); - -// Both date and time must be disabled -picker.assertDisabled(); -``` - -## Related Elements - -- `DatePickerElement` - For date only selection -- `TimePickerElement` - For time only selection diff --git a/docs/specifications/DetailsElement.md b/docs/specifications/DetailsElement.md deleted file mode 100644 index 2cd8bf1..0000000 --- a/docs/specifications/DetailsElement.md +++ /dev/null @@ -1,120 +0,0 @@ -# DetailsElement Specification - -## Overview - -`DetailsElement` is a Playwright element wrapper for the `` web component. It provides helpers to open/close and access the summary/content. - -## Tag Name - -``` -vaadin-details -``` - -## Class Hierarchy - -``` -VaadinElement - └── DetailsElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `HasStyleElement` | Style attribute support | -| `HasThemeElement` | Theme variants support | -| `HasTooltipElement` | Tooltip support | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-details"` | HTML tag name | - -## API Methods - -### Constructor - -```java -DetailsElement(Locator locator) -``` - -Creates a new `DetailsElement` from a Playwright locator. - -### Static Factory Methods - -#### getBySummaryText(Page page, String summary) - -Get a details component by its summary text. - -```java -DetailsElement details = DetailsElement.getBySummaryText(page, "More Information"); -``` - -### State Methods - -| Method | Description | -|--------|-------------| -| `isOpen()` | Whether the details is opened | -| `setOpen(boolean open)` | Set opened state by clicking summary | -| `getSummaryText()` | Get the text of the summary | - -### Locator Methods - -| Method | Description | -|--------|-------------| -| `getSummaryLocator()` | Locator for the summary element | -| `getContentLocator()` | Locator for the visible content | - -### Assertions - -| Method | Description | -|--------|-------------| -| `assertOpened()` | Assert that details is opened | -| `assertClosed()` | Assert that details is closed | -| `assertEnabled()` | Assert that component is enabled | -| `assertDisabled()` | Assert that component is disabled | -| `assertContentVisible()` | Assert content is visible | -| `assertContentNotVisible()` | Assert content is hidden | - -## Usage Examples - -### Basic Usage - -```java -DetailsElement details = DetailsElement.getBySummaryText(page, "Advanced Options"); - -// Check and toggle state -details.assertClosed(); -details.setOpen(true); -details.assertOpened(); - -// Verify content visibility -details.assertContentVisible(); - -// Get summary text -String summary = details.getSummaryText(); // "Advanced Options" -``` - -### Accessing Content - -```java -DetailsElement details = DetailsElement.getBySummaryText(page, "Settings"); -details.setOpen(true); - -// Access the content area -Locator content = details.getContentLocator(); -content.locator("input").first().fill("value"); -``` - -### Disabled State - -```java -DetailsElement details = DetailsElement.getBySummaryText(page, "Locked Section"); -details.assertDisabled(); -``` - -## Related Elements - -- `AccordionElement` - Multiple collapsible panels -- `AccordionPanelElement` - Individual accordion panel diff --git a/docs/specifications/DialogElement.md b/docs/specifications/DialogElement.md deleted file mode 100644 index 55de24e..0000000 --- a/docs/specifications/DialogElement.md +++ /dev/null @@ -1,132 +0,0 @@ -# DialogElement Specification - -## Overview - -`DialogElement` is a Playwright element wrapper for the `` web component. It provides access to header/content/footer slots, modal flags and open state. - -## Tag Name - -``` -vaadin-dialog -``` - -## Class Hierarchy - -``` -VaadinElement - └── DialogElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `HasThemeElement` | Theme variants support | -| `HasStyleElement` | Style attribute support | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-dialog"` | HTML tag name | - -## API Methods - -### Constructors - -```java -DialogElement(Page page) -``` - -Creates a `DialogElement` by resolving the dialog with ARIA role on the page. - -```java -DialogElement(Locator locator) -``` - -Creates a `DialogElement` from an existing locator. - -### Static Factory Methods - -#### getByHeaderText(Page page, String summary) - -Get a dialog by its header text (accessible name). - -```java -DialogElement dialog = DialogElement.getByHeaderText(page, "Confirm Action"); -``` - -### State Methods - -| Method | Description | -|--------|-------------| -| `isOpen()` | Whether the dialog is open (visible) | -| `isModal()` | Whether the dialog is modal (not modeless) | -| `closeWithEscape()` | Close the dialog using Escape key | -| `getHeaderText()` | Get the header text from title slot | - -### Locator Methods - -| Method | Description | -|--------|-------------| -| `getHeaderLocator()` | Locator for header-content slot | -| `getContentLocator()` | Locator for dialog content (non-slotted) | -| `getFooterLocator()` | Locator for footer slot | - -### Assertions - -| Method | Description | -|--------|-------------| -| `assertOpen()` | Assert that dialog is open | -| `assertClosed()` | Assert that dialog is closed (hidden) | -| `assertModal()` | Assert that dialog is modal | -| `assertModeless()` | Assert that dialog is modeless | -| `assertHeaderText(String)` | Assert header text matches | - -## Usage Examples - -### Basic Usage - -```java -// Get dialog by ARIA role -DialogElement dialog = new DialogElement(page); -dialog.assertOpen(); - -// Get dialog by header -DialogElement confirmDialog = DialogElement.getByHeaderText(page, "Confirm Delete"); -confirmDialog.assertHeaderText("Confirm Delete"); - -// Close with Escape -confirmDialog.closeWithEscape(); -confirmDialog.assertClosed(); -``` - -### Modal vs Modeless - -```java -DialogElement modal = new DialogElement(page); -modal.assertModal(); - -DialogElement modeless = DialogElement.getByHeaderText(page, "Info"); -modeless.assertModeless(); -``` - -### Accessing Content - -```java -DialogElement dialog = DialogElement.getByHeaderText(page, "Edit User"); - -// Access content area -Locator content = dialog.getContentLocator(); -content.locator("input[name='email']").fill("user@example.com"); - -// Access footer for buttons -Locator footer = dialog.getFooterLocator(); -footer.locator("vaadin-button").filter( - new Locator.FilterOptions().setHasText("Save")).click(); -``` - -## Related Elements - -- `PopoverElement` - For popover overlays -- `NotificationElement` - For toast notifications diff --git a/docs/specifications/EmailFieldElement.md b/docs/specifications/EmailFieldElement.md deleted file mode 100644 index 0eddab1..0000000 --- a/docs/specifications/EmailFieldElement.md +++ /dev/null @@ -1,124 +0,0 @@ -# EmailFieldElement Specification - -## Overview - -`EmailFieldElement` is a Playwright element wrapper for the `` web component. It extends `TextFieldElement` with email-specific functionality. - -## Tag Name - -``` -vaadin-email-field -``` - -## Class Hierarchy - -``` -VaadinElement - └── TextFieldElement - └── EmailFieldElement -``` - -## Inherited Interfaces - -All interfaces from `TextFieldElement`: -- `HasValidationPropertiesElement` -- `HasInputFieldElement` -- `HasPrefixElement` -- `HasSuffixElement` -- `HasClearButtonElement` -- `HasPlaceholderElement` -- `HasAllowedCharPatternElement` -- `HasThemeElement` -- `FocusableElement` -- `HasAriaLabelElement` -- `HasEnabledElement` -- `HasTooltipElement` - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-email-field"` | HTML tag name | - -## API Methods - -### Constructor - -```java -EmailFieldElement(Locator locator) -``` - -Creates a new `EmailFieldElement` from a Playwright locator. - -### Static Factory Methods - -#### getByLabel(Page page, String label) - -Locates an email field by its label. - -```java -EmailFieldElement email = EmailFieldElement.getByLabel(page, "Email Address"); -``` - -#### getByLabel(Locator locator, String label) - -Locates an email field by label within a scope. - -```java -EmailFieldElement email = EmailFieldElement.getByLabel(formLocator, "Contact Email"); -``` - -## Usage Examples - -### Basic Usage - -```java -EmailFieldElement email = EmailFieldElement.getByLabel(page, "Email"); - -// Set value -email.setValue("user@example.com"); - -// Assert value -email.assertValue("user@example.com"); - -// Clear -email.clickClearButton(); -``` - -### Validation - -```java -EmailFieldElement email = EmailFieldElement.getByLabel(page, "Email"); - -// Set invalid email -email.setValue("invalid-email"); -email.assertInvalid(); - -// Set valid email -email.setValue("valid@email.com"); -email.assertValid(); -``` - -### Inherited Methods - -All methods from `TextFieldElement` are available: - -```java -EmailFieldElement email = EmailFieldElement.getByLabel(page, "Email"); - -// Min/max length -email.setMinLength(5); -email.setMaxLength(100); - -// Pattern (overrides default email pattern) -email.setPattern("[a-z]+@company\\.com"); - -// Focus -email.focus(); -email.blur(); -``` - -## Related Elements - -- `TextFieldElement` - Base text field -- `PasswordFieldElement` - For password input diff --git a/docs/specifications/GridElement.md b/docs/specifications/GridElement.md index 63eed67..a9a6f1e 100644 --- a/docs/specifications/GridElement.md +++ b/docs/specifications/GridElement.md @@ -1,5 +1,9 @@ # GridElement Specification +> For the authoritative method list and signatures, see the auto-generated +> [api-reference.md](../../skills/vaadin-playwright-test/api-reference.md). This +> file focuses on behaviour and usage that signatures alone don't convey. + ## Overview `GridElement` is a Playwright element wrapper for the `` web component. It provides helpers for querying rows and cells, accessing cell content by row/column index or header text, and interacting with the grid's selection, sorting, and row details features. Row and cell access methods **auto-scroll** the grid as needed to bring virtualized rows into view. diff --git a/docs/specifications/IntegerFieldElement.md b/docs/specifications/IntegerFieldElement.md deleted file mode 100644 index 8d02f4c..0000000 --- a/docs/specifications/IntegerFieldElement.md +++ /dev/null @@ -1,136 +0,0 @@ -# IntegerFieldElement Specification - -## Overview - -`IntegerFieldElement` is a Playwright element wrapper for the `` web component. It provides typed helpers to read and modify integer-specific attributes such as `min`, `max`, and `step`, and convenient factory methods to locate the element by its accessible label. - -## Tag Name - -``` -vaadin-integer-field -``` - -## Class Hierarchy - -``` -VaadinElement - └── AbstractNumberFieldElement - └── IntegerFieldElement -``` - -## Inherited Interfaces - -All interfaces from `AbstractNumberFieldElement`: -- `HasValidationPropertiesElement` -- `HasInputFieldElement` -- `HasPrefixElement` -- `HasSuffixElement` -- `HasClearButtonElement` -- `HasPlaceholderElement` -- `HasAllowedCharPatternElement` -- `HasThemeElement` -- `FocusableElement` -- `HasAriaLabelElement` -- `HasEnabledElement` -- `HasTooltipElement` - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-integer-field"` | HTML tag name | - -## API Methods - -### Constructor - -```java -IntegerFieldElement(Locator locator) -``` - -Creates a new `IntegerFieldElement` from a Playwright locator. - -### Static Factory Methods - -#### getByLabel(Page page, String label) - -Locates an integer field by its label using ARIA role `spinbutton`. - -```java -IntegerFieldElement quantity = IntegerFieldElement.getByLabel(page, "Quantity"); -``` - -#### getByLabel(Locator locator, String label) - -Locates an integer field by label within a scope. - -### Step Property - -| Method | Description | -|--------|-------------| -| `getStep()` | Get step as Integer or null | -| `setStep(int step)` | Set the step value | -| `assertStep(Integer step)` | Assert step value or null | - -### Min Property - -| Method | Description | -|--------|-------------| -| `getMin()` | Get minimum as Integer or null | -| `setMin(int min)` | Set the minimum value | -| `assertMin(Integer min)` | Assert minimum value or null | - -### Max Property - -| Method | Description | -|--------|-------------| -| `getMax()` | Get maximum as Integer or null | -| `setMax(int max)` | Set the maximum value | -| `assertMax(Integer max)` | Assert maximum value or null | - -## Usage Examples - -### Basic Usage - -```java -IntegerFieldElement quantity = IntegerFieldElement.getByLabel(page, "Quantity"); - -// Set value -quantity.setValue("10"); - -// Assert value -quantity.assertValue("10"); -``` - -### Constraints - -```java -IntegerFieldElement age = IntegerFieldElement.getByLabel(page, "Age"); - -// Set constraints -age.setMin(0); -age.setMax(120); -age.setStep(1); - -// Assert constraints -age.assertMin(0); -age.assertMax(120); -age.assertStep(1); -``` - -### Step Controls (from AbstractNumberFieldElement) - -```java -IntegerFieldElement counter = IntegerFieldElement.getByLabel(page, "Counter"); -counter.assertHasControls(true); - -// Use step buttons -counter.clickIncreaseButton(); -counter.clickDecreaseButton(); -``` - -## Related Elements - -- `NumberFieldElement` - For decimal (double) values -- `BigDecimalFieldElement` - For BigDecimal values -- `AbstractNumberFieldElement` - Base class diff --git a/docs/specifications/ListBoxElement.md b/docs/specifications/ListBoxElement.md deleted file mode 100644 index 8c5be9d..0000000 --- a/docs/specifications/ListBoxElement.md +++ /dev/null @@ -1,136 +0,0 @@ -# ListBoxElement Specification - -## Overview - -`ListBoxElement` is a Playwright element wrapper for the `` web component. It supports single and multiple selection, item-level enablement assertions, and label-based lookup. - -## Tag Name - -``` -vaadin-list-box -``` - -## Class Hierarchy - -``` -VaadinElement - └── ListBoxElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `HasAriaLabelElement` | ARIA label accessibility | -| `HasStyleElement` | Style attribute support | -| `HasTooltipElement` | Tooltip support | -| `HasEnabledElement` | Enabled/disabled state | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-list-box"` | HTML tag name | -| `FIELD_ITEM_TAG_NAME` | `"vaadin-item"` | Item tag name | -| `MULTIPLE_ATTRIBUTE` | `"multiple"` | Multiple selection attribute | - -## API Methods - -### Constructor - -```java -ListBoxElement(Locator locator) -``` - -Creates a new `ListBoxElement` from a Playwright locator. - -### Static Factory Methods - -#### getByLabel(Page page, String label) - -Get a list box by its accessible label. - -```java -ListBoxElement list = ListBoxElement.getByLabel(page, "Select Option"); -``` - -### Selection Methods - -| Method | Description | -|--------|-------------| -| `selectItem(String item)` | Select item by text (toggles in multi mode) | -| `getSingleSelectedValue()` | Get selected value for single-select | -| `getSelectedValue()` | Get all selected values as List | - -### Mode Methods - -| Method | Description | -|--------|-------------| -| `isMultiple()` | Whether multiple selection is enabled | -| `assertMultiple()` | Assert multiple selection mode | -| `assertSingle()` | Assert single selection mode | - -### Assertions - -| Method | Description | -|--------|-------------| -| `assertSelectedValue(String...)` | Assert selected values match | -| `assertEnabled()` | Assert list box is enabled | -| `assertDisabled()` | Assert list box is disabled | -| `assertItemEnabled(String item)` | Assert specific item is enabled | -| `assertItemDisabled(String item)` | Assert specific item is disabled | - -## Usage Examples - -### Single Selection - -```java -ListBoxElement list = ListBoxElement.getByLabel(page, "Country"); -list.assertSingle(); - -// Select an item -list.selectItem("France"); - -// Get selected value -String selected = list.getSingleSelectedValue(); // "France" - -// Assert selection -list.assertSelectedValue("France"); -``` - -### Multiple Selection - -```java -ListBoxElement list = ListBoxElement.getByLabel(page, "Skills"); -list.assertMultiple(); - -// Select multiple items -list.selectItem("Java"); -list.selectItem("Python"); -list.selectItem("JavaScript"); - -// Get all selected -List selected = list.getSelectedValue(); - -// Assert all selections -list.assertSelectedValue("Java", "Python", "JavaScript"); - -// Toggle off -list.selectItem("Python"); -list.assertSelectedValue("Java", "JavaScript"); -``` - -### Item State - -```java -ListBoxElement list = ListBoxElement.getByLabel(page, "Options"); - -// Check item states -list.assertItemEnabled("Option A"); -list.assertItemDisabled("Option B"); -``` - -## Related Elements - -- `SelectElement` - Dropdown select component -- `RadioButtonGroupElement` - Single selection radio group diff --git a/docs/specifications/MenuBarElement.md b/docs/specifications/MenuBarElement.md deleted file mode 100644 index c0b3ee0..0000000 --- a/docs/specifications/MenuBarElement.md +++ /dev/null @@ -1,110 +0,0 @@ -# MenuBarElement Specification - -## Overview - -`MenuBarElement` is a Playwright element wrapper for the `` web component. It provides utilities to access menu items and open submenus. - -## Tag Name - -``` -vaadin-menu-bar -``` - -## Class Hierarchy - -``` -VaadinElement - └── MenuBarElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `HasThemeElement` | Theme variants support | -| `HasStyleElement` | Style attribute support | -| `HasAriaLabelElement` | ARIA label accessibility | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-menu-bar"` | HTML tag name | - -## API Methods - -### Constructors - -```java -MenuBarElement(Page page) -``` - -Creates a `MenuBarElement` from the first menu bar on the page. - -```java -MenuBarElement(Locator locator) -``` - -Creates a `MenuBarElement` from an existing locator. - -### Static Factory Methods - -#### getByLabel(Page page, String label) - -Get a menu bar by its accessible label. - -```java -MenuBarElement menuBar = MenuBarElement.getByLabel(page, "Main Menu"); -``` - -### Menu Operations - -| Method | Description | -|--------|-------------| -| `getMenuItemElement(String name)` | Get a menu item by visible label | -| `openSubMenu(String name)` | Click item and return submenu overlay | - -## Usage Examples - -### Basic Usage - -```java -// Get menu bar -MenuBarElement menuBar = new MenuBarElement(page); - -// Or by label -MenuBarElement mainMenu = MenuBarElement.getByLabel(page, "File Menu"); - -// Get a menu item -MenuItemElement fileItem = menuBar.getMenuItemElement("File"); -fileItem.click(); -``` - -### Opening Submenus - -```java -MenuBarElement menuBar = new MenuBarElement(page); - -// Open a submenu -MenuElement fileMenu = menuBar.openSubMenu("File"); - -// Select from submenu -fileMenu.getMenuItemElement("New").click(); - -// Or open nested submenu -MenuElement recentMenu = fileMenu.openSubMenu("Recent Files"); -recentMenu.getMenuItemElement("document.txt").click(); -``` - -### Theme Variants - -```java -MenuBarElement menuBar = MenuBarElement.getByLabel(page, "Actions"); -menuBar.assertHasTheme("primary"); -``` - -## Related Elements - -- `MenuElement` - Menu overlay list -- `MenuItemElement` - Individual menu item -- `ContextMenuElement` - Right-click context menu diff --git a/docs/specifications/MenuElement.md b/docs/specifications/MenuElement.md deleted file mode 100644 index 4ec3c6c..0000000 --- a/docs/specifications/MenuElement.md +++ /dev/null @@ -1,108 +0,0 @@ -# MenuElement Specification - -## Overview - -`MenuElement` is a Playwright element wrapper for the menu overlay list ``. It represents the dropdown menu that appears when a menu bar item is clicked. - -## Tag Name - -``` -vaadin-menu-bar-list-box -``` - -## Class Hierarchy - -``` -VaadinElement - └── MenuElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `HasThemeElement` | Theme variants support | -| `HasStyleElement` | Style attribute support | -| `HasAriaLabelElement` | ARIA label accessibility | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-menu-bar-list-box"` | HTML tag name | - -## API Methods - -### Constructors - -```java -MenuElement(Page page) -``` - -Creates a `MenuElement` from the first menu list box on the page. - -```java -MenuElement(Locator locator) -``` - -Creates a `MenuElement` from an existing locator. - -### Static Factory Methods - -#### getByLabel(Page page, String label) - -Get a menu overlay by its accessible label. - -```java -MenuElement menu = MenuElement.getByLabel(page, "File Menu"); -``` - -### Menu Operations - -| Method | Description | -|--------|-------------| -| `getMenuItemElement(String name)` | Get a menu item by visible label | -| `openSubMenu(String name)` | Click item and return next submenu overlay | - -## Usage Examples - -### Basic Usage - -```java -// After opening menu bar item -MenuBarElement menuBar = new MenuBarElement(page); -MenuElement fileMenu = menuBar.openSubMenu("File"); - -// Get menu item -MenuItemElement newItem = fileMenu.getMenuItemElement("New"); -newItem.click(); -``` - -### Nested Submenus - -```java -MenuBarElement menuBar = new MenuBarElement(page); - -// Open first level -MenuElement editMenu = menuBar.openSubMenu("Edit"); - -// Open nested submenu -MenuElement formatMenu = editMenu.openSubMenu("Format"); - -// Select from nested menu -formatMenu.getMenuItemElement("Bold").click(); -``` - -### By Label - -```java -// Get menu directly by accessible name -MenuElement menu = MenuElement.getByLabel(page, "Insert Menu"); -menu.getMenuItemElement("Table").click(); -``` - -## Related Elements - -- `MenuBarElement` - Parent menu bar -- `MenuItemElement` - Individual menu item -- `ContextMenuElement` - Right-click context menu diff --git a/docs/specifications/MenuItemElement.md b/docs/specifications/MenuItemElement.md deleted file mode 100644 index 9347daa..0000000 --- a/docs/specifications/MenuItemElement.md +++ /dev/null @@ -1,109 +0,0 @@ -# MenuItemElement Specification - -## Overview - -`MenuItemElement` is a Playwright element wrapper for individual menu items ``. It represents a clickable item within a menu bar or menu overlay. - -## Tag Name - -``` -vaadin-menu-bar-button -``` - -## Class Hierarchy - -``` -VaadinElement - └── MenuItemElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `HasThemeElement` | Theme variants support | -| `HasStyleElement` | Style attribute support | -| `HasAriaLabelElement` | ARIA label accessibility | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-menu-bar-button"` | HTML tag name | - -## API Methods - -### Constructor - -```java -MenuItemElement(Locator locator) -``` - -Creates a `MenuItemElement` from an existing locator. - -### Static Factory Methods - -#### getByLabel(Locator locator, String label) - -Get a menu item by its accessible label within a scope. - -```java -MenuItemElement item = MenuItemElement.getByLabel(menuLocator, "Save"); -``` - -### State Assertions - -| Method | Description | -|--------|-------------| -| `assertExpanded()` | Assert that item shows submenu (expanded) | -| `assertCollapsed()` | Assert that item is collapsed | - -### Inherited Methods - -From `VaadinElement`: -- `click()` - Click the menu item -- `getText()` - Get the item text - -## Usage Examples - -### Basic Usage - -```java -// Get menu item within a menu bar -MenuBarElement menuBar = new MenuBarElement(page); -MenuItemElement fileItem = MenuItemElement.getByLabel(menuBar.getLocator(), "File"); - -// Click the item -fileItem.click(); -``` - -### Checking Expansion State - -```java -MenuBarElement menuBar = new MenuBarElement(page); -MenuItemElement fileItem = menuBar.getMenuItemElement("File"); - -// Initially collapsed -fileItem.assertCollapsed(); - -// Click to expand -fileItem.click(); -fileItem.assertExpanded(); -``` - -### Within Menu Overlay - -```java -MenuBarElement menuBar = new MenuBarElement(page); -MenuElement menu = menuBar.openSubMenu("Edit"); - -// Get item from overlay -MenuItemElement copyItem = menu.getMenuItemElement("Copy"); -copyItem.click(); -``` - -## Related Elements - -- `MenuBarElement` - Parent menu bar -- `MenuElement` - Menu overlay containing items -- `ButtonElement` - For standalone buttons diff --git a/docs/specifications/MessageInputElement.md b/docs/specifications/MessageInputElement.md index 75f60d8..22a303f 100644 --- a/docs/specifications/MessageInputElement.md +++ b/docs/specifications/MessageInputElement.md @@ -1,131 +1,12 @@ -# MessageInputElement Specification +# MessageInputElement -## Overview +> Full API (methods, signatures, descriptions): see [api-reference.md](../../skills/vaadin-playwright-test/api-reference.md). This note covers only behaviour that isn't obvious from the signatures. -`MessageInputElement` is a Playwright element wrapper for the `` web component. It provides access to the internal text area and send button, value manipulation, submit actions and i18n property accessors. +## The component clears the text area after submit -## Tag Name - -``` -vaadin-message-input -``` - -## Class Hierarchy - -``` -VaadinElement - └── MessageInputElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `FocusableElement` | Focus operations (delegates to the native textarea input) | -| `HasEnabledElement` | Enabled/disabled state (delegates to the native textarea input) | -| `HasStyleElement` | Style attribute support | -| `HasThemeElement` | Theme variants support | -| `HasTooltipElement` | Tooltip support | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-message-input"` | HTML tag name | - -## API Methods - -### Constructor - -```java -MessageInputElement(Locator locator) -``` - -Creates a new `MessageInputElement` from a Playwright locator. - -### Static Factory Methods - -#### get(Page page) - -Get the first `` on the page. - -```java -MessageInputElement input = MessageInputElement.get(page); -``` - -#### get(Locator locator) - -Get the first `` within a locator scope. - -```java -MessageInputElement input = MessageInputElement.get(chatLayout); -``` - -### Locator Methods - -| Method | Description | -|--------|-------------| -| `getTextAreaLocator()` | Locator for the internal `` | -| `getTextAreaInputLocator()` | Locator for the native textarea inside the text area (`slot="textarea"`) | -| `getSendButtonLocator()` | Locator for the internal send button (``) | - -### Value Methods - -| Method | Description | -|--------|-------------| -| `getValue()` | Get the current text area value | -| `setValue(String)` | Set the message text (fills the textarea and syncs the component value) | -| `clear()` | Clear the text area | - -### Action Methods - -| Method | Description | -|--------|-------------| -| `submit()` | Click the send button to submit the message | -| `submitByEnter()` | Press Enter on the text area to submit | -| `typeAndSubmit(String)` | Set a value then click the send button | - -### I18n Methods - -| Method | Description | -|--------|-------------| -| `getMessagePlaceholder()` | Get the placeholder text on the text area | -| `getSendButtonText()` | Get the send button text content | - -### Assertions - -| Method | Description | -|--------|-------------| -| `assertValue(String)` | Assert the text area input has the expected value | -| `assertSendButtonVisible()` | Assert the send button is visible | -| `assertSendButtonHidden()` | Assert the send button is hidden | -| `assertSendButtonEnabled()` | Assert the send button is enabled | -| `assertSendButtonDisabled()` | Assert the send button is disabled | -| `assertMessagePlaceholder(String)` | Assert the text area placeholder matches | -| `assertSendButtonText(String)` | Assert the send button text matches | - -## Usage Examples - -### Basic Usage +Submitting (via `submit()`, `submitByEnter()`, or `typeAndSubmit(...)`) causes the component to clear its text area, so `getValue()` / `assertValue()` return empty afterwards. `submit()` clicks the send button; `submitByEnter()` presses Enter on the text area. ```java -// Get first message input on the page -MessageInputElement input = MessageInputElement.get(page); - -// Type a message and submit by clicking send -input.typeAndSubmit("Hello!"); - -// Or set value and submit with Enter -input.setValue("Hello again!"); -input.submitByEnter(); -``` - -### Verifying Submit Behavior - -```java -MessageInputElement input = new MessageInputElement( - page.locator("#my-message-input")); - input.setValue("Test message"); input.assertValue("Test message"); input.submit(); @@ -134,44 +15,6 @@ input.submit(); input.assertValue(""); ``` -### Checking Enabled/Disabled State - -```java -MessageInputElement disabledInput = new MessageInputElement( - page.locator("#disabled-input")); -disabledInput.assertDisabled(); - -MessageInputElement enabledInput = MessageInputElement.get(page); -enabledInput.assertEnabled(); -``` - -### Custom I18n - -```java -MessageInputElement input = new MessageInputElement( - page.locator("#custom-i18n-input")); - -// Verify custom placeholder and button text -input.assertMessagePlaceholder("Type your message here..."); -input.assertSendButtonText("Submit"); -``` - -### Accessing Internal Locators - -```java -MessageInputElement input = MessageInputElement.get(page); - -// Access the internal text area -Locator textArea = input.getTextAreaLocator(); - -// Access the native textarea for low-level interaction -Locator nativeTextarea = input.getTextAreaInputLocator(); - -// Access the send button -Locator sendBtn = input.getSendButtonLocator(); -``` - -## Related Elements +## Focus/enabled delegate to the native textarea -- `TextAreaElement` - For standalone text areas -- `ButtonElement` - For standalone buttons +`FocusableElement` and `HasEnabledElement` operations delegate to the internal native textarea input, not the outer `` host. diff --git a/docs/specifications/NotificationElement.md b/docs/specifications/NotificationElement.md index cda7b41..5b49afe 100644 --- a/docs/specifications/NotificationElement.md +++ b/docs/specifications/NotificationElement.md @@ -1,129 +1,14 @@ -# NotificationElement Specification +# NotificationElement -## Overview +> Full API (methods, signatures, descriptions): see [api-reference.md](../../skills/vaadin-playwright-test/api-reference.md). This note covers only behaviour that isn't obvious from the signatures. -`NotificationElement` is a Playwright element wrapper for notification cards ``. It provides helpers to check visibility and content of toast notifications. - -## Tag Name - -``` -vaadin-notification-card -``` - -## Class Hierarchy - -``` -VaadinElement - └── NotificationElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `HasThemeElement` | Theme variants support | -| `HasStyleElement` | Style attribute support | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-notification-card"` | HTML tag name | - -## API Methods - -### Constructors - -```java -NotificationElement(Page page) -``` - -Creates a `NotificationElement` from the first notification card on the page. - -```java -NotificationElement(Locator locator) -``` - -Creates a `NotificationElement` from an existing locator. +## Constructor scopes to open cards only The constructor scopes its locator to open cards only (`vaadin-notification-card[slot]`), so closed and never-opened cards are excluded. It targets the single open notification; when several are open at once, use `getByText` to disambiguate. -### Factory Methods - -| Method | Description | -|--------|-------------| -| `getByText(Page page, String text)` | Get an open notification by (a substring of) its text | - -### State Methods - -| Method | Description | -|--------|-------------| -| `isOpen()` | Whether the notification is visible | - -### Locator Methods - -| Method | Description | -|--------|-------------| -| `getContentLocator()` | Locator for the notification content | - -### Assertions - -| Method | Description | -|--------|-------------| -| `assertOpen()` | Assert that notification is visible | -| `assertClosed()` | Assert that notification is hidden | -| `assertContent(String content)` | Assert notification contains the given text (substring) | - -## Usage Examples - -### Basic Usage - ```java -// Trigger an action that shows notification -page.locator("vaadin-button").filter( - new Locator.FilterOptions().setHasText("Save")).click(); - -// Check notification -NotificationElement notification = new NotificationElement(page); -notification.assertOpen(); -notification.assertContent("Changes saved successfully"); -``` - -### Theme Variants - -```java -NotificationElement notification = new NotificationElement(page); - -// Check for success theme -notification.assertTheme("success"); - -// Check for error theme -notification.assertTheme("error"); - -// Check for warning theme -notification.assertTheme("warning"); -``` - -### Waiting for Notification to Close - -```java -NotificationElement notification = new NotificationElement(page); -notification.assertOpen(); - -// Wait for auto-close -notification.assertClosed(); -``` - -### Multiple Notifications - -```java -// Get a specific open notification by its text +// Get a specific open notification by (a substring of) its text NotificationElement errorNotification = NotificationElement.getByText(page, "Error"); errorNotification.assertOpen(); errorNotification.assertContent("Error"); ``` - -## Related Elements - -- `DialogElement` - For modal dialogs -- `PopoverElement` - For popover overlays diff --git a/docs/specifications/NumberFieldElement.md b/docs/specifications/NumberFieldElement.md deleted file mode 100644 index f2359e3..0000000 --- a/docs/specifications/NumberFieldElement.md +++ /dev/null @@ -1,145 +0,0 @@ -# NumberFieldElement Specification - -## Overview - -`NumberFieldElement` is a Playwright element wrapper for the `` web component. It provides helpers for numeric attributes (`min`, `max`, `step`) using `Double` types and locator utilities to find the component by its accessible label. - -## Tag Name - -``` -vaadin-number-field -``` - -## Class Hierarchy - -``` -VaadinElement - └── AbstractNumberFieldElement - └── NumberFieldElement -``` - -## Inherited Interfaces - -All interfaces from `AbstractNumberFieldElement`: -- `HasValidationPropertiesElement` -- `HasInputFieldElement` -- `HasPrefixElement` -- `HasSuffixElement` -- `HasClearButtonElement` -- `HasPlaceholderElement` -- `HasAllowedCharPatternElement` -- `HasThemeElement` -- `FocusableElement` -- `HasAriaLabelElement` -- `HasEnabledElement` -- `HasTooltipElement` - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-number-field"` | HTML tag name | - -## API Methods - -### Constructor - -```java -NumberFieldElement(Locator locator) -``` - -Creates a new `NumberFieldElement` from a Playwright locator. - -### Static Factory Methods - -#### getByLabel(Page page, String label) - -Locates a number field by its label using ARIA role `spinbutton`. - -```java -NumberFieldElement price = NumberFieldElement.getByLabel(page, "Price"); -``` - -#### getByLabel(Locator locator, String label) - -Locates a number field by label within a scope. - -### Step Property - -| Method | Description | -|--------|-------------| -| `getStep()` | Get step as Double or null | -| `setStep(double step)` | Set the step value | -| `assertStep(Double step)` | Assert step value or null | - -### Min Property - -| Method | Description | -|--------|-------------| -| `getMin()` | Get minimum as Double or null | -| `setMin(double min)` | Set the minimum value | -| `assertMin(Double min)` | Assert minimum value or null | - -### Max Property - -| Method | Description | -|--------|-------------| -| `getMax()` | Get maximum as Double or null | -| `setMax(double max)` | Set the maximum value | -| `assertMax(Double max)` | Assert maximum value or null | - -## Usage Examples - -### Basic Usage - -```java -NumberFieldElement price = NumberFieldElement.getByLabel(page, "Price"); - -// Set value -price.setValue("99.99"); - -// Assert value -price.assertValue("99.99"); -``` - -### Constraints - -```java -NumberFieldElement temperature = NumberFieldElement.getByLabel(page, "Temperature"); - -// Set constraints -temperature.setMin(-40.0); -temperature.setMax(100.0); -temperature.setStep(0.5); - -// Assert constraints -temperature.assertMin(-40.0); -temperature.assertMax(100.0); -temperature.assertStep(0.5); -``` - -### Step Controls (from AbstractNumberFieldElement) - -```java -NumberFieldElement amount = NumberFieldElement.getByLabel(page, "Amount"); -amount.assertHasControls(true); - -// Use step buttons -amount.clickIncreaseButton(); -amount.clickDecreaseButton(); -``` - -### Validation - -```java -NumberFieldElement field = NumberFieldElement.getByLabel(page, "Value"); -field.assertRequired(); -field.assertInvalid(); -field.assertErrorMessage("Value is required"); -``` - -## Related Elements - -- `IntegerFieldElement` - For integer values -- `BigDecimalFieldElement` - For BigDecimal values -- `AbstractNumberFieldElement` - Base class diff --git a/docs/specifications/PasswordFieldElement.md b/docs/specifications/PasswordFieldElement.md deleted file mode 100644 index 6e81ddf..0000000 --- a/docs/specifications/PasswordFieldElement.md +++ /dev/null @@ -1,133 +0,0 @@ -# PasswordFieldElement Specification - -## Overview - -`PasswordFieldElement` is a Playwright element wrapper for the `` web component. It extends `TextFieldElement` with password-specific functionality including masked input. - -## Tag Name - -``` -vaadin-password-field -``` - -## Class Hierarchy - -``` -VaadinElement - └── TextFieldElement - └── PasswordFieldElement -``` - -## Inherited Interfaces - -All interfaces from `TextFieldElement`: -- `HasValidationPropertiesElement` -- `HasInputFieldElement` -- `HasPrefixElement` -- `HasSuffixElement` -- `HasClearButtonElement` -- `HasPlaceholderElement` -- `HasAllowedCharPatternElement` -- `HasThemeElement` -- `FocusableElement` -- `HasAriaLabelElement` -- `HasEnabledElement` -- `HasTooltipElement` - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-password-field"` | HTML tag name | - -## API Methods - -### Constructor - -```java -PasswordFieldElement(Locator locator) -``` - -Creates a new `PasswordFieldElement` from a Playwright locator. - -### Static Factory Methods - -#### getByLabel(Page page, String label) - -Locates a password field by its label. - -```java -PasswordFieldElement password = PasswordFieldElement.getByLabel(page, "Password"); -``` - -## Usage Examples - -### Basic Usage - -```java -PasswordFieldElement password = PasswordFieldElement.getByLabel(page, "Password"); - -// Set value -password.setValue("secretPassword123"); - -// Assert value -password.assertValue("secretPassword123"); - -// Clear -password.clickClearButton(); -``` - -### Validation - -```java -PasswordFieldElement password = PasswordFieldElement.getByLabel(page, "Password"); - -// Set min length -password.setMinLength(8); -password.assertMinLength(8); - -// Check validation -password.setValue("short"); -password.assertInvalid(); - -password.setValue("validPassword123"); -password.assertValid(); -``` - -### Pattern Validation - -```java -PasswordFieldElement password = PasswordFieldElement.getByLabel(page, "Password"); - -// Require at least one digit and one uppercase -password.setPattern("(?=.*\\d)(?=.*[A-Z]).+"); - -password.setValue("nodigits"); -password.assertInvalid(); - -password.setValue("Password1"); -password.assertValid(); -``` - -### Inherited Methods - -All methods from `TextFieldElement` are available: - -```java -PasswordFieldElement password = PasswordFieldElement.getByLabel(page, "Password"); - -// Focus operations -password.focus(); -password.blur(); - -// Enabled state -password.assertEnabled(); - -// Placeholder -password.assertPlaceholder("Enter your password"); -``` - -## Related Elements - -- `TextFieldElement` - Base text field -- `EmailFieldElement` - For email input diff --git a/docs/specifications/PopoverElement.md b/docs/specifications/PopoverElement.md deleted file mode 100644 index fbd508c..0000000 --- a/docs/specifications/PopoverElement.md +++ /dev/null @@ -1,129 +0,0 @@ -# PopoverElement Specification - -## Overview - -`PopoverElement` is a Playwright element wrapper for the `` web component. It provides helpers to check visibility and access content of popover overlays. - -## Tag Name - -``` -vaadin-popover -``` - -## Class Hierarchy - -``` -VaadinElement - └── PopoverElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `HasThemeElement` | Theme variants support | -| `HasStyleElement` | Style attribute support | -| `HasAriaLabelElement` | ARIA label accessibility | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-popover"` | HTML tag name | - -## API Methods - -### Constructors - -```java -PopoverElement(Page page) -``` - -Creates a `PopoverElement` by resolving the popover with ARIA dialog role. - -```java -PopoverElement(Locator locator) -``` - -Creates a `PopoverElement` from an existing locator. - -### Static Factory Methods - -#### getByLabel(Page page, String label) - -Get a popover by its accessible label. - -```java -PopoverElement popover = PopoverElement.getByLabel(page, "Help Info"); -``` - -### State Methods - -| Method | Description | -|--------|-------------| -| `isOpen()` | Whether the popover is visible | - -### Locator Methods - -| Method | Description | -|--------|-------------| -| `getContentLocator()` | Locator for the popover content | - -### Assertions - -| Method | Description | -|--------|-------------| -| `assertOpen()` | Assert that popover is open | -| `assertClosed()` | Assert that popover is hidden | - -## Usage Examples - -### Basic Usage - -```java -// Click trigger element -page.locator(".help-icon").click(); - -// Check popover -PopoverElement popover = new PopoverElement(page); -popover.assertOpen(); - -// Access content -Locator content = popover.getContentLocator(); -assertThat(content).containsText("Help information"); -``` - -### By Label - -```java -// Get specific popover by accessible name -PopoverElement helpPopover = PopoverElement.getByLabel(page, "Field Help"); -helpPopover.assertOpen(); -``` - -### Theme Variants - -```java -PopoverElement popover = new PopoverElement(page); -popover.assertHasTheme("arrow"); -``` - -### Interacting with Content - -```java -PopoverElement popover = new PopoverElement(page); -popover.assertOpen(); - -// Click a button inside the popover -Locator content = popover.getContentLocator(); -content.locator("vaadin-button").click(); - -// Popover may close after action -popover.assertClosed(); -``` - -## Related Elements - -- `DialogElement` - For modal dialogs -- `NotificationElement` - For toast notifications -- `ContextMenuElement` - For context menus diff --git a/docs/specifications/ProgressBarElement.md b/docs/specifications/ProgressBarElement.md deleted file mode 100644 index c759f55..0000000 --- a/docs/specifications/ProgressBarElement.md +++ /dev/null @@ -1,140 +0,0 @@ -# ProgressBarElement Specification - -## Overview - -`ProgressBarElement` is a Playwright element wrapper for the `` web component. It supports value/min/max setters and assertions and indeterminate state. - -## Tag Name - -``` -vaadin-progress-bar -``` - -## Class Hierarchy - -``` -VaadinElement - └── ProgressBarElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `HasThemeElement` | Theme variants support | -| `HasStyleElement` | Style attribute support | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-progress-bar"` | HTML tag name | -| `INDETERMINATE_ATTRIBUTE` | `"indeterminate"` | Indeterminate state attribute | - -## API Methods - -### Constructor - -```java -ProgressBarElement(Locator locator) -``` - -Creates a new `ProgressBarElement` from a Playwright locator. - -### Value Methods - -| Method | Description | -|--------|-------------| -| `getValue()` | Get current value from `aria-valuenow` | -| `setValue(double value)` | Set the progress value | -| `assertValue(Double expected)` | Assert value matches | - -### Min Property - -| Method | Description | -|--------|-------------| -| `getMin()` | Get minimum from `aria-valuemin` | -| `setMin(double min)` | Set the minimum value | -| `assertMin(double min)` | Assert minimum matches | - -### Max Property - -| Method | Description | -|--------|-------------| -| `getMax()` | Get maximum from `aria-valuemax` | -| `setMax(double max)` | Set the maximum value | -| `assertMax(double max)` | Assert maximum matches | - -### Indeterminate State - -| Method | Description | -|--------|-------------| -| `isIndeterminate()` | Whether bar is indeterminate | -| `setIndeterminate(boolean)` | Set indeterminate state | -| `assertIndeterminate()` | Assert indeterminate state | -| `assertNotIndeterminate()` | Assert not indeterminate | - -## Usage Examples - -### Basic Usage - -```java -ProgressBarElement progress = new ProgressBarElement( - page.locator("vaadin-progress-bar").first() -); - -// Set value -progress.setValue(0.5); - -// Get current value -double value = progress.getValue(); // 0.5 - -// Assert value -progress.assertValue(0.5); -``` - -### Min/Max Range - -```java -ProgressBarElement progress = new ProgressBarElement(locator); - -// Set range -progress.setMin(0.0); -progress.setMax(100.0); -progress.setValue(75.0); - -// Assert -progress.assertMin(0.0); -progress.assertMax(100.0); -progress.assertValue(75.0); -``` - -### Indeterminate State - -```java -ProgressBarElement loading = new ProgressBarElement( - page.locator(".loading-indicator vaadin-progress-bar") -); - -// Show loading -loading.setIndeterminate(true); -loading.assertIndeterminate(); - -// Complete loading -loading.setIndeterminate(false); -loading.setValue(1.0); -loading.assertNotIndeterminate(); -``` - -### Theme Variants - -```java -ProgressBarElement progress = new ProgressBarElement(locator); -progress.assertHasTheme("success"); -progress.assertHasTheme("error"); -progress.assertHasTheme("contrast"); -``` - -## Related Elements - -- `UploadElement` - File upload with progress diff --git a/docs/specifications/RadioButtonElement.md b/docs/specifications/RadioButtonElement.md index 83859b7..4a6fc1a 100644 --- a/docs/specifications/RadioButtonElement.md +++ b/docs/specifications/RadioButtonElement.md @@ -1,93 +1,15 @@ -# RadioButtonElement Specification +# RadioButtonElement -## Overview +> Full API (methods, signatures, descriptions): see [api-reference.md](../../skills/vaadin-playwright-test/api-reference.md). This note covers only behaviour that isn't obvious from the signatures. -`RadioButtonElement` is a Playwright element wrapper for the `` web component. It is package-private and intended for internal use by `RadioButtonGroupElement`. +## Package-private — use through RadioButtonGroupElement -## Tag Name - -``` -vaadin-radio-button -``` - -## Class Hierarchy - -``` -VaadinElement - └── RadioButtonElement (package-private) -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `FocusableElement` | Focus operations | -| `HasAriaLabelElement` | ARIA label accessibility | -| `HasEnabledElement` | Enabled/disabled state | -| `HasHelperElement` | Helper text support | -| `HasValueElement` | Value operations | -| `HasStyleElement` | Style attribute support | -| `HasLabelElement` | Label support | -| `HasValidationPropertiesElement` | Validation properties | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-radio-button"` | HTML tag name | - -## API Methods - -### Constructor - -```java -RadioButtonElement(Locator locator) -``` - -Creates a new `RadioButtonElement` from a Playwright locator. - -### Static Factory Methods (package-private) - -#### getByLabel(Locator locator, String label) - -Get a radio button by its label within a scope. - -### Checked State (package-private) - -| Method | Description | -|--------|-------------| -| `isChecked()` | Whether the radio is checked | -| `check()` | Check the radio button | -| `assertChecked()` | Assert that radio is checked | -| `assertNotChecked()` | Assert that radio is not checked | - -### Locator Methods - -| Method | Description | -|--------|-------------| -| `getEnabledLocator()` | Returns input locator | -| `getAriaLabelLocator()` | Returns input locator | -| `getFocusLocator()` | Returns input locator | - -## Usage Examples - -Radio buttons should be used through `RadioButtonGroupElement`: +`RadioButtonElement` is package-private and intended for internal use by `RadioButtonGroupElement`; its factory and checked-state methods are also package-private. Drive radio buttons through the group rather than constructing them directly. ```java RadioButtonGroupElement group = RadioButtonGroupElement.getByLabel(page, "Gender"); - -// Select by label group.selectByLabel("Male"); -// Get specific radio button RadioButtonElement maleRadio = group.getRadioButtonByLabel("Male"); maleRadio.assertChecked(); - -RadioButtonElement femaleRadio = group.getRadioButtonByLabel("Female"); -femaleRadio.assertNotChecked(); ``` - -## Related Elements - -- `RadioButtonGroupElement` - Parent group container -- `CheckboxElement` - For multiple selections diff --git a/docs/specifications/RadioButtonGroupElement.md b/docs/specifications/RadioButtonGroupElement.md deleted file mode 100644 index cbf1afc..0000000 --- a/docs/specifications/RadioButtonGroupElement.md +++ /dev/null @@ -1,138 +0,0 @@ -# RadioButtonGroupElement Specification - -## Overview - -`RadioButtonGroupElement` is a Playwright element wrapper for the `` web component. It provides helpers to select by label/value and assert selected state. - -## Tag Name - -``` -vaadin-radio-group -``` - -## Class Hierarchy - -``` -VaadinElement - └── RadioButtonGroupElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `HasLabelElement` | Label support | -| `HasEnabledElement` | Enabled/disabled state | -| `HasHelperElement` | Helper text support | -| `HasValidationPropertiesElement` | Validation properties | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-radio-group"` | HTML tag name | - -## API Methods - -### Constructor - -```java -RadioButtonGroupElement(Locator locator) -``` - -Creates a new `RadioButtonGroupElement` from a Playwright locator. - -### Static Factory Methods - -#### getByLabel(Page page, String label) - -Get a radio group by its accessible label. - -```java -RadioButtonGroupElement gender = RadioButtonGroupElement.getByLabel(page, "Gender"); -``` - -### Selection Methods - -| Method | Description | -|--------|-------------| -| `selectByLabel(String label)` | Select radio by its label text | -| `selectByValue(String value)` | Select radio by its value | -| `setValue(String value)` | Set selected value by label | -| `getRadioButtonByLabel(String label)` | Get specific radio button | - -### Assertions - -| Method | Description | -|--------|-------------| -| `assertValue(String value)` | Assert selected value by label | - -## Usage Examples - -### Basic Usage - -```java -RadioButtonGroupElement gender = RadioButtonGroupElement.getByLabel(page, "Gender"); - -// Select by label -gender.selectByLabel("Male"); - -// Assert selection -gender.assertValue("Male"); -``` - -### Select by Value - -```java -RadioButtonGroupElement priority = RadioButtonGroupElement.getByLabel(page, "Priority"); - -// Select using internal value -priority.selectByValue("high"); -``` - -### Access Individual Radio Buttons - -```java -RadioButtonGroupElement options = RadioButtonGroupElement.getByLabel(page, "Options"); - -// Get specific radio -RadioButtonElement optionA = options.getRadioButtonByLabel("Option A"); -optionA.assertChecked(); - -RadioButtonElement optionB = options.getRadioButtonByLabel("Option B"); -optionB.assertNotChecked(); - -// Check enabled state -optionA.assertEnabled(); -optionB.assertDisabled(); -``` - -### Validation - -```java -RadioButtonGroupElement required = RadioButtonGroupElement.getByLabel(page, "Selection"); - -// Assert empty (no selection) -required.assertValue(""); - -// Check validation state -required.assertRequired(); -required.assertInvalid(); - -// Make selection -required.selectByLabel("Option 1"); -required.assertValid(); -``` - -### Helper Text - -```java -RadioButtonGroupElement group = RadioButtonGroupElement.getByLabel(page, "Choose"); -group.assertHelperText("Select one option"); -``` - -## Related Elements - -- `RadioButtonElement` - Individual radio button -- `CheckboxElement` - For multiple selections -- `ListBoxElement` - Alternative single/multi selection diff --git a/docs/specifications/SelectElement.md b/docs/specifications/SelectElement.md deleted file mode 100644 index a96efef..0000000 --- a/docs/specifications/SelectElement.md +++ /dev/null @@ -1,144 +0,0 @@ -# SelectElement Specification - -## Overview - -`SelectElement` is a Playwright element wrapper for the `` web component. It provides helpers to open the overlay and pick items by visible text, along with aria/placeholder/validation mixins. - -## Tag Name - -``` -vaadin-select -``` - -## Class Hierarchy - -``` -VaadinElement - └── SelectElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `FocusableElement` | Focus operations | -| `HasAriaLabelElement` | ARIA label accessibility | -| `HasInputFieldElement` | Input field operations | -| `HasPrefixElement` | Prefix slot support | -| `HasThemeElement` | Theme variants support | -| `HasPlaceholderElement` | Placeholder text support | -| `HasEnabledElement` | Enabled/disabled state | -| `HasTooltipElement` | Tooltip support | -| `HasValidationPropertiesElement` | Validation properties | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-select"` | HTML tag name | -| `FIELD_ITEM_TAG_NAME` | `"vaadin-select-item"` | Item tag name | -| `FIELD_OVERLAY_TAG_NAME` | `"vaadin-select-list-box"` | Overlay tag name | - -## API Methods - -### Constructor - -```java -SelectElement(Locator locator) -``` - -Creates a new `SelectElement` from a Playwright locator. - -### Static Factory Methods - -#### getByLabel(Page page, String label) - -Locates a select by its label. - -```java -SelectElement country = SelectElement.getByLabel(page, "Country"); -``` - -### Selection Methods - -| Method | Description | -|--------|-------------| -| `selectItem(String item)` | Select item by visible label | -| `getValue()` | Get selected value label | - -### Locator Methods - -| Method | Description | -|--------|-------------| -| `getInputLocator()` | Returns value slot locator | -| `getAriaLabelLocator()` | Returns screen reader label | -| `getFocusLocator()` | Returns input locator | -| `getEnabledLocator()` | Returns input locator | -| `getLabelLocator()` | Returns label slot | - -### Assertions - -| Method | Description | -|--------|-------------| -| `assertValue(String expected)` | Assert selected value label | -| `assertPlaceholder(String placeholder)` | Assert placeholder text | -| `assertAriaLabel(String ariaLabel)` | Assert ARIA label | - -## Usage Examples - -### Basic Usage - -```java -SelectElement country = SelectElement.getByLabel(page, "Country"); - -// Select an item -country.selectItem("France"); - -// Get selected value -String selected = country.getValue(); // "France" - -// Assert selection -country.assertValue("France"); -``` - -### Placeholder - -```java -SelectElement category = SelectElement.getByLabel(page, "Category"); - -// Assert placeholder -category.assertPlaceholder("Select a category..."); - -// Make selection -category.selectItem("Electronics"); -category.assertValue("Electronics"); -``` - -### Validation - -```java -SelectElement required = SelectElement.getByLabel(page, "Type"); - -// Check required and invalid -required.assertRequired(); -required.assertInvalid(); - -// Make selection -required.selectItem("Premium"); -required.assertValid(); -``` - -### Enabled State - -```java -SelectElement select = SelectElement.getByLabel(page, "Options"); -select.assertEnabled(); - -// After disabling -select.assertDisabled(); -``` - -## Related Elements - -- `ListBoxElement` - List-based selection -- `RadioButtonGroupElement` - Radio-based selection diff --git a/docs/specifications/SideNavigationElement.md b/docs/specifications/SideNavigationElement.md deleted file mode 100644 index e900af7..0000000 --- a/docs/specifications/SideNavigationElement.md +++ /dev/null @@ -1,133 +0,0 @@ -# SideNavigationElement Specification - -## Overview - -`SideNavigationElement` is a Playwright element wrapper for the `` web component. It provides methods to navigate and interact with sidebar navigation menus. - -## Tag Name - -``` -vaadin-side-nav -``` - -## Class Hierarchy - -``` -VaadinElement - └── SideNavigationElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `HasLabelElement` | Label support | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-side-nav"` | HTML tag name | - -## API Methods - -### Constructor - -```java -SideNavigationElement(Locator locator) -``` - -Creates a new `SideNavigationElement` from a Playwright locator. - -### Static Factory Methods - -#### getByLabel(Page page, String label) - -Get side navigation by its accessible label. - -```java -SideNavigationElement nav = SideNavigationElement.getByLabel(page, "Main Navigation"); -``` - -### Navigation Methods - -| Method | Description | -|--------|-------------| -| `getItem(String label)` | Get navigation item by label text | -| `clickItem(String label)` | Click a navigation item | -| `toggle()` | Toggle the collapsed state via label click | - -### State Methods - -| Method | Description | -|--------|-------------| -| `isCollapsed()` | Whether the nav is collapsed | - -### Locator Methods - -| Method | Description | -|--------|-------------| -| `getLabelLocator()` | Locator for the label slot | - -### Assertions - -| Method | Description | -|--------|-------------| -| `assertCollapsed()` | Assert nav is collapsed | -| `assertExpanded()` | Assert nav is expanded | -| `assertCollapsible()` | Assert nav can be collapsed | -| `assertNotCollapsible()` | Assert nav cannot be collapsed | - -## Usage Examples - -### Basic Usage - -```java -SideNavigationElement nav = SideNavigationElement.getByLabel(page, "Main Menu"); - -// Click a navigation item -nav.clickItem("Dashboard"); - -// Get specific item -SideNavigationItemElement settings = nav.getItem("Settings"); -settings.assertCurrent(); -``` - -### Collapsed State - -```java -SideNavigationElement nav = SideNavigationElement.getByLabel(page, "Menu"); - -// Check collapsibility -nav.assertCollapsible(); - -// Expand if collapsed -if (nav.isCollapsed()) { - nav.toggle(); -} -nav.assertExpanded(); - -// Collapse -nav.toggle(); -nav.assertCollapsed(); -``` - -### Nested Navigation - -```java -SideNavigationElement nav = SideNavigationElement.getByLabel(page, "Admin"); - -// Navigate to nested item -// First expand parent -SideNavigationItemElement users = nav.getItem("Users"); -users.toggle(); // Expand -users.assertExpanded(); - -// Click nested item -nav.clickItem("User List"); -``` - -## Related Elements - -- `SideNavigationItemElement` - Individual navigation item -- `TabSheetElement` - Tab-based navigation diff --git a/docs/specifications/SideNavigationItemElement.md b/docs/specifications/SideNavigationItemElement.md deleted file mode 100644 index e37bf5e..0000000 --- a/docs/specifications/SideNavigationItemElement.md +++ /dev/null @@ -1,145 +0,0 @@ -# SideNavigationItemElement Specification - -## Overview - -`SideNavigationItemElement` is a Playwright element wrapper for the `` web component. It represents individual items within a side navigation menu. - -## Tag Name - -``` -vaadin-side-nav-item -``` - -## Class Hierarchy - -``` -VaadinElement - └── SideNavigationItemElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `HasEnabledElement` | Enabled/disabled state | -| `HasPrefixElement` | Prefix slot support | -| `HasSuffixElement` | Suffix slot support | -| `HasLabelElement` | Label support | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-side-nav-item"` | HTML tag name | - -## API Methods - -### Constructor - -```java -SideNavigationItemElement(Locator locator) -``` - -Creates a new `SideNavigationItemElement` from a Playwright locator. - -### State Methods - -| Method | Description | -|--------|-------------| -| `isExpanded()` | Whether the item is expanded (has children) | -| `toggle()` | Toggle the expansion state | -| `navigate()` | Click the link to navigate | - -### Locator Methods - -| Method | Description | -|--------|-------------| -| `getLabelLocator()` | Returns the item locator | - -### Assertions - -| Method | Description | -|--------|-------------| -| `assertExpanded()` | Assert item is expanded | -| `assertCollapsed()` | Assert item is collapsed | -| `assertEnabled()` | Assert item is enabled | -| `assertDisabled()` | Assert item is disabled | -| `assertCurrent()` | Assert item is current route | -| `assertNotCurrent()` | Assert item is not current | - -## Usage Examples - -### Basic Usage - -```java -SideNavigationElement nav = SideNavigationElement.getByLabel(page, "Menu"); -SideNavigationItemElement dashboard = nav.getItem("Dashboard"); - -// Navigate -dashboard.navigate(); - -// Check if current -dashboard.assertCurrent(); -``` - -### Expandable Items with Children - -```java -SideNavigationElement nav = SideNavigationElement.getByLabel(page, "Menu"); -SideNavigationItemElement admin = nav.getItem("Administration"); - -// Check and toggle expansion -admin.assertCollapsed(); -admin.toggle(); -admin.assertExpanded(); - -// Navigate to child (now visible) -SideNavigationItemElement users = nav.getItem("Users"); -users.navigate(); -``` - -### Disabled Items - -```java -SideNavigationElement nav = SideNavigationElement.getByLabel(page, "Menu"); -SideNavigationItemElement restricted = nav.getItem("Restricted Area"); - -// Check disabled state -restricted.assertDisabled(); -``` - -### Current Route - -```java -SideNavigationElement nav = SideNavigationElement.getByLabel(page, "Menu"); - -// Navigate to dashboard -SideNavigationItemElement dashboard = nav.getItem("Dashboard"); -dashboard.navigate(); -dashboard.assertCurrent(); - -// Navigate to settings -SideNavigationItemElement settings = nav.getItem("Settings"); -settings.navigate(); -settings.assertCurrent(); -dashboard.assertNotCurrent(); -``` - -### Prefix/Suffix Icons - -```java -SideNavigationItemElement item = nav.getItem("Settings"); - -// Access prefix (icon) -Locator prefix = item.getPrefixLocator(); -assertThat(prefix).isVisible(); - -// Access suffix (badge) -Locator suffix = item.getSuffixLocator(); -assertThat(suffix).hasText("3"); -``` - -## Related Elements - -- `SideNavigationElement` - Parent navigation container -- `TabElement` - For tab-based navigation diff --git a/docs/specifications/TabElement.md b/docs/specifications/TabElement.md deleted file mode 100644 index d0af37d..0000000 --- a/docs/specifications/TabElement.md +++ /dev/null @@ -1,128 +0,0 @@ -# TabElement Specification - -## Overview - -`TabElement` is a Playwright element wrapper for tabs ``. It represents individual tab buttons within a tab container. - -## Tag Name - -``` -vaadin-tab -``` - -## Class Hierarchy - -``` -VaadinElement - └── TabElement -``` - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-tab"` | HTML tag name | -| `FIELD_PARENT_TAG_NAME` | `"vaadin-tabs"` | Parent tabs container | - -## API Methods - -### Constructor - -```java -TabElement(Locator locator) -``` - -Creates a new `TabElement` from a Playwright locator. - -### Static Factory Methods - -#### getTabByText(Locator locator, String summary) - -Get a tab by visible text within a scope. - -```java -TabElement tab = TabElement.getTabByText(containerLocator, "Details"); -``` - -#### getSelectedTab(Locator locator) - -Get the currently selected tab within a scope. - -```java -TabElement selected = TabElement.getSelectedTab(containerLocator); -``` - -### State Methods - -| Method | Description | -|--------|-------------| -| `isSelected()` | Whether the tab is selected | -| `select()` | Select the tab by clicking | -| `getLabel()` | Get the tab label text | - -### Assertions - -| Method | Description | -|--------|-------------| -| `assertSelected()` | Assert that tab is selected | -| `assertNotSelected()` | Assert that tab is not selected | - -## Usage Examples - -### Basic Usage - -```java -// Get tab by text -TabElement detailsTab = TabElement.getTabByText(page.locator("body"), "Details"); - -// Select the tab -detailsTab.select(); - -// Assert selection -detailsTab.assertSelected(); -``` - -### Through TabSheetElement - -```java -TabSheetElement tabSheet = TabSheetElement.get(page); - -// Get tab by label -TabElement overview = tabSheet.getTab("Overview"); -overview.assertSelected(); - -// Get currently selected tab -TabElement current = tabSheet.getSelectedTab(); -String label = current.getLabel(); // "Overview" -``` - -### Multiple Tabs - -```java -TabSheetElement tabSheet = TabSheetElement.get(page); - -// Initial state -TabElement tab1 = tabSheet.getTab("Tab 1"); -TabElement tab2 = tabSheet.getTab("Tab 2"); - -tab1.assertSelected(); -tab2.assertNotSelected(); - -// Switch tabs -tab2.select(); -tab2.assertSelected(); -tab1.assertNotSelected(); -``` - -### Get Tab Label - -```java -TabElement selected = TabElement.getSelectedTab(page.locator("body")); -String currentLabel = selected.getLabel(); -System.out.println("Current tab: " + currentLabel); -``` - -## Related Elements - -- `TabSheetElement` - Parent tab sheet container -- `SideNavigationItemElement` - For side navigation diff --git a/docs/specifications/TabSheetElement.md b/docs/specifications/TabSheetElement.md deleted file mode 100644 index b16187a..0000000 --- a/docs/specifications/TabSheetElement.md +++ /dev/null @@ -1,137 +0,0 @@ -# TabSheetElement Specification - -## Overview - -`TabSheetElement` is a Playwright element wrapper for the `` web component. It provides helpers to access/select tabs and current content panel. - -## Tag Name - -``` -vaadin-tabsheet -``` - -## Class Hierarchy - -``` -VaadinElement - └── TabSheetElement -``` - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-tabsheet"` | HTML tag name | - -## API Methods - -### Constructor - -```java -TabSheetElement(Locator locator) -``` - -Creates a new `TabSheetElement` from a Playwright locator. - -### Static Factory Methods - -#### get(Page page) - -Get the first tabsheet instance on the page. - -```java -TabSheetElement tabSheet = TabSheetElement.get(page); -``` - -### Tab Methods - -| Method | Description | -|--------|-------------| -| `getTab(String label)` | Get a tab by its label | -| `getSelectedTab()` | Get the currently selected tab | -| `selectTab(String label)` | Select a tab by label text | - -### Content Methods - -| Method | Description | -|--------|-------------| -| `getContentLocator()` | Locator for visible content panel | - -### Assertions - -| Method | Description | -|--------|-------------| -| `assertTabsCount(int count)` | Assert the number of tabs | - -## Usage Examples - -### Basic Usage - -```java -TabSheetElement tabSheet = TabSheetElement.get(page); - -// Assert tab count -tabSheet.assertTabsCount(3); - -// Select a tab -tabSheet.selectTab("Settings"); - -// Get selected tab -TabElement selected = tabSheet.getSelectedTab(); -selected.assertSelected(); -``` - -### Accessing Tab Content - -```java -TabSheetElement tabSheet = TabSheetElement.get(page); - -// Select tab -tabSheet.selectTab("Profile"); - -// Access content area -Locator content = tabSheet.getContentLocator(); -content.locator("input[name='email']").fill("user@example.com"); -``` - -### Working with Individual Tabs - -```java -TabSheetElement tabSheet = TabSheetElement.get(page); - -// Get specific tab -TabElement profileTab = tabSheet.getTab("Profile"); -TabElement settingsTab = tabSheet.getTab("Settings"); - -// Check states -profileTab.assertSelected(); -settingsTab.assertNotSelected(); - -// Switch -settingsTab.select(); -settingsTab.assertSelected(); -profileTab.assertNotSelected(); -``` - -### Tab Navigation Flow - -```java -TabSheetElement wizard = TabSheetElement.get(page); - -// Step 1 -wizard.selectTab("Step 1"); -Locator content = wizard.getContentLocator(); -content.locator("input").fill("value"); - -// Next step -wizard.selectTab("Step 2"); -// ... continue - -// Assert final tab -wizard.getSelectedTab().assertSelected(); -``` - -## Related Elements - -- `TabElement` - Individual tab -- `AccordionElement` - For accordion-style content diff --git a/docs/specifications/TextAreaElement.md b/docs/specifications/TextAreaElement.md index dff125d..1a5d107 100644 --- a/docs/specifications/TextAreaElement.md +++ b/docs/specifications/TextAreaElement.md @@ -1,156 +1,13 @@ -# TextAreaElement Specification +# TextAreaElement -## Overview +> Full API (methods, signatures, descriptions): see [api-reference.md](../../skills/vaadin-playwright-test/api-reference.md). This note covers only behaviour that isn't obvious from the signatures. -`TextAreaElement` is a Playwright element wrapper for the `` web component. It extends `TextFieldElement` with a textarea input slot and label-based lookup. +## Input locator points at the textarea slot -## Tag Name - -``` -vaadin-text-area -``` - -## Class Hierarchy - -``` -VaadinElement - └── TextFieldElement - └── TextAreaElement -``` - -## Inherited Interfaces - -All interfaces from `TextFieldElement`: -- `HasValidationPropertiesElement` -- `HasInputFieldElement` -- `HasPrefixElement` -- `HasSuffixElement` -- `HasClearButtonElement` -- `HasPlaceholderElement` -- `HasAllowedCharPatternElement` -- `HasThemeElement` -- `FocusableElement` -- `HasAriaLabelElement` -- `HasEnabledElement` -- `HasTooltipElement` - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-text-area"` | HTML tag name | - -## API Methods - -### Constructor - -```java -TextAreaElement(Locator locator) -``` - -Creates a new `TextAreaElement` from a Playwright locator. - -### Static Factory Methods - -#### getByLabel(Page page, String label) - -Locates a text area by its label. - -```java -TextAreaElement description = TextAreaElement.getByLabel(page, "Description"); -``` - -### Overridden Methods - -#### getInputLocator() - -Returns the textarea slot locator instead of input. +`TextAreaElement` extends `TextFieldElement` but overrides `getInputLocator()` to return the `slot="textarea"` element instead of a plain `input`, so all inherited value/field operations target the multi-line textarea. ```java public Locator getInputLocator() { return getLocator().locator("*[slot=\"textarea\"]").first(); } ``` - -## Usage Examples - -### Basic Usage - -```java -TextAreaElement description = TextAreaElement.getByLabel(page, "Description"); - -// Set value -description.setValue("This is a multi-line\ntext description."); - -// Assert value -description.assertValue("This is a multi-line\ntext description."); - -// Clear -description.clickClearButton(); -``` - -### Length Constraints - -```java -TextAreaElement notes = TextAreaElement.getByLabel(page, "Notes"); - -// Set constraints -notes.setMinLength(10); -notes.setMaxLength(500); - -// Assert constraints -notes.assertMinLength(10); -notes.assertMaxLength(500); -``` - -### Validation - -```java -TextAreaElement comments = TextAreaElement.getByLabel(page, "Comments"); - -// Check required -comments.assertRequired(); -comments.assertInvalid(); - -// Fill and validate -comments.setValue("My comment"); -comments.assertValid(); -``` - -### Focus and State - -```java -TextAreaElement feedback = TextAreaElement.getByLabel(page, "Feedback"); - -// Focus -feedback.focus(); - -// Enabled state -feedback.assertEnabled(); - -// Placeholder -feedback.assertPlaceholder("Enter your feedback..."); -``` - -### Inherited Methods - -All methods from `TextFieldElement` are available: - -```java -TextAreaElement bio = TextAreaElement.getByLabel(page, "Biography"); - -// Pattern validation -bio.setPattern("[A-Za-z\\s]+"); - -// ARIA label -bio.assertAriaLabel("Biography"); - -// Tooltip -bio.assertTooltip("Tell us about yourself"); -``` - -## Related Elements - -- `TextFieldElement` - Single-line text input -- `EmailFieldElement` - For email input -- `PasswordFieldElement` - For password input diff --git a/docs/specifications/TextFieldElement.md b/docs/specifications/TextFieldElement.md deleted file mode 100644 index 00be6c2..0000000 --- a/docs/specifications/TextFieldElement.md +++ /dev/null @@ -1,157 +0,0 @@ -# TextFieldElement Specification - -## Overview - -`TextFieldElement` is a Playwright element wrapper for the `` web component. It provides a comprehensive API for interacting with and testing Vaadin text field components. - -## Tag Name - -``` -vaadin-text-field -``` - -## Class Hierarchy - -``` -VaadinElement - └── TextFieldElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `HasValidationPropertiesElement` | Validation properties support | -| `HasInputFieldElement` | Input field operations | -| `HasPrefixElement` | Prefix slot support | -| `HasSuffixElement` | Suffix slot support | -| `HasClearButtonElement` | Clear button functionality | -| `HasPlaceholderElement` | Placeholder text support | -| `HasAllowedCharPatternElement` | Character pattern restrictions | -| `HasThemeElement` | Theme variants support | -| `FocusableElement` | Focus operations | -| `HasAriaLabelElement` | ARIA label accessibility | -| `HasEnabledElement` | Enabled/disabled state | -| `HasTooltipElement` | Tooltip support | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-text-field"` | HTML tag name | -| `MAXLENGTH_ATTRIBUTE` | `"maxlength"` | Maximum length attribute | -| `PATTERN_ATTRIBUTE` | `"pattern"` | Validation pattern attribute | -| `MIN_LENGTH_ATTRIBUTE` | `"minLength"` | Minimum length attribute | - -## API Methods - -### Constructor - -```java -TextFieldElement(Locator locator) -``` - -Creates a new `TextFieldElement` from a Playwright locator. - -### Static Factory Methods - -#### getByLabel(Page page, String label) - -Locates a text field by its label on a page. - -```java -TextFieldElement field = TextFieldElement.getByLabel(page, "Username"); -``` - -#### getByLabel(Locator locator, String label) - -Locates a text field by its label within a specific locator context. - -```java -TextFieldElement field = TextFieldElement.getByLabel(formLocator, "Email"); -``` - -### Property Methods - -#### Minimum Length - -| Method | Description | -|--------|-------------| -| `getMinLength()` | Returns the minimum length or `null` if not set | -| `setMinLength(int min)` | Sets the minimum length | -| `assertMinLength(Integer min)` | Asserts the minimum length value | - -#### Maximum Length - -| Method | Description | -|--------|-------------| -| `getMaxLength()` | Returns the maximum length or `null` if not set | -| `setMaxLength(int max)` | Sets the maximum length | -| `assertMaxLength(Integer max)` | Asserts the maximum length value | - -#### Pattern - -| Method | Description | -|--------|-------------| -| `getPattern()` | Returns the validation pattern or `null` if not set | -| `setPattern(String pattern)` | Sets the validation pattern | -| `assertPattern(String pattern)` | Asserts the pattern value | - -### Locator Methods - -| Method | Description | -|--------|-------------| -| `getFocusLocator()` | Returns the locator for focus operations | -| `getAriaLabelLocator()` | Returns the locator for ARIA label | -| `getEnabledLocator()` | Returns the locator for enabled state | - -## Usage Examples - -### Basic Usage - -```java -// Get text field by label -TextFieldElement username = TextFieldElement.getByLabel(page, "Username"); - -// Set value (inherited from HasInputFieldElement) -username.setValue("john.doe"); - -// Assert value -username.assertValue("john.doe"); -``` - -### Validation - -```java -TextFieldElement email = TextFieldElement.getByLabel(page, "Email"); - -// Set validation constraints -email.setMinLength(5); -email.setMaxLength(50); -email.setPattern("[a-z]+@[a-z]+\\.[a-z]+"); - -// Assert constraints -email.assertMinLength(5); -email.assertMaxLength(50); -email.assertPattern("[a-z]+@[a-z]+\\.[a-z]+"); -``` - -### Focus and State - -```java -TextFieldElement field = TextFieldElement.getByLabel(page, "Name"); - -// Focus the field -field.focus(); - -// Check enabled state -field.assertEnabled(); -field.assertDisabled(); -``` - -## Related Elements - -- `EmailFieldElement` - Specialized for email input -- `PasswordFieldElement` - Specialized for password input -- `TextAreaElement` - Multi-line text input -- `NumberFieldElement` - Numeric input diff --git a/docs/specifications/TimePickerElement.md b/docs/specifications/TimePickerElement.md index 7cef237..0f991fa 100644 --- a/docs/specifications/TimePickerElement.md +++ b/docs/specifications/TimePickerElement.md @@ -1,145 +1,16 @@ -# TimePickerElement Specification +# TimePickerElement -## Overview +> Full API (methods, signatures, descriptions): see [api-reference.md](../../skills/vaadin-playwright-test/api-reference.md). This note covers only behaviour that isn't obvious from the signatures. -`TimePickerElement` is a Playwright element wrapper for the `` web component. It adds convenience methods for `LocalTime` values and lookup by label. +## String values use HH:mm, LocalTime is set directly -## Tag Name +`setValue(String)` (inherited from `HasInputFieldElement`) / `assertValue(String)` expect the `HH:mm` display format (e.g. `"09:00"`), while `setValue(LocalTime)` sets the value directly. Pick the overload matching your format. -``` -vaadin-time-picker -``` - -## Class Hierarchy - -``` -VaadinElement - └── TimePickerElement -``` - -## Implemented Interfaces +## Asserting a cleared value -| Interface | Description | -|-----------|-------------| -| `HasInputFieldElement` | Input field operations | -| `HasValidationPropertiesElement` | Validation properties | -| `HasClearButtonElement` | Clear button functionality | -| `HasPlaceholderElement` | Placeholder text support | -| `HasThemeElement` | Theme variants support | -| `FocusableElement` | Focus operations | -| `HasAriaLabelElement` | ARIA label accessibility | -| `HasEnabledElement` | Enabled/disabled state | -| `HasTooltipElement` | Tooltip support | -| `HasLabelElement` | Label support | -| `HasHelperElement` | Helper text support | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-time-picker"` | HTML tag name | -| `LOCAL_TIME` | DateTimeFormatter | HH:mm format | - -## API Methods - -### Constructor +After clearing, assert emptiness with the `LocalTime` overload passing an explicit null cast: ```java -TimePickerElement(Locator locator) -``` - -Creates a new `TimePickerElement` from a Playwright locator. - -### Static Factory Methods - -#### getByLabel(Page page, String label) - -Locates a time picker by its label. - -```java -TimePickerElement time = TimePickerElement.getByLabel(page, "Start Time"); -``` - -#### getByLabel(Locator locator, String label) - -Locates a time picker by label within a scope. - -### Value Methods - -| Method | Description | -|--------|-------------| -| `setValue(LocalTime time)` | Set value using LocalTime (HH:mm format) | -| `getValueAsLocalTime()` | Get value as LocalTime or null | - -### Assertions - -| Method | Description | -|--------|-------------| -| `assertValue(LocalTime value)` | Assert value as LocalTime | - -### Locator Methods - -| Method | Description | -|--------|-------------| -| `getAriaLabelLocator()` | Returns input locator | -| `getFocusLocator()` | Returns input locator | -| `getEnabledLocator()` | Returns input locator | - -## Usage Examples - -### Basic Usage - -```java -TimePickerElement startTime = TimePickerElement.getByLabel(page, "Start Time"); - -// Set value with LocalTime -startTime.setValue(LocalTime.of(14, 30)); - -// Get value -LocalTime time = startTime.getValueAsLocalTime(); // 14:30 - -// Assert value -startTime.assertValue(LocalTime.of(14, 30)); -``` - -### String Format - -```java -TimePickerElement time = TimePickerElement.getByLabel(page, "Meeting Time"); - -// Set using string (inherited from HasInputFieldElement) -time.setValue("09:00"); -time.assertValue("09:00"); -``` - -### Clear and Validation - -```java -TimePickerElement time = TimePickerElement.getByLabel(page, "Time"); - -// Clear time.clickClearButton(); time.assertValue((LocalTime) null); - -// Validation -time.assertRequired(); -time.assertInvalid(); - -time.setValue(LocalTime.of(10, 0)); -time.assertValid(); ``` - -### Enabled State - -```java -TimePickerElement time = TimePickerElement.getByLabel(page, "Closing Time"); -time.assertEnabled(); - -// After disabling -time.assertDisabled(); -``` - -## Related Elements - -- `DatePickerElement` - For date selection -- `DateTimePickerElement` - Combined date and time picker diff --git a/docs/specifications/TreeGridElement.md b/docs/specifications/TreeGridElement.md index 3f04329..34c5b1b 100644 --- a/docs/specifications/TreeGridElement.md +++ b/docs/specifications/TreeGridElement.md @@ -1,5 +1,9 @@ # TreeGridElement Specification +> For the authoritative method list and signatures, see the auto-generated +> [api-reference.md](../../skills/vaadin-playwright-test/api-reference.md). This +> file focuses on behaviour and usage that signatures alone don't convey. + ## Overview `TreeGridElement` is a Playwright element wrapper for `` backed by a Vaadin `TreeGrid`. It extends `GridElement` with tree-specific APIs for querying hierarchy levels, checking expanded/collapsed/leaf state, and performing single-row or level-based bulk expand and collapse operations. diff --git a/docs/specifications/UploadElement.md b/docs/specifications/UploadElement.md index 4c1d3df..2c845ba 100644 --- a/docs/specifications/UploadElement.md +++ b/docs/specifications/UploadElement.md @@ -1,159 +1,16 @@ -# UploadElement Specification +# UploadElement -## Overview +> Full API (methods, signatures, descriptions): see [api-reference.md](../../skills/vaadin-playwright-test/api-reference.md). This note covers only behaviour that isn't obvious from the signatures. -`UploadElement` is a Playwright element wrapper for the `` web component. It provides helpers to feed files via the native file input, inspect the file list entries, and assert upload completion using the file row state. +## Files are fed through the hidden native file input -## Tag Name - -``` -vaadin-upload -``` - -## Class Hierarchy - -``` -VaadinElement - └── UploadElement -``` - -## Implemented Interfaces - -| Interface | Description | -|-----------|-------------| -| `HasEnabledElement` | Enabled/disabled state | -| `HasValidationPropertiesElement` | Validation properties | -| `HasThemeElement` | Theme variants support | -| `FocusableElement` | Focus operations | - -## Constants - -| Constant | Value | Description | -|----------|-------|-------------| -| `FIELD_TAG_NAME` | `"vaadin-upload"` | HTML tag name | -| `FILE_ITEM_TAG_NAME` | `"vaadin-upload-file"` | File row tag name | - -## API Methods - -### Constructor - -```java -UploadElement(Locator locator) -``` - -Creates a new `UploadElement` from a Playwright locator. - -### Static Factory Methods - -#### getByButtonText(Page page, String buttonText) - -Get upload component by the text of its upload button. - -```java -UploadElement upload = UploadElement.getByButtonText(page, "Upload Files"); -``` - -### File Operations - -| Method | Description | -|--------|-------------| -| `uploadFiles(Path... files)` | Upload files via hidden input | -| `removeFile(String fileName)` | Remove file using remove button | - -### Locator Methods - -| Method | Description | -|--------|-------------| -| `getFileInputLocator()` | Locator for native file input | -| `getUploadButtonLocator()` | Locator for upload button | -| `getFileItemLocator(String fileName)` | Locator for file row | -| `getFileStatusLocator(String fileName)` | Locator for file status | -| `getFocusLocator()` | Returns upload button locator | -| `getEnabledLocator()` | Returns upload button locator | - -### Assertions - -| Method | Description | -|--------|-------------| -| `assertHasFile(String fileName)` | Assert file is in list | -| `assertNoFile(String fileName)` | Assert file is not in list | -| `assertFileComplete(String fileName)` | Assert file upload complete | -| `assertMaxFilesReached()` | Assert max files limit reached | - -## Usage Examples - -### Basic Upload +`uploadFiles(Path...)` feeds files via the component's hidden native `` (Playwright `setInputFiles`), not by clicking the upload button. Upload completion is asserted from the file row's state, so wait for it after adding a file rather than assuming the upload is instant. ```java -UploadElement upload = UploadElement.getByButtonText(page, "Upload"); - -// Upload a file Path testFile = Path.of("/path/to/test.pdf"); upload.uploadFiles(testFile); -// Assert file appears upload.assertHasFile("test.pdf"); - -// Wait for completion +// Wait for the row to report completion upload.assertFileComplete("test.pdf"); ``` - -### Multiple Files - -```java -UploadElement upload = UploadElement.getByButtonText(page, "Upload Documents"); - -// Upload multiple files -upload.uploadFiles( - Path.of("/path/to/file1.pdf"), - Path.of("/path/to/file2.pdf"), - Path.of("/path/to/file3.pdf") -); - -// Assert all files -upload.assertHasFile("file1.pdf"); -upload.assertHasFile("file2.pdf"); -upload.assertHasFile("file3.pdf"); -``` - -### Remove File - -```java -UploadElement upload = UploadElement.getByButtonText(page, "Attachments"); - -// Upload file -upload.uploadFiles(Path.of("/path/to/document.pdf")); -upload.assertHasFile("document.pdf"); - -// Remove file -upload.removeFile("document.pdf"); -upload.assertNoFile("document.pdf"); -``` - -### Max Files - -```java -UploadElement upload = UploadElement.getByButtonText(page, "Images"); - -// Upload to max limit -upload.uploadFiles(Path.of("/path/to/image1.png")); -upload.uploadFiles(Path.of("/path/to/image2.png")); - -// Assert max reached -upload.assertMaxFilesReached(); -``` - -### File Status - -```java -UploadElement upload = UploadElement.getByButtonText(page, "Upload"); -upload.uploadFiles(Path.of("/path/to/file.pdf")); - -// Access status locator -Locator status = upload.getFileStatusLocator("file.pdf"); -assertThat(status).containsText("100%"); -``` - -## Related Elements - -- `ProgressBarElement` - For general progress display diff --git a/docs/specifications/VaadinElement.md b/docs/specifications/VaadinElement.md index 7426d06..ecfcdc1 100644 --- a/docs/specifications/VaadinElement.md +++ b/docs/specifications/VaadinElement.md @@ -1,5 +1,9 @@ # VaadinElement Specification +> For the authoritative method list and signatures, see the auto-generated +> [api-reference.md](../../skills/vaadin-playwright-test/api-reference.md). This +> file focuses on behaviour and usage that signatures alone don't convey. + ## Overview `VaadinElement` is the abstract base class for all typed Playwright wrappers around Vaadin components. It exposes common helpers such as clicking, visibility assertions, text retrieval and generic DOM property access. Concrete components add component-specific APIs on top of this. diff --git a/docs/specifications/VirtualListElement.md b/docs/specifications/VirtualListElement.md index 13f0c01..968d099 100644 --- a/docs/specifications/VirtualListElement.md +++ b/docs/specifications/VirtualListElement.md @@ -1,5 +1,9 @@ # VirtualListElement Specification +> For the authoritative method list and signatures, see the auto-generated +> [api-reference.md](../../skills/vaadin-playwright-test/api-reference.md). This +> file focuses on behaviour and usage that signatures alone don't convey. + ## Overview `VirtualListElement` is a Playwright element wrapper for the `` web component. It wraps a virtualized scrollable list that lazily renders items as the user scrolls. It provides helpers for scrolling, querying visible rows, accessing rendered item content, and retrieving typed component elements inside items. diff --git a/llms.txt b/llms.txt index 2627a3e..470f694 100644 --- a/llms.txt +++ b/llms.txt @@ -17,6 +17,17 @@ 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 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](AGENTS.md) - Repository guidelines, coding conventions, pitfalls & patterns @@ -25,42 +36,24 @@ submit.click(); ## Element Specifications -Detailed API documentation for each element wrapper: - -- [VaadinElement](docs/specifications/VaadinElement.md) - Base class for all elements -- [TextFieldElement](docs/specifications/TextFieldElement.md) - Text input -- [TextAreaElement](docs/specifications/TextAreaElement.md) - Multi-line text -- [EmailFieldElement](docs/specifications/EmailFieldElement.md) - Email input -- [PasswordFieldElement](docs/specifications/PasswordFieldElement.md) - Password input -- [NumberFieldElement](docs/specifications/NumberFieldElement.md) - Decimal numbers -- [IntegerFieldElement](docs/specifications/IntegerFieldElement.md) - Integer numbers -- [BigDecimalFieldElement](docs/specifications/BigDecimalFieldElement.md) - BigDecimal numbers -- [DatePickerElement](docs/specifications/DatePickerElement.md) - Date selection -- [TimePickerElement](docs/specifications/TimePickerElement.md) - Time selection -- [DateTimePickerElement](docs/specifications/DateTimePickerElement.md) - Date and time -- [CheckboxElement](docs/specifications/CheckboxElement.md) - Checkbox input -- [RadioButtonGroupElement](docs/specifications/RadioButtonGroupElement.md) - Radio group -- [SelectElement](docs/specifications/SelectElement.md) - Dropdown select -- [ListBoxElement](docs/specifications/ListBoxElement.md) - List selection -- [ButtonElement](docs/specifications/ButtonElement.md) - Buttons -- [DialogElement](docs/specifications/DialogElement.md) - Modal dialogs -- [NotificationElement](docs/specifications/NotificationElement.md) - Toast notifications -- [PopoverElement](docs/specifications/PopoverElement.md) - Popover overlays -- [AccordionElement](docs/specifications/AccordionElement.md) - Accordion container -- [AccordionPanelElement](docs/specifications/AccordionPanelElement.md) - Accordion panel -- [DetailsElement](docs/specifications/DetailsElement.md) - Collapsible details -- [TabSheetElement](docs/specifications/TabSheetElement.md) - Tab container -- [TabElement](docs/specifications/TabElement.md) - Individual tab -- [CardElement](docs/specifications/CardElement.md) - Card layout -- [MenuBarElement](docs/specifications/MenuBarElement.md) - Menu bar -- [MenuElement](docs/specifications/MenuElement.md) - Menu overlay -- [MenuItemElement](docs/specifications/MenuItemElement.md) - Menu item -- [ContextMenuElement](docs/specifications/ContextMenuElement.md) - Context menu -- [SideNavigationElement](docs/specifications/SideNavigationElement.md) - Side navigation -- [SideNavigationItemElement](docs/specifications/SideNavigationItemElement.md) - Navigation item -- [UploadElement](docs/specifications/UploadElement.md) - File upload -- [ProgressBarElement](docs/specifications/ProgressBarElement.md) - Progress indicator -- [AbstractNumberFieldElement](docs/specifications/AbstractNumberFieldElement.md) - Number field base +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 +- [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 +- [MessageInputElement](docs/specifications/MessageInputElement.md) - Submit behaviour +- [NotificationElement](docs/specifications/NotificationElement.md) - Open-card scoping +- [RadioButtonElement](docs/specifications/RadioButtonElement.md) - Internal use via group +- [TextAreaElement](docs/specifications/TextAreaElement.md) - Input-locator override +- [UploadElement](docs/specifications/UploadElement.md) - Hidden-file-input pattern ## Key Patterns diff --git a/skills/vaadin-playwright-test/SKILL.md b/skills/vaadin-playwright-test/SKILL.md index 2f44813..5593080 100644 --- a/skills/vaadin-playwright-test/SKILL.md +++ b/skills/vaadin-playwright-test/SKILL.md @@ -78,8 +78,20 @@ Read the target view source provided by the user. Extract: - Navigation triggers → button labels or menu items that cause route changes. See [element-mapping.md](element-mapping.md) for the full component → element -class table. Each element also has detailed documentation with examples in -the [specifications folder](https://github.com/parttio/dramafinder/tree/master/docs/specifications). +class table, and [api-reference.md](api-reference.md) for the **complete public +API** (every element, its methods, signatures and one-line descriptions) of the +version you have installed. + +> **Never download or unzip the DramaFinder jar/sources to discover its API.** +> The complete, always-current signature reference is bundled beside this skill +> in [api-reference.md](api-reference.md) (auto-generated from source). If a +> method isn't there, it doesn't exist in this version — do not guess or dig +> into the jar. The few components with non-obvious behaviour also have prose +> docs in the [specifications folder](https://github.com/parttio/dramafinder/tree/master/docs/specifications). +> +> To look up an element, **grep `api-reference.md` for the element name and read +> only that section** (each is a `### Element` heading) — don't read the +> whole file. Shared mixin methods are documented once under "Shared mixins". Before writing any raw locator, confirm there is genuinely no wrapper: check [element-mapping.md](element-mapping.md) **and** scan `src/main/java` for diff --git a/skills/vaadin-playwright-test/api-reference.md b/skills/vaadin-playwright-test/api-reference.md new file mode 100644 index 0000000..e4ff833 --- /dev/null +++ b/skills/vaadin-playwright-test/api-reference.md @@ -0,0 +1,1531 @@ +# DramaFinder API Reference + +> **Auto-generated from source — do not edit by hand.** Regenerate with `jbang tools/generate-api-reference.java`. +> DramaFinder 1.1.3-SNAPSHOT — 42 element wrappers. + +Complete public API of every DramaFinder element wrapper. Each element lists the shared mixin interfaces it implements; those interfaces' methods are documented once under **Shared mixins** at the end (not repeated per element). Method one-liners come from Javadoc. + +**Do not download or unzip the DramaFinder jar to discover its API — it is all here.** + +## Elements + +[AbstractNumberFieldElement](#abstractnumberfieldelement) · [AccordionElement](#accordionelement) · [AccordionPanelElement](#accordionpanelelement) · [AvatarElement](#avatarelement) · [BigDecimalFieldElement](#bigdecimalfieldelement) · [ButtonElement](#buttonelement) · [CardElement](#cardelement) · [CheckboxElement](#checkboxelement) · [ComboBoxElement](#comboboxelement) · [ContextMenuElement](#contextmenuelement) · [DatePickerElement](#datepickerelement) · [DateTimePickerElement](#datetimepickerelement) · [DetailsElement](#detailselement) · [DialogElement](#dialogelement) · [EmailFieldElement](#emailfieldelement) · [GridElement](#gridelement) · [IntegerFieldElement](#integerfieldelement) · [ListBoxElement](#listboxelement) · [MenuBarElement](#menubarelement) · [MenuElement](#menuelement) · [MenuItemElement](#menuitemelement) · [MessageInputElement](#messageinputelement) · [MessageListElement](#messagelistelement) · [MultiSelectComboBoxElement](#multiselectcomboboxelement) · [NotificationElement](#notificationelement) · [NumberFieldElement](#numberfieldelement) · [PasswordFieldElement](#passwordfieldelement) · [PopoverElement](#popoverelement) · [ProgressBarElement](#progressbarelement) · [RadioButtonGroupElement](#radiobuttongroupelement) · [SelectElement](#selectelement) · [SideNavigationElement](#sidenavigationelement) · [SideNavigationItemElement](#sidenavigationitemelement) · [SplitLayoutElement](#splitlayoutelement) · [TabElement](#tabelement) · [TabSheetElement](#tabsheetelement) · [TextAreaElement](#textareaelement) · [TextFieldElement](#textfieldelement) · [TimePickerElement](#timepickerelement) · [TreeGridElement](#treegridelement) · [UploadElement](#uploadelement) · [VirtualListElement](#virtuallistelement) + +### AbstractNumberFieldElement + +Base abstraction for Vaadin number-like fields. + +*abstract* **Extends:** VaadinElement +**Implements:** HasValidationPropertiesElement, HasInputFieldElement, HasPrefixElement, HasSuffixElement, HasClearButtonElement, HasPlaceholderElement, HasAllowedCharPatternElement, HasThemeElement, FocusableElement, HasAriaLabelElement, HasEnabledElement, HasTooltipElement + +**Constructors:** + +- `AbstractNumberFieldElement(Locator locator)` — Creates a new AbstractNumberFieldElement. + +**Methods:** + +- `boolean getHasControls()` — Whether the step controls (increase/decrease buttons) are visible. +- `void assertHasControls(boolean hasControls)` — Assert the visibility of step controls. +- `void clickIncreaseButton()` — Click the increase button. +- `void clickDecreaseButton()` — Click the decrease button. + +### AccordionElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** HasStyleElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-accordion"` + +**Constructors:** + +- `AccordionElement(Locator locator)` — Create a new AccordionElement. + +**Methods:** + +- `void assertPanelCount(int count)` — Assert the number of panels present in the accordion. +- `AccordionPanelElement getPanel(String summary)` — Get a panel by its summary text. +- `void openPanel(String summary)` — Open a panel by its summary text. +- `void closePanel(String summary)` — Close a panel by its summary text. +- `boolean isPanelOpened(String summary)` — Whether the panel with the given summary is open. +- `void assertPanelOpened(String summary)` — Assert that the panel with the given summary is open. +- `void assertPanelClosed(String summary)` — Assert that the panel with the given summary is closed. +- `AccordionPanelElement getOpenedPanel()` — Get the currently opened panel. + +### AccordionPanelElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-accordion-panel"`, `String FIELD_HEADING_TAG_NAME = "vaadin-accordion-heading"` + +**Constructors:** + +- `AccordionPanelElement(Locator locator)` — Create a new AccordionPanelElement. + +**Static factory methods:** + +- `AccordionPanelElement getAccordionPanelBySummary(Locator locator, String summary)` — Get an accordion panel by its summary text within a scope. +- `AccordionPanelElement getOpenedAccordionPanel(Locator locator)` — Get the currently opened accordion panel within a scope. + +**Methods:** + +- `void assertOpened()` — Assert that the panel is opened. +- `void assertClosed()` — Assert that the panel is closed. +- `boolean isOpen()` — Whether the panel is open. +- `void setOpen(boolean open)` — Set the open state by clicking the summary when needed. +- `Locator getSummaryLocator()` — Locator pointing to the summary heading. +- `String getSummaryText()` — Text content of the summary heading. +- `Locator getContentLocator()` — Locator pointing to the first non-slotted content element. +- `void assertContentVisible()` — Assert that the content area is visible. +- `void assertContentNotVisible()` — Assert that the content area is not visible. +- `void assertEnabled()` — Assert that the panel is enabled. +- `void assertDisabled()` — Assert that the panel is disabled. + +### AvatarElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** FocusableElement, HasStyleElement, HasThemeElement, HasTooltipElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-avatar"` + +**Constructors:** + +- `AvatarElement(Locator locator)` — Create a new AvatarElement. + +**Static factory methods:** + +- `AvatarElement get(Page page)` — Get the first AvatarElement on the page. +- `AvatarElement get(Locator locator)` — Get the first AvatarElement within a scope. +- `AvatarElement getByName(Page page, String name)` — Get an AvatarElement by its name attribute. +- `AvatarElement getByName(Locator locator, String name)` — Get an AvatarElement by its name attribute within a scope. + +**Methods:** + +- `String getName()` — Get the avatar's name. +- `void setName(String name)` — Set the avatar's name. +- `String getAbbreviation()` — Get the displayed abbreviation. +- `void setAbbreviation(String abbr)` — Set the abbreviation. +- `String getImage()` — Get the image URL. +- `void setImage(String img)` — Set the image URL. +- `Integer getColorIndex()` — Get the background color index. +- `void setColorIndex(int colorIndex)` — Set the background color index. +- `void assertName(String name)` — Assert the avatar's name property value. +- `void assertAbbreviation(String abbr)` — Assert the avatar's abbreviation. +- `void assertHasImage()` — Assert that the avatar has an image set. +- `void assertHasNoImage()` — Assert that the avatar has no image set. + +### BigDecimalFieldElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** HasValidationPropertiesElement, HasInputFieldElement, HasPrefixElement, HasSuffixElement, HasClearButtonElement, HasPlaceholderElement, HasAllowedCharPatternElement, HasThemeElement, FocusableElement, HasAriaLabelElement, HasEnabledElement, HasTooltipElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-big-decimal-field"` + +**Constructors:** + +- `BigDecimalFieldElement(Locator locator)` — Create a new BigDecimalFieldElement. + +**Static factory methods:** + +- `BigDecimalFieldElement getByLabel(Page page, String label)` — Get the BigDecimalFieldElement by its label. +- `BigDecimalFieldElement getByLabel(Locator locator, String label)` — Get the BigDecimalFieldElement by its label within a given scope. + +### ButtonElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** FocusableElement, HasAriaLabelElement, HasEnabledElement, HasPrefixElement, HasStyleElement, HasSuffixElement, HasThemeElement, HasTooltipElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-button"` + +**Constructors:** + +- `ButtonElement(Locator locator)` — Create a new ButtonElement. + +**Static factory methods:** + +- `ButtonElement getByText(Page page, String text)` — Get a ButtonElement by its accessible name or visible text. +- `ButtonElement getByText(Page page, Page.GetByRoleOptions options)` — Get a ButtonElement by its accessible name with custom role options. +- `ButtonElement getByText(Locator locator, String text)` — Get a ButtonElement by its accessible name or visible text within a scope. +- `ButtonElement getByText(Locator locator, Locator.GetByRoleOptions options)` — Get a ButtonElement by its accessible name with custom role options within a scope. +- `ButtonElement getByLabel(Page page, String text)` — Alias for #getByText(Page, String). + +### CardElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** HasThemeElement, HasStyleElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-card"` + +**Constructors:** + +- `CardElement(Locator locator)` — Create a new CardElement. + +**Static factory methods:** + +- `CardElement getByTitle(Page page, String title)` — Get a card by title +- `CardElement getByTitle(Locator locator, String title)` — Get a card by title + +**Methods:** + +- `Locator getTitleLocator()` — Locator for the title slot. +- `Locator getSubtitleLocator()` — Locator for the subtitle slot. +- `Locator getHeaderLocator()` — Locator for the header slot. +- `Locator getHeaderPrefixLocator()` — Locator for the header prefix slot. +- `Locator getHeaderSuffixLocator()` — Locator for the header suffix slot. +- `Locator getMediaLocator()` — Locator for the media slot. +- `Locator getFooterLocator()` — Locator for the footer slot. +- `Locator getContentLocator()` — Locator for the default (content) slot. +- `void assertTitle(String title)` — Assert the card title text, or absence when null. +- `void assertSubtitle(String subtitle)` — Assert the card subtitle text, or absence when null. + +### CheckboxElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** FocusableElement, HasAriaLabelElement, HasEnabledElement, HasHelperElement, HasValueElement, HasStyleElement, HasLabelElement, HasValidationPropertiesElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-checkbox"` + +**Constructors:** + +- `CheckboxElement(Locator locator)` — Create a new CheckboxElement. + +**Static factory methods:** + +- `CheckboxElement getByLabel(Page page, String label)` — Get a CheckboxElement by its accessible label. + +**Methods:** + +- `boolean isChecked()` — Whether the checkbox is currently checked. +- `void assertChecked()` — Assert that the checkbox is checked. +- `void assertNotChecked()` — Assert that the checkbox is not checked. +- `void assertChecked(boolean checked)` — Assert the checkbox's checked state. +- `void check()` — Check the checkbox. +- `void uncheck()` — Uncheck the checkbox. +- `void isChecked(boolean checked)` — Check or uncheck the checkbox. +- `boolean isIndeterminate()` — Whether the checkbox is in indeterminate state. +- `void assertIndeterminate()` — Assert that the checkbox is indeterminate. +- `void assertNotIndeterminate()` — Assert that the checkbox is not indeterminate. +- `void setIndeterminate(boolean indeterminate)` — Set the indeterminate state. + +### ComboBoxElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** FocusableElement, HasAriaLabelElement, HasInputFieldElement, HasPrefixElement, HasThemeElement, HasPlaceholderElement, HasEnabledElement, HasTooltipElement, HasValidationPropertiesElement, HasClearButtonElement, HasAllowedCharPatternElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-combo-box"`, `String FIELD_ITEM_TAG_NAME = "vaadin-combo-box-item"` + +**Constructors:** + +- `ComboBoxElement(Locator locator)` — Create a new ComboBoxElement. + +**Static factory methods:** + +- `ComboBoxElement getByLabel(Page page, String label)` — Get the ComboBoxElement by its label. +- `ComboBoxElement getByLabel(Locator locator, String label)` — Get the ComboBoxElement by its label within a given scope. + +**Methods:** + +- `void selectItem(String item)` — Select an item by its visible label. +- `void filterAndSelectItem(String filter, String item)` — Type filter text into the input, then click the matching item. +- `void setFilter(String filter)` — Type into the input to trigger filtering. +- `String getFilter()` — Get the current filter value from the DOM property. +- `void open()` — Open the combo box overlay. +- `void close()` — Close the combo box overlay. +- `boolean isOpened()` — Whether the overlay is currently open. +- `void assertOpened()` — Assert that the combo box overlay is open. +- `void assertClosed()` — Assert that the combo box overlay is closed. +- `boolean isReadOnly()` — Whether the combo box is read-only. +- `void assertReadOnly()` — Assert that the combo box is read-only. +- `void assertNotReadOnly()` — Assert that the combo box is not read-only. +- `Locator getToggleButtonLocator()` — Locator for the toggle button part. +- `void clickToggleButton()` — Click the dropdown toggle button. +- `int getOverlayItemCount()` — Count visible overlay items. +- `void assertItemCount(int expected)` — Assert that the overlay contains exactly the expected number of items. + +### ContextMenuElement + +PlaywrightElement for context menu overlays . + +**Extends:** VaadinElement +**Implements:** HasStyleElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-context-menu"`, `String FIELD_LIST_BOX_TAG_NAME = "vaadin-context-menu-list-box"` + +**Constructors:** + +- `ContextMenuElement(Page page)` — Create a ContextMenuElement from the page overlay. +- `ContextMenuElement(Locator locator)` — Create a ContextMenuElement from an existing locator. + +**Static factory methods:** + +- `void openOn(Locator target)` — Open the context menu by invoking a context-click on the provided target. + +**Methods:** + +- `void assertOpen()` — Assert that the context menu overlay is open. +- `void assertClosed()` — Assert that the context menu overlay is closed or hidden. +- `ContextMenuElement openSubMenu(String itemLabel)` — Open a submenu and return its overlay. +- `void selectItem(String itemLabel)` — Select a menu item by its accessible name. +- `void assertItemDisabled(String itemLabel)` — Assert that a menu item is disabled. +- `void assertItemEnabled(String itemLabel)` — Assert that a menu item is enabled. +- `Locator getListBoxLocator()` — Locator for the context menu list box. +- `void assertItemChecked(String itemLabel)` — Assert that a checkable menu item is checked. +- `void assertItemNotChecked(String itemLabel)` — Assert that a checkable menu item is not checked. + +### DatePickerElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** HasInputFieldElement, HasValidationPropertiesElement, HasClearButtonElement, HasPlaceholderElement, HasThemeElement, FocusableElement, HasAriaLabelElement, HasEnabledElement, HasTooltipElement, HasLabelElement, HasHelperElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-date-picker"` + +**Constructors:** + +- `DatePickerElement(Locator locator)` — Create a new DatePickerElement. + +**Static factory methods:** + +- `DatePickerElement getByLabel(Page page, String label)` — Get the DatePickerElement by its label. +- `DatePickerElement getByLabel(Locator locator, String label)` — Get the DatePickerElement by its label within a given scope. + +**Methods:** + +- `void setValue(LocalDate date)` — Set the value using a LocalDate formatted as ISO-8601. +- `LocalDate getValueAsLocalDate()` — Get the current value as a LocalDate. +- `void assertValue(LocalDate value)` — Assert that the value equals the provided date. + +### DateTimePickerElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** HasInputFieldElement, HasValidationPropertiesElement, HasClearButtonElement, HasPlaceholderElement, HasThemeElement, FocusableElement, HasAriaLabelElement, HasEnabledElement, HasTooltipElement, HasLabelElement, HasHelperElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-date-time-picker"`, `DateTimeFormatter ISO_LOCAL_DATE_TIME = new DateTimeFormatterBuilder().parseCaseInsensitive().append(ISO_LOCAL_DATE).appendLiteral('T').append(TimePickerElement.LOCAL_TIME).toFormatter()` + +**Constructors:** + +- `DateTimePickerElement(Locator locator)` — Create a new DateTimePickerElement. + +**Static factory methods:** + +- `DateTimePickerElement getByLabel(Page page, String label)` — Get the DateTimePickerElement by its label. +- `DateTimePickerElement getByLabel(Locator locator, String label)` — Get the DateTimePickerElement by its label within a given scope. + +**Methods:** + +- `void setValue(LocalDateTime date)` — Set the value using a LocalDateTime. +- `LocalDateTime getValueAsLocalDateTime()` — Get the current value as a LocalDateTime. +- `void assertValue(LocalDateTime value)` — Assert that the value equals the provided date-time. +- `void setDate(String date)` — Set only the date part (string input) and dispatch change events. +- `void setTime(String date)` — Set only the time part (string input) and dispatch change events. +- `void assertDateValue(String date)` — Assert the date sub-field value equals the expected string. +- `void assertTimeValue(String time)` — Assert the time sub-field value equals the expected string. + +### DetailsElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** HasStyleElement, HasThemeElement, HasTooltipElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-details"` + +**Constructors:** + +- `DetailsElement(Locator locator)` — Create a new DetailsElement. + +**Static factory methods:** + +- `DetailsElement getBySummaryText(Page page, String summary)` — Get a details component by its summary text. + +**Methods:** + +- `void assertEnabled()` — Assert that the component is enabled. +- `void assertDisabled()` — Assert that the component is disabled. +- `void assertOpened()` — Assert that the details is opened. +- `void assertClosed()` — Assert that the details is closed. +- `boolean isOpen()` — Whether the details is opened. +- `void setOpen(boolean open)` — Set the opened state by clicking the summary when necessary. +- `Locator getSummaryLocator()` — Locator for the summary element. +- `String getSummaryText()` — Text of the summary element. +- `Locator getContentLocator()` — Locator for the currently visible content container. +- `void assertContentVisible()` — Assert that the content is visible. +- `void assertContentNotVisible()` — Assert that the content is not visible. + +### DialogElement + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** HasThemeElement, HasStyleElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-dialog"` + +**Constructors:** + +- `DialogElement(Page page)` — Create a DialogElement by resolving the dialog with ARIA role. +- `DialogElement(Locator locator)` — Create a DialogElement from an existing locator. + +**Static factory methods:** + +- `DialogElement getByHeaderText(Page page, String summary)` — Get a dialog by its header text (accessible name). + +**Methods:** + +- `void closeWithEscape()` — Close the dialog using the Escape key. +- `Locator getOverlayLocator()` — Locator for the overlay rendered in the dialog's shadow DOM. +- `boolean isOpen()` — Whether the dialog is open (visible). +- `void assertOpen()` — Assert that the dialog is open. +- `boolean isModal()` — Whether the dialog is modal (i.e. not modeless). +- `void assertModal()` — Assert that the dialog is modal. +- `void assertModeless()` — Assert that the dialog is modeless. +- `void assertClosed()` — Assert that the dialog is closed (its overlay is hidden). +- `String getHeaderText()` — Get the header text from the title slot. +- `void assertHeaderText(String headerText)` — Assert the header text matches. +- `Locator getHeaderLocator()` — Locator for the header content slot. +- `Locator getContentLocator()` — Locator for the dialog content (first non-slotted child). +- `Locator getFooterLocator()` — Locator for the footer slot. + +### EmailFieldElement `` + +PlaywrightElement for . + +**Extends:** TextFieldElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-email-field"` + +**Constructors:** + +- `EmailFieldElement(Locator locator)` — Create a new EmailFieldElement. + +**Static factory methods:** + +- `EmailFieldElement getByLabel(Page page, String label)` — Get the EmailFieldElement by its label. +- `EmailFieldElement getByLabel(Locator locator, String label)` — Get the EmailFieldElement by its label within a given scope. + +### GridElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** FocusableElement, HasStyleElement, HasThemeElement, HasEnabledElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-grid"` + +**Constructors:** + +- `GridElement(Locator locator)` — Create a new GridElement. + +**Static factory methods:** + +- `GridElement get(Page page)` — Get the first GridElement on the page. +- `GridElement get(Locator parent)` — Get the first GridElement within a parent locator. +- `GridElement getById(Page page, String id)` — Get a GridElement by its id attribute. + +**Methods:** + +- `int getRenderedRowCount()` — Get the number of rows currently rendered in the DOM. +- `int getTotalRowCount()` — Get the total number of rows (data items) in the grid. +- `int getColumnCount()` — Get the number of visible (non-hidden) columns. +- `boolean isAllRowsVisible()` — Whether the grid has allRowsVisible enabled. +- `boolean isMultiSort()` — Whether the grid has multi-sort enabled. +- `boolean isColumnReorderingAllowed()` — Whether column reordering is allowed. +- `Optional findHeaderCell(int columnIndex)` — Find a header cell by column index. +- `Optional findHeaderCell(int headerRowIndex, int columnIndex)` — Find a header cell by header row index and column index. +- `Optional findHeaderCellByText(String text)` — Find a header cell by its text content. +- `Optional findHeaderCellByText(int headerRowIndex, String text)` — Find a header cell by header row index and text content. +- `List getHeaderCellContents()` — Get the text content of all visible header cells. +- `Optional findFooterCell(int columnIndex)` — Find a footer cell by column index. +- `Optional findFooterCell(int footerRowIndex, int columnIndex)` — Find a footer cell by footer row index and column index. +- `Optional findFooterCellByText(String text)` — Find a footer cell by its text content. +- `Optional findFooterCellByText(int footerRowIndex, String text)` — Find a footer cell by footer row index and text content. +- `List getFooterCellContents()` — Get the text content of all visible footer cells. +- `Optional findCell(int row, int column)` — Find a body cell by row index and column index. +- `Optional findCell(int row, String columnHeaderText)` — Find a body cell by row index and column header text. +- `List findRowIndexesWithColumnText(int columnIndex, String text)` — Find row indexes where the cell in the given column has the given text. +- `Optional findRow(int rowIndex)` — Find a row by its index. +- `void scrollToRow(int rowIndex)` — Scroll the grid so that the given row index becomes visible. +- `void scrollToStart()` — Scroll to the very beginning of the grid. +- `void scrollToEnd()` — Scroll to the very end of the grid. +- `void select(int rowIndex)` — Select a row by id. +- `void deselect(int rowIndex)` — Deselect a row by id. +- `int getSelectedItemCount()` — Get the number of currently selected items. +- `boolean isSelectAllChecked()` — Check if the select-all checkbox is checked. +- `boolean isSelectAllIndeterminate()` — Check if the select-all checkbox is indeterminate. +- `boolean isSelectAllUnchecked()` — Check if the select-all checkbox is unchecked. +- `void checkSelectAll()` — Check the select-all checkbox. +- `void uncheckSelectAll()` — Uncheck the select-all checkbox. +- `void waitForGridToStopLoading()` — Wait for the grid to finish loading after a scroll or other action that triggers loading of new rows. +- `boolean isRowInView(int rowIndex)` — Whether the row with the given index is currently scrolled into view (at least partially visible between the header and footer), without triggering any scrolling. +- `void assertRowCount(int expected)` — Assert that the grid has the given total number of rows (data items). +- `void assertEmpty()` — Assert that the grid has no rows. +- `void assertColumnCount(int expected)` — Assert that the grid has the given number of visible (non-hidden) columns. +- `void assertAllRowsVisible()` — Assert that allRowsVisible is enabled. +- `void assertNotAllRowsVisible()` — Assert that allRowsVisible is not enabled. +- `void assertMultiSort()` — Assert that multi-sort is enabled. +- `void assertNotMultiSort()` — Assert that multi-sort is not enabled. +- `void assertColumnReorderingAllowed()` — Assert that column reordering is allowed. +- `void assertColumnReorderingNotAllowed()` — Assert that column reordering is not allowed. +- `void assertCellContent(int row, int column, String expected)` — Assert that the body cell at the given row and column has the given text content. +- `void assertCellContent(int row, String columnHeaderText, String expected)` — Assert that the body cell at the given row and column header has the given text content. +- `void assertCellPresent(int row, int column)` — Assert that a cell exists at the given row and column. +- `void assertCellNotPresent(int row, int column)` — Assert that no cell exists at the given row and column. +- `void assertHeaderCellContents(String... expected)` — Assert that the visible header cells have exactly the given text contents, in order. +- `void assertHeaderCell(int column, String expected)` — Assert that the header cell at the given column has the given text content. +- `void assertColumnPresent(String headerText)` — Assert that a column with the given header text exists. +- `void assertColumnNotPresent(String headerText)` — Assert that no column with the given header text exists. +- `void assertFooterCellContents(String... expected)` — Assert that the visible footer cells have exactly the given text contents, in order. +- `void assertFooterCell(int column, String expected)` — Assert that the footer cell at the given column has the given text content. +- `void assertFooterPresent(String footerText)` — Assert that a footer cell with the given text exists. +- `void assertFooterNotPresent(String footerText)` — Assert that no footer cell with the given text exists. +- `void assertRowPresent(int rowIndex)` — Assert that a row exists at the given index (auto-scrolling if necessary). +- `void assertRowNotPresent(int rowIndex)` — Assert that no row exists at the given index. +- `void assertRowInView(int rowIndex)` — Assert that the row with the given index is currently scrolled into view. +- `void assertRowNotInView(int rowIndex)` — Assert that the row with the given index is not currently scrolled into view. +- `void assertRowIndexesWithColumnText(int column, String text, Integer... expected)` — Assert that the cells in the given column with the given text appear at exactly the given row indexes. +- `void assertSelectedItemCount(int expected)` — Assert that the given number of items are currently selected. +- `void assertRowSelected(int rowIndex)` — Assert that the row at the given index is selected. +- `void assertRowNotSelected(int rowIndex)` — Assert that the row at the given index is not selected. +- `void assertSelectAllChecked()` — Assert that the select-all checkbox is checked. +- `void assertSelectAllUnchecked()` — Assert that the select-all checkbox is unchecked. +- `void assertSelectAllIndeterminate()` — Assert that the select-all checkbox is indeterminate. +- `void assertDetailsOpen(int rowIndex)` — Assert that the details panel of the row at the given index is open. +- `void assertDetailsClosed(int rowIndex)` — Assert that the details panel of the row at the given index is closed. + +#### GridElement.CellElement + +Represents a cell in the grid, providing access to the table cell (td or th), the cell content (vaadin-grid-cell-content) and the column index. + +- `Locator getTableCellLocator()` — Get the locator for the table cell (td or th). +- `int getColumnIndex()` — Get the column index (0-based) of this cell. +- `Locator getCellContentLocator()` — Get the locator for the cell content (vaadin-grid-cell-content) assigned to this cell. +- `String getContentSlotName()` — Get the name of the slot used for the cell content. +- `void click()` — Click the cell content. + +#### GridElement.HeaderCellElement + +Represents a header cell in the grid, providing access to the table cell (th), the cell content and sorting. + +- `boolean isSortable()` — Whether the header cell supports sorting. +- `void clickSort()` — Click the header cell sorter to sort the column. +- `boolean isSortAscending()` — Whether the column is currently sorted in ascending order. +- `boolean isSortDescending()` — Whether the column is currently sorted in descending order. +- `boolean isNotSorted()` — Whether the column is currently not sorted. +- `void assertSortAscending()` — Assert that the column is sorted in ascending order. +- `void assertSortDescending()` — Assert that the column is sorted in descending order. +- `void assertNotSorted()` — Assert that the column is not sorted. +- `void assertSortable()` — Assert that the header cell supports sorting. +- `void assertNotSortable()` — Assert that the header cell does not support sorting. + +#### GridElement.FooterCellElement + +Represents a footer cell in the grid, providing access to the table cell (td) and the cell content. + + +#### GridElement.RowElement + +Represents a row in the grid, providing access to the row locator, row index, and methods for accessing cells and interacting with the row (selection, details). + +- `Locator getRowLocator()` — Get the locator for the row (tr). +- `int getRowIndex()` — Get the row index (0-based) of this row. +- `CellElement getCell(int columnIndex)` — Get the cell element for the given column index in this row. +- `CellElement getCell(String columnHeaderText)` — Get the cell element for the given column header text in this row. +- `CellElement getDetailsCell()` — Get the cell element for the details column in this row. +- `boolean isSelected()` — Whether this row is selected. +- `void select()` — Select this row. +- `void deselect()` — Deselect this row. +- `void openDetails()` — Whether the details for this row are open. +- `void closeDetails()` — Close the details for this row. +- `boolean isDetailsOpen()` — Whether the details for this row are open. +- `void assertSelected()` — Assert that this row is selected. +- `void assertNotSelected()` — Assert that this row is not selected. +- `void assertDetailsOpen()` — Assert that this row's details panel is open. +- `void assertDetailsClosed()` — Assert that this row's details panel is closed. + +### IntegerFieldElement `` + +PlaywrightElement for . + +**Extends:** AbstractNumberFieldElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-integer-field"` + +**Constructors:** + +- `IntegerFieldElement(Locator locator)` — Creates a new IntegerFieldElement. + +**Static factory methods:** + +- `IntegerFieldElement getByLabel(Page page, String label)` — Get the IntegerFieldElement by its label. +- `IntegerFieldElement getByLabel(Locator locator, String label)` — Get the IntegerFieldElement by its label within a given scope. + +**Methods:** + +- `Integer getStep()` — Get the current step value. +- `void setStep(int step)` — Set the step value. +- `void assertStep(Integer step)` — Assert that the step attribute matches the expected value. +- `Integer getMin()` — Get the current min value. +- `void setMin(int min)` — Set the min value. +- `void assertMin(Integer min)` — Assert that the min attribute matches the expected value. +- `Integer getMax()` — Get the current max value. +- `void setMax(int max)` — Set the max value. +- `void assertMax(Integer max)` — Assert that the max attribute matches the expected value. + +### ListBoxElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** HasAriaLabelElement, HasStyleElement, HasTooltipElement, HasEnabledElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-list-box"`, `String FIELD_ITEM_TAG_NAME = "vaadin-item"`, `String MULTIPLE_ATTRIBUTE = "multiple"` + +**Constructors:** + +- `ListBoxElement(Locator locator)` — Create a new ListBoxElement. + +**Static factory methods:** + +- `ListBoxElement getByLabel(Page page, String label)` — Get the ListBoxElement by its label. + +**Methods:** + +- `void selectItem(String item)` — Select the item based on its text. +- `String getSingleSelectedValue()` — Get the selected value for single-select list boxes. +- `List getSelectedValue()` — Get all selected values for multi-select list boxes. +- `void assertSelectedValue(String... expected)` — Assert that the selected values match the expected labels. +- `void assertItemEnabled(String item)` — Assert that a specific item is enabled. +- `void assertItemDisabled(String item)` — Assert that a specific item is disabled. +- `boolean isMultiple()` +- `void assertMultiple()` — Assert that multiple selection is enabled. +- `void assertSingle()` — Assert that single selection mode is enabled. + +### MenuBarElement + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** HasThemeElement, HasStyleElement, HasAriaLabelElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-menu-bar"` + +**Constructors:** + +- `MenuBarElement(Page page)` — Create a MenuBarElement from the page. +- `MenuBarElement(Locator locator)` — Create a MenuBarElement from an existing locator. + +**Static factory methods:** + +- `MenuBarElement getByLabel(Page page, String label)` — Get a menu bar by its accessible label. + +**Methods:** + +- `MenuItemElement getMenuItemElement(String name)` — Get a menu item by visible label. +- `MenuElement openSubMenu(String name)` — Click a menu item to open its submenu and return the submenu overlay. + +### MenuElement + +PlaywrightElement for the menu overlay list . + +**Extends:** VaadinElement +**Implements:** HasThemeElement, HasStyleElement, HasAriaLabelElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-menu-bar-list-box"` + +**Constructors:** + +- `MenuElement(Page page)` — Create a MenuElement from the page. +- `MenuElement(Locator locator)` — Create a MenuElement from an existing locator. + +**Static factory methods:** + +- `MenuElement getByLabel(Page page, String label)` — Get a menu overlay by its accessible label. + +**Methods:** + +- `MenuItemElement getMenuItemElement(String name)` — Get a menu item by its visible label within this menu. +- `MenuElement openSubMenu(String name)` — Click a menu item to open its submenu and return the next overlay. + +### MenuItemElement + +PlaywrightElement for individual menu items . + +**Extends:** VaadinElement +**Implements:** HasThemeElement, HasStyleElement, HasAriaLabelElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-menu-bar-button"` + +**Constructors:** + +- `MenuItemElement(Locator locator)` — Create a MenuItemElement from an existing locator. + +**Static factory methods:** + +- `MenuItemElement getByLabel(Locator locator, String label)` — Get a menu item by its accessible label within a scope. + +**Methods:** + +- `void assertExpanded()` — Assert that the menu item is expanded (shows submenu). +- `void assertCollapsed()` — Assert that the menu item is collapsed. + +### MessageInputElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** FocusableElement, HasEnabledElement, HasStyleElement, HasThemeElement, HasTooltipElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-message-input"` + +**Constructors:** + +- `MessageInputElement(Locator locator)` — Create a new MessageInputElement. + +**Static factory methods:** + +- `MessageInputElement get(Page page)` — Get the first on the page. +- `MessageInputElement get(Locator locator)` — Get the first within a locator scope. + +**Methods:** + +- `Locator getTextAreaLocator()` — Locator for the internal . +- `Locator getTextAreaInputLocator()` — Locator for the native textarea inside the text area (slot="textarea"). +- `Locator getSendButtonLocator()` — Locator for the internal send button (). +- `String getValue()` — Get the current text area value. +- `void setValue(String value)` — Set the message text by filling the internal textarea input. +- `void clear()` — Clear the text area. +- `void assertValue(String value)` — Assert that the text area input has the expected value. +- `void submit()` — Click the send button to submit the message. +- `void submitByEnter()` — Press Enter on the text area to submit the message. +- `void typeAndSubmit(String message)` — Set a message value and then click the send button. +- `void assertSendButtonVisible()` — Assert that the send button is visible. +- `void assertSendButtonHidden()` — Assert that the send button is hidden. +- `void assertSendButtonEnabled()` — Assert that the send button is enabled. +- `void assertSendButtonDisabled()` — Assert that the send button is disabled. +- `String getMessagePlaceholder()` — Get the placeholder text on the text area. +- `void assertMessagePlaceholder(String expected)` — Assert that the text area placeholder matches the expected text. +- `String getSendButtonText()` — Get the send button text content. +- `void assertSendButtonText(String expected)` — Assert that the send button text matches the expected text. + +### MessageListElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** HasStyleElement, HasThemeElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-message-list"`, `String FIELD_MESSAGE_TAG_NAME = "vaadin-message"` + +**Constructors:** + +- `MessageListElement(Locator locator)` — Create a new MessageListElement. + +**Static factory methods:** + +- `MessageListElement get(Page page)` — Get the first on the page. +- `MessageListElement get(Locator locator)` — Get the first within a locator scope. + +**Methods:** + +- `Locator getMessages()` — Locator for all children. +- `Locator getMessage(int index)` — Locator for a single message by index. +- `Locator getMessageByUserName(String userName)` — Locator for the first message whose author name contains the given text. +- `String getMessageText(int index)` — Get the text content of the message at the given index. +- `String getMessageUserName(int index)` — Get the user name of the message at the given index. +- `String getMessageTime(int index)` — Get the time of the message at the given index. +- `void assertMessageCount(int count)` — Assert that the list contains exactly the expected number of messages. +- `void assertEmpty()` — Assert that the list contains no messages. +- `void assertMessageText(int index, String expected)` — Assert that the message at the given index has the expected text. +- `void assertMessageUserName(int index, String expected)` — Assert that the message at the given index has the expected user name. +- `void assertMessageTime(int index, String expected)` — Assert that the message at the given index has the expected time. + +### MultiSelectComboBoxElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** FocusableElement, HasAriaLabelElement, HasInputFieldElement, HasThemeElement, HasPlaceholderElement, HasEnabledElement, HasTooltipElement, HasValidationPropertiesElement, HasClearButtonElement, HasAllowedCharPatternElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-multi-select-combo-box"`, `String FIELD_ITEM_TAG_NAME = "vaadin-multi-select-combo-box-item"`, `String FIELD_CHIP_TAG_NAME = "vaadin-multi-select-combo-box-chip"` + +**Constructors:** + +- `MultiSelectComboBoxElement(Locator locator)` — Create a new MultiSelectComboBoxElement. + +**Static factory methods:** + +- `MultiSelectComboBoxElement getByLabel(Page page, String label)` — Get the MultiSelectComboBoxElement by its label. +- `MultiSelectComboBoxElement getByLabel(Locator locator, String label)` — Get the MultiSelectComboBoxElement by its label within a given scope. + +**Methods:** + +- `void selectItem(String item)` — Select an item by its visible label. +- `void deselectItem(String item)` — Deselect an item by its visible label. +- `void selectItems(String... items)` — Select multiple items in sequence. +- `void deselectItems(String... items)` — Deselect multiple items in sequence. +- `void filterAndSelectItem(String filter, String item)` — Type filter text into the input, then click the matching item. +- `void setFilter(String filter)` — Type into the input to trigger filtering. +- `String getFilter()` — Get the current filter value from the DOM property. +- `void open()` — Open the combo box overlay. +- `void close()` — Close the combo box overlay. +- `boolean isOpened()` — Whether the overlay is currently open. +- `void assertOpened()` — Assert that the combo box overlay is open. +- `void assertClosed()` — Assert that the combo box overlay is closed. +- `boolean isReadOnly()` — Whether the combo box is read-only. +- `void assertReadOnly()` — Assert that the combo box is read-only. +- `void assertNotReadOnly()` — Assert that the combo box is not read-only. +- `Locator getToggleButtonLocator()` — Locator for the toggle button part. +- `void clickToggleButton()` — Click the dropdown toggle button. +- `int getOverlayItemCount()` — Count visible overlay items. +- `void assertItemCount(int expected)` — Assert that the overlay contains exactly the expected number of items. +- `Locator getChipLocators()` — Get the locator for all non-overflow chips. +- `Locator getOverflowChipLocator()` — Get the locator for the overflow chip. +- `List getSelectedItems()` — Get the labels of all currently selected items by reading the selectedItems property from the web component. +- `int getSelectedItemCount()` — Get the count of currently selected items from the selectedItems property. +- `void assertSelectedItems(String... expected)` — Assert that the selected item labels match the expected values. +- `void assertSelectedCount(int expected)` — Assert that the number of selected items matches. +- `T getOverlayItemComponent(String itemText, Class type)` — Get a typed component element from an overlay item matching the given text. +- `T getOverlayItemComponent(int index, Class type)` — Get a typed component element from an overlay item at the given visible index. + +### NotificationElement + +PlaywrightElement for notification cards . + +**Extends:** VaadinElement +**Implements:** HasThemeElement, HasStyleElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-notification-card"` + +**Constructors:** + +- `NotificationElement(Page page)` — Create a NotificationElement for the open notification on the page. +- `NotificationElement(Locator locator)` — Create a NotificationElement from an existing locator. + +**Static factory methods:** + +- `NotificationElement getByText(Page page, String text)` — Get an open notification by (a substring of) its text. + +**Methods:** + +- `boolean isOpen()` — Whether the notification is open (visible). +- `void assertOpen()` — Assert that the notification is open. +- `void assertClosed()` — Assert that the notification is closed. +- `Locator getContentLocator()` — Locator for the notification content. +- `void assertContent(String content)` — Assert that the notification contains the given text. + +### NumberFieldElement `` + +PlaywrightElement for . + +**Extends:** AbstractNumberFieldElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-number-field"` + +**Constructors:** + +- `NumberFieldElement(Locator locator)` — Creates a new NumberFieldElement. + +**Static factory methods:** + +- `NumberFieldElement getByLabel(Page page, String label)` — Get the NumberFieldElement by its label. +- `NumberFieldElement getByLabel(Locator locator, String label)` — Get the NumberFieldElement by its label within a given scope. + +**Methods:** + +- `Double getStep()` — Get the current step value. +- `void setStep(double step)` — Set the step value. +- `void assertStep(Double step)` — Assert that the step attribute matches the expected value. +- `Double getMin()` — Get the current min value. +- `void setMin(double min)` — Set the min value. +- `void assertMin(Double min)` — Assert that the min attribute matches the expected value. +- `Double getMax()` — Get the current max value. +- `void setMax(double max)` — Set the max value. +- `void assertMax(Double max)` — Assert that the max attribute matches the expected value. + +### PasswordFieldElement `` + +PlaywrightElement for . + +**Extends:** TextFieldElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-password-field"` + +**Constructors:** + +- `PasswordFieldElement(Locator locator)` — Create a new PasswordFieldElement. + +**Static factory methods:** + +- `PasswordFieldElement getByLabel(Page page, String label)` — Get the PasswordFieldElement by its accessible name, searching the entire page. + +### PopoverElement + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** HasThemeElement, HasStyleElement, HasAriaLabelElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-popover"` + +**Constructors:** + +- `PopoverElement(Page page)` — Create a PopoverElement by resolving the dialog with ARIA role. +- `PopoverElement(Locator locator)` — Create a PopoverElement from an existing locator. + +**Static factory methods:** + +- `PopoverElement getByLabel(Page page, String label)` — Get a popover by its accessible label. + +**Methods:** + +- `boolean isOpen()` — Whether the popover is open (visible). +- `void assertOpen()` — Assert that the popover is open. +- `void assertClosed()` — Assert that the popover is closed (hidden). +- `Locator getContentLocator()` — Locator for the popover content. + +### ProgressBarElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** HasThemeElement, HasStyleElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-progress-bar"`, `String INDETERMINATE_ATTRIBUTE = "indeterminate"` + +**Constructors:** + +- `ProgressBarElement(Locator locator)` — Create a ProgressBarElement from an existing locator. + +**Methods:** + +- `double getValue()` — Current numeric value parsed from aria-valuenow. +- `void setValue(double min)` — Set the progress bar value. +- `void assertValue(Double expected)` — Assert that the numeric value matches. +- `Double getMin()` — Get the min value. +- `void setMin(double min)` — Set the min value. +- `void assertMin(double min)` — Assert that min matches the expected value. +- `Double getMax()` — Get the max value. +- `void setMax(double max)` — Set the max value. +- `void assertMax(double max)` — Assert that max matches the expected value. +- `boolean isIndeterminate()` — Whether the bar is indeterminate. +- `void assertIndeterminate()` — Assert indeterminate state. +- `void assertNotIndeterminate()` — Assert not indeterminate. +- `void setIndeterminate(boolean indeterminate)` — Set the indeterminate state. + +### RadioButtonGroupElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** HasLabelElement, HasEnabledElement, HasHelperElement, HasValidationPropertiesElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-radio-group"` + +**Constructors:** + +- `RadioButtonGroupElement(Locator locator)` — Create a new RadioButtonGroupElement. + +**Static factory methods:** + +- `RadioButtonGroupElement getByLabel(Page page, String label)` — Get the group by its accessible label. + +**Methods:** + +- `void selectByLabel(String label)` — Select a radio by its label text. +- `void selectByValue(String value)` — Select a radio by its value. +- `RadioButtonElement getRadioButtonByLabel(String label)` — Get a specific radio by its label within the group. +- `void setValue(String value)` — Set the selected value by label. +- `void assertValue(String value)` — Assert the selected value by label. + +### SelectElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** FocusableElement, HasAriaLabelElement, HasInputFieldElement, HasPrefixElement, HasThemeElement, HasPlaceholderElement, HasEnabledElement, HasTooltipElement, HasValidationPropertiesElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-select"`, `String FIELD_ITEM_TAG_NAME = "vaadin-select-item"`, `String FIELD_OVERLAY_TAG_NAME = "vaadin-select-list-box"` + +**Constructors:** + +- `SelectElement(Locator locator)` — Create a new SelectElement. + +**Static factory methods:** + +- `SelectElement getByLabel(Page page, String label)` — Get the SelectElement by its accessible name, searching the entire page. +- `SelectElement getByLabel(Locator locator, String label)` — Get the SelectElement by its accessible name within a given scope. + +**Methods:** + +- `void selectItem(String item)` — Select an item by its visible label. + +### SideNavigationElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** HasLabelElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-side-nav"` + +**Constructors:** + +- `SideNavigationElement(Locator locator)` + +**Static factory methods:** + +- `SideNavigationElement getByLabel(Page page, String label)` — Get the SideNavigationElement by its label. + +**Methods:** + +- `boolean isCollapsed()` — Checks if the side nav is collapsed. +- `void assertCollapsed()` — Asserts that the side nav is collapsed. +- `void assertExpanded()` — Asserts that the side nav is expanded. +- `void assertCollapsible()` — Asserts that the side nav is collapsible. +- `void assertNotCollapsible()` — Asserts that the side nav is not collapsible. +- `SideNavigationItemElement getItem(String label)` — Gets a SideNavigationItemElement by its label text. +- `void clickItem(String label)` — Clicks an item by its label. +- `void toggle()` — Toggles the expansion state of the item. + +### SideNavigationItemElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** HasEnabledElement, HasPrefixElement, HasSuffixElement, HasLabelElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-side-nav-item"` + +**Constructors:** + +- `SideNavigationItemElement(Locator locator)` + +**Methods:** + +- `boolean isExpanded()` — Checks if the item is expanded. +- `void assertExpanded()` — Asserts that the item is expanded. +- `void assertCollapsed()` — Asserts that the item is collapsed. +- `void assertCurrent()` — Asserts that the item is current. +- `void assertNotCurrent()` — Asserts that the item is not current. +- `void toggle()` — Toggles the expansion state of the item. +- `void navigate()` + +### SplitLayoutElement `` + +PlaywrightElement for vaadin-split-layout. + +**Extends:** VaadinElement +**Implements:** HasStyleElement, HasThemeElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-split-layout"` + +**Constructors:** + +- `SplitLayoutElement(Locator locator)` — Create a new SplitLayoutElement. + +**Static factory methods:** + +- `SplitLayoutElement get(Page page)` — Get the first split layout on the page. + +**Methods:** + +- `Locator getPrimaryLocator()` — Locator for the primary content (slot="primary"). +- `Locator getSecondaryLocator()` — Locator for the secondary content (slot="secondary"). +- `Locator getHandleLocator()` — Locator for the splitter handle (shadow part="handle"). +- `void assertVertical()` — Assert that the layout orientation is vertical. +- `void assertHorizontal()` — Assert that the layout orientation is horizontal. +- `void dragSplitterBy(double deltaX, double deltaY)` — Drag the splitter by a delta offset in pixels. + +### TabElement `` + +PlaywrightElement for tabs . + +**Extends:** VaadinElement + +**Constants:** `String FIELD_PARENT_TAG_NAME = "vaadin-tabs"`, `String FIELD_TAG_NAME = "vaadin-tab"` + +**Constructors:** + +- `TabElement(Locator locator)` — Create a TabElement from an existing locator. + +**Static factory methods:** + +- `TabElement getTabByText(Locator locator, String summary)` — Get a tab by visible text within a scope. +- `TabElement getSelectedTab(Locator locator)` — Get the currently selected tab within a scope. + +**Methods:** + +- `boolean isSelected()` — Whether the tab is currently selected. +- `void select()` — Select the tab by clicking it. +- `String getLabel()` — Get the tab label text. +- `void assertSelected()` — Assert that the tab is selected. +- `void assertNotSelected()` — Assert that the tab is not selected. + +### TabSheetElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-tabsheet"` + +**Constructors:** + +- `TabSheetElement(Locator locator)` — Create a TabSheetElement from an existing locator. + +**Static factory methods:** + +- `TabSheetElement get(Page page)` — Get the first tabsheet instance on the page. + +**Methods:** + +- `void assertTabsCount(int count)` — Assert the count of tabs. +- `TabElement getTab(String label)` — Get a tab by its label. +- `TabElement getSelectedTab()` — Get the currently selected tab. +- `void selectTab(String label)` — Select a tab by label text. +- `Locator getContentLocator()` — Locator for the currently visible content panel. + +### TextAreaElement `` + +PlaywrightElement for . + +**Extends:** TextFieldElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-text-area"` + +**Constructors:** + +- `TextAreaElement(Locator locator)` — Create a new TextAreaElement. + +**Static factory methods:** + +- `TextAreaElement getByLabel(Page page, String label)` — Get the TextAreaElement by its accessible name, searching the entire page. +- `TextAreaElement getByLabel(Locator locator, String label)` — Get the TextAreaElement by its accessible name, scoped to the given locator. + +**Methods:** + +- `Locator getInputLocator()` — {@inheritDoc} + +### TextFieldElement `` + +PlaywrightElement for + +**Extends:** VaadinElement +**Implements:** HasValidationPropertiesElement, HasInputFieldElement, HasPrefixElement, HasSuffixElement, HasClearButtonElement, HasPlaceholderElement, HasAllowedCharPatternElement, HasThemeElement, FocusableElement, HasAriaLabelElement, HasEnabledElement, HasTooltipElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-text-field"`, `String MAXLENGTH_ATTRIBUTE = "maxlength"`, `String PATTERN_ATTRIBUTE = "pattern"`, `String MIN_LENGTH_ATTRIBUTE = "minLength"` + +**Constructors:** + +- `TextFieldElement(Locator locator)` — Creates a new TextFieldElement + +**Static factory methods:** + +- `TextFieldElement getByLabel(Page page, String label)` — Get the TextFieldElement by its accessible name, searching the entire page. +- `TextFieldElement getByLabel(Locator locator, String label)` — Get the TextFieldElement by its accessible name, scoped to the given locator. + +**Methods:** + +- `Integer getMinLength()` — Get the current minimum length of the text field. +- `void setMinLength(int min)` — Set the minimum length for the text field. +- `void assertMinLength(Integer min)` — Assert that the minimum length of the text field is as expected. +- `Integer getMaxLength()` — Get the current maximum length of the text field. +- `void setMaxLength(int max)` — Set the maximum length for the text field. +- `void assertMaxLength(Integer max)` — Assert that the maximum length of the text field is as expected. +- `String getPattern()` — Get the current pattern of the text field. +- `void setPattern(String pattern)` — Set the pattern for the text field. +- `void assertPattern(String pattern)` — Assert that the pattern of the text field is as expected. + +### TimePickerElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** HasInputFieldElement, HasValidationPropertiesElement, HasClearButtonElement, HasPlaceholderElement, HasThemeElement, FocusableElement, HasAriaLabelElement, HasEnabledElement, HasTooltipElement, HasLabelElement, HasHelperElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-time-picker"`, `DateTimeFormatter LOCAL_TIME = DateTimeFormatter.ofPattern("HH:mm")` + +**Constructors:** + +- `TimePickerElement(Locator locator)` — Create a new TimePickerElement. + +**Static factory methods:** + +- `TimePickerElement getByLabel(Page page, String label)` — Get the TimePickerElement by its label. +- `TimePickerElement getByLabel(Locator locator, String label)` — Get the TimePickerElement by its label within a given scope. + +**Methods:** + +- `void setValue(LocalTime time)` — Set the value using a LocalTime formatted as HH:mm. +- `LocalTime getValueAsLocalTime()` — Get the current value as a LocalTime. +- `void assertValue(LocalTime value)` — Assert that the value equals the provided time. + +### TreeGridElement + +PlaywrightElement for Vaadin Tree Grid. + +**Extends:** GridElement + +**Constants:** `String FIELD_TAG_NAME = GridElement.FIELD_TAG_NAME` + +**Constructors:** + +- `TreeGridElement(Locator locator)` — Create a new TreeGridElement. + +**Static factory methods:** + +- `TreeGridElement get(Page page)` — Get the first TreeGridElement on the page. +- `TreeGridElement get(Locator parent)` — Get the first TreeGridElement within a parent locator. +- `TreeGridElement getById(Page page, String id)` — Get a TreeGridElement by its id attribute. + +**Methods:** + +- `Optional findTreeRow(int rowIndex)` — Find the tree row at the given index, returning a TreeRowElement that exposes tree-specific state and actions. +- `boolean isRowExpanded(int rowIndex)` — Whether the row at the given index is expanded. +- `boolean isRowCollapsed(int rowIndex)` — Whether the row at the given index is collapsed (has children but is not expanded). +- `boolean isRowLeaf(int rowIndex)` — Whether the row at the given index is a leaf node (has no children). +- `int getRowLevel(int rowIndex)` — Get the hierarchy level of the row at the given index (0-based; root items are level 0). +- `int getExpandedRowCount()` — Get the number of currently visible expanded rows. +- `void expandRow(int rowIndex)` — Expand the row at the given index. +- `void collapseRow(int rowIndex)` — Collapse the row at the given index. +- `void toggleRow(int rowIndex)` — Toggle the expand/collapse state of the row at the given index. + +#### TreeGridElement.TreeRowElement + +Represents a row in a TreeGrid, extending GridElement.RowElement with tree-specific state queries and expand/collapse actions. + +- `Locator getTreeToggleLocator()` — Get the locator for the vaadin-grid-tree-toggle element in this row. +- `boolean isExpanded()` — Whether this row is expanded. +- `boolean isLeaf()` — Whether this row is a leaf node (has no children). +- `boolean isCollapsed()` — Whether this row is collapsed (has children but is not expanded). +- `int getLevel()` — Get the hierarchy level of this row (0-based; root items are level 0). +- `void expand()` — Expand this row. +- `void collapse()` — Collapse this row. +- `void toggle()` — Toggle the expand/collapse state of this row. + +### UploadElement `` + +PlaywrightElement for vaadin-upload. + +**Extends:** VaadinElement +**Implements:** HasEnabledElement, HasValidationPropertiesElement, HasThemeElement, FocusableElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-upload"`, `String FILE_ITEM_TAG_NAME = "vaadin-upload-file"` + +**Constructors:** + +- `UploadElement(Locator locator)` — Create a new UploadElement. + +**Static factory methods:** + +- `UploadElement getByButtonText(Page page, String buttonText)` — Get the UploadElement by the accessible text of its upload button. + +**Methods:** + +- `Locator getFileInputLocator()` — Locator for the native input[type=file] element. +- `Locator getUploadButtonLocator()` — Locator for the primary upload button. +- `Locator getFileItemLocator(String fileName)` — Locator for a specific file row. +- `Locator getFileStatusLocator(String fileName)` — Locator for the status cell of a given file row. +- `void uploadFiles(Path... files)` — Upload one or more files by feeding the hidden input. +- `void removeFile(String fileName)` — Remove a file from the list using the remove button. +- `void assertHasFile(String fileName)` — Assert that a file is listed in the upload file list. +- `void assertNoFile(String fileName)` — Assert that a file is not present in the upload file list. +- `void assertFileComplete(String fileName)` — Assert that a file row is marked complete. +- `void assertMaxFilesReached()` + +### VirtualListElement `` + +PlaywrightElement for . + +**Extends:** VaadinElement +**Implements:** FocusableElement, HasStyleElement + +**Constants:** `String FIELD_TAG_NAME = "vaadin-virtual-list"` + +**Constructors:** + +- `VirtualListElement(Locator locator)` — Create a new VirtualListElement. + +**Static factory methods:** + +- `VirtualListElement get(Page page)` — Get the first VirtualListElement on the page. + +**Methods:** + +- `int getRowCount()` — Get the total number of items in the list. +- `int getFirstVisibleRowIndex()` — Get the index of the first row that is at least partially visible. +- `int getLastVisibleRowIndex()` — Get the index of the last row that is at least partially visible. +- `int getVisibleRowCount()` — Get the number of currently visible rows in a single browser round-trip. +- `boolean isRowInView(int rowIndex)` — Whether the given row index is currently visible in the viewport. +- `Locator getRenderedItems()` — Get a locator matching all currently rendered child elements. +- `Locator getItemByIndex(int index)` — Get the rendered DOM element at the given virtual index. +- `Locator getItemByText(String text)` — Get a rendered item containing the given text. +- `T getItemComponent(int index, Class type)` — Get a typed component element from the rendered item at the given virtual index. +- `T getItemComponentByText(String text, Class type)` — Get a typed component element from the rendered item whose text matches. +- `T getComponent(Class type)` — Get the first typed component element found anywhere in the currently rendered items. +- `void scrollToRow(int rowIndex)` — Scroll the list so that the given row index becomes visible. +- `void scrollToStart()` — Scroll to the very beginning of the list. +- `void scrollToEnd()` — Scroll to the very end of the list. +- `void assertRowCount(int expected)` — Assert the total number of items matches the expected count. +- `void assertRowInView(int rowIndex)` — Assert that the given row index is currently visible. +- `void assertRowNotInView(int rowIndex)` — Assert that the given row index is NOT currently visible. +- `void assertFirstVisibleRow(int expected)` — Assert that the first visible row index equals the expected value. +- `void assertLastVisibleRow(int expected)` — Assert that the last visible row index equals the expected value. +- `void assertItemRendered(String text)` — Assert that an item containing the given text is currently rendered. +- `void assertEmpty()` — Assert the list has zero items. + +## Shared mixins + +Behaviours composed into elements via `implements`. An element that lists a mixin below exposes all of that mixin's methods. + +### FocusableElement + +Mixin for components that can receive keyboard focus. + +**Extends:** HasLocatorElement + +**Methods:** + +- `Locator getFocusLocator()` — The locator to focus/blur. +- `void focus()` — Focus the component. +- `void blur()` — Blur the component. +- `String getTabIndex()` — Current tab index as string (from tabIndex attribute). +- `void assertIsFocused()` — Assert that the component has focus. +- `void assertIsNotFocused()` — Assert that the component does not have focus. + +### HasAllowedCharPatternElement + +Mixin for components supporting allowedCharPattern to constrain input. + +**Extends:** HasLocatorElement + +**Methods:** + +- `String getAllowedCharPattern()` — Get the current allowedCharPattern. +- `void setAllowedCharPattern(String pattern)` — Set the allowedCharPattern. +- `void assertAllowedCharPattern(String pattern)` — Assert that the allowedCharPattern matches the expected value. + +### HasAriaLabelElement + +Mixin for components exposing an ARIA label. + +**Extends:** HasLocatorElement + +**Methods:** + +- `Locator getAriaLabelLocator()` — Locator where the aria-label is applied. +- `String getAriaLabel()` — Get the current aria-label value. +- `void assertAriaLabel(String ariaLabel)` — Assert that the aria-label matches the expected text, or is absent when null. + +### HasClearButtonElement + +Mixin for components with a clear button part. + +**Extends:** HasLocatorElement + +**Methods:** + +- `Locator getClearButtonLocator()` — Locator for the clear button (part~=clear-button). +- `void clickClearButton()` — Click the clear button. +- `boolean isClearButtonVisible()` — Whether the clear button is visible. +- `void assertClearButtonVisible()` — Assert that the clear button is visible. +- `void assertClearButtonNotVisible()` — Assert that the clear button is not visible. + +### HasEnabledElement + +Mixin for components that expose enabled/disabled state. + +**Extends:** HasLocatorElement + +**Methods:** + +- `Locator getEnabledLocator()` — Locator used to check enablement. +- `boolean isEnabled()` — Whether the component is enabled. +- `boolean isEnabled(boolean enabled)` — Whether the component's enabled state matches the expected value. +- `void assertEnabled()` — Assert that the component is enabled. +- `void assertEnabled(boolean enabled)` — Assert that the component is enabled (true) or disabled (false). +- `void assertDisabled()` — Assert that the component is disabled. + +### HasHelperElement + +Mixin for components that provide helper text via the helper slot. + +**Extends:** HasLocatorElement + +**Methods:** + +- `Locator getHelperLocator()` — Locator for the helper slot content. +- `String getHelperText()` — Text content of the helper slot. +- `void assertHelperHasText(String helperText)` — Assert that the helper slot has the expected text. + +### HasInputFieldElement + +Convenience mixin grouping common capabilities of Vaadin input fields (label, value handling, helper and styling). + +**Extends:** HasHelperElement, HasValueElement, HasStyleElement, HasLabelElement + +*Marker interface — composes the mixins listed above; no own methods.* + +### HasLabelElement + +Mixin for components that render a visible label. + +**Extends:** HasLocatorElement + +**Methods:** + +- `Locator getLabelLocator()` — Locator for the visible label element. +- `String getLabel()` — Get the label text. +- `void assertLabel(String label)` — Assert that the label text matches, or is hidden when null. + +### HasLocatorElement + +Base contract for objects that expose a Playwright Locator. + +**Methods:** + +- `Locator getLocator()` — The root locator for the component. +- `void waitForVaadinIdle()` — Block until Vaadin Flow has no active client-server exchange in flight. + +### HasPlaceholderElement + +Mixin for components that support the placeholder attribute. + +**Extends:** HasLocatorElement + +**Methods:** + +- `void setPlaceholder(String placeholder)` — Set the placeholder attribute. +- `String getPlaceholder()` — Get the current placeholder text. +- `void assertPlaceholder(String placeholder)` — Assert that the placeholder matches the expected text. + +### HasPrefixElement + +Utilities to interact with components implementing Vaadin's HasPrefix(slot="prefix"). + +**Extends:** HasLocatorElement + +**Methods:** + +- `Locator getPrefixLocator()` — Locator for the prefix slot content. +- `String getPrefixText()` — Text content of the prefix slot. +- `void assertPrefixHasText(String text)` — Assert that the prefix slot has the expected text, or is hidden when null. + +### HasStyleElement + +Mixin for components exposing styling via CSS classes. + +**Extends:** HasLocatorElement + +**Methods:** + +- `String getCssClass()` — Get the raw class attribute value. +- `void assertCssClass(String... classnames)` — Assert the component has exactly the provided class names, or no classes when null. + +### HasSuffixElement + +Utilities to interact with components implementing Vaadin's HasSuffix (slot="suffix"). + +**Extends:** HasLocatorElement + +**Methods:** + +- `Locator getSuffixLocator()` — Locator for the suffix slot content. +- `String getSuffixText()` — Text content of the suffix slot. +- `void assertSuffixHasText(String text)` — Assert that the suffix slot has the expected text, or is hidden when null. + +### HasThemeElement + +Mixin for components that support the theme attribute. + +**Extends:** HasLocatorElement + +**Methods:** + +- `String getTheme()` — Get the current theme attribute value. +- `void assertTheme(String theme)` — Assert that the theme attribute matches, or is absent when null. + +### HasTooltipElement + +Utilities to interact with components implementing Vaadin's HasTooltip the first child with role tooltip + +**Extends:** HasLocatorElement + +**Methods:** + +- `Locator getTooltipLocator()` — Locator for the tooltip content (role=tooltip). +- `String getTooltipText()` — Tooltip text content. +- `void assertTooltipHasText(String text)` + +### HasValidationPropertiesElement + +Mixin for components exposing validation state and error messages. + +**Extends:** HasLocatorElement + +**Methods:** + +- `Locator getErrorMessageLocator()` — Locator for the error message slot. +- `void assertValid()` — Assert that the component is valid (not invalid). +- `void assertInvalid()` — Assert that the component is invalid. +- `void assertErrorMessage(String errorMessage)` — Assert that the error message equals the expected text. + +### HasValueElement + +Mixin for components that expose a textual value through an input slot. + +**Extends:** HasLocatorElement + +**Methods:** + +- `Locator getInputLocator()` — Locator for the native input element inside the component. +- `String getValue()` — Get the current string value. +- `void setValue(String value)` — Set the field value by filling the input and dispatching a change event. +- `void clear()` — Clear the input value. +- `void assertValue(String value)` — Assert that the input value matches the expected string. + +## Base class + +Every element extends `VaadinElement`; these methods are available on all of them. + +### VaadinElement + +Base class for typed Playwright wrappers around Vaadin components. + +*abstract* **Implements:** HasLocatorElement + +**Constructors:** + +- `VaadinElement(Locator locator)` — Create a new VaadinElement wrapper. + +**Methods:** + +- `void click()` — Click the component root. +- `String getText()` — Get the textual content of the component root. +- `void setProperty(String name, Object value)` — Set a DOM property on the underlying element (e.g. value, disabled). +- `Object getProperty(String name)` — Get a DOM property from the underlying element. +- `boolean isVisible()` — Whether the component is visible. +- `void assertVisible()` — Assert that the component is visible. +- `void assertHidden()` — Assert that the component is hidden. +- `boolean isVisible(boolean visible)` — Whether the component's visibility matches the expected state. +- `void assertVisible(boolean visible)` — Assert the component's visibility state. +- `boolean isHidden()` — Whether the component is hidden. + diff --git a/tools/generate-api-reference.java b/tools/generate-api-reference.java new file mode 100644 index 0000000..87f17fa --- /dev/null +++ b/tools/generate-api-reference.java @@ -0,0 +1,314 @@ +///usr/bin/env jbang "$0" "$@" ; exit $? +//JAVA 21 +//DEPS com.github.javaparser:javaparser-core:3.26.4 + +// Generates skills/vaadin-playwright-test/api-reference.md — a dense, complete +// signature index of every DramaFinder element wrapper — straight from source, +// so it can never drift from the released API. +// +// Run locally: jbang tools/generate-api-reference.java +// In CI: see .github/workflows/api-reference.yml +// +// It lives in the SKILL folder on purpose: the skill is the self-contained +// artifact that travels to consumer projects, so the reference must be inside +// it (a copy in docs/ would not ship with the skill). llms.txt links to this +// same path via a raw GitHub URL. + +import com.github.javaparser.StaticJavaParser; +import com.github.javaparser.ParserConfiguration; +import com.github.javaparser.ParserConfiguration.LanguageLevel; +import com.github.javaparser.ast.CompilationUnit; +import com.github.javaparser.ast.Modifier; +import com.github.javaparser.ast.body.*; +import com.github.javaparser.ast.expr.*; +import com.github.javaparser.ast.nodeTypes.NodeWithJavadoc; +import com.github.javaparser.javadoc.Javadoc; + +import java.io.IOException; +import java.nio.file.*; +import java.util.*; +import java.util.stream.*; + +// Package-private on purpose: JBang compiles this under its hyphenated file name, +// and javac only allows a *public* top-level class to differ from the file name. +class GenerateApiReference { + + static final Path REPO = Paths.get(System.getProperty("repo.dir", ".")); + static final Path ELEMENT_DIR = REPO.resolve("src/main/java/org/vaadin/addons/dramafinder/element"); + static final Path OUT = REPO.resolve("skills/vaadin-playwright-test/api-reference.md"); + + public static void main(String[] args) throws IOException { + StaticJavaParser.getParserConfiguration().setLanguageLevel(LanguageLevel.JAVA_21); + + // Parse every top-level type, keyed by simple name. + Map> elements = new TreeMap<>(); // element wrappers (alpha) + Map> mixins = new TreeMap<>(); // element/shared/* + TypeDeclaration base = null; // VaadinElement + + List files; + try (Stream s = Files.walk(ELEMENT_DIR)) { + files = s.filter(p -> p.toString().endsWith(".java")).sorted().collect(Collectors.toList()); + } + for (Path f : files) { + // Skip the internal utils package — not part of the public test API. + if (f.getParent().getFileName().toString().equals("utils")) continue; + CompilationUnit cu = StaticJavaParser.parse(f); + for (TypeDeclaration t : cu.getTypes()) { + if (!t.isPublic()) continue; + String name = t.getNameAsString(); + if (t instanceof AnnotationDeclaration) continue; // @PlaywrightElement marker + boolean shared = f.getParent().getFileName().toString().equals("shared"); + if (shared) { mixins.put(name, t); } + else if (name.equals("VaadinElement")) { base = t; } + else { elements.put(name, t); } + } + } + + StringBuilder md = new StringBuilder(); + String version = readVersion(); + + md.append("# DramaFinder API Reference\n\n"); + md.append("> **Auto-generated from source — do not edit by hand.** "); + md.append("Regenerate with `jbang tools/generate-api-reference.java`.\n"); + md.append("> DramaFinder ").append(version).append(" — ") + .append(elements.size()).append(" element wrappers.\n\n"); + md.append("Complete public API of every DramaFinder element wrapper. Each element lists "); + md.append("the shared mixin interfaces it implements; those interfaces' methods are "); + md.append("documented once under **Shared mixins** at the end (not repeated per element). "); + md.append("Method one-liners come from Javadoc.\n\n"); + md.append("**Do not download or unzip the DramaFinder jar to discover its API — it is all here.**\n\n"); + + // Table of contents for the elements. + md.append("## Elements\n\n"); + md.append(elements.keySet().stream() + .map(n -> "[" + n + "](#" + anchor(n) + ")") + .collect(Collectors.joining(" · "))); + md.append("\n\n"); + + for (var e : elements.entrySet()) { + renderType(md, e.getValue(), 3, true); + } + + md.append("## Shared mixins\n\n"); + md.append("Behaviours composed into elements via `implements`. An element that lists a "); + md.append("mixin below exposes all of that mixin's methods.\n\n"); + for (var e : mixins.entrySet()) { + renderType(md, e.getValue(), 3, false); + } + + if (base != null) { + md.append("## Base class\n\n"); + md.append("Every element extends `VaadinElement`; these methods are available on all of them.\n\n"); + renderType(md, base, 3, false); + } + + Files.createDirectories(OUT.getParent()); + Files.writeString(OUT, md.toString()); + System.out.println("Wrote " + OUT + " (" + elements.size() + " elements, " + + mixins.size() + " mixins)"); + } + + /** Render one type: heading, tag, javadoc, hierarchy, constants, constructors, methods, nested types. */ + static void renderType(StringBuilder md, TypeDeclaration t, int level, boolean isElement) { + String name = t.getNameAsString(); + md.append("#".repeat(level)).append(" ").append(name); + String tag = tagOf(t); + if (tag != null) md.append(" `<").append(tag).append(">`"); + md.append("\n\n"); + + firstSentence(t).ifPresent(s -> md.append(s).append("\n\n")); + + // Hierarchy hints. + List ext = extendedNames(t); + List impl = implementedNames(t); + if (t instanceof ClassOrInterfaceDeclaration cid && cid.isAbstract()) { + md.append("*abstract* "); + } + if (!ext.isEmpty()) md.append("**Extends:** ").append(String.join(", ", ext)).append(" \n"); + if (!impl.isEmpty()) md.append("**Implements:** ").append(String.join(", ", impl)).append(" \n"); + if (!ext.isEmpty() || !impl.isEmpty()) md.append("\n"); + + // Public constants. + List constants = t.getFields().stream() + .filter(f -> f.isPublic() && f.isStatic() && f.isFinal()) + .flatMap(f -> f.getVariables().stream() + .map(v -> "`" + f.getElementType().asString() + " " + v.getNameAsString() + + (v.getInitializer().map(i -> " = " + i).orElse("")) + "`")) + .collect(Collectors.toList()); + if (!constants.isEmpty()) { + md.append("**Constants:** ").append(String.join(", ", constants)).append("\n\n"); + } + + // Public constructors. + List ctors = t.getConstructors().stream() + .filter(NodeWithModifiersPublic()).collect(Collectors.toList()); + if (!ctors.isEmpty()) { + md.append("**Constructors:**\n\n"); + for (ConstructorDeclaration c : ctors) { + md.append("- `").append(ctorSig(c)).append("`"); + firstSentence(c).ifPresent(s -> md.append(" — ").append(s)); + md.append("\n"); + } + md.append("\n"); + } + + // Public methods, split into static factories and instance methods. + boolean isIface = t instanceof ClassOrInterfaceDeclaration c2 && c2.isInterface(); + List methods = t.getMethods().stream() + .filter(m -> m.isPublic() || (isIface && !m.isStatic() && !m.isPrivate())) + .filter(m -> !isOverride(m)) // mixin impls / internal locators — covered by the mixin section + .collect(Collectors.toList()); + List statics = methods.stream().filter(MethodDeclaration::isStatic).collect(Collectors.toList()); + List instance = methods.stream().filter(m -> !m.isStatic()).collect(Collectors.toList()); + + if (!statics.isEmpty()) { + md.append("**Static factory methods:**\n\n"); + statics.forEach(m -> appendMethod(md, m)); + md.append("\n"); + } + if (!instance.isEmpty()) { + md.append(isElement ? "**Methods:**\n\n" : "**Methods:**\n\n"); + instance.forEach(m -> appendMethod(md, m)); + md.append("\n"); + } + if (statics.isEmpty() && instance.isEmpty() && constants.isEmpty() && ctors.isEmpty()) { + md.append("*Marker interface — composes the mixins listed above; no own methods.*\n\n"); + } + + // Public nested types (e.g. GridElement.RowElement / CellElement). + List> nested = t.getMembers().stream() + .filter(m -> m instanceof TypeDeclaration) + .map(m -> (TypeDeclaration) m) + .filter(td -> td.isPublic()) + .collect(Collectors.toList()); + for (TypeDeclaration n : nested) { + // Render nested with a qualified heading so the anchor is unique. + String saved = n.getNameAsString(); + md.append("#".repeat(level + 1)).append(" ").append(name).append(".").append(saved).append("\n\n"); + firstSentence(n).ifPresent(s -> md.append(s).append("\n\n")); + n.getMethods().stream() + .filter(m -> m.isPublic() && !isOverride(m)) + .forEach(m -> appendMethod(md, m)); + md.append("\n"); + } + } + + static void appendMethod(StringBuilder md, MethodDeclaration m) { + md.append("- `").append(methodSig(m)).append("`"); + firstSentence(m).ifPresent(s -> md.append(" — ").append(s)); + md.append("\n"); + } + + // ---- signature helpers ------------------------------------------------- + + static String methodSig(MethodDeclaration m) { + return m.getType().asString() + " " + m.getNameAsString() + "(" + params(m.getParameters()) + ")"; + } + + static String ctorSig(ConstructorDeclaration c) { + return c.getNameAsString() + "(" + params(c.getParameters()) + ")"; + } + + static String params(List ps) { + return ps.stream() + .map(p -> p.getType().asString() + (p.isVarArgs() ? "..." : "") + " " + p.getNameAsString()) + .collect(Collectors.joining(", ")); + } + + // ---- annotation / hierarchy helpers ------------------------------------ + + /** Resolve the @PlaywrightElement tag, following constant references within the same type. */ + static String tagOf(TypeDeclaration t) { + var ann = t.getAnnotationByName("PlaywrightElement"); + if (ann.isEmpty()) return null; + AnnotationExpr a = ann.get(); + Expression value = null; + if (a instanceof SingleMemberAnnotationExpr s) value = s.getMemberValue(); + else if (a instanceof NormalAnnotationExpr n) { + value = n.getPairs().stream().filter(p -> p.getNameAsString().equals("value")) + .map(MemberValuePair::getValue).findFirst().orElse(null); + } + return resolveString(t, value); + } + + /** Best-effort constant folding: string literal, or a `FIELD` / `Type.FIELD` reference to a local constant. */ + static String resolveString(TypeDeclaration t, Expression value) { + if (value == null) return null; + if (value.isStringLiteralExpr()) return value.asStringLiteralExpr().getValue(); + String constName = null; + if (value.isNameExpr()) constName = value.asNameExpr().getNameAsString(); + else if (value.isFieldAccessExpr()) constName = value.asFieldAccessExpr().getNameAsString(); + if (constName != null) { + for (FieldDeclaration f : t.getFields()) { + for (VariableDeclarator v : f.getVariables()) { + if (v.getNameAsString().equals(constName) && v.getInitializer().isPresent() + && v.getInitializer().get().isStringLiteralExpr()) { + return v.getInitializer().get().asStringLiteralExpr().getValue(); + } + } + } + } + return null; // unresolved constant from another class — omit rather than print noise + } + + static List extendedNames(TypeDeclaration t) { + if (t instanceof ClassOrInterfaceDeclaration cid) { + return cid.getExtendedTypes().stream().map(x -> x.getNameAsString()).collect(Collectors.toList()); + } + return List.of(); + } + + static List implementedNames(TypeDeclaration t) { + if (t instanceof ClassOrInterfaceDeclaration cid) { + var list = cid.isInterface() ? cid.getExtendedTypes() : cid.getImplementedTypes(); + if (cid.isInterface()) return List.of(); // handled via extends for interfaces + return list.stream().map(x -> x.getNameAsString()).collect(Collectors.toList()); + } + return List.of(); + } + + static boolean isOverride(MethodDeclaration m) { + return m.getAnnotationByName("Override").isPresent(); + } + + static java.util.function.Predicate NodeWithModifiersPublic() { + return c -> c.getModifiers().contains(Modifier.publicModifier()); + } + + // ---- javadoc ----------------------------------------------------------- + + static Optional firstSentence(NodeWithJavadoc n) { + Optional jd = n.getJavadoc(); + if (jd.isEmpty()) return Optional.empty(); + String text = jd.get().getDescription().toText(); + if (text == null || text.isBlank()) return Optional.empty(); + // Collapse whitespace, stop at the first blank line (before

details). + text = text.replaceAll("\\s+", " ").trim(); + // Strip leftover inline-tag braces that toText may keep. + text = text.replaceAll("\\{@\\w+\\s+([^}]+)}", "$1"); + // Truncate at the first real sentence end, skipping "e.g." / "i.e." abbreviations. + int from = 0; + while (true) { + int dot = text.indexOf(". ", from); + if (dot < 0) break; + String before = text.substring(0, dot); + if (before.endsWith("e.g") || before.endsWith("i.e")) { from = dot + 2; continue; } + text = text.substring(0, dot + 1); + break; + } + return Optional.of(text.trim()); + } + + static String anchor(String name) { + return name.toLowerCase(Locale.ROOT).replaceAll("[^a-z0-9]+", ""); + } + + static String readVersion() { + try { + String pom = Files.readString(REPO.resolve("pom.xml")); + var m = java.util.regex.Pattern.compile("([^<]+)").matcher(pom); + if (m.find()) return m.group(1); // first is the project version + } catch (IOException ignored) {} + return ""; + } +}