mount

Component Only

Cypress does not have a built-in cy.mount() command. The command must be set up in your support file. By default, when you use the Cypress app to configure your project, one will be automatically scaffolded for you.

This guide covers how to customize the cy.mount() command to fit the needs of your app.

We recommend setting up a custom cy.mount() command instead of importing the mount command from the mounting libraries. Doing so offers a few advantages:

  • You don't need to import the mount command into every test as the cy.mount() command is available globally.
  • You can set up common scenarios that you usually have to do in each test, like wrapping a component in a React Provider or adding Vue plugins.

Let's take a look at how to implement the command.

Creating a New cy.mount() Command

Different frameworks render their components differently, so we provide framework-specific mount() functions, which can be imported like so:

import { mount } from 'cypress/react'

// For Vue 3
import { mount } from 'cypress/vue'

// For Vue 2
import { mount } from 'cypress/vue-2'

To use cy.mount(), add a custom command to the commands file using Cypress.Commands.add(). Below are examples to start with for your commands:

import { mount } from 'cypress/react'

Cypress.Commands.add('mount', (component, options) => {
  // Wrap any parent components needed
  // ie: return mount(<MyProvider>{component}</MyProvider>, options)
  return mount(component, options)
})

import { mount } from 'cypress/vue'

Cypress.Commands.add('mount', (component, options = {}) => {
  // Setup options object
  options.global = options.global || {}
  options.global.stubs = options.global.stubs || {}
  options.global.stubs['transition'] = false
  options.global.components = options.global.components || {}
  options.global.plugins = options.global.plugins || []

  /* Add any global plugins */
  // options.global.plugins.push({
  //   install(app) {
  //     app.use(MyPlugin);
  //   },
  // });

  /* Add any global components */
  // options.global.components['Button'] = Button;

  return mount(component, options)
})

import { mount } from 'cypress/vue-2'

Cypress.Commands.add('mount', (component, options = {}) => {
  // Setup options object
  options.extensions = options.extensions || {}
  options.extensions.plugins = options.extensions.plugins || []
  options.extensions.components = options.extensions.components || {}

  /* Add any global plugins */
  // options.global.plugins.push({
  //   install(app) {
  //     app.use(MyPlugin);
  //   },
  // });

  /* Add any global components */
  // options.global.components['Button'] = Button;

  return mount(component, options)
})

Adding TypeScript Typings for cy.mount() Commands

When working in TypeScript, you will need to add custom typings for your commands to get code completion and to avoid any TypeScript errors.

The typings need to be in a location that any code can access, therefore, we recommend creating a cypress.d.ts file in the root directory, and use this example as a starting point for customizing your own command:

import { MountOptions, MountReturn } from 'cypress/react'

declare global {
  namespace Cypress {
    interface Chainable {
      /**
       * Mounts a React node
       * @param component React Node to mount
       * @param options Additional options to pass into mount
       */
      mount(
        component: React.ReactNode,
        options?: MountOptions
      ): Cypress.Chainable<MountReturn>
    }
  }
}

import { mount } from 'cypress/vue'

type MountParams = Parameters<typeof mount>
type OptionsParam = MountParams[1]

declare global {
  namespace Cypress {
    interface Chainable {
      /**
       * Helper mount function for Vue Components
       * @param component Vue Component or JSX Element to mount
       * @param options Options passed to Vue Test Utils
       */
      mount(component: any, options?: OptionsParam): Chainable<any>
    }
  }
}

If your tests have trouble finding the types for the custom commands, manually include the cypress.d.ts file in all your tsconfig.json files like so:

"include": ["./src", "cypress.d.ts"]

Additional Mount Command Examples

Visit the guides for scenarios in React and Vue for customizing a mount command.