Este documento explica como executar os testes automatizados do sistema NFSe-emissao utilizando o Cypress.
Node.js instalado (versão 16 ou superior)
NPM ou Yarn instalado
Projeto NFSe-emissao configurado e funcionando localmente
Para instalar o Cypress, execute o seguinte comando no terminal:
npm install cypress@14.4.0 cypress-file-upload --save-dev
Se você encontrar problemas durante a instalação, pode tentar limpar o cache e reinstalar:
npx cypress cache clear
npx cypress install
Para simplificar o processo de instalação e execução, você pode usar os scripts PowerShell fornecidos:
| Script | Descrição | Quando Usar |
|--------|-----------|------------|
| executar-testes-cypress.ps1 | Limpa o cache, instala o Cypress, verifica se o servidor está rodando e inicia o Cypress no modo interativo | Para primeira execução ou quando precisar de uma instalação limpa |
| executar-testes-sem-limpar-cache.ps1 | Instala o Cypress sem limpar o cache e executa os testes em modo headless | Para execução rápida ou quando há problemas com limpeza de cache |
# Para primeira execução ou quando precisar de uma instalação limpa
.\executar-testes-cypress.ps1
# Para execução rápida ou quando há problemas com limpeza de cache
.\executar-testes-sem-limpar-cache.ps1
Estes scripts automatizam o processo de instalação e execução do Cypress com as configurações adequadas.
O projeto utiliza comandos personalizados do Cypress para facilitar a escrita dos testes. Abaixo estão os principais comandos disponíveis:
| Comando | Descrição | Exemplo |
|---------|-----------|--------|
| cy.fazerLogin(username, password) | Realiza o login no sistema | cy.fazerLogin('admin', 'senha123') |
| cy.irPara(rota) | Navega para uma rota específica | cy.irPara('/prestadores') |
| cy.verificarTitulo(titulo) | Verifica se o título da página está correto | cy.verificarTitulo('Prestadores') |
| cy.selecionarOpcao(seletor, valor) | Seleciona uma opção em um select personalizado | cy.selecionarOpcao('.select', 'Opção 1') |
| cy.anexarArquivo(seletor, nomeArquivo, tipoArquivo) | Anexa um arquivo a um input de arquivo | cy.anexarArquivo('input[type="file"]', 'logo.png', 'image/png') |
Estes comandos estão definidos no arquivo cypress/support/commands.ts e os tipos estão declarados em cypress/support/index.d.ts.
Para abrir o Cypress em modo interativo, onde você pode selecionar os testes visualmente:
npm run cypress:open
Isso abrirá a interface gráfica do Cypress, onde você pode:
Selecionar o tipo de teste (E2E ou Component)
Escolher o navegador para executar os testes
Visualizar e executar os testes individualmente
Para executar todos os testes em modo headless, gerando relatórios e screenshots para testes que falharem.
npm run cypress:run
Ou simplesmente:
npm test
Se você encontrar erros relacionados a permissões ao executar o Cypress, tente usar o navegador Electron em vez do Chrome:
npx cypress run --browser electron
Se você encontrar erros como “resource busy or locked” ao limpar o cache do Cypress, tente:
Fechar todas as instâncias do Cypress em execução
Executar o script sem limpar o cache: executar-testes-sem-limpar-cache.ps1
Se o problema persistir, reinicie o computador e tente novamente
Se você encontrar erros de tipo relacionados aos comandos personalizados, verifique se o arquivo cypress/support/index.d.ts está configurado corretamente com as definições de tipo para todos os comandos personalizados.
Se você encontrar problemas com caracteres especiais nos arquivos de teste (como á, é, í, etc. aparecendo incorretamente), execute o script de correção de codificação:
.\corrigir-encoding-simples.ps1
Este script corrige problemas de codificação de caracteres nos arquivos de teste, garantindo que todos estejam em UTF-8 sem BOM. É importante que todos os arquivos de teste estejam em UTF-8 para evitar problemas com caracteres especiais.
Para executar um teste específico:
npx cypress run --spec "cypress/e2e/login.cy.ts"
Substitua login.cy.ts pelo arquivo de teste que deseja executar.
Os testes estão organizados na pasta cypress/e2e e cobrem as seguintes funcionalidades:
login.cy.ts: Testes de autenticação
prestadores.cy.ts: Testes de cadastro e gestão de prestadores
tomadores.cy.ts: Testes de cadastro e gestão de tomadores
servicos.cy.ts: Testes de cadastro e gestão de serviços
nfse.cy.ts: Testes de emissão de notas fiscais
relatorios.cy.ts: Testes de geração de relatórios
dashboard.cy.ts: Testes do painel principal
navegacao.cy.ts: Testes de navegação pelo sistema
upload-logomarca.cy.ts: Testes de upload de logomarca
all-tests.cy.ts: Execução de todos os testes em sequência
Após a execução dos testes, o Cypress gera relatórios detalhados com:
Número de testes executados
Número de testes bem-sucedidos e falhos
Tempo de execução
Capturas de tela em caso de falhas
Logs detalhados de cada etapa
Se você encontrar erros de permissão como EACCES ao tentar executar o Cypress com o Chrome, tente as seguintes soluções:
./executar-cypress.ps1
Este script configura o Cypress para usar o navegador Electron embutido e evita problemas de permissão.
npx cypress open --browser electron
npx cypress cache clear
E depois tente executar novamente.
$env:CYPRESS_BROWSER = "electron"
$env:ELECTRON_EXTRA_LAUNCH_ARGS = "--no-sandbox"
$env:CYPRESS_NO_SANDBOX = "1"
npx cypress open
Verifique se os seletores CSS estão corretos
Aumente o timeout para elementos que demoram a carregar
Verifique se a aplicação está rodando corretamente na porta 3000
Verifique se os dados de login em cypress/fixtures/usuario.json estão corretos
Certifique-se de que o sistema de autenticação está funcionando corretamente
Verifique se os arquivos de teste existem em cypress/fixtures
Certifique-se de que o componente de upload está funcionando corretamente
Para manter os testes atualizados:
Atualize os dados de teste em cypress/fixtures quando necessário
Atualize os seletores CSS se a interface do usuário mudar
Adicione novos testes para novas funcionalidades
Execute os testes regularmente para garantir que tudo continua funcionando