Login com Playwright: Automatize a Autenticação sem Testes Instáveis

A automação de login com Playwright parece simples à primeira vista: abrir uma página, preencher um e-mail, digitar uma senha, clicar em um botão. Mas quando uma suíte de testes cresce além de algumas dezenas de casos, o mesmo fluxo de login que funcionava localmente começa a falhar no CI. As sessões expiram no meio da execução, os workers paralelos disputam a mesma conta, e cada teste paga um imposto de login de 5 a 15 segundos antes mesmo de começar.

Este guia detalha como lidar com a autenticação no Playwright da maneira correta. Você aprenderá quando reutilizar uma sessão salva, quando isolar contas por worker, como autenticar via API em vez de UI, e como evitar que fluxos de MFA e OAuth transformem seu pipeline em um gargalo.

Por que o Login com Playwright Precisa de uma Estratégia

Login com Playwright: Automatize a Autenticação sem Testes Instáveis - Por que o Login com Playwright Precisa de uma Estratégia.

O Playwright executa cada teste em um contexto de navegador isolado. Isso significa que cookies, localStorage e cache são separados para cada teste por padrão. Esse isolamento é ótimo para reprodutibilidade, mas também significa que a autenticação não é transferida automaticamente. Sem uma estratégia, cada teste faz login do zero.

Com 20 testes, isso é irritante. Com 200 testes rodando em oito workers paralelos, é um problema sério. Cada login via UI leva segundos. Multiplique isso por centenas de testes e você adicionou de 10 a 25 minutos de sobrecarga de login a cada execução. Pior: se todos os workers compartilham uma conta, uma alteração de senha ou um prompt de MFA derruba toda a suíte.

A solução é tratar a autenticação como infraestrutura, não como código repetido dentro de cada teste. O Playwright fornece um mecanismo embutido para isso: storageState.

O Padrão Principal: Salve o Estado de Login uma Vez, Reutilize em Tudo

A API storageState do Playwright captura cookies e localStorage de um contexto de navegador autenticado e os salva em um arquivo JSON. Testes posteriores carregam esse arquivo e já começam autenticados.

Aqui está o fluxo de trabalho recomendado:

1. Crie um diretório playwright/.auth e adicione-o ao .gitignore imediatamente. O arquivo de estado contém cookies de sessão e tokens que podem se passar pela sua conta de teste.
2. Escreva um arquivo de configuração que faça login uma vez e salve o estado.
3. Configure todos os projetos de teste para carregar esse estado salvo.

Passo 1: Crie o Arquivo de Configuração

Crie tests/auth.setup.ts:

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

const authFile = path.join(__dirname, '../playwright/.auth/user.json');

setup('authenticate', async ({ page }) => {
  // Substitua pelos seus próprios passos de login.
  await page.goto('https://github.com/login');
  await page.getByLabel('Username or email address').fill('username');
  await page.getByLabel('Password').fill('password');
  await page.getByRole('button', { name: 'Sign in' }).click();

  // Aguarde a URL final para garantir que os cookies sejam realmente definidos.
  await page.waitForURL('https://github.com/');

  // Salve o estado autenticado.
  await page.context().storageState({ path: authFile });
});

Passo 2: Integre-o na Configuração

Em playwright.config.ts, declare o projeto de configuração como dependência para todos os projetos de teste:

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

export default defineConfig({
  projects: [
    { name: 'setup', testMatch: /.*\.setup\.ts/ },
    {
      name: 'chromium',
      use: {
        ...devices['Desktop Chrome'],
        storageState: 'playwright/.auth/user.json',
      },
      dependencies: ['setup'],
    },
    {
      name: 'firefox',
      use: {
        ...devices['Desktop Firefox'],
        storageState: 'playwright/.auth/user.json',
      },
      dependencies: ['setup'],
    },
  ],
});

Passo 3: Escreva Testes que Começam Autenticados

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

test('dashboard shows user name', async ({ page }) => {
  // page já está autenticada.
  await page.goto('https://github.com/');
});

Esse padrão funciona bem quando todos os testes podem rodar com a mesma conta sem interferir uns nos outros. Se seus testes modificam o estado do servidor, você precisa de uma abordagem diferente.

Quando um Único Login Compartilhado Não é Suficiente

Login com Playwright: Automatize a Autenticação sem Testes Instáveis - Quando um Único Login Compartilhado Não é Suficiente.

Uma única sessão salva falha em dois cenários comuns:

• Testes modificam o estado do servidor. Um teste altera uma configuração enquanto outro a lê. Executar em paralelo com uma conta cria condições de corrida.
• A autenticação é específica do navegador. Alguns aplicativos vinculam sessões a impressões digitais do navegador ou user agents, então um estado salvo no Chromium não funcionará no Firefox.

Nesses casos, o Playwright recomenda uma conta por worker paralelo. Cada worker autentica uma vez com sua própria conta, e todos os testes nesse worker reutilizam a sessão do worker.

Fixture de Autenticação por Worker

Crie playwright/fixtures.ts:

import { test as baseTest, expect } from '@playwright/test';
import fs from 'fs';
import path from 'path';

