How to Test Vue Component Reactivity in Cypress Component Tests
Mount Vue components in Cypress, trigger real inputs, and assert reactive UI changes and emitted events with retryable browser assertions.

To test Vue component reactivity in Cypress, mount the component with its initial props, change a public input or interact with its UI, and assert the resulting DOM with a retryable .should(). If an interaction should emit an event, pass a Cypress spy as the event prop and assert its payload. This checks the component’s observable contract in a real browser, without coupling the test to private implementation details.
Cypress documents Vue 3+ component testing with Vite or Webpack. The examples below use a small controlled stepper; adjust the prop, selector, and event names to match your component. See the Cypress Vue component testing overview and the Vue examples for framework-specific guidance.
1. Set up Cypress component testing
Install Cypress and configure component testing for the project’s Vue version and bundler. Cypress’s component-test dev server compiles and serves the component spec and support files. The exact configuration depends on your existing Vite or Webpack setup, so start with Cypress’s component testing setup guide rather than copying a config intended for a different project.
Register a mount command in the component support file. A minimal Vue 3 setup looks like this:
import { mount } from 'cypress/vue'
Cypress.Commands.add('mount', mount)
Put that code in the component support file selected by your Cypress configuration, commonly cypress/support/component.js or component.ts. Ensure that file is loaded as the component support file. Cypress’s Vue integration supplies the mount utility; the component test then imports a real Vue SFC and mounts it in the test browser.
For TypeScript projects, add a declaration for the custom command if your Cypress types do not already know it:
/// <reference types="cypress" />
declare namespace Cypress {
interface Chainable {
mount: typeof import('cypress/vue').mount
}
}
Use the project’s installed Cypress and Vue package versions when setting this up. Cypress’s framework guide covers the supported Vue integration and the configuration options for the component dev server: Vue component testing and component framework configuration.
2. Build a test around the component’s contract
A component reactivity test should answer a user-facing question: after a particular input or action, what changes on screen, and what event is emitted? This keeps the spec useful through refactors. Prefer a dedicated data-cy attribute for important targets rather than selecting a broad tag or class that may be shared by unrelated markup. Cypress recommends dedicated test selectors in its getting-started example.
Here is a minimal controlled component. It receives a count and emits the next value when the button is clicked:
<!-- Stepper.vue -->
<script setup>
const props = defineProps({
count: { type: Number, required: true },
})
const emit = defineEmits(['change'])
function increment() {
emit('change', props.count + 1)
}
</script>
<template>
<output data-cy="counter">{{ count }}</output>
<button data-cy="increment" @click="increment">Increment</button>
</template>
The parent owns the value in this example. Clicking emits a proposed next value; the component does not mutate its prop. This distinction matters: a controlled component will only display the next count if its parent passes an updated prop back. Test the emitted contract and the displayed prop value as separate behaviors.
3. Test initial and prop-driven rendering
Mount with the prop value you want to verify, then assert the rendered output. Mounting is queued and asynchronous, so keep assertions in Cypress’s command chain rather than expecting the component to have rendered synchronously on the next JavaScript line.
import Stepper from './Stepper.vue'
describe('<Stepper />', () => {
it('renders the initial count prop', () => {
cy.mount(Stepper, { props: { count: 4 } })
cy.get('[data-cy=counter]').should('have.text', '4')
})
})
This verifies the prop-to-template path: the value supplied at mount appears in the DOM. To test another prop value, mount with that value in a separate test. When the question is whether the same mounted instance responds to a changed prop, update props using the component wrapper pattern supported by your Cypress Vue integration and assert the new output. Cypress’s examples document accessing the Vue Test Utils wrapper through the mount result; follow the API for your installed version rather than assuming a mount result shape.
For example, a prop-driven label might be tested by mounting with two different values across isolated cases:
it('renders a label supplied by the parent', () => {
cy.mount(Stepper, { props: { count: 8, label: 'Items' } })
cy.get('[data-cy=label]').should('have.text', 'Items')
})
Add a label prop and corresponding element to the component if that is part of its API. The example illustrates the pattern, not an assumption that every stepper has a label.
4. Test a reactive update after a click
For an interactive component, exercise the same control a user would use. Assert the visible result after the action with .should(), which retries the query and assertion until it passes or reaches the command timeout.

