O Playwright controla navegadores e testa aplicações web. No ecossistema JavaScript e TypeScript, o Playwright Test acrescenta executor, fixtures, asserções, projetos e relatórios. QA ganha comandos convenientes, isolamento de estado e histórico detalhado de falhas.
A ferramenta é adequada para fluxos de usuário, verificações de estado da interface e algumas tarefas de API. A espera automática não substitui o entendimento da aplicação: um botão pronto para interação não significa que um processo de negócio terminou, e uma resposta HTTP bem-sucedida não significa que seus dados estão corretos.
Instalação e reprodutibilidade
Para um novo projeto de treinamento, use npm init playwright@latest. Escolha JavaScript ou TypeScript e a instalação dos navegadores. Use uma versão do Node suportada pela versão selecionada. Em um repositório existente, preserve package-lock.json e instale as dependências com npm ci.
As versões dos navegadores estão vinculadas à versão instalada do Playwright. Depois de atualizar o pacote, atualize seus navegadores e verifique as dependências de sistema da CI. Um executável global arbitrário pode introduzir diferenças entre máquinas locais e agentes; documente explicitamente essa escolha.
Localizadores e nomes acessíveis
O Playwright oferece localizadores por papel, rótulo, texto e ID de teste. Um localizador descreve como encontrar um elemento no estado atual da página. Isso é preferível a guardar uma referência antiga a um nó do DOM que a aplicação pode substituir durante a renderização.
Escolha atributos conforme seu significado. Em um formulário, getByLabel conecta o teste ao rótulo acessível; em um botão, getByRole com um nome expressa uma ação do usuário. Se houver várias correspondências, restrinja o contêiner. Escolher automaticamente a primeira pode esconder ambiguidade e clicar no botão errado.
Um exemplo independente
No projeto criado, salve tests/profile.spec.js. O exemplo usa uma página em memória, sem servidor. Execute npx playwright test tests/profile.spec.js. A regra de treinamento rejeita um nome vazio e mostra sucesso para um nome não vazio; não há persistência real.
const { test, expect } = require('@playwright/test');
test('validates the name after submission', async ({ page }) => {
await page.setContent(`
<label>Name <input id="name"></label>
<button id="save">Save</button><p role="status"></p>
<script>
document.querySelector('#save').onclick = () => {
const name = document.querySelector('#name').value.trim();
setTimeout(() => {
document.querySelector('[role=status]').textContent =
name ? 'Saved' : 'Enter a name';
}, 100);
};
</script>`);
await page.getByRole('button', { name: 'Save' }).click();
await expect(page.getByRole('status')).toHaveText('Enter a name');
await page.getByLabel('Name').fill('Anna');
await page.getByRole('button', { name: 'Save' }).click();
await expect(page.getByRole('status')).toHaveText('Saved');
});Espere um erro para o valor vazio, seguido de sucesso para um valor válido. toHaveText repete a observação até a condição ser atendida ou o tempo se esgotar. await é obrigatório em ações e asserções assíncronas: omiti-lo pode causar execução fora de ordem e verificações incompletas.
Pelo que a ferramenta realmente espera
Antes de uma ação, o Playwright verifica condições necessárias, como visibilidade e possibilidade de interação, conforme a operação. Ele não sabe se um cálculo em segundo plano, a entrega de e-mail ou o processamento de fila terminou. Esses resultados exigem uma condição observável separada.
Prefira asserções web-first para interfaces dinâmicas. Ler o texto imediatamente e compará-lo com um assert comum verifica apenas um instante. Porém, não substitua toda espera por um timeout enorme: se o evento não deve ocorrer, esperar mais não corrige o cenário.
Passando para um perfil real
Crie um usuário de teste separado, abra sua área de conta e envie um nome contendo apenas espaços. Espere um erro e a manutenção do valor originalmente salvo. Em outro cenário, envie um nome novo válido e consulte o perfil pela interface ou API, conforme o objetivo do teste.
Um teste com simulação de rede confirma o tratamento da resposta fornecida pelo cliente. Mantenha uma verificação de integração separada sem substituir essa operação para verificar a persistência real. Deixe clara no nome da suíte a fronteira entre um erro controlado da interface e uma conexão real com o backend.
Fixtures e independência
O Playwright Test usa contextos para criar um estado de navegador isolado para cada teste. Isso ajuda com cookies e armazenamento, mas não isola automaticamente registros do servidor. Dois contextos usando uma mesma conta ainda podem alterar o mesmo perfil ou carrinho.
Fixtures podem preparar usuários, clientes de API e entidades necessárias. Escolha o escopo da fixture de forma deliberada. Um recurso compartilhado no escopo de worker deve ser seguro para todos os testes daquele worker; dados mutáveis de cenário ficam melhor quando criados separadamente.
Projetos e matriz de navegadores
Projetos descrevem configurações como navegador, viewport, localidade e outros parâmetros. Execute uma matriz baseada em riscos, em vez de testar automaticamente todas as combinações possíveis. Confirme primeiro o fluxo crítico e depois acrescente áreas sensíveis ao ambiente selecionado.
A emulação móvel não substitui um telefone real com teclado, permissões e integrações de sistema. O WebKit automatizado também não deve ser apresentado como teste completo do Safari dos usuários. Registre as limitações de cobertura junto com os resultados.
Traces e investigação
O Trace Viewer ajuda a examinar ações e o estado da página ao redor de uma falha. Salve traces conforme uma política acordada, como em novas tentativas ou falhas, e disponibilize-os na CI. Antes de publicar, considere quais dados aparecem nos registros de rede e nas capturas de tela.
Comece pela primeira expectativa não atendida: qual requisição foi enviada, o que retornou e o que a interface mostrou. Evite reescrever um localizador às cegas quando o backend está indisponível. Uma nova execução aprovada é uma observação útil, mas a falha original ainda precisa ser classificada.
Para um cenário com vários usuários, crie dois contextos separados e identifique o papel de cada participante no relatório. Salvar um arquivo de estado de armazenamento para acelerar o login não deve misturar contas ou expor dados de sessão em um artefato público. Confirme que o estado pertence ao ambiente necessário e continua válido. Se a preparação da autenticação falhar, identifique essa etapa: dezenas de erros posteriores em elementos da área de conta não são defeitos independentes da interface.
Erros e conclusões práticas
Problemas típicos incluem ausência de await, contas mutáveis compartilhadas, cliques forçados sem investigação e verificação apenas de uma mensagem. Edite os testes gerados: geradores ajudam a começar, mas não selecionam riscos, dados ou critérios de sucesso para a equipe.
Uma suíte Playwright confiável combina isolamento, localizadores claros, resultados de negócio explícitos e artefatos úteis. O início rápido da ferramenta é valioso quando a equipe cuida do estado do servidor e dos limites de cobertura com o mesmo rigor.
Leitura adicional
- →Playwright: instalação
- →Playwright: espera automática
- →Playwright: fixtures de teste
- →Playwright: visualizador de traces
Um exercício local reproduzível
O projeto de prática preparado fixa @playwright/test 1.59.1 com um lockfile e usa um ambiente Python local. Seus sete casos em Chromium exercitam o formulário de apelido com entradas vazias, curtas, nos limites, grandes demais, com espaços e Unicode. Cada caso recebe sua própria página e declara o resultado esperado. Nenhuma conta externa ou site em produção está envolvido.
npm ci
npx playwright install chromium
npm test
# If a test fails and produces a trace:
npx playwright show-trace test-results/<case-directory>/trace.zipA configuração inicia o servidor local e preserva traces em caso de falha. Os localizadores usam o rótulo do campo e o papel do botão para comunicar a intenção do usuário. As asserções são repetidas até a condição ser atendida ou o timeout expirar; chamadas arbitrárias de sleep são desnecessárias neste formulário síncrono.
await page.goto("/demo.html");
await page.getByLabel("Nickname").fill("ab");
await page.getByRole("button", { name: "Validate" }).click();
await expect(page.getByRole("alert")).toHaveText("Use 3–12 ASCII letters.");
await expect(page.getByLabel("Nickname")).toBeFocused();Para um exercício de falha deliberada, altere o texto de erro esperado em um teste local, execute somente esse teste, examine o trace preservado e restaure a asserção. Um teste aprovado comprova que este ambiente atende a essas verificações; não estabelece que um produto real seja acessível ou tenha sido testado de forma abrangente. Acrescente o fluxo real e as asserções de backend ao adaptar o exemplo.