Playwright 1.63: locks, traces mais ricos e testes mais fáceis de manter

O Playwright 1.63 traz melhorias que resolvem problemas comuns em suítes de automação: concorrência sobre dados compartilhados, elementos duplicados na tela, iframes difíceis de localizar e diagnósticos pouco claros quando um teste falha.

Não é uma versão focada em uma única grande API. Ela refina o dia a dia de quem mantém testes E2E em projetos reais: preserva o paralelismo onde ele é seguro e adiciona mais contexto para investigar falhas com rapidez.

Neste artigo, vamos explorar as novidades mais importantes e entender quando vale a pena adotá-las.

1. Test locks: paralelismo sem conflito de dados

Executar testes em paralelo deixa a pipeline mais rápida, mas pode causar comportamentos instáveis quando dois testes alteram o mesmo recurso.

Alguns exemplos comuns:

Dois testes mudam as configurações da mesma conta.
Vários cenários usam o mesmo usuário de teste.
Uma integração externa possui limite de requisições.
A criação de dados depende de um recurso único, como um cupom ou agenda.

Antes, a solução geralmente envolvia reduzir o número de workers, executar uma parte da suíte em modo serial ou criar controles manuais. Com os test locks, você informa apenas quais testes não podem ser executados ao mesmo tempo.

import { test, expect } from '@playwright/test';

test(
  'deve atualizar as configurações do usuário',
  { lock: 'user-settings' },
  async ({ page }) => {
    await page.goto('/settings');
    await page.getByLabel('Receber notificações').uncheck();
    await page.getByRole('button', { name: 'Salvar' }).click();

    await expect(page.getByText('Configurações salvas')).toBeVisible();
  },
);

Qualquer teste que use o mesmo lock (user-settings) aguardará sua vez. Os demais continuam rodando em paralelo, inclusive em arquivos, workers e projetos diferentes.

Aplicando o lock a um grupo de testes

Quando todos os cenários de uma área compartilham o mesmo recurso, o lock pode ficar no describe:

import { test } from '@playwright/test';

test.describe('configurações da conta', { lock: 'user-settings' }, () => {
  test('deve alterar o idioma', async ({ page }) => {
    // ...
  });

  test('deve alterar as notificações', async ({ page }) => {
    // ...
  });
});

Um teste também pode declarar mais de um lock. Use esse recurso para proteger dependências realmente compartilhadas — não como substituto de isolamento de dados. Sempre que possível, prefira criar usuários e dados independentes por teste.

2. Encontrando elementos em iframes com menos código

Muitas aplicações modernas usam iframes para pagamentos, autenticação, chat ou widgets de terceiros. Até agora, era necessário localizar primeiro o iframe para depois buscar o elemento dentro dele.

No Playwright 1.63, page.frameLocator() e frame.frameLocator() podem ser chamados sem seletor. Nesse caso, o Playwright procura nos frames da árvore atual:

await page.frameLocator().getByRole('button', { name: 'Pagar agora' }).click();

Isso é útil quando o elemento desejado existe em apenas um iframe e o seletor do iframe é frágil, dinâmico ou pouco significativo.

O restante do locator ainda precisa encontrar o elemento dentro de um único frame. Se a busca corresponder a mais de um iframe, o Playwright lança um erro para evitar que o teste clique no elemento errado.

Para fluxos mais complexos, ou quando você precisa deixar explícita a origem do elemento, continue usando um seletor para o iframe:

const paymentFrame = page.frameLocator('iframe[title="Pagamento seguro"]');

await paymentFrame.getByLabel('Número do cartão').fill('4242 4242 4242 4242');

3. `locator.visible()` para elementos realmente interativos

É comum uma interface manter versões ocultas de um mesmo botão — por exemplo, uma para desktop e outra para mobile. Nesses casos, um locator genérico pode encontrar os dois elementos e tornar a ação ambígua.

O novo locator.visible() restringe a busca a elementos visíveis:

await page.locator('button').visible().filter({ hasText: 'Continuar' }).click();

Ele é a alternativa recomendada ao uso do pseudo-seletor CSS :visible:

// Evite este padrão em novos testes.
await page.locator('button:visible').click();

// Prefira este.
await page.locator('button').visible().click();

Ainda assim, comece com locators orientados à semântica, como getByRole, getByLabel e getByTestId. O visible() é um refinamento útil quando há mais de uma correspondência, e não uma justificativa para escolher seletores genéricos.

Transforme boas práticas em uma suíte de verdade

As APIs novas ajudam, mas a diferença aparece quando elas fazem parte de uma estratégia de automação bem estruturada: seleção de locators, organização dos testes, dados confiáveis e integração com a CI.

Se você quer aprender Playwright com TypeScript de forma prática e construir essa base passo a passo, conheça o curso de Playwright. Se o seu desafio envolve decisões de arquitetura, evolução na carreira ou obstáculos específicos do seu projeto, a mentoria individual oferece uma orientação direcionada ao seu contexto.

4. Traces que unem tela, DOM e acessibilidade

O Trace Viewer já é uma das ferramentas mais valiosas do Playwright para investigar falhas. Na versão 1.63, a configuração de snapshots passou a permitir escolher exatamente o que será capturado a cada ação: DOM, árvore ARIA e tela.

import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    trace: {
      mode: 'on-first-retry',
      snapshots: {
        dom: true,
        aria: true,
        screen: true,
      },
    },
  },
});

Com snapshots ARIA e de tela habilitados, o modo Display Aria do Trace Viewer mostra a captura visual ao lado da árvore de acessibilidade. Ao passar o mouse sobre um nó ARIA, o elemento correspondente é destacado na imagem.

