O codegen gera um .spec.ts funcional no tempo que leva para clicar por um fluxo uma vez. O teste gerado se chama 'test', contém as credenciais que você digitou e raramente inclui mais de uma assertion. Tratá-lo como código pronto é o erro mais comum.
O que o codegen realmente gera
O codegen é o gravador de testes nativo do Playwright. Você o inicia com um único comando e interage com uma página no navegador que abre. Um painel na lateral escreve o TypeScript correspondente (ou JavaScript, Python, Java ou C#) conforme você avança.
O que você obtém é um arquivo .spec.ts que contém:
- Chamadas
page.goto()para qualquer navegação - Métodos de ação como
click(),fill(),check()eselectOption()para cada interação realizada - Locators para cada elemento que você tocou, escolhidos automaticamente pela estratégia de locator do Playwright
- Uma assertion básica no final se você usou a ferramenta de assertion no inspector
O código gerado já roda. Cole em um arquivo de teste e rode com npx playwright test: na maioria dos casos passa na primeira tentativa. O valor não está em a saída ser perfeita; está em você ter um esqueleto funcional em menos de dois minutos em vez de trinta.
Rodando o codegen contra lab.becomeqa.com
Inicie o codegen contra qualquer URL:
npx playwright codegen https://lab.becomeqa.comDuas janelas abrem ao mesmo tempo. A primeira é um navegador Chromium padrão mostrando a página de destino. A segunda é o Playwright Inspector: uma janela separada com um painel de código, um botão de gravar e um seletor de locator.
Você não precisa de um projeto especial para isso. O codegen funciona completamente fora de um projeto Playwright. Se você está em um diretório de projeto, o código gerado respeita a linguagem configurada. Se não, usa TypeScript como padrão.
Para gerar código em uma linguagem específica:
# JavaScript
npx playwright codegen --target javascript https://lab.becomeqa.com
# Python
npx playwright codegen --target python https://lab.becomeqa.com
# Java
npx playwright codegen --target java https://lab.becomeqa.comPara usar um navegador específico em vez do Chromium padrão:
npx playwright codegen --browser firefox https://lab.becomeqa.com
npx playwright codegen --browser webkit https://lab.becomeqa.comA flag --browser é útil quando você suspeita que locators diferem entre Chromium e WebKit, ou quando está construindo um teste que testa especificamente o comportamento do Firefox.
A interface do codegen: três ferramentas para conhecer
O Playwright Inspector oferece três recursos que vale entender antes de começar a gravar.
O botão Record inicia e para a gravação. Quando está ativo (vermelho), toda interação na janela do navegador é capturada como código. Clique novamente para pausar sem fechar a sessão. Isso permite navegar manualmente para um estado difícil de alcançar (como abrir um modal ou navegar várias páginas fundo) e retomar a gravação quando estiver lá. O seletor de locator (ícone de mira) muda o navegador para o modo de inspeção. Mova o cursor sobre qualquer elemento e o Inspector mostra o locator que o Playwright geraria para ele, junto com uma prévia de quantos elementos esse locator corresponde. Verde significa um match. Amarelo significa múltiplos matches, então esse locator é ambíguo e não deve ser usado em testes. O painel de assertion (ícone de checkbox) permite adicionar assertions durante a gravação. Clique nele, depois clique em um elemento no navegador, e o codegen insere uma assertiontoBeVisible() no código. Você também pode assertar conteúdo de texto ou estado de checagem pelo dropdown que aparece. É um dos recursos menos aproveitados: iniciantes costumam gravar ações mas esquecem de assertar qualquer coisa.
Por que o codegen prioriza getByRole
Quando você clica em um botão chamado "Login", o codegen não gera page.locator('button.login-btn'). Gera page.getByRole('button', { name: 'Login' }).
Isso é intencional. A estratégia de locator do Playwright prioriza nessa ordem:
1. getByRole: corresponde por role ARIA e nome acessível
2. getByLabel: para inputs de formulário associados a um label
3. getByPlaceholder: para inputs com texto de placeholder
4. getByText: para elementos não-interativos
5. getByTestId: para elementos com atributo data-testid
6. CSS ou XPath: último recurso
O motivo de getByRole vir primeiro é a resiliência. A classe CSS de um botão pode mudar quando um designer atualiza o stylesheet. Sua posição no DOM pode mudar quando alguém adiciona uma nova feature. Mas um botão chamado "Login" quase sempre continua chamado "Login": mudar isso quebraria a UI para usuários reais também. Testes construídos sobre locators acessíveis são mais estáveis porque quebram pelas mesmas razões que os usuários perceberiam.
Quando você vê o codegen gerando algo como page.locator('.btn-primary'), isso é um sinal de que o elemento não tem um bom nome acessível. Vale parar e perguntar se um atributo data-testid pode ser adicionado a esse elemento.
aria-label ou garantir que o elemento label esteja corretamente associado ao seu input. Melhor acessibilidade e melhores locators de teste vêm da mesma fonte.Gravando um fluxo completo de login
Como gravar um teste de login real contra lab.becomeqa.com, passo a passo.
Inicie o codegen:
npx playwright codegen https://lab.becomeqa.comCom as duas janelas abertas e a gravação ativa, execute esta sequência no navegador:
1. Clique no botão de Login na navegação
2. Preencha o campo de email com uma conta de teste
3. Preencha o campo de senha
4. Clique em Submit
5. Aguarde o dashboard carregar
6. Use o seletor de assertion para assertar que algo no dashboard está visível
Após completar essas etapas, o painel do Inspector mostra algo próximo a isso:
import { test, expect } from '@playwright/test';
test('test', async ({ page }) => {
await page.goto('https://lab.becomeqa.com/');
await page.getByRole('button', { name: 'Login' }).click();
await page.getByLabel('Email').fill('user@example.com');
await page.getByLabel('Password').fill('senha123');
await page.getByRole('button', { name: 'Submit' }).click();
await expect(page.getByText('My Travel Items')).toBeVisible();
});Clique no botão de copiar no Inspector, crie um arquivo em tests/login.spec.ts e cole. Execute:
npx playwright test tests/login.spec.ts --project=chromiumPassa. Você tem um teste funcional no tempo que levou para clicar pelo fluxo de login uma vez.
Limpando o código gerado
O código gerado roda, mas não é de qualidade para produção. Três coisas precisam de atenção antes de entrar em uma suite de testes real.
Credenciais hardcoded. O código gerado contém o email e senha reais que você digitou. Eles não pertencem ao controle de versão. Mova para variáveis de ambiente:import { test, expect } from '@playwright/test';
test('usuário consegue fazer login', async ({ page }) => {
await page.goto('/');
await page.getByRole('button', { name: 'Login' }).click();
await page.getByLabel('Email').fill(process.env.TEST_EMAIL!);
await page.getByLabel('Password').fill(process.env.TEST_PASSWORD!);
await page.getByRole('button', { name: 'Submit' }).click();
await expect(page.getByText('My Travel Items')).toBeVisible();
});Se você tem uma baseURL no playwright.config.ts, substitua também a URL hardcoded no page.goto() por '/'.
'test'. Renomeie para descrever o comportamento que está sendo verificado, como 'usuário consegue fazer login com credenciais válidas'.
Assertions ausentes. O codegen só grava ações e as assertions que você adicionou explicitamente. Um teste de login deveria assertar mais de uma coisa: não só que o texto "My Travel Items" aparece, mas que a URL mudou, ou que o menu do usuário mostra o email correto. Adicione manualmente.
Locators repetitivos. Se você gravou um fluxo que usa o mesmo locator cinco vezes, extraia para uma variável:
const emailInput = page.getByLabel('Email');
await emailInput.fill(process.env.TEST_EMAIL!);Isso é menor no nível do teste, mas se torna essencial quando os mesmos locators aparecem em múltiplos arquivos de teste. É o momento em que você migra para o Page Object Model. Não faça isso antes de precisar.
Gravando em diferentes navegadores e salvando a saída em arquivo
O codegen suporta os três motores de navegador do Playwright. Por padrão usa Chromium. Mude para Firefox ou WebKit quando precisar de locators que funcionem em diferentes motores ou ao debugar comportamento específico de navegador:
npx playwright codegen --browser webkit https://lab.becomeqa.comVocê também pode salvar o código gerado diretamente em um arquivo em vez de copiar do painel do Inspector:
npx playwright codegen --output tests/login.spec.ts https://lab.becomeqa.comCom --output, o arquivo é escrito quando você fecha a janela do Inspector. Se o arquivo já existe, é sobrescrito. Combine com uma linguagem de destino específica para gerar arquivos de teste em qualquer stack suportada:
npx playwright codegen --target javascript --output tests/login.spec.js https://lab.becomeqa.comPara times que usam emulação de dispositivos, o codegen suporta --device para simular viewports mobile:
npx playwright codegen --device "iPhone 13" https://lab.becomeqa.comIsso abre o navegador no tamanho de tela do iPhone 13 com o user agent correto. O código gerado inclui devices['iPhone 13'] nas opções de contexto.
Usando o codegen como explorador de locators (sem gravar testes)
Um dos usos mais práticos do codegen não envolve gravar um teste completo. Às vezes você só precisa encontrar o locator certo para um elemento específico e não quer gastar tempo inspecionando o DOM manualmente.
Inicie o codegen, clique no seletor de locator e mova o cursor sobre o elemento que te interessa. O Inspector mostra o locator em tempo real. Também mostra quantos elementos correspondem: informação crítica antes de commitar um locator em um teste.
npx playwright codegen https://lab.becomeqa.comDepois que o navegador abrir, pressione o botão de gravar para parar a gravação e não gerar código desnecessário. Mude para o modo de seletor de locator e passe o cursor sobre os elementos. O Inspector atualiza o display do locator enquanto você navega entre os elementos. Você pode digitar no campo de locator para testar variações e ver quantos elementos correspondem.
Esse fluxo de trabalho substitui horas de tentativa e erro no test runner. Você valida um locator antes de escrever o teste, não depois que ele falha.
Os limites do codegen: o que ele não consegue gravar
O codegen lida com a maioria das interações do usuário: cliques, preenchimento de formulários, navegação, dropdowns, checkboxes, radio buttons. Algumas categorias ele trata mal ou não trata de forma alguma:
Upload de arquivos. O codegen não consegue gravarpage.setInputFiles(). Quando você clica em um input de arquivo e seleciona um arquivo do sistema, o codegen pode capturar o clique mas não a seleção do arquivo. Você precisa escrever o código de upload manualmente.
Drag and drop. Eventos HTML de arrastar e soltar não se traduzem bem em gravações do codegen. O código gerado pode mostrar um clique sem o movimento de arraste, o que significa que a interação silenciosamente não faz o que você espera. Use page.dragAndDrop() ou simule os eventos individuais mousedown, mousemove e mouseup para interações de arraste confiáveis.
Esperas complexas. O codegen grava ações no momento que você as executa. Não grava o pensamento implícito que você faz como humano ("esperei o spinner desaparecer antes de clicar"). Em ambientes lentos ou instáveis, testes gerados podem falhar porque rodam mais rápido do que a UI espera. Adicione esperas explícitas onde o fluxo exige:
await page.waitForLoadState('networkidle');
await expect(page.getByRole('progressbar')).toBeHidden();context.waitForEvent('page'). O codegen pode perder completamente a nova aba.
Estados autenticados. O codegen não conhece autenticação armazenada. Se você quer que os testes iniciem já logados, use storageState do Playwright para salvar os cookies de sessão após logar uma vez. Esse estado é carregado no início de cada teste. O codegen pode ajudar a gravar o login uma vez, mas o padrão de storage state precisa ser configurado manualmente.
Fluxos OAuth e login por terceiros. Qualquer fluxo que redireciona para um provedor de identidade externo (Google, GitHub, Microsoft) é difícil de gravar com codegen. Os locators existem em uma página de terceiro que você pode não controlar. Esses fluxos precisam de tratamento separado e frequentemente exigem mockar o callback OAuth em vez de passar pelo provedor real.
FAQ
O código do codegen está pronto para commitar diretamente?Raramente. É um ponto de partida rápido, não um teste pronto. Sempre renomeie o teste, remova credenciais hardcoded, verifique se as assertions são significativas, e confirme que os locators correspondem à estrutura de acessibilidade da página.
Posso usar o codegen em uma URL localhost?Sim. npx playwright codegen http://localhost:3000 funciona exatamente da mesma forma. Se o seu app exige autenticação para chegar à página que você quer gravar, faça login manualmente antes de clicar no botão de gravar.
Só se não houver melhor opção. Um seletor CSS como .item-card:nth-child(2) vai quebrar no momento em que o layout da página mudar. Tente entender por que o Playwright voltou para CSS: o elemento provavelmente não tem um nome acessível. Se você não conseguir adicionar um, getByTestId com um atributo data-testid é a próxima melhor opção.
Nenhuma diferença mensurável. A gravação acontece no processo do Inspector, não dentro do próprio navegador.
Posso pausar no meio da gravação e navegar manualmente?Sim. Clique no botão de gravar para pausar, navegue para o estado que precisa e clique em gravar novamente para retomar. Apenas interações com a gravação ativa são capturadas.
Por que o codegen geroupage.locator('text=Submit') em vez de getByRole?
Isso acontece quando o Playwright não encontra um locator confiável baseado em role. Cai para correspondência por texto. Verifique se o elemento é um botão com nome acessível; deveria gerar getByRole('button', { name: 'Submit' }) para um elemento botão padrão.
