Testes que passam localmente mas falham no CI quase sempre não são bugs nos testes: são diferenças de ambiente entre versões do Node, builds do navegador ou dependências de sistema que faltam. O Docker resolve isso empacotando o Playwright, os binários dos navegadores e todas as dependências em uma única imagem. Ela roda de forma idêntica no seu laptop, na máquina de um colega e no CI.

Por que QA engineers precisam do Docker

Sem Docker:
  • Seus testes passam localmente com Node 20, falham no CI com Node 18
  • A versão do Chrome no CI difere do laptop
  • Variáveis de ambiente configuradas diferente em cada máquina
  • Um novo membro do time passa um dia tentando fazer os testes rodar
Com Docker:
  • Os testes rodam no mesmo container localmente e no CI
  • Todos usam as mesmas versões de Node, Chrome e dependências
  • Novo membro do time: docker compose up — testes rodando em 2 minutos

Conceitos básicos

Image

Uma image é um blueprint: um snapshot somente-leitura de um sistema de arquivos com software instalado. Pense como uma classe no código.

playwright/playwright:latest — imagem com Playwright e navegadores pré-instalados
node:20-alpine — Node.js 20 no Alpine Linux mínimo

Container

Um container é uma instância em execução de uma imagem. Vários containers podem rodar a partir da mesma imagem simultaneamente. Como criar vários objetos a partir da mesma classe.

Dockerfile

Instruções para construir uma imagem customizada. Você começa de uma imagem base e adiciona seus arquivos e configurações.

Docker Compose

Ferramenta para rodar vários containers juntos. Seus testes podem precisar de um servidor web e de um banco de dados rodando. O Compose inicia tudo com um único comando.

Seu primeiro Dockerfile para Playwright

O Playwright fornece imagens Docker oficiais com navegadores pré-instalados:

# Dockerfile
FROM mcr.microsoft.com/playwright:v1.44.0-jammy

# Diretório de trabalho dentro do container
WORKDIR /app

# Copia os arquivos de dependências primeiro (otimização de cache)
COPY package.json package-lock.json ./

# Instala as dependências Node
RUN npm ci

# Copia o restante do projeto
COPY . .

# Comando padrão: rodar todos os testes
CMD ["npx", "playwright", "test"]

Construa a imagem: 

docker build -t my-playwright-tests .

Rode os testes: 

docker run my-playwright-tests

Chrome, Firefox e WebKit estão todos dentro do container. Nenhuma instalação de navegador necessária na máquina host.

Rodando testes com Docker

Execução básica

# Rodar todos os testes
docker run my-playwright-tests

# Rodar um arquivo específico
docker run my-playwright-tests npx playwright test tests/login.spec.ts

# Rodar com variável de ambiente
docker run -e BASE_URL=https://staging.myapp.com my-playwright-tests

# Montar diretório local (para ver os resultados dos testes)
docker run -v $(pwd)/playwright-report:/app/playwright-report my-playwright-tests

Salvando resultados dos testes

O sistema de arquivos do container some quando ele para. Use volume mounts para salvar relatórios:

docker run \
  -v $(pwd)/playwright-report:/app/playwright-report \
  -v $(pwd)/test-results:/app/test-results \
  my-playwright-tests

O playwright-report/ aparece na sua máquina local após a execução.

Docker Compose para testes full stack

Testar de verdade frequentemente exige que a aplicação também esteja rodando. O Compose inicia tudo junto.

# docker-compose.yml
version: '3.8'

services:
  # A aplicação sendo testada
  app:
    image: myapp:latest
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=test
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/testdb
    depends_on:
      db:
        condition: service_healthy

  # Banco de dados
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: testdb
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  # Testes Playwright
  tests:
    build: .
    environment:
      - BASE_URL=http://app:3000
    depends_on:
      - app
    volumes:
      - ./playwright-report:/app/playwright-report
      - ./test-results:/app/test-results

Rode tudo: 

docker compose up --exit-code-from tests

O que acontece nessa ordem:

  • Inicia o banco de dados
  • Espera ele estar healthy
  • Inicia a aplicação
  • Roda os testes
  • Retorna o exit code dos testes (para o CI saber se passou ou falhou)
--exit-code-from tests faz o processo terminar com o exit code do container de testes.

