How to Test Next.js Components with Cypress

Ensure Cypress is configured to load the support file, and keep its path and extension aligned with your project’s TypeScript or JavaScript setup. The example gives TypeScript the command type; a JavaScript project can use the mount registration without the declaration block. If Launchpad generates an equivalent file, use that generated setup rather than registering a second, conflicting command.

4. Write a first component test

Import the component into a component spec, mount it with the props needed for the behavior under test, and assert on a stable selector or accessible output. For example, suppose stepper.tsx exports a component that accepts an initial prop and renders its count in an element marked data-cy="counter":

import { Stepper } from './stepper'

describe('Stepper', () => {
  it('renders its initial count', () => {
    cy.mount(<Stepper initial={2} />)
    cy.get('[data-cy=counter]').should('have.text', '2')
  })
})

This is an illustrative mount-and-assert pattern, adapted from Cypress’s React examples; it is not a claim about a particular project’s component API or a test run. Replace the import, props, and selector with those from your app. Cypress mounts the JSX in a real browser, so the test can inspect browser-rendered output rather than relying on a simulated DOM.

For an interactive component, assert the visible result of an action. For example, if the Stepper renders an increment button and updates the same counter:

import { Stepper } from './stepper'

describe('Stepper', () => {
  it('increments when the user selects the increment button', () => {
    cy.mount(<Stepper initial={2} />)
    cy.get('[data-cy=increment]').click()
    cy.get('[data-cy=counter]').should('have.text', '3')
  })
})

Prefer selectors that are part of the component’s testing or accessibility contract. If the component depends on a provider, context, router, or other app-level setup, supply the required dependency in the test harness or wrap the component with the appropriate provider. A component test does not automatically recreate the whole Next.js runtime.

Source: Cypress React examples.

5. Load global styles in component tests

Component specs need the styles relevant to the behavior you are checking. For the documented Next.js styling setup, preserve this marker in the <head> of the component testing index HTML:

<div id="__next_css__DO_NOT_USE__"></div>

Import your app’s global stylesheet from the component support file. The exact path depends on your repository; for example:

import '../../src/index.css'

Use the stylesheet path that actually exists in your project. If global styles do not appear, check both the marker and the import path. Cypress documents that a missing marker can prevent global styles from applying or cause mounting to fail.

Source: Cypress guidance for testing component styles.

6. Choose component testing or end-to-end testing

Choose the test type based on what must execute for the behavior to be meaningful:

A page that expects data from getServerSideProps or getStaticProps can receive undefined props when mounted directly as a component because those methods do not run in component testing. Cypress recommends E2E testing for Next.js pages and component testing for individual components in a Next.js app. Component tests do not validate server-rendered behavior.

Source: Cypress React Component Testing.

7. Run and maintain the tests

1. Open Cypress and select Component Testing to run specs in its interactive browser, or use the component run command for CI.
2. Confirm the selected testing type is Component Testing and the configured Next.js component dev server starts successfully.
3. Keep specs near their components or in the component spec location used by your repository’s Cypress configuration.
4. Pass explicit props and set up required providers so each spec describes its own assumptions.
5. Keep component tests focused on isolated UI behavior. Add E2E coverage for server-dependent pages and complete user journeys.

Cypress compiles and serves the component specs using the configured development server, which is shut down when Cypress closes or a run finishes. As with any compiled test workflow, runtime depends on the project and setup; the cited documentation does not establish a universal speed comparison or benchmark.

8. Troubleshoot common problems

9. Browser screenshots for visual review

A Cypress assertion checks a specific condition, such as whether a count changes after a click. A screenshot is useful when you also need a reviewable image of a browser-rendered page or component state. For a Next.js page that needs its real server-side behavior, capture the running page through its URL; a screenshot does not replace the component or E2E assertions described above.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server from ScreenshotNeo. A GET request captures a URL as an image or PDF. For a screenshot of a running page, use:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Replace the example URL with a page you can access. See the ScreenshotNeo API documentation for options and response details. Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000.

Sign up for ScreenshotNeo and get 1,000 free screenshots a month, with no card required.

FAQ

Can I use Cypress component testing for a complete Next.js page?

You can mount React UI, but component testing does not execute Next.js server-only page methods. Use E2E tests when the page’s behavior depends on those methods or its full server-backed path.

Does Cypress component testing use a real browser?

Yes. Cypress describes component testing as mounting components directly in a real browser, using its configured component development server.

Which bundler should I configure for Next.js?

The documented Next.js component testing configuration uses Webpack, with framework: 'next' and bundler: 'webpack'.

Do I need to import global CSS into every spec?

The documented setup imports the app stylesheet from the component support file, so specs using that support setup receive the global stylesheet without repeating the import in each spec. Keep the required CSS injection marker in the component index HTML.