Pipeline de QA com Cypress: Guia Completo do Zero

Introdução

Neste artigo, você aprenderá a criar uma pipeline completa de QA (Quality Assurance) utilizando Cypress para testes automatizados. Ao final, você terá uma pipeline funcionando que executa testes automaticamente a cada commit no seu repositório.

O que é uma Pipeline de QA?

Uma pipeline de QA é um processo automatizado que executa testes sempre que há mudanças no código. Isso garante que novas funcionalidades não quebrem o que já estava funcionando, aumentando a qualidade e confiabilidade do software.

Pré-requisitos

Antes de começar, certifique-se de ter instalado:

• Node.js (versão 16 ou superior)
• npm ou yarn
• Git
• Uma conta no GitHub

PASSO 1: Criando o Projeto

Primeiro, vamos criar a estrutura básica do projeto.

1.1 Crie uma pasta para o projeto

mkdir projeto-cypress-pipeline
cd projeto-cypress-pipeline

O que fizemos: Criamos um diretório vazio onde nosso projeto será desenvolvido.

1.2 Inicialize o projeto Node.js

npm init -y

O que fizemos: O comando npm init -y cria o arquivo package.json que gerencia as dependências do projeto. O -y aceita automaticamente as configurações padrão.

PASSO 2: Instalando o Cypress

2.1 Instale o Cypress como dependência de desenvolvimento

npm install cypress --save-dev

O que fizemos: Instalamos o Cypress localmente no projeto. O --save-dev indica que é uma ferramenta de desenvolvimento, não necessária em produção.

2.2 Abra o Cypress pela primeira vez

npx cypress open

O que fizemos: Este comando abre a interface do Cypress e cria automaticamente a estrutura de pastas necessária:

• cypress/e2e/ - onde ficam os testes
• cypress/fixtures/ - dados de teste
• cypress/support/ - comandos customizados
• cypress.config.js - configurações do Cypress

Feche a janela do Cypress após abrir. Agora temos a estrutura pronta!

PASSO 3: Criando um Teste de Exemplo

Vamos criar um teste real que será executado na nossa pipeline.

3.1 Crie o arquivo de teste

Crie o arquivo cypress/e2e/exemplo-teste.cy.js com o seguinte conteúdo:

// cypress/e2e/exemplo-teste.cy.js
describe('Teste de Exemplo - Busca no Google', () => {

  // Este bloco executa antes de cada teste
  beforeEach(() => {
    // Visita a página do Google
    cy.visit('https://www.google.com')
  })
  it('Deve carregar a página inicial do Google', () => {
    // Verifica se o título contém "Google"
    cy.title().should('include', 'Google')

    // Verifica se o logo do Google está visível
    cy.get('img[alt*="Google"]').should('be.visible')
  })
  it('Deve realizar uma busca', () => {
    // Aceita os cookies se aparecer o banner
    cy.get('body').then($body => {
      if ($body.find('button:contains("Aceitar")').length > 0) {
        cy.contains('button', 'Aceitar').click()
      }
    })
    // Digita no campo de busca
    cy.get('textarea[name="q"]').type('Cypress automation{enter}')

    // Aguarda os resultados carregarem
    cy.url().should('include', 'search?q=Cypress')

    // Verifica se há resultados
    cy.get('#search').should('be.visible')
  })
  it('Deve verificar o campo de busca está presente', () => {
    // Verifica se o campo de busca existe e está visível
    cy.get('textarea[name="q"]').should('exist').and('be.visible')
  })
})

O que fizemos:

• describe() agrupa os testes relacionados
• beforeEach() executa antes de cada teste (útil para preparar o ambiente)
• it() define cada caso de teste individual
• cy.visit() navega para uma URL
• cy.get() seleciona elementos na página
• should() faz asserções/verificações
• type() simula digitação
• Criamos 3 testes: verificar carregamento, realizar busca e verificar elemento

PASSO 4: Configurando o Cypress

4.1 Edite o arquivo cypress.config.js

