How I structure a Java test automation project (and the free template I made from it)

Description and use

The author built a Java test automation template that removes repetitive setup, provides isolated browser sessions, Playwright traces, WireMock stubs, and Allure reports.

Problem

New test automation projects repeatedly spend weeks on boilerplate tasks such as choosing library versions, organizing folders, wiring reports, and writing CI pipelines.

Outcome

The template standardizes project structure, eliminates boilerplate, ensures isolated test execution, and provides rich diagnostics via traces and Allure reports, enabling faster, more reliable test development.

Workflow

• Define a single rule: tests contain assertions, other layers do not.
• Create page objects, API clients, and repositories without assertions.
• Write tests that only perform assertions.
• Configure Playwright to give each test its own browser session via a JUnit extension.
• Attach screenshots and traces on failure using the extension.
• Use WireMock to stub external APIs for logic checks and keep a few real API tests.
• Implement fluent query builders for RabbitMQ/Elasticsearch helpers.
• Tag tests with layer (ui, api, db, integration) and level (smoke, regression).
• Run smoke tests on PRs and full suite nightly via Maven groups.
• Retry failed tests once and mark flaky tests in the report.
• Clone the template, rename package with a script, and start writing tests.
• Use GitHub Actions for CI with secrets from environment variables.

Evidence

Every time I started a new test automation project, the first weeks went to the same chores: choosing library versions, deciding on folders, wiring reports, writing a pipeline.

Source

Tests assert. Everything else acts.

Source

The template gives every test its own isolated browser session.

Source

When a test fails, the same extension attaches a screenshot and a Playwright trace to the report.

Source

Tests against a public test API fail when that API is slow or down. For logic checks I stub the service with WireMock and keep only a few tests against the real one.

Source

The whole structure is available as a free GitHub template with: Playwright UI tests, REST Assured + WireMock for API tests, Database, RabbitMQ and Elasticsearch helpers, Allure reports and a GitHub Actions pipeline.

Source