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:
✅ Use ThreadLocal<Page> 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<argLine> 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
