Mcube333/playwright-java-test-writer

Playwright Java Test Writer

Transforme casos de teste manuais em testes Playwright Java que parecem ter sido escritos por alguém que domina o framework: seguros para paralelismo, sem sleeps instáveis, page objects que escondem localizadores e relatórios Allure que rastreiam de volta aos IDs dos casos de teste originais.

Fluxo de Trabalho

1. Interpretar os casos de teste manuais

Extraia para cada caso: ID, título, prioridade/severidade, pré-condições, dados de teste, passos, resultado esperado por passo. As entradas variam (linhas do Excel, exportações Jira, Gherkin, texto livre); normalize-as antes de escrever código.

Se um caso não for automatizável como está (necessita OTP de celular real, julgamento visual como "parece correto", pagamento de terceiros com dinheiro real), não o finja. Liste-o em Não automatizado na saída com o motivo e uma sugestão (mock da API, usar OTP de teste, comparação de snapshot visual).

2. Detectar convenções do framework existentes primeiro

Se o usuário compartilhar arquivos do repositório (BaseTest, uma classe de página, testng.xml, pom.xml), espelhe-os exatamente: nomes de pacotes, nomes de classes base, estilo de nomenclatura, estilo de asserção, como a configuração é lida. Consistência com o código deles é mais importante que o estilo de referência abaixo.

Se nada for compartilhado, use o scaffold em references/framework-scaffold.md. Gere os arquivos do scaffold (BaseTest, PlaywrightFactory, BasePage, config) apenas quando o usuário pedir um framework ou claramente não tiver um; caso contrário, presuma que eles existem e gere apenas page objects e testes.

3. Projetar page objects

• Uma classe por página ou componente reutilizável (cabeçalho, gaveta do carrinho, painel de filtros). Componentes têm sua própria classe e são compostos nas páginas.
• Localizadores são campos private final Locator inicializados no construtor. Testes nunca chamam page.locator(...) diretamente.
• Métodos da página descrevem intenção do usuário (login(user, pass), addToCart(nomeProduto)), não mecânica (clicaBotao2). Anote-os com Allure @Step("...") usando placeholders de parâmetros, para que o relatório se assemelhe ao caso manual.
• Ações que navegam retornam o próximo page object (fluxo fluente). Métodos que permanecem na página retornam this ou void.
• Reutilize métodos de página existentes antes de adicionar novos. Se dois passos mapeiam a mesma intenção, use um método.
• Exponha estado para asserções através de getters nomeados por intenção que retornam Locator (ex.: mensagemErro()), para que os testes possam usar asserções web-first.

Prioridade de localizadores (do mais estável ao menos estável):

1. getByTestId (configure o nome do atributo uma vez se o app usar data-test, data-qa, etc.)
2. getByRole com nome acessível
3. getByLabel / getByPlaceholder / getByText para texto visível ao usuário
4. CSS em atributos estáveis
5. XPath, apenas como último recurso, com um comentário explicando o motivo

Se o usuário não forneceu DOM, HTML ou screenshots, você está chutando localizadores. Escreva o melhor palpite e marque-o com // TODO-VERIFICAR localizador para que nada seja enviado silenciosamente com seletores inventados. Mencione a quantidade de localizadores não verificados no resumo.

4. Escrever os testes