Isso ajuda especialmente quando a falha está relacionada a:

Nome acessível incorreto em botões e campos.
Elementos visualmente presentes, mas ausentes da árvore de acessibilidade.
Locators por role que não encontram o componente esperado.
Diferenças entre o que a pessoa usuária vê e o que tecnologias assistivas interpretam.

Use a captura completa com intenção. Ela torna os artefatos de teste mais ricos, mas pode aumentar o volume de dados gerados na CI.

5. Relatórios com mais contexto e foco em performance

A versão 1.63 também melhora a leitura de execuções longas ou com falhas intermitentes.

Parâmetros estruturados em `test.step()`

Agora é possível associar dados estruturados a passos manuais:

await test.step(
  'realizar login',
  async () => {
    await page.goto('/login');
    await page.getByLabel('E-mail').fill('admin@example.com');
    await page.getByLabel('Senha').fill(process.env.TEST_PASSWORD!);
    await page.getByRole('button', { name: 'Entrar' }).click();
  },
  { params: { profile: 'admin' } },
);

Os reporters recebem esses parâmetros e o HTML Report e o Trace Viewer passam a mostrar subtítulos com informações como o locator ou a URL envolvidos na ação. Evite inserir senhas, tokens ou dados pessoais nos parâmetros, pois eles podem aparecer nos artefatos da execução.

Waterfall de duração no HTML Report

O relatório HTML agora exibe um waterfall de duração ao lado dos passos do teste. Isso facilita identificar onde um cenário está gastando tempo: navegação, espera por resposta de API, interação com o navegador ou uma etapa de preparação.

Reporter `perfetto`

Para analisar a execução em uma linha do tempo, existe um novo reporter nativo:

npx playwright test --reporter=perfetto

Ele gera um arquivo no formato Trace Event, compatível com o Perfetto UI e com chrome://tracing. Cada worker aparece em uma faixa da linha do tempo, o que ajuda a visualizar gargalos e o grau de paralelismo da suíte.

Outras novidades que valem atenção

Além dos destaques, o Playwright 1.63 inclui mudanças úteis para projetos específicos:

httpCredentials agora aceita uma lista de credenciais, escolhendo a primeira compatível com a origem da requisição.
O estado do navegador pode incluir o Origin Private File System (OPFS), útil para aplicações que usam esse armazenamento do navegador.
Novos eventos dialogclosed em page e browserContext avisam quando um diálogo JavaScript é aceito, dispensado ou fechado.
ariaSnapshotJSON() retorna snapshots ARIA como JSON, uma opção prática para integrações e ferramentas que processam os dados programaticamente.
Os métodos de API request aceitam tipo genérico para tipar o retorno de response.json().
Há novas opções de emulação para reducedMotion, forcedColors e contrast.
--add-reporter adiciona um reporter pela linha de comando sem substituir os reporters definidos no arquivo de configuração.
npx playwright install --no-remove preserva navegadores usados por outras instalações do Playwright na máquina.

Antes de atualizar: dois avisos de compatibilidade

A atualização é simples, mas vale conferir estes pontos antes de promovê-la para a CI.

Pacotes experimentais de component testing

Os pacotes @playwright/experimental-ct-react, @playwright/experimental-ct-react17 e @playwright/experimental-ct-vue não receberão mais atualizações. O caminho recomendado é migrar para o modelo de stories e galleries, introduzido na versão 1.62.

Se a sua equipe usa component testing experimental, planeje essa migração antes de ficar dependente de APIs descontinuadas.

Ubuntu 20.04 não é mais suportado

O Playwright 1.63 encerra o suporte ao Ubuntu 20.04. Revise imagens Docker, runners auto-hospedados e agentes legados da CI.

Para Docker, mantenha a versão do pacote e da imagem alinhadas. Por exemplo:

image: mcr.microsoft.com/playwright:v1.63.0-noble

Fixar a tag evita incompatibilidades entre a versão do Playwright instalada no projeto e os executáveis de navegador disponíveis no container.

Como atualizar para o Playwright 1.63

Em um projeto TypeScript ou JavaScript que utiliza Playwright Test, atualize a dependência e os navegadores:

npm install -D @playwright/test@1.63.0
npx playwright install

Depois, execute a suíte localmente e na CI:

npx playwright test

Minha sugestão é atualizar em uma branch separada, validar os testes mais críticos e só então começar a adotar as novas APIs. Os test locks costumam trazer valor imediato para suítes que sofrem com concorrência; já os recursos de trace e relatório são excelentes para reduzir o tempo de diagnóstico nas próximas falhas.

Conclusão

O Playwright 1.63 não muda a forma de escrever testes do zero — ele torna uma boa suíte mais confiável e mais fácil de investigar.

Os locks permitem proteger recursos compartilhados sem sacrificar toda a execução paralela. A busca em iframes e os locators visíveis reduzem código e ambiguidades. Já os novos traces e relatórios aproximam o diagnóstico técnico do que realmente aconteceu na tela.

Para conferir todos os detalhes e APIs da versão, consulte as notas oficiais de lançamento do Playwright 1.63 e a documentação de Docker antes de atualizar a sua pipeline.

Se a atualização para o Playwright 1.63 despertou a vontade de levar sua automação além de exemplos isolados, o curso de Playwright com TypeScript é o próximo passo para aprofundar a prática. E, para definir uma estratégia compatível com a sua experiência e seus objetivos em QA, conheça a mentoria individual.