// cypress.config.js
const { defineConfig } = require('cypress')
module.exports = defineConfig({
  e2e: {
    // URL base para os testes
    baseUrl: 'https://www.google.com',

    // Tempo máximo de espera para comandos (em ms)
    defaultCommandTimeout: 10000,

    // Tempo máximo para carregar uma página
    pageLoadTimeout: 30000,

    // Configuração de vídeo e screenshots
    video: true,
    screenshotOnRunFailure: true,

    // Configuração dos testes
    setupNodeEvents(on, config) {
      // implementar listeners de eventos aqui
      return config
    },
  },
})

O que fizemos: Configuramos parâmetros importantes:

• baseUrl: URL padrão para os testes
• defaultCommandTimeout: quanto tempo esperar por elementos
• video: grava vídeo dos testes
• screenshotOnRunFailure: tira print quando falha

PASSO 5: Adicionando Scripts no package.json

5.1 Edite o arquivo package.json

Adicione os seguintes scripts na seção "scripts":

{
  "name": "projeto-cypress-pipeline",
  "version": "1.0.0",
  "description": "Projeto de exemplo com pipeline Cypress",
  "scripts": {
    "cypress:open": "cypress open",
    "cypress:run": "cypress run",
    "test": "cypress run --browser chrome",
    "test:headed": "cypress run --headed --browser chrome"
  },
  "devDependencies": {
    "cypress": "^13.6.0"
  }
}

O que fizemos: Criamos atalhos para executar os testes:

• cypress:open: abre a interface gráfica
• cypress:run: executa testes no modo headless (sem interface)
• test: executa testes no Chrome headless
• test:headed: executa com interface visível

PASSO 6: Testando Localmente

Antes de criar a pipeline, vamos testar localmente.

6.1 Execute os testes

npm test

O que acontece: O Cypress executará todos os testes do diretório cypress/e2e/ e mostrará os resultados no terminal.

6.2 Execute com interface gráfica (opcional)

npm run cypress:open

O que acontece: Abre a interface do Cypress onde você pode ver os testes executando em tempo real, útil para debug.

PASSO 7: Criando a Pipeline no GitHub Actions

Agora vamos automatizar os testes para executarem a cada push no GitHub.

7.1 Crie a estrutura de pastas

mkdir -p .github/workflows

7.2 Crie o arquivo de configuração da pipeline

Crie o arquivo .github/workflows/cypress-tests.yml:

# .github/workflows/cypress-tests.yml
name: Pipeline Cypress E2E Tests
# Quando a pipeline será executada
on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]
# Definição dos jobs
jobs:
  cypress-run:
    # Sistema operacional
    runs-on: ubuntu-22.04

    # Nome do job
    name: Testes E2E com Cypress

    steps:
      # 1. Faz checkout do código
      - name: Checkout do código
        uses: actions/checkout@v4

      # 2. Configura o Node.js
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'

      # 3. Instala as dependências
      - name: Instalar dependências
        run: npm ci

      # 4. Executa os testes Cypress
      - name: Executar testes Cypress
        uses: cypress-io/github-action@v6
        with:
          browser: chrome
          headed: false

      # 5. Upload de screenshots em caso de falha
      - name: Upload de screenshots
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: cypress-screenshots
          path: cypress/screenshots

      # 6. Upload de vídeos dos testes
      - name: Upload de vídeos
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: cypress-videos
          path: cypress/videos

O que fizemos — Explicação detalhada:

• name: Nome da pipeline que aparecerá no GitHub
• on: Define quando executar (push e pull requests nas branches main/develop)
• runs-on: Sistema operacional (Ubuntu Linux)
• steps: Sequência de ações:

1. checkout: Baixa o código do repositório
2. setup-node: Instala Node.js versão 18
3. npm ci: Instala dependências (mais rápido que npm install)
4. cypress-io/github-action: Action oficial do Cypress que executa os testes
5. upload-artifact: Salva screenshots se houver falhas
6. upload-artifact: Salva vídeos dos testes