export * from '@playwright/test';

export const test = baseTest.extend<{}, { workerStorageState: string }>({
  storageState: ({ workerStorageState }, use) => use(workerStorageState),

  workerStorageState: [async ({ browser }, use) => {
    const id = test.info().parallelIndex;
    const fileName = path.resolve(test.info().project.outputDir, `.auth/${id}.json`);

    if (fs.existsSync(fileName)) {
      await use(fileName);
      return;
    }

    // Autentique em um contexto limpo.
    const page = await browser.newPage({ storageState: undefined });
    const account = await acquireAccount(id);

    await page.goto('https://github.com/login');
    await page.getByLabel('Username or email address').fill(account.username);
    await page.getByLabel('Password').fill(account.password);
    await page.getByRole('button', { name: 'Sign in' }).click();
    await page.waitForURL('https://github.com/');

    await page.context().storageState({ path: fileName });
    await page.close();
    await use(fileName);
  }, { scope: 'worker' }],
});

Em seguida, importe test do seu arquivo de fixtures em vez de @playwright/test. Escrever os arquivos de autenticação em testProject.outputDir significa que o Playwright os limpa automaticamente antes de cada execução, então sessões obsoletas nunca vazam para a próxima execução.

Autentique via API em vez de UI

Para projetos de configuração, o login via UI raramente é o caminho mais rápido. Se seu aplicativo suporta autenticação baseada em API, use a fixture request do Playwright para autenticar sem abrir um navegador. Isso é mais rápido e elimina a instabilidade de interações com formulários, redirecionamentos e renderização no lado do cliente.

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

const authFile = 'playwright/.auth/user.json';

setup('authenticate via API', async ({ request }) => {
  await request.post('https://github.com/login', {
    form: {
      'user': 'user',
      'password': 'password'
    }
  });
  await request.storageState({ path: authFile });
});

Use autenticação via API para velocidade na configuração. Reserve testes de login via UI para os casos dedicados que verificam o próprio fluxo de login.

A Pegadinha do Session Storage

storageState salva cookies e localStorage por padrão. Ele não salva sessionStorage. Se seu aplicativo armazena tokens JWT ou IDs de sessão no sessionStorage, o padrão comum produz silenciosamente testes não autenticados. Funciona localmente porque a sessão do navegador persiste, mas falha no CI.

Para verificar onde seu aplicativo armazena tokens de autenticação, abra o DevTools após o login e inspecione a aba Application. Se os tokens estiverem no IndexedDB, passe indexedDB: true para storageState() (disponível desde o Playwright 1.51). Se estiverem no sessionStorage, você precisará de uma solução manual que leia e restaure os valores explicitamente.

Lidando com MFA, OAuth e Magic Links

A autenticação de múltiplos fatores agora é o padrão na maioria das organizações. Provedores OAuth, sistemas SSO e magic links por e-mail adicionam dependências externas que sua suíte de testes não pode controlar totalmente. Veja como mantê-los gerenciáveis.

Códigos MFA e TOTP

Para senhas de uso único baseadas em tempo, gere códigos na configuração do teste usando uma biblioteca como otplib com um segredo compartilhado. Isso evita esperar pela entrega de SMS ou e-mail. Para códigos enviados por e-mail, use um serviço de e-mail de teste com uma API que você possa consultar no arquivo de configuração.

import { authenticator } from 'otplib';

const code = authenticator.generate(process.env.TOTP_SECRET);
await page.getByLabel('Verification code').fill(code);

Fluxos OAuth

Simule OAuth na camada de teste de funcionalidade para velocidade, mas mantenha pelo menos um teste de integração que exercite o fluxo real de redirecionamento, troca de tokens e tratamento de callback. URIs de redirecionamento mal configuradas e implementações PKCE quebradas só aparecem quando você testa o real.

Magic Links

Para fluxos de magic link, intercepte o e-mail com uma API de e-mail de teste, extraia a URL de confirmação e navegue diretamente para ela. Isso evita esperar que um humano clique no link.

Anti-Padrões Comuns no Login com Playwright

Evite esses erros que aparecem em suítes de testes reais:

• Credenciais hardcoded no Git. Armazene credenciais em variáveis de ambiente ou em um gerenciador de segredos. Arquivos storageState vazados são incidentes de segurança, não falhas de teste.
• Tokens de autenticação globalmente compartilhados. Um token armazenado em uma variável global após o primeiro teste cria uma cadeia de dependências oculta. Quando expira no meio da execução, todos os testes downstream falham.
• Esperas dependentes de tempo. Use page.waitForURL() ou expect(locator).toBeVisible() em vez de page.waitForTimeout() após o login. Fluxos de autenticação envolvem redirecionamentos em várias URLs, e sleeps fixos são a fonte mais comum de instabilidade.
• Testar apenas o caminho feliz. Cubra credenciais inválidas, bloqueios de conta, códigos MFA expirados e asserções SSO falhas. Lógica de bloqueio fraca é um problema de segurança que usuários reais enfrentam.
• Sessões remanescentes entre execuções. Escreva arquivos de autenticação em testProject.outputDir para que o Playwright os limpe automaticamente. Teardown explícito para sessões no lado do servidor mantém o ambiente consistente.

