Quick Start

Get started with Drama Finder in minutes with real examples

This guide walks you through creating your first Playwright tests for Vaadin components using Drama Finder.

Basic Test Setup

1. Create a base test class

   Extend AbstractBasePlaywrightIT to set up Playwright for your tests:

   package com.example.tests;
   
   import org.springframework.boot.test.context.SpringBootTest;
   import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
   import org.springframework.boot.test.web.server.LocalServerPort;
   import org.vaadin.addons.dramafinder.AbstractBasePlaywrightIT;
   
   @SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
   public abstract class BaseIT extends AbstractBasePlaywrightIT {
   
       @LocalServerPort
       private int port;
   
       @Override
       public String getUrl() {
           return String.format("http://localhost:%d/", port);
       }
   }
   

   The AbstractBasePlaywrightIT class handles browser lifecycle, page setup, and Vaadin synchronization automatically.

2. Write your first test

   Create a test class for a simple form:

   package com.example.tests;
   
   import org.junit.jupiter.api.Test;
   import org.springframework.boot.test.context.SpringBootTest;
   import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
   import org.vaadin.addons.dramafinder.element.TextFieldElement;
   
   @SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
   public class SimpleExampleIT extends BaseIT {
   
       @Test
       public void testTooltip() {
           // Get a text field by its accessible label
           TextFieldElement textfield = TextFieldElement.getByLabel(page, "Textfield");
           
           // Assert that it's visible
           textfield.assertVisible();
           
           // Assert that the textfield has a tooltip
           textfield.assertTooltipHasText("Tooltip for textfield");
       }
   }
   
3. Run the test

   Execute your integration test:

   mvn -Dit.test=SimpleExampleIT verify
   

Working with Text Fields

Drama Finder provides comprehensive support for Vaadin text fields with intuitive methods:

Basic Operations

// Find by label
TextFieldElement textfield = TextFieldElement.getByLabel(page, "Username");

// Assert visibility
textfield.assertVisible();

// Set and verify value
textfield.setValue("john.doe");
textfield.assertValue("john.doe");

// Clear the field
textfield.clear();
textfield.assertValue("");

// Test required field validation
TextFieldElement textfield = TextFieldElement.getByLabel(page, "Email");
textfield.setValue("");
textfield.assertInvalid();

assertThat(textfield.getErrorMessageLocator()).hasText("Field is required");

// Test pattern validation
TextFieldElement codeField = TextFieldElement.getByLabel(page, "Validated Textfield");
codeField.setValue("123");
codeField.assertInvalid();
codeField.assertErrorMessage("Minimum length is 6 characters");

codeField.setValue("1238456");
codeField.assertValid();

TextFieldElement textfield = TextFieldElement.getByLabel(page, "Validated Textfield");

// Verify attributes
textfield.assertPattern("\\d{7}");
textfield.assertMinLength(6);
textfield.assertMaxLength(7);
textfield.assertAllowedCharPattern("[0-8]");

// Get attribute values
String pattern = textfield.getPattern();
Integer minLength = textfield.getMinLength();
Integer maxLength = textfield.getMaxLength();

TextFieldElement textfield = TextFieldElement.getByLabel(page, "Textfield");

// Verify helper text
textfield.assertHelperHasText("Helper text");
String helperText = textfield.getHelperText();

// Access helper component
TextFieldElement fieldWithHelper = TextFieldElement.getByLabel(page, "TextField with helper component");
TextFieldElement helperComponent = new TextFieldElement(fieldWithHelper.getHelperLocator());
helperComponent.assertVisible();
helperComponent.assertHelperHasText("Internal helper");

Working with Buttons

Button elements support finding by text and provide assertion methods:

import org.vaadin.addons.dramafinder.element.ButtonElement;
import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;

// Find button by text
ButtonElement button = ButtonElement.getByText(page, "Click me");

// Assert enabled/disabled state
button.assertEnabled();

// Click and verify result
button.click();
assertThat(page.getByText("Button clicked!")).isVisible();

// Check theme
ButtonElement saveButton = ButtonElement.getByText(page, "Save");
saveButton.assertTheme("success");

// Verify CSS classes
button.assertCssClass("custom-button");

// Test focus
button.focus();
button.assertIsFocused();

Working with Grids

Drama Finder provides powerful Grid testing capabilities:

Basic Grid Operations

import org.vaadin.addons.dramafinder.element.GridElement;

// Find grid by ID
GridElement grid = GridElement.getById(page, "basic-grid");
grid.assertVisible();

// Verify row and column counts
int totalRows = grid.getTotalRowCount();
int visibleRows = grid.getRenderedRowCount();
int columns = grid.getColumnCount();

// Get header text
List<String> headers = grid.getHeaderCellContents();
// Returns: ["First Name", "Last Name", "Email"]

// Access specific cells
var firstCell = grid.findCell(0, 0);  // row 0, column 0
assertThat(firstCell.get().getCellContentLocator()).hasText("First1");