PASSO 8: Inicializando o Git e Enviando para o GitHub

8.1 Crie o arquivo .gitignore

# .gitignore
node_modules/
cypress/videos/
cypress/screenshots/
cypress/downloads/
.DS_Store

O que fizemos: Definimos arquivos que não devem ser enviados ao GitHub (dependências, vídeos, etc).

8.2 Inicialize o repositório Git

git init
git add .
git commit -m "Configuração inicial da pipeline Cypress"

O que fizemos:

• git init: Cria repositório Git local
• git add .: Adiciona todos os arquivos
• git commit: Salva as mudanças com mensagem

8.3 Crie um repositório no GitHub

1. Acesse https://github.com
2. Clique em “New repository”
3. Dê um nome (ex: projeto-cypress-pipeline)
4. Não inicialize com README
5. Clique em “Create repository”

8.4 Conecte e envie o código

git remote add origin https://github.com/SEU-USUARIO/projeto-cypress-pipeline.git
git branch -M main
git push -u origin main

O que fizemos: Conectamos o repositório local ao GitHub e enviamos o código.

PASSO 9: Verificando a Pipeline em Ação

9.1 Acesse a aba Actions no GitHub

1. Vá ao seu repositório no GitHub
2. Clique na aba “Actions”
3. Você verá a pipeline executando!

9.2 Acompanhe a execução

• Verde ✅: Todos os testes passaram
• Vermelho ❌: Algum teste falhou
• Clique na execução para ver detalhes

9.3 Visualize os artefatos

Se houver falhas, você pode baixar:

• Screenshots: Capturas de tela do momento da falha
• Vídeos: Gravação completa dos testes

PASSO 10: Fazendo Mudanças e Testando a Pipeline

Vamos adicionar um novo teste para ver a pipeline em ação.

10.1 Crie um novo arquivo de teste

Crie cypress/e2e/teste-adicional.cy.js:

// cypress/e2e/teste-adicional.cy.jsdescribe('Teste Adicional - Verificações Básicas', () => {

  it('Deve verificar elementos da página', () => {
    cy.visit('https://example.com')

    // Verifica o título da página
    cy.title().should('eq', 'Example Domain')

    // Verifica se há um heading h1
    cy.get('h1').should('be.visible')
      .and('contain', 'Example Domain')

    // Verifica se há um link
    cy.get('a').should('exist')
  })
  it('Deve clicar em um link', () => {
    cy.visit('https://example.com')

    // Clica no link "More information..."
    cy.contains('More information').click()

    // Verifica se foi redirecionado
    cy.url().should('include', 'iana.org')
  })
})

10.2 Teste localmente

npm test

10.3 Envie para o GitHub

git add .
git commit -m "Adicionando novo teste"
git push

O que acontece: Automaticamente a pipeline será executada e você verá os resultados na aba Actions!

Como Executar os Testes — Resumo dos Comandos

Execução Local

# Modo headless (sem interface - mais rápido)
npm test
# Modo headed (com interface visível)
npm run test:headed
# Interface gráfica interativa
npm run cypress:open
# Executar arquivo específico
npx cypress run --spec "cypress/e2e/exemplo-teste.cy.js"

Execução na Pipeline

Os testes executam automaticamente quando você:

1. Faz push para as branches main ou develop
2. Abre um Pull Request
3. Pode executar manualmente na aba Actions > Run workflow

Estrutura Final do Projeto

projeto-cypress-pipeline/
├── .github/
│   └── workflows/
│       └── cypress-tests.yml       # Configuração da pipeline
├── cypress/
│   ├── e2e/
│   │   ├── exemplo-teste.cy.js     # Testes principais
│   │   └── teste-adicional.cy.js   # Testes adicionais
│   ├── fixtures/                   # Dados de teste
│   ├── support/
│   │   ├── commands.js             # Comandos customizados
│   │   └── e2e.js                  # Configurações globais
├── node_modules/                   # Dependências (não versionar)
├── .gitignore                      # Arquivos ignorados pelo Git
├── cypress.config.js               # Configurações do Cypress
└── package.json                    # Dependências e scripts

