How to Use Cypress with Next.js for End-to-End Testing

To use Cypress with Next.js, install Cypress in your Next.js project, then write tests that visit your Next.js app URLs. Run your Next.js app locally or in test mode, and execute Cypress tests to simulate user interactions and verify UI behavior.

Syntax

Here is the basic syntax to write a Cypress test for a Next.js app:

• describe(): Groups related tests.
• it(): Defines a single test case.
• cy.visit(): Opens a page URL in the test browser.
• cy.get(): Selects elements on the page.
• cy.contains(): Finds elements containing specific text.
• cy.click(): Simulates a click event.
• cy.should(): Asserts expected conditions.

javascript

describe('Home Page', () => {
  it('loads successfully', () => {
    cy.visit('http://localhost:3000')
    cy.contains('Welcome to Next.js!').should('be.visible')
  })
})

Example

This example shows a complete Cypress test for a Next.js app homepage. It visits the local app, checks the page title text, clicks a navigation link, and verifies the new page content.

javascript

describe('Next.js App Navigation', () => {
  beforeEach(() => {
    cy.visit('http://localhost:3000')
  })

  it('shows homepage content', () => {
    cy.contains('Welcome to Next.js!').should('be.visible')
  })

  it('navigates to About page', () => {
    cy.get('nav').contains('About').click()
    cy.url().should('include', '/about')
    cy.contains('About Page').should('be.visible')
  })
})

Output

✔ Home page loads and shows welcome text
✔ Navigation to About page works and shows About content

Common Pitfalls

Common mistakes when using Cypress with Next.js include:

• Not running the Next.js app before starting Cypress tests, causing cy.visit() to fail.
• Using incorrect URLs or ports in cy.visit().
• Not waiting for dynamic content to load before assertions.
• Selecting elements without stable selectors, leading to flaky tests.

Always start your Next.js app with npm run dev or npm start before running Cypress.

javascript

/* Wrong: Trying to visit without running Next.js app */
describe('Test without app running', () => {
  it('fails to load page', () => {
    cy.visit('http://localhost:3000') // This will fail if app is not running
  })
})

/* Right: Ensure app is running before tests */
// Run `npm run dev` or `npm start` in another terminal before running Cypress tests

Quick Reference

Summary tips for using Cypress with Next.js:

• Install Cypress with npm install cypress --save-dev.
• Run your Next.js app locally before testing.
• Use cy.visit() with your app URL (usually http://localhost:3000).
• Write tests to simulate user actions and check UI changes.
• Use stable selectors like data-cy attributes for reliable element targeting.

Key Takeaways

Always run your Next.js app locally before running Cypress tests to avoid visit errors.

Use cy.visit() to open your Next.js pages and cy.get() or cy.contains() to select elements.

Write clear, simple tests that simulate user actions and check visible UI changes.

Use stable selectors like data-cy attributes to avoid flaky tests.

Install Cypress as a dev dependency and run tests with npx cypress open or npx cypress run.