it('emits the next count when increment is clicked', () => {
const onChange = cy.spy().as('onChange')
cy.mount(Stepper, {
props: { count: 0, onChange },
})
cy.get('[data-cy=counter]').should('have.text', '0')
cy.get('[data-cy=increment]').click()
cy.get('@onChange').should('have.been.calledWith', 1)
})
In Vue, a declared event such as change is passed to a component as the corresponding listener prop, here onChange. Cypress’s Vue examples use a spy passed through mount props to check an emitted event. The exact event name and payload are part of your component contract; if it emits an object or multiple arguments, assert the documented shape your parent relies on.
For an uncontrolled component that owns reactive state internally, clicking may directly change the displayed count. In that case, the DOM assertion is the primary contract:
it('updates its displayed count after a click', () => {
cy.mount(InternalStepper)
cy.get('[data-cy=counter]').should('have.text', '0')
cy.get('[data-cy=increment]').click()
cy.get('[data-cy=counter]').should('have.text', '1')
})
Use the version that describes the real component. Do not assert both a changed DOM value and an emitted event unless the component promises both; a controlled component may emit without changing its own prop-backed display.
5. Test input, computed output, and conditional UI
Computed properties and watchers are implementation mechanisms. To test them robustly, change the public input that should affect them and assert the resulting display, enabled state, or other observable behavior.
For a search component, for example, type into the input and assert the filtered result:
it('updates visible results when the query changes', () => {
cy.mount(SearchList, {
props: { items: ['Vue', 'Cypress', 'React'] },
})
cy.get('[data-cy=search]').type('Vue')
cy.get('[data-cy=result]').should('have.length', 1)
cy.get('[data-cy=result]').first().should('have.text', 'Vue')
})
This test proves the input-to-rendered-results behavior, regardless of whether the component uses a computed value, a watcher, or another supported Vue pattern. Vue’s reactivity fundamentals guide describes how reactive state updates component output. Keep the test focused on the behavior the component promises.
For conditional content, trigger the condition through a public prop or control and assert presence or absence:
cy.get('[data-cy=details]').should('not.exist')
cy.get('[data-cy=toggle-details]').click()
cy.get('[data-cy=details]').should('be.visible')
If a watcher should emit or perform a visible action when a prop changes, drive that change through the supported component interface and assert its consequence. Avoid calling private methods or mutating internal state through the wrapper simply to make a watcher run. Such tests can pass while the user-facing path is broken.
6. Check emitted events: spy or wrapper
Use a Cypress spy when the test is about whether an event handler ran and what it received. Spy assertions are concise and produce useful failures for call counts and arguments:
const onChange = cy.spy().as('onChange')
cy.mount(Stepper, { props: { count: 2, onChange } })
cy.get('[data-cy=increment]').click()
cy.get('@onChange').should('have.been.calledOnceWith', 3)
Cypress also supports obtaining the Vue Test Utils wrapper and inspecting wrapper.emitted(). That API is useful when a test needs the recorded collection of several events, but it returns recorded data rather than a Cypress spy, and Cypress notes its assertions may have less helpful error output. The essential choice is:
| Approach | Useful when | Tradeoff |
|---|---|---|
| Cypress spy passed as event prop | Checking calls, counts, or expected payload arguments | Assert the listener prop name and event payload correctly |
Vue Test Utils emitted() |
Inspecting multiple recorded event names and their argument arrays | Unpack the recorded structure; assertions are not spy assertions |
Follow Cypress’s Vue examples for the wrapper retrieval syntax supported by your version. Avoid mixing wrapper calls with Cypress commands in a way that assumes synchronous rendering; use Cypress’s chain and retry behavior where available.
7. Wait for reactivity without fixed delays
Prefer an assertion on the expected DOM state over cy.wait(500) or another arbitrary delay. Cypress retries .should() assertions, so the test waits for the observable condition rather than guessing how long Vue needs to flush an update. This is especially useful after clicks, typing, prop changes, and state-driven conditional rendering.
Use a fixed wait only when the behavior itself includes a real time-based contract, such as a debounce interval, and even then assert the resulting behavior as well. For network-dependent components, wait on the relevant request or response when that is part of the tested flow, then assert the rendered state. A test that only waits for time can be both slow on a fast machine and flaky on a slower one.
Cypress’s Vue documentation points out that cy.mount() is queued and does not mean the component has already rendered at the instant the call is made. Keep commands in Cypress’s chain. If using Vue Test Utils methods inside a then callback, handle asynchronous updates explicitly according to that API rather than assuming Cypress will retry a one-shot assertion.
8. Mount app dependencies consistently
Components often rely on a router, store, plugin, global component, or injection. If production renders the component with app-level dependencies but the test mounts it alone, the test may fail before reaching the behavior under test. Cypress recommends a customized mount command for shared setup.
A general pattern is to create the app dependencies for each mount and pass them as Vue plugins. The exact store or router setup is application-specific:
import { mount } from 'cypress/vue'
import { createStore } from 'vuex'
Cypress.Commands.add('mountWithStore', (component, options = {}) => {
const store = createStore({
state: () => ({ count: 0 }),
})
return mount(component, {
...options,
global: {
...options.global,
plugins: [store, ...(options.global?.plugins || [])],
},
})
})
Use isolated state for each test so one test cannot change the store state observed by another. Apply the same approach to router instances and plugin state when the component depends on them. Cypress’s Vue examples cover custom mounting and Vuex configuration.
For Nuxt, Cypress does not provide a dedicated Nuxt framework definition and does not read nuxt.config. Its documented route for Nuxt 3+ is Vue with Vite, with explicit handling for aliases and auto-imports; explicit imports in the component are another option. Confirm that the component-test dev server has the aliases, styles, and transforms needed by the component rather than assuming the app’s full Nuxt runtime is present.
9. Common failures and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
cy.mount is not a function |
The custom command was not registered or the component support file is not loaded. | Import mount from cypress/vue, register the command, and verify the component support-file configuration. |
| Vue SFC import or compile error | The component dev server is missing Vue or project bundler configuration. | Check that component testing uses the project’s supported Vite or Webpack setup and Vue transforms. |
Alias such as @/ cannot resolve |
The component-test config does not include the app’s alias. | Configure the Vite or Webpack alias for component testing; Cypress’s framework configuration guide describes customizing the dev server. |
| Plugin injection or store is undefined | The component was mounted without the app-level plugin or provider. | Install the needed plugin in a custom mount command and create isolated plugin state per test. |
| Event spy is never called | The listener prop name, event name, or interaction does not match the component API. | Confirm the component’s emitted event declaration and bind the correctly named listener prop; ensure the test triggers the relevant UI control. |
| Assertion sees old text or flakes | A synchronous assertion or fixed timing assumption is used, or the UI path did not cause the expected state change. | Use a Cypress query followed by retryable .should(); verify the test drives the public input and that the contract expects a changed display. |
| Nuxt auto-import fails in a spec | The component-test environment does not load Nuxt auto-import configuration. | Use explicit imports or configure the needed aliases and auto-imports as described for Vue with Vite. |
Vue’s Options API has an additional initialization detail: its data function returns the initial object Vue makes reactive. Adding a new property directly to the component instance after creation will not trigger reactive updates in that model. Declare the state property during initialization, then test the behavior through the public UI. See Vue’s reactivity fundamentals.
10. Keep the suite reliable and useful
- Assert observable behavior. Test rendered content, state reflected in accessibility attributes, enabled or disabled controls, and emitted payloads that callers depend on.
- Use stable selectors. Prefer a specific
data-cyhook for test targets; avoid selectors coupled to incidental CSS classes or broad tag names. - Keep cases focused. One test should make clear which input caused which visible result. Separate initial rendering, prop behavior, interaction, and event payload when that makes failures easier to diagnose.
- Use fresh dependencies. Recreate mutable stores and plugin instances for each test to prevent state leakage.
- Avoid private-state shortcuts. Driving inputs through props and controls protects tests from implementation refactors and exercises the path a parent or user actually uses.
- Use the browser when browser behavior matters. Component testing is helpful for DOM events and rendered output. Keep pure logic tests at the unit level when there is no browser-facing behavior to verify.
Performance comes mainly from the work each mounted component and its dependencies perform. Mount only the dependencies required by the behavior under test, avoid loading an entire application shell for a small component, and keep selectors and assertions targeted. Do not trade correctness for an arbitrary sleep intended to make a slow test pass; diagnose expensive setup or the actual asynchronous dependency.
11. Or skip the browser setup
If you need a screenshot of a rendered page while investigating a visual or state-dependent issue, ScreenshotNeo can capture the resulting URL with one request. It complements component tests: Cypress verifies interactions and event contracts; a screenshot gives you an image of a page state to inspect or use elsewhere.

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 accepts cookie or consent banners like a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. ScreenshotNeo is a website screenshot API and MCP server by ScreenshotNeo.
Sign up free for 1,000 screenshots a month, with no card required.
12. FAQ
Should a component test inspect Vue’s internal reactive state?
Usually, no. Assert the visible result or emitted event that forms the component’s contract. Internal-state inspection couples the test to how the component is implemented.
Can I test a component that uses a computed property?
Yes. Change the input that feeds the computed output, then assert the rendered result. The behavior is the important part; the test does not need to assert that a computed property exists.
When should I use Cypress component tests instead of end-to-end tests?
Use a component test when the behavior can be understood by mounting the component with its dependencies and interacting with it. Use an end-to-end test when the contract depends on the full app flow, such as routing, server data, and navigation working together.
Does a screenshot prove that a component is reactive?
A screenshot records a visual state at capture time. It does not prove that a click, prop change, or emitted event caused that state; use the Cypress interaction and assertion for that proof.