// Find cell by header text
var emailCell = grid.findCell(0, "Email");
assertThat(emailCell.get().getCellContentLocator()).hasText("[e-mail]");

// Test lazy-loaded grid
GridElement lazyGrid = GridElement.getById(page, "lazy-grid");
assertEquals(10000, lazyGrid.getTotalRowCount());

// Scroll to distant row
var row = lazyGrid.findRow(9000);
assertThat(row.get().getCell(0).getCellContentLocator()).hasText("First9001");

Common Assertions

All Drama Finder elements support common assertions:

TextFieldElement field = TextFieldElement.getByLabel(page, "Username");

// Visibility
field.assertVisible();
field.assertHidden();

// Enabled/Disabled
field.assertEnabled();
field.assertDisabled();

// Focus
field.assertIsFocused();
field.assertIsNotFocused();

// ARIA attributes
field.assertAriaLabel("Username field");

// Theme
field.assertTheme("small");

// CSS classes
field.assertCssClass("custom-field");

// Prefix and suffix
field.assertPrefixHasText("$");
field.assertSuffixHasText("USD");

Element Locators

Drama Finder provides access to internal locators for advanced scenarios:

TextFieldElement textfield = TextFieldElement.getByLabel(page, "Search");

// Component root locator
Locator root = textfield.getLocator();

// Input element locator
Locator input = textfield.getInputLocator();

// Helper text locator
Locator helper = textfield.getHelperLocator();

// Error message locator
Locator error = textfield.getErrorMessageLocator();

// Prefix and suffix locators
Locator prefix = textfield.getPrefixLocator();
Locator suffix = textfield.getSuffixLocator();

// Use with Playwright assertions
assertThat(input).hasAttribute("placeholder", "Enter search term");
assertThat(helper).hasText("Search by name or email");

Factory Methods

Elements provide flexible factory methods for different lookup strategies:

By Label (Page-level)

// Find by accessible label on the page
TextFieldElement field = TextFieldElement.getByLabel(page, "Email");
ButtonElement button = ButtonElement.getByText(page, "Submit");

// Find within a specific container
Locator form = page.locator("#user-form");
TextFieldElement field = TextFieldElement.getByLabel(form, "Email");
ButtonElement button = ButtonElement.getByText(form, "Submit");

// Find grid by element ID
GridElement grid = GridElement.getById(page, "users-grid");

// Wrap an existing locator
Locator existingLocator = page.locator("vaadin-text-field").first();
TextFieldElement field = new TextFieldElement(existingLocator);

Testing Patterns

Pattern: Testing Form Validation

@Test
public void testFormValidation() {
    TextFieldElement email = TextFieldElement.getByLabel(page, "Email");
    TextFieldElement password = TextFieldElement.getByLabel(page, "Password");
    ButtonElement submit = ButtonElement.getByText(page, "Register");

    // Empty form should be invalid
    submit.click();
    email.assertInvalid();
    password.assertInvalid();

    // Fill with valid data
    email.setValue("[e-mail]");
    password.setValue("SecurePass123");
    
    email.assertValid();
    password.assertValid();
    
    submit.click();
    assertThat(page.getByText("Registration successful")).isVisible();
}

Pattern: Testing Dynamic Content

@Test
public void testDynamicContent() {
    ButtonElement loadButton = ButtonElement.getByText(page, "Load Data");
    GridElement grid = GridElement.getById(page, "data-grid");

    // Initially empty
    assertEquals(0, grid.getTotalRowCount());

    // Load data
    loadButton.click();

    // Verify data loaded
    assertTrue(grid.getTotalRowCount() > 0);
    var firstCell = grid.findCell(0, "Name");
    assertThat(firstCell.get().getCellContentLocator()).not().isEmpty();
}

Pattern: Testing Clear Button

@Test
public void testClearButton() {
    TextFieldElement field = TextFieldElement.getByLabel(page, "Search");
    
    // Clear button hidden when empty
    field.assertClearButtonNotVisible();
    
    // Clear button appears with content
    field.setValue("search term");
    field.assertClearButtonVisible();
    
    // Clear removes content
    field.clickClearButton();
    field.assertValue("");
    field.assertClearButtonNotVisible();
}

Best Practices

Key recommendations for writing Drama Finder tests:

1. Use accessible names: Prefer getByLabel() and getByText() over CSS selectors
2. Wait automatically: Drama Finder assertions auto-retry, avoiding flaky tests
3. Scope your lookups: Use scoped factory methods when testing complex layouts
4. Test validation states: Always verify both valid and invalid states
5. Use assertion methods: Prefer assertVisible() over raw Playwright assertions when available

Drama Finder automatically handles Vaadin’s shadow DOM and component lifecycle, so you don’t need to add manual waits or complex selectors.

Next Steps

Element Reference

Explore all available element types and methods

Testing Patterns

Learn advanced testing patterns and best practices

API Documentation

View complete API reference

GitHub Examples

Browse real-world test examples