Como isolar testes paralelos de e-mail com locks do Playwright em 2026?

Última atualização: 24 de outubro de 2026. Conferência baseada nas notas de versão do Playwright, no guia oficial de execução paralela e na API de testes.

O Playwright executa arquivos de teste em paralelo por padrão, mas mantém sequenciais os testes de um mesmo arquivo, salvo configuração diferente, conforme o guia oficial de paralelismo. Portanto, use um bloqueio nomeado para coordenar testes que disputam a mesma conta ou caixa de entrada; não espere que ele identifique a mensagem certa. Para reduzir o risco de um código de verificação ser associado ao teste errado, combine o bloqueio com um identificador exclusivo ou um destino de recebimento isolado.

Esta orientação é para você que executa testes Playwright entre arquivos, workers ou projetos e precisa verificar se há disputa por recursos compartilhados.
Também serve para QA responsável por fluxos de cadastro e verificação por e-mail e para quem mantém o ambiente de testes em CI.

Antes da configuração: inventário dos recursos compartilhados

Comece anotando quais elementos cada teste lê ou altera. Não parta direto para adicionar bloqueios: uma falha intermitente pode vir de mensagens atrasadas, credenciais inválidas, limpeza prematura ou uma regra de entrega, e não necessariamente do paralelismo.

Registre, para cada teste de e-mail:

• Qual conta de teste é usada para criar a sessão ou solicitar a mensagem?
• A caixa de entrada é compartilhada? O teste lê mensagens por uma interface comum ou por uma API de leitura?
• A consulta procura uma mensagem específica ou seleciona a mais recente?
• O teste apaga mensagens, altera o estado da conta ou invalida uma sessão que outro teste também usa?
• O que você precisa demonstrar: que duas operações não acessam o mesmo recurso ao mesmo tempo ou que a mensagem recebida pertence à execução atual?

Essa última distinção define a solução. Um bloqueio coordena acesso concorrente a um recurso identificado. Ele não acrescenta, por conta própria, uma relação verificável entre a mensagem e a execução que a solicitou. Por exemplo, dois testes podem usar o mesmo bloqueio, aguardar sua vez e ainda assim ler uma mensagem antiga se a busca aceitar qualquer mensagem recente da caixa.

Desenhe o fluxo com recursos concretos, não com nomes genéricos como “e-mail”. Se o cadastro e a redefinição de senha compartilham uma conta, registre essa conta como recurso. Se ambos consultam a mesma caixa, registre também a caixa ou a interface de leitura, conforme o ponto de disputa. Quando o recurso é uma combinação — conta mais caixa — identifique os dois componentes.

Atenção: limite o fluxo a testes do seu próprio produto ou de um ambiente para o qual você tem autorização. Não use automação para criar contas em serviços de terceiros.

No planejamento: escolha o limite do bloqueio

Um bloqueio nomeado deve corresponder ao recurso realmente compartilhado. Se testes independentes usam caixas diferentes, não os coloque sob o mesmo nome só por serem testes de e-mail: isso pode serializar trabalho que não precisa esperar. Se dois arquivos usam a mesma conta, por outro lado, nomes distintos não coordenam a disputa.

Defina nomes específicos e estáveis, por exemplo, um nome que identifique o ambiente e a conta compartilhada. Evite um único bloqueio para todo o conjunto de testes: se um teste de notificação não disputa a mesma conta do fluxo de cadastro, não há motivo automático para fazê-lo esperar.

O nome só ajuda quando os testes que acessam o mesmo recurso declaram o mesmo bloqueio dentro do escopo coberto pela execução. Verifique, na versão instalada do Playwright, a forma suportada para declarar e adquirir o bloqueio na API oficial de testes. A API disponível e a sintaxe precisam corresponder à versão do seu projeto; não copie um exemplo de outra versão sem validar o contrato atual.

A resposta para a dúvida sobre arquivos e projetos depende desse escopo. Testes em arquivos diferentes podem coordenar o acesso se participarem da mesma execução do Playwright, declararem o mesmo nome e a API instalada oferecer essa coordenação naquele contexto. Não presuma que um nome idêntico também sincroniza processos iniciados em comandos, jobs de CI ou execuções independentes. Para esses limites, confirme a documentação da versão e a configuração real do seu ambiente.

