Drama Finder

Documentation

The documentation can be found in this repository and also deployed on https://parttio-dramafinder.mintlify.app/ if you find some errors please file an issue.

Usage

Drama Finder is a set of helper classes to test a Vaadin application using Playwright. It gives you access to a list of assertions and actions you can do for our components.

For example:

@Test
public void testTooltip() {
    // get a text that has an accessible name (label or aria label,...) equals to text field
    TextFieldElement textfield = TextFieldElement.getByLabel(page, "Textfield");
    // assert that is visible
    textfield.assertVisible();
    // assert that the textfield has a tooltip
    textfield.assertTooltipHasText("Tooltip for textfield");
}

It also gives you some inner locators.

@Test
public void testHelper() {
    // get a text that has an accessible name (label or aria label,...) equals to text field
    TextFieldElement textfield = TextFieldElement.getByLabel(page, "TextField with helper component");
    // Use the helperLocator to get the TextField added as a helper component
    TextFieldElement helperComponent = new TextFieldElement(textfield.getHelperLocator());
    // You can use Playwright assertions
    assertThat(helperComponent.getHelperLocator()).hasText("Internal helper");
    // or reuse the locator with the API

}

Getting started

Add the addon as a test dependency.

<dependency>
    <groupId>org.vaadin.addons</groupId>
    <artifactId>dramafinder</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <scope>test</scope>
</dependency>

The Drama Finder element classes are built around a plain Playwright Page (or Locator). They have no dependency on any particular test base class, so you can use them with whatever Playwright setup you already have. Just hand a Page to the factory helpers (e.g. getByLabel) or to an element constructor.

The simplest way to get started is to let Spring Boot start the server for you with @SpringBootTest(webEnvironment = RANDOM_PORT) and manage the Playwright Page yourself:

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
public class SimpleExampleViewIT {

    @LocalServerPort
    private int port;

    Playwright playwright;
    Browser browser;
    Page page;

    @BeforeEach
    public void setup() {
        playwright = Playwright.create();
        browser = playwright.chromium().launch();
        page = browser.newPage();
        page.navigate(String.format("http://localhost:%d/", port));
    }

    @AfterEach
    public void tearDown() {
        browser.close();
        playwright.close();
    }

    @Test
    public void testTooltip() {
        // The only thing the element API needs is a Playwright Page
        TextFieldElement textfield = TextFieldElement.getByLabel(page, "Textfield");
        textfield.assertVisible();
        textfield.assertTooltipHasText("Tooltip for textfield");
    }
}

Letting @SpringBootTest start the server is not the only option. You can also write the tests as plain integration tests (e.g. classes ending in IT.java run by the maven-failsafe-plugin) and start/stop the server separately with Maven — for example using the spring-boot:start and spring-boot:stop goals bound to the pre-integration-test / post-integration-test phases — before the ITs execute. In that case the test simply navigates to the externally started server's URL. Either way, the element API only ever needs a Playwright Page, so you are free to obtain it however suits your project.

Optional: AbstractBasePlaywrightIT convenience base class

If you don't already have a Playwright setup, Drama Finder ships an optional AbstractBasePlaywrightIT base class that handles the boilerplate for you: creating and closing the Playwright/Browser, opening a fresh page and navigating to your view before each test, waiting for Vaadin to finish loading, sensible default timeouts, and headless toggling (via the headless system property or HEADLESS environment variable). Extending it is purely a convenience — it is never required to use the element API.

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
public class SimpleExampleViewIT extends AbstractBasePlaywrightIT {

    @LocalServerPort
    private int port;

    @Override
    public String getUrl() {
        return String.format("http://localhost:%d/", port);
    }

    @Test
    public void testTooltip() {
        TextFieldElement textfield = TextFieldElement.getByLabel(page, "Textfield");
        textfield.assertVisible();
        textfield.assertTooltipHasText("Tooltip for textfield");
    }
}

Note

The API is in early stage of development.

If you notice something missing please create a ticket or a Pull Request.

The tests in the demo application is not meant to be a best practice since it's primarly here to test the API. For example it will test the getter like getMinLength without waiting which is a bad practice.

@Test
public void testPattern() {
    // use Playwright assertion to wait
    textfield.assertMinLength(6);
    // doesn't wait but will test `getMinLength`, use the previous in your code
    assertEquals(6, textfield.getMinLength());
}

Development instructions

Starting the test/demo server:

mvn spring-boot:run

This deploys demo at http://localhost:8080 The demo is only here to run the test

Javadoc

Public APIs in the dramafinder module are documented with concise Javadoc:

• Element classes include a short summary referencing the underlying Vaadin tag (e.g., vaadin-text-field) and any noteworthy behaviors.
• Public methods document parameters, return values, and null semantics.
• Factory helpers (e.g., getByLabel) note the ARIA role used to locate the element.

Running tests

To run the unit tests, execute the following command:

mvn test

Integration tests

The integration tests are built using Spring Boot, Playwright, and Axe-core. The tests are located in files ending with IT.java in the sortable-layout-demo module. The tests are run with the maven-failsafe-plugin when the it profile is activated.

To run the integration tests, execute the following command:

mvn -Pit verify

To debug the UI with a visible browser, disable headless mode using either the headless property or the debug-ui profile:

# system property
mvn -Dit.test=ContextMenuViewIT -Dheadless=false verify

# convenient profile
mvn -Pdebug-ui -Dit.test=ContextMenuViewIT verify

You will need to add the profile in your pom.xml:

<profile>
    <id>debug-ui</id>
    <properties>
        <headless>false</headless>
    </properties>
</profile>

Cutting a release

Before cutting a release, make sure the build passes properly locally and in GitHub Actions based verification build.

To tag a release and increment versions, issue:

mvn release:prepare release:clean

Answer questions, defaults most often fine. Note that release:perform is not needed as there is a GitHub Action is set up build and to push release to Maven Central automatically.

Directory will automatically pick up new releases within about half an hour, but if browser or Vaadin version support change, be sure to adjust the metadata in Vaadin Directory UI.