Otimizando o Dockerfile

O cache de camadas torna os rebuilds rápidos. A regra principal: coloque o que muda raramente no topo.

FROM mcr.microsoft.com/playwright:v1.44.0-jammy

WORKDIR /app

# 1. Copia os arquivos de dependências (mudam raramente)
COPY package.json package-lock.json ./
# Esta camada fica em cache até o package.json mudar
RUN npm ci

# 2. Copia o restante (muda a cada commit)
COPY . .

CMD ["npx", "playwright", "test"]

Se você só alterou arquivos de teste, o Docker reutiliza a camada do npm ci do cache. Tempo de build: segundos em vez de minutos.

Integração com CI/CD

GitHub Actions

# .github/workflows/playwright.yml
name: Playwright Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Build test image
        run: docker build -t playwright-tests .
      
      - name: Run tests
        run: |
          docker run \
            -v ${{ github.workspace }}/playwright-report:/app/playwright-report \
            -e BASE_URL=${{ secrets.STAGING_URL }} \
            playwright-tests
      
      - name: Upload report
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: playwright-report
          path: playwright-report/

GitLab CI

# .gitlab-ci.yml
test:
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker build -t tests .
    - docker run
        -v $(pwd)/playwright-report:/app/playwright-report
        -e BASE_URL=$STAGING_URL
        tests
  artifacts:
    when: always
    paths:
      - playwright-report/

Comandos Docker úteis para QA

# Listar containers em execução
docker ps

# Listar todas as imagens
docker images

# Parar todos os containers em execução
docker stop $(docker ps -q)

# Remover todos os containers parados
docker container prune

# Remover imagens não utilizadas
docker image prune

# Acompanhar logs do container
docker logs -f <container-id>

# Abrir um shell dentro de um container em execução (ótimo para debug)
docker exec -it <container-id> /bin/bash

# Rodar um container de forma interativa
docker run -it my-playwright-tests /bin/bash

Debugando dentro de um container

Quando os testes falham apenas no container:

# Iniciar o container com shell em vez dos testes
docker run -it my-playwright-tests /bin/bash

# Agora você está dentro do container
# Verificar o que está instalado
node --version
npx playwright --version

# Rodar testes manualmente
npx playwright test tests/login.spec.ts --headed --debug

# Verificar variáveis de ambiente
env | grep BASE_URL

Problemas comuns:

  • BASE_URL apontando para localhost (funciona no host, falha no container: use o nome do serviço em vez disso)
  • Variáveis de ambiente faltando
  • Permissões de arquivo (arquivos criados fora do container podem pertencer ao root dentro dele)

A imagem oficial do Playwright para Docker

# Baixar a imagem do Playwright
docker pull mcr.microsoft.com/playwright:v1.44.0-jammy

# Ver o que está dentro
docker run -it mcr.microsoft.com/playwright:v1.44.0-jammy /bin/bash

# Verificar navegadores instalados
npx playwright install --list

Tags importantes:

  • v1.44.0-jammy: versão específica do Playwright no Ubuntu 22.04 (Jammy)
  • latest: versão mais recente (pode quebrar quando o Playwright atualiza)
  • Sempre fixe em uma versão específica em produção

Resumo

| Conceito | O que é |

|----------|---------|

| Image | Blueprint com software pré-instalado |

| Container | Instância em execução de uma imagem |

| Dockerfile | Instruções para construir uma imagem customizada |

| Docker Compose | Roda vários containers juntos |

| Volume mount | Compartilha arquivos entre host e container |

Para o Playwright especificamente:

1. Use mcr.microsoft.com/playwright como imagem base — navegadores incluídos

2. Monte os diretórios de relatório para os resultados sobreviverem ao container parar

3. Use o Compose para iniciar sua aplicação e os testes juntos

4. Fixe as versões das imagens: latest causa quebras inesperadas

Docker transforma "funciona na minha máquina" em "funciona em qualquer lugar". Para QA, isso significa que os testes estão realmente testando o software, não brigando com diferenças de ambiente.

→ Veja também: Docker para Testadores: Executando Playwright em Contêineres | CI/CD para QA: GitHub Actions, Jenkins e GitLab Comparados | GitHub Actions para Testes Playwright: A Configuração Completa (2026)