Interpretando os Resultados

Terminal/Console

Teste de Exemplo - Busca no Google
    ✓ Deve carregar a página inicial do Google (1234ms)
    ✓ Deve realizar uma busca (2345ms)
    ✓ Deve verificar o campo de busca está presente (567ms)
3 passing (4s)

• ✓ = Teste passou
• Tempo entre parênteses = duração do teste
• passing = total de testes que passaram

GitHub Actions

• Status verde: Todos os testes passaram
• Status vermelho: Algum teste falhou
• Clique no job para ver logs detalhados
• Baixe artefatos (vídeos/screenshots) para debug

Dicas Importantes

1. Seletores Confiáveis

Prefira seletores por:

• data-testid: cy.get('[data-testid="botao-login"]')
• ID: cy.get('#meu-id')
• Evite classes CSS que mudam com frequência

2. Esperas Inteligentes

// Espera elemento estar visível
cy.get('.elemento').should('be.visible')
// Espera requisição completar
cy.intercept('GET', '/api/dados').as('getDados')
cy.wait('@getDados')

3. Comandos Customizados

Crie em cypress/support/commands.js:

Cypress.Commands.add('login', (email, senha) => {
  cy.get('#email').type(email)
  cy.get('#senha').type(senha)
  cy.get('#botao-login').click()
})
// Usar: cy.login('user@example.com', 'senha123')

4. Fixtures para Dados

Crie cypress/fixtures/usuarios.json:

{
  "usuarioPadrao": {
    "email": "teste@example.com",
    "senha": "senha123"
  }
}

Use no teste:

cy.fixture('usuarios').then((usuarios) => {
  cy.login(usuarios.usuarioPadrao.email, usuarios.usuarioPadrao.senha)
})

Próximos Passos

Agora que sua pipeline está funcionando, você pode:

1. Adicionar mais testes: Cubra diferentes funcionalidades
2. Testar em múltiplos navegadores: Chrome, Firefox, Edge
3. Adicionar relatórios: Mochawesome, Allure
4. Integrar com Slack/Email: Notificações de falhas
5. Testes de API: Use cy.request()
6. Paralelização: Execute testes mais rápido

Solução de Problemas Comuns

Erro: “Cypress is not installed”

npm install cypress --save-dev

Erro: “Timed out waiting for element”

Aumente o timeout:

cy.get('.elemento', { timeout: 10000 })

Pipeline falha mas local funciona

Verifique:

• Versões do Node.js
• Cache do npm: npm ci ao invés de npm install
• Variáveis de ambiente

Testes instáveis

Use cy.wait() com moderação, prefira:

javascript

cy.get('.loading').should('not.exist')
cy.get('.conteudo').should('be.visible')

Conclusão

Parabéns! 🎉 Você criou uma pipeline completa de QA com Cypress que:

✅ Executa testes automaticamente a cada commit

✅ Fornece feedback rápido sobre problemas

✅ Gera vídeos e screenshots de falhas

✅ Pode ser executada localmente e no CI/CD

✅ É escalável e fácil de manter

Esta base sólida permite que você expanda seus testes e garanta a qualidade contínua do seu software. Continue praticando e adicionando mais testes ao seu projeto!

Se esse artigo fez sentido pra você, tem muito mais no meu ebook Do Zero ao QA Sênior — um roadmap completo com técnicas, ferramentas, KPIs, automação e plano de carreira para cada fase: Júnior, Pleno e Sênior.

Mais de 20 anos de experiência em projetos críticos de telecom, saúde e governo condensados num guia prático que eu gostaria de ter tido quando comecei.

👇 Acesse aqui:

https://lilianborbadeoliveira.hotmart.host/do-zero-ao-qa-senior-328ec0f1-ac56-4dab-999d-cbef69135bf4