Na configuração: separe bloqueio de isolamento da caixa

O bloqueio do Playwright e a capacidade da caixa de entrada de separar mensagens resolvem problemas diferentes. O primeiro coordena testes que compartilham um recurso durante uma execução. A segunda ajuda a identificar ou separar mensagens recebidas. Uma não substitui a outra.

No seu projeto, adote um padrão explícito para cada recurso: identifique o nome do bloqueio, os testes que devem usá-lo e o motivo. Em seguida, confira se a configuração de paralelismo permite que esses testes concorram. O Playwright tem modos de execução e configurações que mudam quais testes rodam ao mesmo tempo; consulte o guia de testes paralelos antes de decidir que um bloqueio cobre um conjunto inteiro.

Não transforme o modo serial em solução automática. Tornar um grupo inteiro sequencial pode mascarar qual recurso causa a disputa e reduzir paralelismo de testes sem relação entre si. Prefira coordenar o menor recurso compartilhado que explica o conflito. Se a API ou o modo escolhido impuser um limite maior, documente esse efeito para quem mantém a suíte.

Uma ficha curta por recurso evita configurações ambíguas:

• Recurso: conta, caixa, endpoint de leitura ou combinação.
• Testes participantes: arquivos e projetos que realmente acessam o recurso.
• Nome compartilhado: identificador usado pelos testes que disputam o recurso.
• Escopo confirmado: execução e configuração nas quais a coordenação funciona.
• Verificação da mensagem: critério independente que confirma a associação com o teste atual.

Esse registro também ajuda a distinguir “o bloqueio não foi aplicado” de “o bloqueio funcionou, mas a consulta encontrou uma mensagem inadequada”.

Durante a execução: coordene apenas quem disputa

Aplique o mesmo nome aos testes que acessam o mesmo recurso. Por exemplo, se dois fluxos alteram a mesma conta de cadastro, ambos devem declarar a coordenação correspondente antes de usá-la. Se um teste consulta outra caixa independente, ele não deve adquirir esse bloqueio apenas por também validar e-mail.

Trate a aquisição como uma fronteira: o teste precisa obter o bloqueio antes da primeira operação que possa conflitar e mantê-lo durante o acesso protegido. Se a seção crítica termina antes da leitura da caixa, mas outro teste pode limpar ou substituir o estado antes da consulta, o bloqueio está delimitado no lugar errado. Se ele engloba todo o teste sem necessidade, você pode estar serializando navegação, preparação e asserções que poderiam ocorrer em paralelo.

Compare o comportamento com e sem coordenação em um cenário controlado do seu próprio produto. Registre qual conta e caixa cada teste acessa, qual mensagem seleciona e se a interferência desaparece com o bloqueio. Não use apenas o resultado “passou” como evidência: um teste pode passar por acaso ao ler uma mensagem compatível de uma execução anterior.

Se a falha continuar com os acessos compartilhados coordenados, examine a associação da mensagem. Um bloqueio não valida o conteúdo retornado, não limpa mensagens antigas e não garante que uma caixa tenha recebido a mensagem esperada. Também não substitui a confirmação de entrega em um teste de ponta a ponta.

Depois da chegada: associe a mensagem à execução atual

Para evitar a situação conhecida como troca de códigos entre testes, inclua nos e-mails do seu produto um marcador de teste que permita reconhecer a solicitação correspondente. Pode ser um identificador exclusivo da execução, um valor presente no assunto ou no corpo, ou um dado de correlação que o teste consiga comparar com o estado atual. Escolha um mecanismo que o próprio produto possa emitir e que não revele dados pessoais reais.

A asserção deve verificar mais do que “existe um e-mail com código”. Confirme que a mensagem corresponde ao identificador da execução, que o código ou link pertence ao fluxo solicitado e que a conta está no estado esperado. Se a caixa não permite filtrar por marcador, faça a consulta e rejeite explicitamente mensagens que não correspondam à execução atual; não aceite a primeira mensagem disponível.

