How to Get Started with Cypress Component Testing for Vue

Cypress Component Testing lets you mount a Vue component in a real browser and test its rendered output and behavior in isolation. To get started, install Cypress in your Vue project, open Cypress, choose Component Testing, let the Launchpad configure the project, then write a spec that imports the component and calls cy.mount().

Cypress documents Vue setups with Vite and Webpack. The exact compatibility versions can change, so check the current Vue component testing guide for your Cypress, Vue, and bundler versions before setup.

1. Install and open Cypress

Run the install command from the root of the Vue project, where its package.json lives:

npm install cypress --save-dev

Then launch the Cypress App:

npx cypress open

You can also use Yarn, pnpm, or Bun; see Cypress’s installation guide for the current commands. Cypress belongs in development dependencies because it is part of the test workflow, not the production application bundle.

2. Configure Component Testing in the Launchpad

In the Cypress App, select Component Testing.
Let Cypress detect the project framework and bundler. Select Vue and the bundler your app uses if prompted.
Review the dependencies and configuration Cypress proposes, then let the Launchpad scaffold the component-testing setup.
Select an installed browser and start Component Testing.

The central setting is component.devServer, which tells Cypress how to serve the component test environment using Vue and the project’s bundler. Cypress typically discovers a Vite or Webpack configuration in the project; use explicit configuration when discovery fails or when the component-test environment needs a specific setup. See Get started with Component Testing and component framework configuration.

Vite or Webpack?

Use the bundler already used by the Vue app. Cypress documents Vue component testing with Vite and Webpack. Its retrieved Vue overview lists Vue 3 with Vite 8 and Vue 3 with Webpack 5+; verify the live compatibility guidance before relying on those version details.

Project setup	What to do
Vue with Vite	Choose the Vite path in the Launchpad and allow Cypress to discover the project’s Vite config when possible.
Vue with Webpack	Choose the Webpack path and allow Cypress to discover the app’s Webpack config when possible.
Custom or undiscovered config	Set the appropriate `viteConfig` or `webpackConfig` in the component dev-server configuration as described in Cypress’s configuration guide.

A separate, duplicated bundler configuration is not generally needed when Cypress can reuse the project configuration. Add an override when the default discovery or test-specific setup requires it.

3. Write and run a first Vue component spec

Create a component spec, import the Vue single-file component, and mount it. For example, if Stepper.vue is beside the spec:

import Stepper from './Stepper.vue'

describe('<Stepper />', () => {
  it('mounts', () => {
    cy.mount(Stepper)
  })
})

Run the spec from the Cypress App. Cypress’s Vue component examples use this import-and-mount pattern; its API documentation describes the Vue mount support.

Assert rendered output and user behavior

A mount-only test confirms the component can render. Useful component tests also check visible output and the effects of user actions. Pass props just as the component expects, interact through the browser, and assert observable behavior rather than internal implementation details.

import Stepper from './Stepper.vue'

describe('<Stepper />', () => {
  it('renders its starting value and reports an increment', () => {
    const onChange = cy.spy().as('onChange')

    cy.mount(Stepper, {
      props: {
        initialValue: 0,
        onChange,
      },
    })

    cy.contains('button', 'Increment').click()
    cy.contains('1')
    cy.get('@onChange').should('have.been.called')
  })
})

This illustrates the general pattern, not a promise about a particular component’s prop names or markup. Adapt the props, accessible button name, and expected output to the component. Cypress’s Vue examples demonstrate props and callback/event props with a Cypress spy, and the Vue API documents mounting.

4. Add shared mounting setup when the app needs it

Components may depend on app-level plugins, such as a router, store, or UI plugin. For a realistic isolated test, register the dependencies the component actually needs in the component-test setup or mount options. Import those dependencies explicitly and keep the setup aligned with the app. Avoid assuming the test automatically runs the full application bootstrap.

Likewise, framework aliases and bundler plugins must be available to the component dev server. If an import works in the application but fails in a component spec, check whether Cypress discovered the same bundler config and whether its aliases or plugins are included.

5. Account for Nuxt differences

