> ## Documentation Index
> Fetch the complete documentation index at: https://parttio-dramafinder-4.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Create a base test class">
    Extend `AbstractBasePlaywrightIT` to set up Playwright for your tests:

    ```java theme={null}
    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);
        }
    }
    ```

    <Note>
      The `AbstractBasePlaywrightIT` class handles browser lifecycle, page setup, and Vaadin synchronization automatically.
    </Note>
  </Step>

  <Step title="Write your first test">
    Create a test class for a simple form:

    ```java theme={null}
    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");
        }
    }
    ```
  </Step>

  <Step title="Run the test">
    Execute your integration test:

    ```bash theme={null}
    mvn -Dit.test=SimpleExampleIT verify
    ```
  </Step>
</Steps>

## Working with Text Fields

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

<CodeGroup>
  ```java Basic Operations theme={null}
  // 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("");
  ```

  ```java Validation theme={null}
  // 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();
  ```

  ```java Attributes and Properties theme={null}
  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();
  ```

  ```java Helper Text and Components theme={null}
  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");
  ```
</CodeGroup>

## Working with Buttons

Button elements support finding by text and provide assertion methods:

```java theme={null}
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:

<CodeGroup>
  ```java Basic Grid Operations theme={null}
  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();
  ```

  ```java Headers and Cells theme={null}
  // 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("person1@example.com");
  ```

  ```java Lazy Loading theme={null}
  // 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");
  ```
</CodeGroup>

## Common Assertions

All Drama Finder elements support common assertions:

```java theme={null}
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:

```java theme={null}
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:

<CodeGroup>
  ```java By Label (Page-level) theme={null}
  // Find by accessible label on the page
  TextFieldElement field = TextFieldElement.getByLabel(page, "Email");
  ButtonElement button = ButtonElement.getByText(page, "Submit");
  ```

  ```java By Label (Scoped) theme={null}
  // Find within a specific container
  Locator form = page.locator("#user-form");
  TextFieldElement field = TextFieldElement.getByLabel(form, "Email");
  ButtonElement button = ButtonElement.getByText(form, "Submit");
  ```

  ```java By ID theme={null}
  // Find grid by element ID
  GridElement grid = GridElement.getById(page, "users-grid");
  ```

  ```java By Locator theme={null}
  // Wrap an existing locator
  Locator existingLocator = page.locator("vaadin-text-field").first();
  TextFieldElement field = new TextFieldElement(existingLocator);
  ```
</CodeGroup>

## Testing Patterns

<Accordion title="Pattern: Testing Form Validation">
  ```java theme={null}
  @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("user@example.com");
      password.setValue("SecurePass123");
      
      email.assertValid();
      password.assertValid();
      
      submit.click();
      assertThat(page.getByText("Registration successful")).isVisible();
  }
  ```
</Accordion>

<Accordion title="Pattern: Testing Dynamic Content">
  ```java theme={null}
  @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();
  }
  ```
</Accordion>

<Accordion title="Pattern: Testing Clear Button">
  ```java theme={null}
  @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();
  }
  ```
</Accordion>

## Best Practices

<Note>
  **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
</Note>

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Element Reference" icon="book" href="/elements">
    Explore all available element types and methods
  </Card>

  <Card title="Testing Patterns" icon="code" href="/patterns">
    Learn advanced testing patterns and best practices
  </Card>

  <Card title="API Documentation" icon="file-code" href="/api">
    View complete API reference
  </Card>

  <Card title="GitHub Examples" icon="github" href="https://github.com/parttio/dramafinder/tree/main/src/test/java">
    Browse real-world test examples
  </Card>
</CardGroup>