--- name: DramaFinder Testing Guidelines description: Best practices for writing Playwright integration tests in this project. --- # Testing Guidelines ## Guiding Principles - **Page Object Model (POM):** All tests should use the Page Object Model. Interactions with the UI should be encapsulated in page objects, and tests should only call methods on these page objects. This isolates the tests from changes in the UI. The page objects are the drama finder elements in `src/main/java/org/vaadin/addons/dramafinder/element`. - **One Test, One Assert:** Each test method should test a single, specific piece of functionality. This makes tests easier to understand and debug. - **Independent and Isolated Tests:** Tests should not depend on the state of other tests. Each test should be able to run independently and in any order. Use `@BeforeEach` and `@AfterEach` to set up and tear down the test environment. - **Descriptive Test Names:** Test names should clearly describe what they are testing. A good test name should make it obvious what the test is doing without having to read the test code. ## Locators - **Prefer user-facing attributes:** When locating elements, prefer user-facing attributes like text content, `aria-label`, `aria-role`, or `data-testid`. These are less likely to change than CSS classes or XPath expressions. - **Avoid implementation-specific locators:** Avoid using locators that are tied to the implementation of a component, such as CSS classes or `id` attributes that are generated by the framework. ## Assertions - **Use Playwright Assertions:** Use the assertions provided by Playwright (`assertThat(page)`) and the `dramafinder` elements whenever possible. These assertions are designed to work with Playwright's auto-waiting mechanism and are more reliable than custom assertions. - **Assert on the user-visible state:** Assertions should check for the user-visible state of the application, not the internal state of a component. For example, instead of asserting that a component has a certain CSS class, assert that it is visible or has the correct text. ## Interactions - **Use the drama finder elements:** All interactions with the UI should be done through the `dramafinder` elements. These elements provide a high-level API for interacting with Vaadin components and handle waiting for elements to be ready automatically. - **Avoid `sleep()`:** Do not use `Thread.sleep()` to wait for elements to appear. Playwright's auto-waiting mechanism handles this automatically. If you need to wait for something specific, use the appropriate `waitFor` method from Playwright or a custom wait condition. ## Test Organization - **Group tests by view:** Tests should be grouped by the view they are testing. For example, all tests for the `LoginView` should be in a class named `LoginViewIT`. ## Debugging - **Use Playwright's debugging tools:** Playwright provides several tools for debugging tests, such as the Playwright Inspector and tracing. Use these tools to debug failing tests. - **Enable tracing on CI:** To help debug failures on CI, you can enable tracing in the Playwright configuration. This will record a trace of the test execution that can be viewed later. ## CI/CD - **Run tests in headless mode:** On CI, tests should be run in headless mode to improve performance and stability. - **Run tests in parallel:** To speed up test execution, run tests in parallel. Make sure your tests are independent and isolated so they can be run in any order.