mount

caution

Cypress Component Testing is currently in beta.

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:

React

:::info

The mount() command exported from the cypress/react module supports standard JSX syntax for mounting components. If you have any questions about mount options that aren't covered in this guide, be sure to check out the module documentation.

:::

import { mount } from "cypress/react";

Vue

:::infoA note for Vue users

The mount() command exported from the cypress/vue library uses Vue Test Utils internally, but instead of mounting your components in a virtual browser in node, it mounts them in your actual browser. If you have any questions about mount options that aren't covered in this guide, be sure to check out the library documentation.

:::

// For Vue 3
import { mount } from "cypress/vue";

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

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

React

:::info

The mount() command exported from the cypress/react module supports standard JSX syntax for mounting components. If you have any questions about mount options that aren't covered in this guide, be sure to check out the module documentation.

:::

import { mount } from "cypress/react";

Vue

:::infoA note for Vue users

The mount() command exported from the cypress/vue library uses Vue Test Utils internally, but instead of mounting your components in a virtual browser in node, it mounts them in your actual browser. If you have any questions about mount options that aren't covered in this guide, be sure to check out the library documentation.

:::

// 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:

React

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);
});

Vue 2

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);
});

Vue 3

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);
});

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:

React

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>;
    }
  }
}

Vue

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.