O marcador não precisa ser um segredo de autenticação. Ele serve para correlação no ambiente de teste. Evite usar endereço, nome ou outros dados de uma pessoa real como atalho para identificar execuções. Para reduzir o uso de informações pessoais em cenários de teste, use também os critérios do checklist de e-mail para QA. Ao definir a limpeza das mensagens, registre o que deve ser mantido e por quanto tempo, para que uma repetição não leia dados antigos nem apague evidências de outra execução.

Lembrete: uma caixa exclusiva pode diminuir a disputa entre testes, mas ainda exige uma asserção de conteúdo. Separar destinos não prova, sozinho, que o produto enviou o código correto ou concluiu o fluxo esperado.

Na nova tentativa: proteja a limpeza e o estado antigo

Uma repetição após falha pode encontrar a caixa e a conta em estado diferente da primeira execução. A documentação do Playwright descreve como novas tentativas são executadas e o que acontece com os workers; verifique os detalhes no guia oficial de novas tentativas. Não suponha que repetir o teste equivale a começar com uma caixa vazia ou com uma conta recriada.

Decida explicitamente o que acontece antes de cada tentativa:

• A conta é reutilizada, recriada ou restaurada para um estado conhecido?
• Mensagens anteriores são preservadas, marcadas como antigas ou removidas?
• A limpeza usa o mesmo recurso protegido que a leitura e a escrita?
• O identificador da tentativa distingue a execução original da repetição?
• Os logs permitem saber qual tentativa solicitou cada mensagem?

Se a limpeza altera a mesma caixa ou conta que outro teste pode acessar, ela também participa da disputa. Coloque-a sob a coordenação apropriada ou mova-a para um mecanismo de preparação que não concorra com a execução dos testes. Evite apagar mensagens “mais recentes” sem uma condição que identifique as mensagens pertencentes ao teste: isso pode apagar evidências de outra execução.

Registre evidência suficiente para reconstruir a sequência: identificador da execução, tentativa, recurso usado, momento em que a solicitação foi feita, mensagem selecionada e motivo da asserção. Faça isso sem registrar o conteúdo completo de mensagens que possam conter dados sensíveis ou credenciais. Para validar a entrega e investigar falhas de recebimento sem misturar as hipóteses, consulte também o guia de diagnóstico de entrega.

Na revisão: decida entre manter o bloqueio e isolar recursos

Use estas condições para escolher o próximo passo:

• Se dois ou mais testes acessam simultaneamente a mesma conta ou caixa e a disputa desaparece ao coordenar esse recurso, mantenha o bloqueio e documente quais testes devem compartilhar o nome.
• Se os testes não disputam o mesmo recurso, mas usam um bloqueio amplo, restrinja o escopo para recuperar paralelismo sem perder a proteção necessária.
• Se um teste ainda pode ler uma mensagem antiga ou de outra execução, acrescente um identificador verificável ou filtre a leitura por um critério de correlação.
• Se a associação não pode ser demonstrada com segurança na caixa compartilhada, use uma conta ou um destino de recebimento separado para aquele fluxo.
• Se uma falha ocorre mesmo com acesso coordenado e mensagem correlacionada, investigue outras causas, como estado incorreto do produto ou entrega incompleta, em vez de aumentar o escopo do bloqueio sem evidência.

A decisão sobre um endereço de recebimento independente depende da finalidade do teste. Se você precisa provar que o produto envia e que a mensagem chega a um destino real, mantenha essa evidência de recebimento e isole o destino conforme a exigência do ambiente. Se você só precisa testar uma parte interna do fluxo, um mecanismo controlado de captura pode ser mais adequado, desde que não seja apresentado como prova de entrega real.

Quando o seu QA precisa receber mensagens de verdade, avalie uma solução de recebimento temporário apenas depois de confirmar se ela atende ao fluxo, à retenção e às regras de acesso da equipe. O guia de e-mail descartável ajuda a avaliar esse tipo de uso; não use uma caixa temporária para contas importantes que exigem recuperação de longo prazo. O MaskSend pode ser uma opção para testes autorizados que precisem de um endereço temporário sem expor sua caixa principal, mas confira as capacidades e a política de retenção disponíveis antes de incluir qualquer serviço no pipeline. O bloqueio coordena o acesso; o identificador ou o destino isolado confirma a qual teste pertence o e-mail.