October DealsAmazon USOctober deal check: compare before you payAmazon US: current deals, useful picks and tech finds.Check DealsClean PCRecommendedOne scan can reveal what keeps slowing WindowsLook for cleanup and repair opportunities.Run ScanOctober DealsAmazon USDeal season is back - check today's better picksAmazon US: current deals, useful picks and tech finds.See Picks×
Skip to content
World desk4 min

How to Test Next.js Components with Cypress

Set up Cypress Component Testing in Next.js, write a browser-based mount-and-assert test, configure global CSS, and choose E2E testing for server-dependent pages.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Use Cypress Component Testing to mount and check an individual React component in a browser; use end-to-end (E2E) tests for Next.js pages whose behavior depends on server-side execution. For Cypress 16, the documented Next.js compatibility floor is Next.js 15.0.4, or Next.js 16. Start with Cypress’s Launchpad, then configure the Next.js component dev server and write a mount-and-assert test.

Check compatibility and set up component testing

Cypress documents React Component Testing with Next.js 15 and 16. The release-specific boundary matters: Cypress 16.0.0 and later require Next.js 15.0.4 or newer, or Next.js 16; Next.js 14 is no longer supported for component testing under that guidance. Check the migration guide for the Cypress version you have installed if you are on a different release.

  1. Open Cypress and choose its Component Testing setup flow in Launchpad. Cypress says Launchpad detects the framework and bundler and scaffolds a configuration file.
  2. Confirm the component configuration in cypress.config.js or cypress.config.ts. The Next.js setup uses the Next framework and Webpack bundler:
import { defineConfig } from 'cypress'

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

This configures a development server that compiles and serves component specs while Cypress runs; it is not a test against the production website. The server shuts down when the Cypress app closes or a run finishes. See Cypress’s component framework configuration for the general configuration model and framework details.

Write a first component test

A component test mounts a component directly in a real browser. Import the component, render it with the props the test needs, and assert a visible result. This illustrative example follows Cypress’s documented React pattern; adapt the import, prop names, and selector to your application.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
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')
  })
})

The data-cy attribute is a stable test selector in this example. If a component needs context, a provider, or other application setup, supply those dependencies through the test harness. A component test does not automatically recreate the entire Next.js runtime. Cypress’s getting-started guide and React examples show the mounting and assertion pattern.

Load global styles in component tests

To apply the app’s global CSS, Cypress’s Next.js styling guidance calls for a marker in the component index HTML’s <head> so Next.js can inject CSS:

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

Import the application stylesheet from the component support file, commonly cypress/support/component.js. Use your project’s actual stylesheet path:

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

If global styles do not appear or mounting fails, check that the marker is present and the support-file import points to the correct stylesheet. See Cypress’s component styling guidance.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Choose component tests or end-to-end tests

Use component tests for isolated UI behavior: rendered output and interactions when the component is mounted with its required inputs and dependencies. Use E2E tests when the question concerns a complete page or flow that relies on Next.js server behavior.

Test type Scope Execution context Best fit
Component An individual component Mounted in Cypress’s component development server in a browser Checking component output and interactions with supplied props and dependencies
End-to-end A full page or user flow Exercises the application and its server-side page behavior Checking page behavior that depends on server execution

In particular, getServerSideProps and getStaticProps are server-only methods; they do not run in a component test. A page depending on either can therefore receive undefined props when mounted this way. Cypress recommends: “Because of this, we recommend using E2E Testing over Component Testing for Next.js pages and Component Testing for individual components in a Next.js app.” That is Cypress’s guidance in its React Component Testing documentation, not a claim that component tests validate server-rendered behavior.

Troubleshoot common setup problems

  • Cypress rejects the Next.js version: compare the installed versions with the Cypress release-specific compatibility boundary. Cypress 16 requires Next.js 15.0.4 or newer, or Next.js 16; Next.js 14 is unsupported for component testing in that release context.
  • The component dev server does not start: check that component.devServer.framework is 'next' and component.devServer.bundler is 'webpack', and review the configuration guidance for your installed Cypress version.
  • Global CSS is missing or mounting fails: verify the __next_css__DO_NOT_USE__ marker in the component index HTML and confirm the stylesheet import in the component support file resolves to the right file.
  • A page test has undefined props: if those props come from getServerSideProps or getStaticProps, move that page-level check to E2E testing. Keep component tests focused on components mounted with explicit inputs.
  • A mounted component fails because of missing context: provide the providers or other dependencies the component requires in the test harness; mounting an isolated component does not supply the full app environment.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Or skip the browser setup

If your task is to capture a website screenshot rather than test a React component, ScreenshotNeo offers a one-request screenshot API. This is not a replacement for Cypress component tests: it captures a URL, not an isolated component’s behavior.

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

See the ScreenshotNeo API documentation for request options. ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Sign up for the free plan.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

More from the Wire

  1. World desk4 min
    How to Spot an AI Voice Scam Before Sending MoneyDon’t rely on how a caller sounds. Pause, call back through a known number, and verify the emergency with another trusted person before sending money.
  2. Mountain View desk4 min
    Google’s SynthID Detector: How to Check AI-Generated Images, Video and AudioGoogle’s SynthID Detector looks for an embedded watermark in supported images, video and audio. Here is what its results do—and do not—show.
  3. Redmond desk20 min
    How to create a link to File or Folder in Windows 11Windows 11 gives you several ways to point to a file or folder without moving or duplicating it. You can create a desktop shortcut,…
Recommended PC Tool
Recommended PC Tool
Crashes, No Sound, or Screen Glitches?Free driver scan
PC Slower Than It Used to Be?Free scan - under a minute

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.