• Um método @Test por caso manual. Nome do método = comportamento (deveMostrarErroParaUsuarioBloqueado), não o ID.
• Rastreabilidade: coloque o ID do caso em @TmsLink("TC-012") e em description. Adicione @Epic, @Feature, @Story, @Severity mapeados da prioridade do caso (P0/Crítico → BLOCKER/CRITICAL, P1 → NORMAL, P2+ → MINOR).
• Cada resultado esperado se torna uma asserção. Um passo sem asserção significa que a verificação manual foi descartada; portanto, faça uma verificação cruzada antes de finalizar.
• Pré-condições vão para helpers de setup ou chamadas de API, não longas cadeias de cliques na UI, quando uma API ou deep link existir. Para pré-condições de login (especialmente OTP/SSO), prefira um login via API uma vez e reutilize via context.storageState() / Browser.NewContextOptions().setStorageStatePath(...).
• Casos repetidos com dados diferentes → um teste com um @DataProvider do TestNG. @TmsLink é estático, então passe o ID do caso como primeira coluna de dados e chame Allure.link(caseId, "tms", caseId) dentro do teste para manter a rastreabilidade por linha. Mantenha os dados de teste fora do corpo do teste (data provider, JSON ou classe de constantes). Nunca use dados reais de clientes.
• Os testes devem ser independentes: sem dependência de ordem de execução, contexto novo por teste, limpar tudo o que for criado.

5. Esperas: baseadas em condições apenas

Esta é a principal fonte de instabilidade, portanto trate como regra rígida:

• Nunca use Thread.sleep ou page.waitForTimeout.
• Prefira asserções web-first: assertThat(locator).isVisible(), hasText, hasCount, assertThat(page).hasURL(...). Elas fazem novas tentativas automaticamente.
• Ações já esperam automaticamente pela capacidade de ação; não adicione esperas redundantes antes de click()/fill().
• Quando uma ação dispara uma chamada de rede cujo resultado importa, envolva-a: page.waitForResponse(r -> r.url().contains("/carrinho") && r.ok(), () -> botaoAdicionar.click()).
• Para spinners/loaders: assertThat(loader).isHidden().
• Para navegação: page.waitForURL("**/checkout**").
• Timeouts personalizados vêm da configuração, nunca números mágicos inline.

Veja references/framework-scaffold.md → "Padrões de espera" para snippets.

6. Segurança paralela

Todos os objetos Playwright (Playwright, Browser, BrowserContext, Page) residem em ThreadLocals gerenciados pela classe base/factory e são criados e fechados por método de teste. Nunca os armazene em campos estáticos ou compartilhe uma Page entre testes. Os page objects recebem a Page via construtor. Estado estático em page objects não é permitido.

Formato de saída

Responda com, nesta ordem:

1. Arquivos: cada arquivo em seu próprio bloco de código com seu caminho completo como cabeçalho (ex.: src/test/java/com/exemplo/paginas/PaginaLogin.java). Arquivos completos e compiláveis com imports, não fragmentos, a menos que o usuário tenha pedido um snippet. Se mais de ~3 arquivos ou o usuário quiser baixá-los, escreva-os também em disco como uma pasta de projeto.
2. Tabela de rastreabilidade: ID do Caso | Método de teste | Passos automatizados | Observações.
3. Não automatizado / lacunas: casos ou passos ignorados e o motivo.
4. Precisa de verificação: quantidade e lista de localizadores TODO-VERIFICAR, suposições sobre dados de teste ou ambiente.

Mantenha a prosa curta; o código é a entrega.

Confidencialidade

Quando o usuário está construindo um portfólio público ou a solicitação menciona um app demo público, mantenha tudo genérico: pacote com.exemplo (ou o que ele especificar), sem nomes de empresa, URLs internos, endpoints internos, dados reais de usuário ou nomes de eventos proprietários. Se os casos manuais colados contiverem esses itens, substitua por equivalentes neutros e mencione isso em uma linha.

Arquivos de referência

• references/framework-scaffold.md: dependências do pom.xml, PlaywrightFactory com ThreadLocals, BaseTest com tracing e anexos do Allure em falha, BasePage, ConfigReader, testng.xml para execução paralela, snippets de padrões de espera. Leia ao fazer scaffolding ou quando precisar da forma exata da API.
• references/example-saucedemo.md: um exemplo completo (casos manuais → page objects → testes → tabela de rastreabilidade) no app público saucedemo.com. Leia para calibrar o estilo de saída.