Login com Playwright e Fluxos de Múltiplas Contas

Os padrões de autenticação do Playwright se destacam em testes automatizados, mas os mesmos princípios se aplicam quando você precisa gerenciar várias sessões logadas fora de uma suíte de testes. Para equipes que operam mídias sociais, gerenciam lojas de e-commerce ou fazem marketing de afiliados em muitas contas, perfis de navegador isolados com impressões digitais únicas impedem que as plataformas vinculem contas e acionem banimentos.

Ferramentas como AdsPower fornecem esse isolamento no nível do navegador. Cada perfil tem seus próprios cookies, localStorage e impressão digital, então um login para uma conta nunca vaza para outra. O AdsPower também oferece uma API Local que integra com Selenium e Puppeteer, o que significa que você pode aplicar padrões de automação estilo Playwright a fluxos reais de múltiplas contas sem expor sessões à detecção. Se você está comparando navegadores anti-detecção para esse tipo de trabalho, veja AdsPower vs Octo Browser vs Hidemyacc para uma análise detalhada.

Para suítes de testes que precisam verificar a consistência da impressão digital antes de executar testes Playwright autenticados, combinar perfis AdsPower com testes de impressão digital BrowserScan ajuda a detectar vazamentos de IP e incompatibilidades de perfil cedo.

Leitura relacionada

• Como Usar AdsPower com Ticketmaster: Configuração e Fluxo de Trabalho - Aprenda a combinar o navegador anti-detecção AdsPower com o Ticketmaster para logins estáveis, acesso à fila e fluxos de trabalho de ingressos com múltiplas contas.
• Revisão Beautiful Soup 2026: Ainda Vale a Pena Usar? - Revisão aprofundada do Beautiful Soup cobrindo pontos fortes, limitações, configuração, preços, casos de uso ideais e como ele se compara ao Selenium e Scrapy em 2026.
• Como Usar o Navegador Anti-Detecção MuLogin: Guia Completo de Configuração - Aprenda a configurar o navegador anti-detecção MuLogin, criar perfis isolados, configurar proxies e gerenciar múltiplas contas sem banimentos neste guia prático.

Fontes e leitura adicional

• Playwright - Gerencie cookies, localStorage, sessionStorage e salve/restaure o estado completo do navegador para persistência de autenticação. Requer o recurso de armazenamento.

FAQ

Qual é a maneira mais rápida de lidar com o login no Playwright?

Autentique uma vez em um projeto de configuração usando a fixture request, salve o estado com storageState() e carregue esse estado em todos os projetos de teste. Isso elimina a sobrecarga de login via UI para todos os testes, exceto aqueles que verificam especificamente o fluxo de login.

O storageState do Playwright salva sessionStorage?

Não. storageState salva cookies e localStorage por padrão. sessionStorage não é salvo. Se seu aplicativo armazena tokens de autenticação no sessionStorage, você precisa de uma solução manual. O suporte a IndexedDB está disponível com indexedDB: true desde o Playwright 1.51.

Como executo testes Playwright em paralelo com autenticação?

Use uma conta por worker paralelo. Crie uma fixture com escopo de worker que autentica uma vez por worker usando testInfo.parallelIndex para diferenciar contas e reutilize o estado de armazenamento do worker em todos os testes do worker.

Devo commitar arquivos de estado de autenticação do Playwright no Git?

Nunca. Arquivos de estado de autenticação contêm cookies de sessão e tokens que podem se passar pela sua conta de teste. Adicione playwright/.auth ao .gitignore e armazene credenciais em variáveis de ambiente ou em um gerenciador de segredos.

Como testo login com MFA no Playwright?

Gere códigos TOTP na configuração usando uma biblioteca como otplib com um segredo compartilhado, ou consulte uma API de e-mail de teste para códigos enviados por e-mail. Evite esperar por entrega real de SMS ou e-mail em testes automatizados.

Quando devo usar login via UI em vez de login via API no Playwright?

Use login via UI apenas em testes dedicados que verificam o próprio fluxo de login: validação de formulário, tratamento de erros, redirecionamentos e prompts de MFA. Para todos os outros testes, a autenticação baseada em API no projeto de configuração é mais rápida e menos instável.

Conclusão

A automação de login com Playwright é um problema resolvido quando você trata a autenticação como infraestrutura. Salve o estado uma vez com storageState, reutilize-o nos testes e isole contas por worker quando os testes modificarem o estado do servidor. Autentique via API para velocidade, reserve o login via UI para testes de fluxo dedicados e nunca commite arquivos de autenticação no seu repositório.

A diferença entre uma suíte que roda em 3 minutos e uma que roda em 25 raramente está na lógica do teste. Está em saber se cada teste paga o imposto de login ou já começa autenticado. Construa a configuração uma vez e todo o seu pipeline ficará mais rápido.

Para leitura adicional, o guia oficial de autenticação do Playwright cobre o padrão de projeto de configuração em profundidade, e o guia completo da Currents para testar autenticação explora OAuth, MFA e integração com CI em escala.