Cypress

Core Idea

Setup do Cypress no Next.js para E2E Testing e Component Testing, incluindo quickstart via create-next-app e configuração manual de cada modo.

Key Concepts

• E2E Testing (cy.visit): simula um usuário navegando a aplicação; requer o servidor Next.js rodando — recomendado rodar contra o build de produção (next build && next start) para se assemelhar ao comportamento real.
• Component Testing (cy.mount): monta um componente específico sem precisar bundlar a aplicação inteira nem subir servidor; requer selecionar framework "Next.js" e bundler: 'webpack' no cypress.config.
• Limitação com Server Components async: Cypress não suporta Component Testing para Server Components async — recomenda-se E2E testing para esses casos.
• start-server-and-test: pacote auxiliar para rodar o servidor Next.js junto com Cypress num único comando de CI.
• cypress run: modo headless, adequado para CI (em vez de cypress open, interativo).

Code Examples

describe('Navigation', () => {
  it('should navigate to the about page', () => {
    cy.visit('http://localhost:3000/')
    cy.get('a[href*="about"]').click()
    cy.url().should('include', '/about')
    cy.get('h1').contains('About')
  })
})

• O que demonstra: teste E2E de navegação entre páginas verificando URL e conteúdo renderizado.

import { defineConfig } from 'cypress'

export default defineConfig({
  component: {
    devServer: { framework: 'next', bundler: 'webpack' },
  },
})

• O que demonstra: configuração necessária para habilitar Component Testing com Next.js.

import Page from '../../app/page'

describe('<Page />', () => {
  it('should render and display expected content', () => {
    cy.mount(<Page />)
    cy.get('h1').contains('Home')
    cy.get('a[href="/about"]').should('be.visible')
  })
})

• O que demonstra: montar um componente diretamente (cy.mount) sem precisar de servidor, verificando presença de link em vez de segui-lo (isso é papel do E2E).

Anti-patterns

• Usar Component Testing para Server Components async: não suportado pelo Cypress; use E2E nesse caso.
• Testar features que dependem de servidor (ex. <Image />) via Component Testing: pode não funcionar out-of-the-box, já que não há servidor Next.js disponível nesse modo.

Key Takeaways

1. Cypress < 13.6.3 não suporta TypeScript 5 com moduleResolution: "bundler" — atualize se enfrentar esse problema.
2. Rode E2E contra o build de produção (next start) para refletir comportamento real, não contra next dev.
3. Use baseUrl no cypress.config.js para simplificar cy.visit("/") em vez da URL completa.
4. Em CI, prefira cypress run (headless) combinado com start-server-and-test.

Connects To

• Testing (ch085): página-índice que lista Cypress como uma das quatro ferramentas cobertas.
• Playwright (ch088): alternativa de E2E testing com abordagem similar.