globalSetup roda uma vez antes de qualquer worker de navegador iniciar, no processo principal, sem acesso direto aos testes. Compartilhe dados por arquivos escritos em disco ou variáveis de ambiente definidas com process.env. O uso mais comum é fazer login uma vez e salvar o resultado com storageState, para que cada teste da suite comece autenticado sem repetir o fluxo de login.

O que é o global setup

O Playwright executa uma função globalSetup uma vez antes de toda a suite de testes começar, e uma função globalTeardown uma vez após tudo terminar. Essas rodam no processo principal, antes de qualquer worker de navegador iniciar.

Use o global setup para:

  • Autenticar e salvar storageState (uso mais comum)
  • Popular o banco de dados de teste com dados de base
  • Iniciar um servidor mock ou servidor de teste
  • Gerar arquivos de dados de teste

Configuração básica

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  globalSetup: require.resolve('./global-setup'),
  globalTeardown: require.resolve('./global-teardown'),
  use: {
    baseURL: 'http://localhost:3000',
  },
});

O uso mais comum: salvando o estado de autenticação

// global-setup.ts
import { chromium, FullConfig } from '@playwright/test';

async function globalSetup(config: FullConfig) {
  const { baseURL } = config.projects[0].use;
  const browser = await chromium.launch();
  const page = await browser.newPage();

  await page.goto(`${baseURL}/login`);
  await page.getByLabel('Email').fill(process.env.TEST_USER_EMAIL!);
  await page.getByLabel('Password').fill(process.env.TEST_USER_PASSWORD!);
  await page.getByRole('button', { name: 'Log in' }).click();
  await page.waitForURL(`${baseURL}/dashboard`);

  // Salva cookies + localStorage para reutilização
  await page.context().storageState({ path: 'playwright/.auth/user.json' });
  await browser.close();
}

export default globalSetup;

// playwright.config.ts — usa o auth salvo em todos os testes
use: {
  storageState: 'playwright/.auth/user.json',
},

Cada teste agora começa já autenticado. Sem step de login. Sem setup de sessão por teste. O login acontece uma única vez.

Múltiplos papéis de usuário

Para apps com papéis de admin e usuário regular:

// global-setup.ts
async function globalSetup(config: FullConfig) {
  const { baseURL } = config.projects[0].use;
  const browser = await chromium.launch();

  // Salva auth do admin
  const adminPage = await browser.newPage();
  await loginAs(adminPage, `${baseURL}`, process.env.ADMIN_EMAIL!, process.env.ADMIN_PASSWORD!);
  await adminPage.context().storageState({ path: 'playwright/.auth/admin.json' });
  await adminPage.close();

  // Salva auth do usuário regular
  const userPage = await browser.newPage();
  await loginAs(userPage, `${baseURL}`, process.env.USER_EMAIL!, process.env.USER_PASSWORD!);
  await userPage.context().storageState({ path: 'playwright/.auth/user.json' });
  await userPage.close();

  await browser.close();
}

async function loginAs(page: Page, baseURL: string, email: string, password: string) {
  await page.goto(`${baseURL}/login`);
  await page.getByLabel('Email').fill(email);
  await page.getByLabel('Password').fill(password);
  await page.getByRole('button', { name: 'Log in' }).click();
  await page.waitForURL(`${baseURL}/dashboard`);
}

Depois use estados de auth diferentes por projeto:

// playwright.config.ts
projects: [
  {
    name: 'admin-tests',
    use: { storageState: 'playwright/.auth/admin.json' },
    testMatch: '**/admin/**/*.spec.ts',
  },
  {
    name: 'user-tests',
    use: { storageState: 'playwright/.auth/user.json' },
    testMatch: '**/user/**/*.spec.ts',
  },
],

Seed de banco de dados no global setup

// global-setup.ts
import { Pool } from 'pg';

async function globalSetup() {
  const pool = new Pool({ connectionString: process.env.DATABASE_URL });

  // Popula dados de base de teste uma vez
  await pool.query(`
    INSERT INTO users (email, password_hash, role)
    VALUES ('testuser@example.com', $1, 'user')
    ON CONFLICT (email) DO NOTHING
  `, [hashedPassword]);

  await pool.end();
}

Seed de banco de dados no global setup funciona para dados de base estáticos. Para dados específicos de teste que precisam ser isolados e limpos, use fixtures: elas rodam por teste e fazem o cleanup automaticamente.

Global teardown

// global-teardown.ts
import { Pool } from 'pg';

async function globalTeardown() {
  // Limpa dados de teste após a suite completa
  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  await pool.query("DELETE FROM users WHERE email LIKE '%@test.example.com'");
  await pool.end();

  // Para quaisquer servidores iniciados no globalSetup
  // (se você armazenou uma referência em process ou global)
}

export default globalTeardown;

Compartilhando dados entre global setup e testes

O global setup roda em um processo separado dos testes. Você não pode passar objetos JavaScript diretamente. As opções são:

Arquivos: salve dados em disco no global setup, leia nos testes. 

// global-setup.ts
import fs from 'fs';

async function globalSetup() {
  const testData = { userId: '123', orderId: '456' };
  fs.writeFileSync('playwright/.test-data.json', JSON.stringify(testData));
}

// nos testes
import testData from '../playwright/.test-data.json';
test('usa dados populados', async ({ page }) => {
  await page.goto(`/orders/${testData.orderId}`);
});

Variáveis de ambiente: defina com process.env.KEY = value no global setup. Ficam disponíveis nos processos worker dos testes. Use para valores simples (IDs, tokens).

Rodando global setup condicionalmente

Pule o global setup ao rodar testes individuais localmente:

// global-setup.ts
async function globalSetup() {
  // Pula se o arquivo de auth já existe e é recente
  const authFile = 'playwright/.auth/user.json';
  if (fs.existsSync(authFile)) {
    const stats = fs.statSync(authFile);
    const ageMinutes = (Date.now() - stats.mtimeMs) / 60000;
    if (ageMinutes < 30) {
      console.log('Estado de auth recente, pulando login...');
      return;
    }
  }

  // Caso contrário, faz login e salva
  // ...
}

Isso torna as execuções locais repetidas mais rápidas: o step de login só acontece quando o auth salvo está ausente ou desatualizado.

→ Veja também: Autenticação no Playwright com storageState (Sem Login em Cada Teste) | Fixtures do Playwright Explicadas: Das Integradas às Personalizadas | Isolamento de Testes: Por que Cada Teste Playwright Deve Ser sem Estado