Playwright Java

Playwright Java – Automação de Testes Avançada

Visão geral

Esta skill produz código de teste Playwright Java com qualidade de produção e nível empresarial. Ela força o uso de Page Object Model (POM), estratégias rigorosas de localizador, execução paralela thread-safe e integração completa com relatórios Allure. Direcionada para Java 17+ e Playwright 1.44+.

Arquivos de referência de suporte estão disponíveis para tópicos mais profundos:

Quando usar esta skill

• Use ao criar um novo projeto Playwright Java do zero
• Use ao escrever classes Page Object ou classes de teste JUnit 5
• Use quando o usuário perguntar sobre testes cross-browser, execução paralela ou relatórios Allure
• Use ao corrigir testes flaky ou substituir Thread.sleep() por waits apropriados
• Use ao configurar Playwright em pipelines CI/CD (GitHub Actions, Jenkins, Docker)
• Use ao combinar chamadas de API e assertions de UI em um único teste (teste híbrido)
• Use quando o usuário mencionar "padrão POM", "BrowserContext", "Playwright fixtures" ou "traces"

Como funciona

Etapa 1: Decida a abordagem

Use esta matriz para escolher o padrão correto antes de escrever qualquer código:

Etapa 2: Crie a estrutura do projeto

Sempre use este layout ao criar um novo projeto:

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

Etapa 3: Configure BaseTest thread-safe

public class BaseTest {
    protected static ThreadLocal<Playwright>     playwrightTL = new ThreadLocal<>();
    protected static ThreadLocal<Browser>        browserTL    = new ThreadLocal<>();
    protected static ThreadLocal<BrowserContext> contextTL    = new ThreadLocal<>();
    protected static ThreadLocal<Page>           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();
        };
    }
}

Etapa 4: Construa classes Page Object

public class LoginPage extends BasePage {

    // Declare TODOS os locators como campos — nunca inline em métodos de ação
    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"; }

    // Métodos de navegação retornam o próximo Page Object — permite encadeamento fluente
    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(); }
}

Etapa 5: Escreva testes com anotações Allure

@ExtendWith(AllureJunit5.class)
class LoginTest extends BaseTest {

    private LoginPage loginPage;

    @BeforeEach
    void openLoginPage() {
        loginPage = new LoginPage(page());
        loginPage.navigate();
    }

    @Test
    @Severity(SeverityLevel.BLOCKER)
    @DisplayName("Credenciais válidas redirecionam para 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<Arguments> 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")
        );
    }
}

Exemplos

Exemplo 1: Teste híbrido API + UI

@Test
void shouldDisplayNewlyCreatedOrder() {
    // Arrange via API — mais rápido que navegar pela 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();
}

Exemplo 2: Mock de network

@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.");
}

Exemplo 3: Teste cross-browser em paralelo

@ParameterizedTest
@MethodSource("browsers")
void shouldRenderCheckoutOnAllBrowsers(String browserName) {
    System.setProperty("browser", browserName);
    new CheckoutPage(page()).navigate();
    assertThat(page().locator(".checkout-form")).isVisible();
}

static Stream<String> browsers() {
    return Stream.of("chromium", "firefox", "webkit");
}

Exemplo 4: Config de execução paralela

# 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

Exemplo 5: Pipeline GitHub Actions de CI

- 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/

Melhores práticas

• ✅ Use ThreadLocal<Page> para cada suíte de testes paralela e segura
• ✅ Declare todos os campos Locator no topo da classe Page Object
• ✅ Retorne o próximo Page Object a partir dos métodos de navegação (encadeamento fluente)
• ✅ Use assertThat(locator) — retenta automaticamente até o timeout
• ✅ Use getByRole, getByLabel, getByTestId como locators de primeira escolha
• ✅ Inicie tracing em @BeforeEach e pare com um caminho de arquivo em @AfterEach
• ✅ Use SoftAssertions ao validar múltiplos campos em uma única página
• ✅ Configure auth state salvo (storageState) para pular login entre classes de teste
• ❌ Nunca use Thread.sleep() — substitua por waitFor() ou waitForResponse()
• ❌ Nunca hardcode URLs base — sempre use ConfigReader.getBaseUrl()
• ❌ Nunca crie uma instância Playwright dentro de um Page Object
• ❌ Nunca use XPath para elementos dinâmicos ou que mudam frequentemente

Armadilhas comuns

• Problema: Testes falham aleatoriamente em modo paralelo Solução: Garanta que cada teste crie sua própria cadeia Playwright → Browser → BrowserContext → Page via ThreadLocal. Nunca compartilhe uma Page entre threads.

• Problema: assertThat(locator).isVisible() dá timeout mesmo quando o elemento aparece Solução: Aumente o timeout com .setTimeout(10_000) ou eleve context.setDefaultTimeout() em BaseTest.

• Problema: Thread.sleep(2000) foi adicionado mas testes continuam flaky Solução: Substitua por page.waitForResponse("**/api/endpoint", () -> action()) ou assertThat(locator).hasText("Done") que faz polling automaticamente.

• Problema: Arquivo zip de trace do Playwright está vazio ou ausente Solução: Garanta que tracing().start() seja chamado antes das ações de teste e tracing().stop() esteja em @AfterEach — não em @AfterAll.

• Problema: Relatório Allure está em branco ou faltam passos Solução: Adicione o agent AspectJ ao maven-surefire-plugin <argLine> em pom.xml — veja references/config.md para o snippet exato.

• Problema: Arquivo de auth storageState está obsoleto e testes redirecionam para login Solução: Re-execute AuthSetup para regenerar target/auth/user-state.json antes da suíte, ou adicione um @BeforeAll que o atualize condicionalmente.

Skills relacionadas

• @rest-assured-java — Use para suítes de testes de API pura sem qualquer interação de UI
• @selenium-java — Alternativa legada; prefira Playwright para todos os novos projetos
• @allure-reporting — Mergulho profundo em anotações Allure, categorias e tendências de histórico
• @testcontainers-java — Use ao lado desta skill quando testes precisam de um banco de dados ou serviço ao vivo
• @github-actions-ci — Para construir pipelines completos de CI com matriz multi-browser