How to Use the Cypress Component Test Runner
Set up Cypress Component Testing, configure its dev server, and write a first browser-based component test with practical setup and debugging guidance.
Cypress Component Testing mounts a component in a real browser so you can interact with the rendered UI and assert its behavior. To get started, install Cypress, open the Cypress App, select Component Testing, and follow the Launchpad to configure the framework and bundler. Then create a component spec, mount the component using the integration for your framework, and run it in the browser. Check the current Cypress compatibility table before setup because supported framework and bundler versions change.
Component tests exercise an individual component in Cypress’s testbed; they do not visit a deployed or staging application like an end-to-end test. Cypress starts a development server to compile and serve the specs and support files. Its documentation describes this as mounting components directly in a real browser rather than a simulated DOM.
1. Install Cypress and open Component Testing
From the project root, install Cypress as a development dependency using your package manager:
npm install cypress --save-dev
# or
yarn add cypress --dev
# or
pnpm add --save-dev cypress
# or
bun add --dev cypressOpen Cypress:
npx cypress openChoose Component Testing when prompted. In the Launchpad, review the detected framework and bundler, accept or adjust the proposed setup, and select a browser. The Launchpad checks dependencies and creates or updates the Cypress configuration. For the standard supported setup, this generated configuration is usually the right starting point.
2. Configure the component development server
Component Testing requires component.devServer. Cypress’s standard configuration specifies the app’s framework and bundler; the bundled Vite and Webpack dev-server implementations mean a separate Cypress dev-server package is generally unnecessary.
const { defineConfig } = require('cypress')
module.exports = defineConfig({
component: {
devServer: {
framework: 'react',
bundler: 'vite',
},
},
})Use values that match your project. For example, do not use the React/Vite values unchanged in a Vue, Angular, or Webpack application. Cypress can reuse discoverable Vite or Webpack configuration. If your framework keeps bundler settings in a meta-framework config that Cypress does not read, you may need to provide relevant aliases or settings in the Cypress bundler configuration. See Cypress component framework configuration for the supported configuration options.
Documented framework and bundler combinations
The following matrix reflects Cypress’s documentation snapshot checked on October 3, 2026. Confirm the live table during setup; it is version-specific and may change.
| Framework | Documented bundler | Version context |
|---|---|---|
| React | Vite 8 or Webpack 5 | React 18–19 |
| Next.js | Webpack 5 | Next.js 15–16, React 18–19 |
| Vue | Vite 8 or Webpack 5 | Vue 3 |
| Angular | Webpack 5 | Angular 21–22 |
| Svelte | Vite 8 or Webpack 5 | Svelte 5 integrations marked Alpha |
| Qwik and Lit | Community integrations | Community-maintained framework definitions |
For a community framework, its definition needs to provide onboarding requirements and a mount adapter. Cypress documents package names following cypress-ct-* or @organization/cypress-ct-*. Treat community integrations and Alpha support according to their documented status; do not assume they have the same support as standard integrations.
3. Locate specs and shared setup
By default, Cypress recognizes component specs ending in .cy.js, .cy.jsx, .cy.ts, or .cy.tsx. Keep the default naming convention or set component.specPattern to match your repository. For example, a project may constrain the pattern to files beneath src.
The default component support file is cypress/support/component.js. Put shared component-test setup there, such as imports or registrations needed by all specs. The component index file defaults to cypress/support/component-index.html; use it for global styles, fonts, and scripts that the mounted components need.
const { defineConfig } = require('cypress')
module.exports = defineConfig({
component: {
specPattern: 'src/**/*.cy.{js,jsx,ts,tsx}',
devServer: {
framework: 'react',
bundler: 'vite',
},
},
})Only add a pattern override if it matches how your specs are actually named and located. Cypress’s configuration reference lists the component defaults and required development-server setting.
4. Write and run a first component test
A component spec imports the component and the mount helper for the selected framework, mounts it, then uses Cypress commands to query, interact with, and assert on the rendered result. Mount imports are framework-specific, so start from the example for your framework rather than copying an import from another integration. The React example below shows the shape of the test; it assumes a React component named Counter and the React mount helper is configured as documented for your Cypress version.
import Counter from './Counter'
import { mount } from 'cypress/react'
describe('<Counter />', () => {
it('increments when the user clicks the button', () => {
mount(<Counter />)
cy.contains('button', 'Increment').click()
cy.get('[data-cy="count"]').should('have.text', '1')
})
})This example expects the component to render a button labeled “Increment” and an element with data-cy="count". Adapt selectors and expected behavior to your component. For Vue, Angular, or Svelte, use that integration’s documented mount API and a matching component example.
- Place the file where
component.specPatternexpects it, for examplesrc/Counter.cy.jsx. - Run
npx cypress open, choose Component Testing, and start the spec in a selected browser. - Inspect the mounted component in the Cypress App. Use the browser’s developer tools when you need to inspect DOM, styles, or runtime errors.
- Use Cypress’s displayed test commands and failure output to locate a failing selector, interaction, or assertion.
For framework-specific setup and examples, consult the React component examples or the relevant framework guide.
5. Understand what Cypress starts
When component testing starts, Cypress reads component.devServer, starts the configured development server on an available port, and serves compiled specs and support files. It loads the component index HTML, then imports the support file and active spec. The bundler’s development transforms and the browser’s rendering behavior are part of this component-test workflow.
For most applications, use the standard component.devServer object. An advanced custom devServer function is available when a project uses a different bundler or needs full control of server startup. It must return the server port and can provide a close callback. A custom server may also need to serve the index HTML and inject support and spec imports in the required order.
6. Adjust configuration only when needed
- Framework and bundler: Match the application’s real framework, versions, and bundler to the documented support matrix.
- Spec pattern: Set
component.specPatternif the repository does not use the default.cy.*locations or extensions. - Support file: Use the component support file for setup shared by component specs.
- Index HTML: Add global styles, fonts, or scripts to the component index HTML when mounted components depend on them.
- Aliases and generated configuration: Cypress can discover standalone Vite or Webpack config files, but does not execute meta-framework configuration such as
nuxt.configto derive generated bundler settings. Supply required aliases through Cypress’s bundler configuration if imports fail. Cypress documents Nuxt 3+ component testing as Vue 3 with Vite; it does not provide a dedicated Nuxt framework definition or readnuxt.config. - Public path:
devServerPublicPathRoutechanges the route used to load compiled specs and assets. An incorrect override can stop them loading; keep the default unless the project requires a different route. - Custom server: Use the function-based server integration for a real need such as an unsupported bundler. It adds responsibility for startup, served assets, import order, port reporting, and shutdown.
7. Troubleshoot common failures
| Symptom | Likely cause | What to check |
|---|---|---|
| Component Testing is missing or setup cannot complete | Cypress was not opened in the intended project, or the app/framework dependencies are not present or detectable. | Run the Cypress App from the project root; confirm the framework and bundler dependencies are installed; follow the Launchpad prompts and review its proposed config. |
| Development server fails to start | The framework/bundler values do not match the project, or the project has incompatible versions/configuration. | Compare actual package versions with Cypress’s current compatibility table. Check the dev-server startup output and correct the framework/bundler configuration. |
| No component specs appear | The file extension or location does not match component.specPattern. |
Use a default .cy.js, .cy.jsx, .cy.ts, or .cy.tsx filename, or update the pattern to include the spec. |
| Spec or asset requests fail to load | A public path override points at the wrong route, or the custom server is not serving compiled assets correctly. | Restore the default devServerPublicPathRoute unless needed. For a custom server, confirm its port and asset routes match the Cypress setup. |
| Imports using aliases fail | The alias is defined only in meta-framework-generated configuration that Cypress does not execute. | Declare the needed alias in the Cypress Vite or Webpack config. Check the Vue/Nuxt notes if using Nuxt. |
| Component mounts but global styles or fonts are absent | The component index HTML does not include application-wide assets. | Add the required CSS, font, or script references to cypress/support/component-index.html. |
| The example mount import is unresolved | A mount helper from another framework or Cypress version was copied. | Use the matching framework’s current Cypress guide and ensure its integration setup is installed/configured. |
| A click succeeds but the assertion fails | The example’s expected labels, selector, initial state, or behavior differ from the actual component. | Inspect the rendered DOM in the Cypress App/browser tools, use selectors matching the component, and assert its actual intended behavior. |
8. Performance, reliability, and cost considerations
The researched Cypress setup material does not provide performance benchmarks or pricing figures, so none are stated here. Component testing starts a development server and compiles the active specs and support files; project configuration and dependencies therefore affect the setup path. Keep shared setup focused, and use the standard framework/bundler integration where it fits to avoid the extra moving parts of a custom server.
Reliability depends first on using a documented framework/version combination and making required aliases and shared assets visible to the Cypress build. The compatibility table is a snapshot, not a guarantee for every repository configuration. Recheck it when upgrading the framework, bundler, or Cypress, especially for integrations labeled Alpha or community-maintained.
Or skip the browser setup
If your goal is a screenshot of a web page rather than an interactive component test, ScreenshotNeo provides a website screenshot API and MCP server. It does not replace Cypress component testing: it captures pages as PNG, JPEG, WebP, or PDF rather than mounting and asserting on a component.
One GET request returns a screenshot. See the ScreenshotNeo API documentation for parameters and response details.
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({
access_key: 'YOUR_API_KEY',
url: 'https://stripe.com',
})
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`)
const bytes = new Uint8Array(await res.arrayBuffer())
await import('node:fs/promises').then(({ writeFile }) => writeFile('shot.webp', bytes))- Cookie banners are accepted like a visitor and removed before the shot, along with 60+ known consent platforms, newsletter popups, and chat widgets. Each step can be turned off.
- Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers report the page verdict and billing status.
- An MCP server lets Claude, Cursor, and other MCP clients use
take_screenshot,get_page_info, andcapture_pdf. - The free plan includes 1,000 shots a month with no card. Paid plans start at $5 for 3,000 shots; every feature is on every plan.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Frequently asked questions
Does Cypress Component Testing require a running deployed app?
No. Cypress starts a development server to compile and serve the component specs and support files. The test mounts a component in Cypress’s testbed, rather than visiting the deployed application.
Can I use Cypress Component Testing with a custom bundler?
Cypress documents a custom development-server function for projects that need a different bundler or full control of startup. It is an advanced integration and must provide the server port; a close callback can also be provided.
Are Cypress component tests the same as end-to-end tests?
No. Component tests mount an individual component. End-to-end tests visit and exercise a running application. Choose based on whether you need to verify component behavior in isolation or application-level flows.
Where can I see Cypress’s current support status?
Use the live Cypress Component Testing getting-started page and its framework/version table. Support changes over time, and Alpha or community integrations have different documented status.