Cypress does not provide a dedicated Nuxt framework definition for component testing and does not execute nuxt.config to recreate the Nuxt environment. Cypress documents Nuxt 3+ component testing as Vue with Vite.

Declare Nuxt aliases such as @ and ~ in the Cypress Vite configuration if the component test server cannot resolve them.
Import auto-imported components and composables explicitly in isolated tests, or configure an equivalent plugin for the component-test environment.
Do not assume Nuxt’s application bootstrap or auto-import behavior is present just because the component works in a Nuxt page.

Use Cypress’s Vue guide and configuration guide for the current Nuxt and Vite details.

What Cypress Component Testing covers

Component testing mounts a component in isolation in a real browser, rather than visiting a production or staging application. Cypress describes this as mounting components “directly in a real browser — not a simulated DOM,” so the browser executes the component while the test focuses on its rendered behavior. A component test is useful for props, visible states, interaction, and integration with explicitly provided dependencies. It does not by itself verify that the entire deployed application, server, and route work together.

Or skip the browser setup

If your next task is capturing a page screenshot rather than testing a Vue component, ScreenshotNeo is a website screenshot API and MCP server for developers. Its one-call API can return an image or PDF; this example saves a WebP response:

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 the request options. Cookie banners are accepted or removed before capture, along with supported newsletter popups and chat widgets; those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.

Troubleshooting

Symptom	Likely cause	Fix
Cypress does not offer or detect Vue	The project is opened from the wrong directory, dependencies are missing, or the framework setup is not recognized.	Open Cypress from the Vue project root, confirm the Vue and bundler dependencies are installed, and follow the Launchpad framework selection.
The component spec cannot resolve a Vite or Webpack import	Cypress did not discover the app config, or the component-test dev server lacks an alias or plugin.	Check the project config location and add the appropriate explicit `viteConfig` or `webpackConfig` override.
A Nuxt alias such as `@` fails	Cypress does not execute `nuxt.config` for component testing.	Declare the alias in the Cypress Vite setup and explicitly import auto-imported dependencies where needed.
A component relying on app context fails during mount	Its router, store, plugin, or provider has not been registered in the isolated test.	Pass or register the required dependency in the test mount setup.
The browser opens but the spec fails before rendering	The component-test server may not match the application’s bundler configuration or supported versions.	Review the current Cypress Vue compatibility guide, compare project and Cypress versions, and inspect the component dev-server configuration.
An interaction assertion never passes	The test may be using the wrong accessible label, prop contract, or expected state.	Check the component’s actual rendered output and public props, then assert the user-visible result and spy behavior that the component is designed to produce.

Performance, reliability, and cost

Component testing starts a browser and a component dev server, so its setup has more moving parts than a simulated-DOM unit test. Keep each spec focused, share only stable mount setup, and avoid loading the entire app when a component needs only a small set of dependencies. The real-browser environment is useful for browser behavior, but it does not remove the need for separate integration or end-to-end coverage of routes and deployed services.

Reliability depends on using the app’s intended bundler configuration and explicitly supplying app context and Nuxt dependencies. For tests of network-dependent behavior, control or stub the relevant boundary where appropriate so the component assertion is not coupled to an unrelated live service. Cypress is installed as a development dependency; the research sources do not establish a price or usage benchmark, so consult Cypress’s current product terms for any cost questions.

Frequently asked questions

Does component testing replace end-to-end testing?

No. It tests a mounted component in isolation. Use end-to-end tests when you need to verify the whole application flow, including routing and deployed services.

Can I test Vue 2?

Check Cypress’s current Vue compatibility documentation for the supported Vue versions and setup path. The retrieved overview specifically describes Vue 3 with Vite and Webpack.

Do I need a separate Vite config for Cypress?

Usually Cypress can discover the project’s Vite config. Add an explicit override when discovery fails or the test environment needs configuration the app config does not provide.

Why does a Nuxt component behave differently when mounted alone?

Component testing does not execute Nuxt’s application configuration or automatically reproduce its aliases and auto-imports. Configure or import the dependencies the isolated component requires.