Cypress Component Testing After Vue 3: Rebuilding Confidence When the DOM Stops Behaving

Most “flakes” are not random. They are tests that were accidentally synchronized to Vue 2’s update timing, or to a DOM structure that no longer exists. Teleport moves content; multiple roots break assumptions about .get('#app') children; async components resolve in a different order under Vite than they did under Webpack in dev.

The fix is to treat selectors and async boundaries as part of the migration, not as “test cleanup later.” Storybook can help lock visual and structural contracts before you invest in a large Cypress CT matrix.

• Unit + VTU: pure logic, composables, Pinia stores, and small presentational components with minimal DOM.
• Cypress CT: complex widgets (data grids, date pickers, wizards) where layout and browser APIs matter.
• E2E: cross-route flows, auth, and integrations—keep this layer thin if CT covers your component edge cases.

1. Pin data-cy hooks to user-meaningful elements, not animation wrappers.
2. Replace implicit waits with retry-friendly assertions (Cypress already leans this way—double down).
3. Stub network at the component boundary; avoid full API simulation in every CT.
4. Run CT in the same build target you ship (legacy vs modern browsers) if you still support older clients.

The default scaffold is mostly correct, but two pieces trip teams up: the bundler entry and the global plugin registration used by the app. Cypress mounts a single component, not the whole app, so any plugin that the component implicitly depends on (Pinia, i18n, router) needs to be wired in the mount helper.

// cypress.config.ts
import { defineConfig } from 'cypress'

export default defineConfig({
  component: {
    devServer: {
      framework: 'vue',
      bundler: 'vite',
    },
    specPattern: 'src/**/*.cy.{ts,tsx}',
  },
})

Then the shared mount helper applies the plugins each suite expects. This is the equivalent of the global setup file you used to maintain for Vue Test Utils:

// cypress/support/component.ts
import { mount } from 'cypress/vue'
import { createPinia } from 'pinia'
import { createI18n } from 'vue-i18n'
import en from '@/locales/en.json'

Cypress.Commands.add('mount', (component, options = {}) => {
  options.global = options.global || {}
  options.global.plugins = [
    ...(options.global.plugins || []),
    createPinia(),
    createI18n({ legacy: false, locale: 'en', messages: { en } }),
  ]
  return mount(component, options)
})

If you are mid-migration to Pinia or still juggling vue-i18n locales, wire the active store version here and avoid mocking what the component actually needs.

The biggest source of red builds after Vue 3 is selectors that rely on DOM structure rather than user-meaningful targets. Replacing structural selectors with role and label-based ones is the single highest-leverage cleanup.

cypress-testing-library pairs naturally with Vue 3 because it leans on accessibility semantics, which Vue's <Teleport> and multi-root components preserve even when DOM structure shifts.

Three Vue 3 features cause the majority of post-migration failures and each has a clean answer.

Teleport

Teleported content (modals, toasts, dropdowns) renders outside the mounted component's root. Use cy.get('body') as the search root, or query by role across the document:

cy.mount(<ConfirmDialog open />)
cy.findByRole('dialog').within(() => {
  cy.findByRole('button', {name: /confirm/i}).click()
})

Fragments / multiple roots

wrapper.element from Vue 2 days no longer points to a single node. Avoid asserting on the wrapper's outer HTML; assert on visible content.

Async setup()

If a component uses <Suspense>, mount it inside its boundary. Cypress retries assertions automatically, so prefer cy.findByText(...) over manual cy.wait().

• Manual cy.wait(500) everywhere. Replace with retried assertions; Cypress already retries most queries until the command timeout.
• Mounting App.vue in CT. That is an E2E test in disguise—and a slow one. CT should mount one component plus its required plugins.
• Snapshot-only assertions. Brittle across class hash changes from scoped styles. Assert on visible behavior instead.
• Re-implementing E2E coverage in CT. CT is a complement to E2E, not a replacement. Keep the migration checklist honest about what each layer covers.
• Skipping accessibility checks. cypress-axe on the most reused components catches more bugs than a third snapshot ever will.

Conclusion

Cypress component tests are most valuable in the window right after Vue 3 lands—when your team is touching the most UI code anyway. Invest in stable selectors and a clear split with E2E, and you will spend less time chasing flakes and more time shipping the migration.