# Testes Cypress: guia completo de integração passo a passo > O Cypress é uma ferramenta de testes de integração para aplicações web. O guia completo apresenta configuração inicial, escrita de testes robustos e execução de fluxos completos. A validação de cenários reais exige o uso de seletores estáveis e o gerenciamento de estados assíncronos. Cypress oferece comandos como cy.intercept para simular respostas de API. A adoção de boas práticas evita falhas intermitentes e garante a confiabilidade dos testes automatizados. *TNT Web · Apps e Software · 07 de setembro de 2026 · Dani Travassos* Testes de integração com Cypress validam fluxos completos da aplicação. Este guia mostra o passo a passo para configurar, escrever e executar testes robustos, evitando armadilhas comuns. Testes de integração com Cypress validam se diferentes partes da sua aplicação funcionam juntas, simulando o fluxo real de um usuário. Neste guia, você vai configurar o ambiente, escrever seu primeiro caso de teste e aprender a evitar erros comuns. O resultado esperado é uma suíte de testes confiável, executável localmente e em integração contínua. Pré-requisitos: Node.js instalado, um projeto front-end (React, Vue, Angular ou mesmo HTML puro) e acesso ao terminal. ## Passo 1: Instalar o Cypress No diretório do seu projeto, rode o comando npm install cypress --save-dev. Isso adiciona o Cypress como dependência de desenvolvimento. Depois, abra a interface gráfica com npx cypress open. Na primeira execução, o Cypress cria uma pasta cypress com exemplos prontos. Dica: se você usa Yarn, o comando é yarn add cypress --dev. Erro comum: esquecer de salvar como dependência de desenvolvimento, o que pode inflar o pacote de produção. ## Passo 2: Configurar o arquivo de suporte Dentro da pasta cypress, você encontra o arquivo support/e2e.js. Ele é carregado antes de cada teste e serve para importar comandos personalizados ou configurações globais. Por padrão, o Cypress já importa o arquivo commands.js, onde você pode criar funções reutilizáveis. Dica: mantenha seletores estáveis, usando atributos como data-cy nos elementos. Erro comum: usar seletores de classe CSS que mudam com frequência, quebrando os testes. ## Passo 3: Escrever o primeiro teste de integração Crie um arquivo em cypress/e2e, por exemplo login.cy.js. Dentro dele, use describe para agrupar casos e it para cada cenário. Um teste simples de login pode ser: describe('Login', () => { it('acessa a área logada', () => { cy.visit('/login'); cy.get('[data-cy=email]').type('usuario@email.com'); cy.get('[data-cy=senha]').type('123456'); cy.get('[data-cy=entrar]').click(); cy.url().should('include', '/dashboard'); }); }); Dica: use cy.intercept() para simular respostas de API e testar cenários de erro sem depender do backend. Erro comum: esquecer de limpar o estado entre testes, o que pode causar falsos positivos. ## Passo 4: Executar e depurar Rode os testes com npx cypress run no terminal ou npx cypress open para o modo interativo. No modo interativo, você vê cada passo executado em tempo real, com a possibilidade de pausar e inspecionar o DOM. O Cypress também grava vídeos e capturas de tela em caso de falha, que ficam na pasta cypress/videos e cypress/screenshots. Dica: use cy.pause() no meio de um teste para inspecionar o estado exato. Erro comum: ignorar as mensagens de erro detalhadas que o Cypress exibe na própria interface. ## Passo 5: Integrar ao CI Para rodar os testes em um ambiente de integração contínua, adicione um script no package.json: "test:e2e": "cypress run". Em seguida, configure o pipeline para executar esse comando após o build da aplicação. Se a sua aplicação precisa de um servidor local, use o cypress run com a opção --config baseUrl=http://localhost:3000 ou o plugin start-server-and-test. Dica: no CI, use a imagem Docker oficial do Cypress para garantir consistência. Erro comum: não aguardar a aplicação estar pronta antes de rodar os testes, gerando falhas intermitentes. ## Checklist do que foi feito - Cypress instalado como dependência de desenvolvimento - Arquivo de suporte configurado com seletores estáveis - Primeiro teste de integração escrito e executado - Depuração feita com modo interativo e vídeos de falha - Integração contínua configurada para rodar a suíte ## Perguntas frequentes ### O Cypress serve para testes unitários? O Cypress é focado em testes de integração e ponta a ponta, não em testes unitários. Para testar funções isoladas, ferramentas como Jest ou Vitest são mais adequadas. O Cypress pode ser usado para testes de componente, mas o cenário principal é validar fluxos completos. ### Qual a diferença entre Cypress e Selenium? O Cypress roda diretamente no navegador via JavaScript, sem precisar de um driver externo como o WebDriver do Selenium. Isso torna a execução mais rápida e a depuração mais integrada. O Selenium é mais flexível para múltiplos navegadores e linguagens, enquanto o Cypress é mais simples para projetos JavaScript. ### Como lidar com testes que dependem de autenticação? Use o comando cy.session() para armazenar o token de login e reutilizá-lo entre testes. Isso evita repetir o fluxo de login em cada caso. Você também pode usar cy.request() para autenticar via API e depois visitar a página com o cookie já definido. ### O Cypress funciona com aplicações que usam iframes? O Cypress suporta iframes, mas exige configuração adicional. Você pode acessar o conteúdo do iframe usando cy.iframe() se tiver o plugin cypress-iframe, ou manipular diretamente com cy.get('iframe').then(). Testes com iframes tendem a ser mais frágeis, então avalie se o fluxo realmente precisa deles. ### Como evitar que testes fiquem lentos? Priorize testes que validem o fluxo principal e use cy.intercept() para simular respostas de API. Evite esperas fixas com cy.wait(1000); prefira asserções automáticas como cy.get().should() que já esperam o elemento aparecer. Isso reduz o tempo de execução e a flakiness. ### Preciso saber programação para usar o Cypress? Um conhecimento básico de JavaScript é suficiente para começar. Os comandos do Cypress são intuitivos e a documentação oficial traz exemplos práticos. Com o tempo, você pode aprender padrões mais avançados, como custom commands e testes de API integrados. --- Fonte (canonical): https://tntweb.com.br/apps-e-software/testes-cypress-guia-completo-de-integracao-passo-a-passo/