--- name: playwright-java-5c656b214a25 description: "Scaffold, write, debug, and enhance enterprise-grade Playwright E2E tests in Java using Page Object Model, JUnit 5, Allure reporting, and parallel execution." category: test-automation risk: safe source: community date_added: "2025-03-08" author: amalsam18 tags: [playwright, java, e2e-testing, junit5, page-object-model, allure, selenium-alternative] tools: [claude, cursor,antigravity] --- # Playwright Java – Advanced Test Automation ## Overview This skill produces production-quality, enterprise-grade Playwright Java test code. It enforces the Page Object Model (POM), strict locator strategies, thread-safe parallel execution, and full Allure reporting integration. Targets Java 17+ and Playwright 1.44+. Supporting reference files are available for deeper topics: | Topic | File | |-------|------| | Maven POM, ConfigReader, Docker/CI setup | `references/config.md` | | Component pattern, dropdowns, uploads, waits | `references/page-objects.md` | | Full assertion API, soft assertions, visual testing | `references/assertions.md` | | Fixtures, test data factory, auth state, retry | `references/fixtures.md` | | Drop-in base class templates | `templates/BaseTest.java`, `templates/BasePage.java` | --- ## When to Use This Skill - Use when scaffolding a new Playwright Java project from scratch - Use when writing Page Object classes or JUnit 5 test classes - Use when the user asks about cross-browser testing, parallel execution, or Allure reports - Use when fixing flaky tests or replacing `Thread.sleep()` with proper waits - Use when setting up Playwright in CI/CD pipelines (GitHub Actions, Jenkins, Docker) - Use when combining API calls and UI assertions in a single test (hybrid testing) - Use when the user mentions "POM pattern", "BrowserContext", "Playwright fixtures", or "traces" --- ## How It Works ### Step 1: Decide the Approach Use this matrix to pick the right pattern before writing any code: | User Request | Approach | |---|---| | New project from scratch | Full scaffold — see `references/config.md` | | Single feature test | POM page class + JUnit5 test class | | API + UI hybrid | `APIRequestContext` alongside `Page` | | Cross-browser | `@MethodSource` parameterized over browser names | | Flaky test fix | Replace `sleep` with `waitFor` / `waitForResponse` | | CI integration | `playwright install --with-deps` in pipeline | | Parallel execution | `junit-platform.properties` + `ThreadLocal` | | Rich reporting | Allure + Playwright trace + video recording | --- ### Step 2: Scaffold the Project Structure Always use this layout when creating a new project: ``` src/ ├── test/ │ ├── java/com/company/tests/ │ │ ├── base/ │ │ │ ├── BaseTest.java ← templates/BaseTest.java │ │ │ └── BasePage.java ← templates/BasePage.java │ │ ├── pages/ │ │ │ └── LoginPage.java │ │ ├── tests/ │ │ │ └── LoginTest.java │ │ ├── utils/ │ │ │ ├── TestDataFactory.java │ │ │ └── WaitUtils.java │ │ └── config/ │ │ └── ConfigReader.java │ └── resources/ │ ├── test.properties │ ├── junit-platform.properties │ └── testdata/users.json pom.xml ``` --- ### Step 3: Set Up Thread-Safe BaseTest ```java public class BaseTest { protected static ThreadLocal playwrightTL = new ThreadLocal<>(); protected static ThreadLocal browserTL = new ThreadLocal<>(); protected static ThreadLocal contextTL = new ThreadLocal<>(); protected static ThreadLocal pageTL = new ThreadLocal<>(); protected Page page() { return pageTL.get(); } @BeforeEach void setUp() { Playwright playwright = Playwright.create(); playwrightTL.set(playwright); Browser browser = resolveBrowser(playwright).launch( new BrowserType.LaunchOptions() .setHeadless(ConfigReader.isHeadless())); browserTL.set(browser); BrowserContext context = browser.newContext(new Browser.NewContextOptions() .setViewportSize(1920, 1080) .setRecordVideoDir(Paths.get("target/videos/")) .setLocale("en-US")); context.tracing().start(new Tracing.StartOptions() .setScreenshots(true).setSnapshots(true)); contextTL.set(context); pageTL.set(context.newPage()); } @AfterEach void tearDown(TestInfo testInfo) { String name = testInfo.getDisplayName().replaceAll("[^a-zA-Z0-9]", "_"); contextTL.get().tracing().stop(new Tracing.StopOptions() .setPath(Paths.get("target/traces/" + name + ".zip"))); pageTL.get().close(); contextTL.get().close(); browserTL.get().close(); playwrightTL.get().close(); } private BrowserType resolveBrowser(Playwright pw) { return switch (System.getProperty("browser", "chromium").toLowerCase()) { case "firefox" -> pw.firefox(); case "webkit" -> pw.webkit(); default -> pw.chromium(); }; } } ``` --- ### Step 4: Build Page Object Classes ```java public class LoginPage extends BasePage { // Declare ALL locators as fields — never inline in action methods private final Locator emailInput; private final Locator passwordInput; private final Locator loginButton; private final Locator errorMessage; public LoginPage(Page page) { super(page); emailInput = page.getByLabel("Email address"); passwordInput = page.getByLabel("Password"); loginButton = page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Sign in")); errorMessage = page.getByTestId("login-error"); } @Override protected String getUrl() { return "/login"; } // Navigation methods return the next Page Object — enables fluent chaining public DashboardPage loginAs(String email, String password) { fill(emailInput, email); fill(passwordInput, password); clickAndWaitForNav(loginButton); return new DashboardPage(page); } public LoginPage loginExpectingError(String email, String password) { fill(emailInput, email); fill(passwordInput, password); loginButton.click(); errorMessage.waitFor(); return this; } public String getErrorMessage() { return errorMessage.textContent(); } } ``` --- ### Step 5: Write Tests with Allure Annotations ```java @ExtendWith(AllureJunit5.class) class LoginTest extends BaseTest { private LoginPage loginPage; @BeforeEach void openLoginPage() { loginPage = new LoginPage(page()); loginPage.navigate(); } @Test @Severity(SeverityLevel.BLOCKER) @DisplayName("Valid credentials redirect to dashboard") void shouldLoginWithValidCredentials() { User user = TestDataFactory.getDefaultUser(); DashboardPage dash = loginPage.loginAs(user.email(), user.password()); assertThat(page()).hasURL(Pattern.compile(".*/dashboard")); assertThat(dash.getWelcomeBanner()).containsText("Welcome, " + user.firstName()); } @Test void shouldShowErrorOnInvalidCredentials() { loginPage.loginExpectingError("bad@test.com", "wrongpass"); SoftAssertions softly = new SoftAssertions(); softly.assertThat(loginPage.getErrorMessage()).contains("Invalid email or password"); softly.assertThat(page()).hasURL(Pattern.compile(".*/login")); softly.assertAll(); } @ParameterizedTest @MethodSource("provideInvalidCredentials") void shouldRejectInvalidCredentials(String email, String password, String expectedError) { loginPage.loginExpectingError(email, password); assertThat(loginPage.getErrorMessage()).containsText(expectedError); } static Stream provideInvalidCredentials() { return Stream.of( Arguments.of("", "password123", "Email is required"), Arguments.of("user@test.com", "", "Password is required"), Arguments.of("notanemail", "pass", "Invalid email format") ); } } ``` --- ## Examples ### Example 1: API + UI Hybrid Test ```java @Test void shouldDisplayNewlyCreatedOrder() { // Arrange via API — faster than navigating through UI APIRequestContext api = page().context().request(); APIResponse response = api.post("/api/orders", RequestOptions.create() .setHeader("Authorization", "Bearer " + authToken) .setData(Map.of("productId", "SKU-001", "quantity", 2))); assertThat(response).isOK(); String orderId = new JsonParser().parse(response.text()) .getAsJsonObject().get("id").getAsString(); OrdersPage orders = new OrdersPage(page()); orders.navigate(); assertThat(orders.getOrderRowById(orderId)).isVisible(); } ``` ### Example 2: Network Mocking ```java @Test void shouldHandleApiFailureGracefully() { page().route("**/api/products", route -> route.fulfill( new Route.FulfillOptions() .setStatus(503) .setBody("{\"error\":\"Service Unavailable\"}") .setContentType("application/json"))); ProductsPage products = new ProductsPage(page()); products.navigate(); assertThat(products.getErrorBanner()) .hasText("We're having trouble loading products. Please try again."); } ``` ### Example 3: Parallel Cross-Browser Test ```java @ParameterizedTest @MethodSource("browsers") void shouldRenderCheckoutOnAllBrowsers(String browserName) { System.setProperty("browser", browserName); new CheckoutPage(page()).navigate(); assertThat(page().locator(".checkout-form")).isVisible(); } static Stream browsers() { return Stream.of("chromium", "firefox", "webkit"); } ``` ### Example 4: Parallel Execution Config ```properties # src/test/resources/junit-platform.properties junit.jupiter.execution.parallel.enabled=true junit.jupiter.execution.parallel.mode.default=concurrent junit.jupiter.execution.parallel.config.strategy=fixed junit.jupiter.execution.parallel.config.fixed.parallelism=4 ``` ### Example 5: GitHub Actions CI Pipeline ```yaml - name: Install Playwright browsers run: mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="install --with-deps" - name: Run tests run: mvn test -Dbrowser=${{ matrix.browser }} -Dheadless=true - name: Upload traces on failure uses: actions/upload-artifact@v4 if: failure() with: name: playwright-traces path: target/traces/ - name: Upload Allure results uses: actions/upload-artifact@v4 if: always() with: name: allure-results path: target/allure-results/ ``` --- ## Best Practices - ✅ Use `ThreadLocal` for every parallel-safe test suite - ✅ Declare all `Locator` fields at the top of the Page Object class - ✅ Return the next Page Object from navigation methods (fluent chaining) - ✅ Use `assertThat(locator)` — it auto-retries until timeout - ✅ Use `getByRole`, `getByLabel`, `getByTestId` as first-choice locators - ✅ Start tracing in `@BeforeEach` and stop with a file path in `@AfterEach` - ✅ Use `SoftAssertions` when validating multiple fields on a single page - ✅ Set up saved auth state (`storageState`) to skip login across test classes - ❌ Never use `Thread.sleep()` — replace with `waitFor()` or `waitForResponse()` - ❌ Never hardcode base URLs — always use `ConfigReader.getBaseUrl()` - ❌ Never create a `Playwright` instance inside a Page Object - ❌ Never use XPath for dynamic or frequently changing elements --- ## Common Pitfalls - **Problem:** Tests fail randomly in parallel mode **Solution:** Ensure every test creates its own `Playwright → Browser → BrowserContext → Page` chain via `ThreadLocal`. Never share a `Page` across threads. - **Problem:** `assertThat(locator).isVisible()` times out even when the element appears **Solution:** Increase timeout with `.setTimeout(10_000)` or raise `context.setDefaultTimeout()` in `BaseTest`. - **Problem:** `Thread.sleep(2000)` was added but tests are still flaky **Solution:** Replace with `page.waitForResponse("**/api/endpoint", () -> action())` or `assertThat(locator).hasText("Done")` which polls automatically. - **Problem:** Playwright trace zip is empty or missing **Solution:** Ensure `tracing().start()` is called before test actions and `tracing().stop()` is in `@AfterEach` — not `@AfterAll`. - **Problem:** Allure report is blank or missing steps **Solution:** Add the AspectJ agent to `maven-surefire-plugin` `` in `pom.xml` — see `references/config.md` for the exact snippet. - **Problem:** `storageState` auth file is stale and tests redirect to login **Solution:** Re-run `AuthSetup` to regenerate `target/auth/user-state.json` before the suite, or add a `@BeforeAll` that conditionally refreshes it. --- ## Related Skills - `@rest-assured-java` — Use for pure API test suites without any UI interaction - `@selenium-java` — Legacy alternative; prefer Playwright for all new projects - `@allure-reporting` — Deep-dive into Allure annotations, categories, and history trends - `@testcontainers-java` — Use alongside this skill when tests need a live database or service - `@github-actions-ci` — For building complete multi-browser matrix CI pipelines --- Source attribution: cocyuhao Original project: https://github.com/cocyuhao/ai-dev-tooling-research-archive/blob/f4a24bd1ab047411d4ae57ee9a96701a7706e779/claude-code-templates/cli-tool/components/skills/development/playwright-java/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2025 Daniel (San) Ávila Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ## Additional upstream notices playwright-java-5c656b214a25/DAVEAI-UPSTREAM-NOTICE.md # Third-party Research Archive Notice This repository is a personal learning and research archive. It may contain copied third-party projects or excerpts for study, comparison, and interview discussion. All original copyrights, licenses, README files, and ownership notices belong to their original authors. Content in this archive should not be interpreted as original work by this GitHub account unless a specific file explicitly says so. # Mega AI Hub resource metadata Creator / publisher: cocyuhao Original project: https://github.com/cocyuhao/ai-dev-tooling-research-archive/blob/f4a24bd1ab047411d4ae57ee9a96701a7706e779/claude-code-templates/cli-tool/components/skills/development/playwright-java/SKILL.md Attribution basis: Source repository record Fields of work: Development & Engineering Roles: Backend Developer, DevOps / SRE, QA / Test Engineer Specialties: Backend, Testing Tools: Java, Playwright Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 5d7a221263814f1d1befb4d3096a96772f6dd1812dc7ae4a2a52e4252759565d