@cypress/mount-utils

Shared utilities for building Cypress component testing mount adapters. This package provides the core infrastructure needed to mount, test, and clean up components across different JavaScript frameworks within the Cypress component testing environment.

Package Information

• Package Name: @cypress/mount-utils
• Package Type: npm
• Language: TypeScript
• Installation: npm install @cypress/mount-utils

Core Imports

import {
  ROOT_SELECTOR,
  getContainerEl,
  setupHooks,
  checkForRemovedStyleOptions
} from "@cypress/mount-utils";

For CommonJS:

const {
  ROOT_SELECTOR,
  getContainerEl,
  setupHooks,
  checkForRemovedStyleOptions
} = require("@cypress/mount-utils");

Basic Usage

import {
  ROOT_SELECTOR,
  getContainerEl,
  setupHooks,
  checkForRemovedStyleOptions
} from "@cypress/mount-utils";

// Set up lifecycle hooks (typically called once)
setupHooks(() => {
  // Optional cleanup callback before each test
  getContainerEl().innerHTML = "";
});

// In your mount function
function mount(component, options = {}) {
  // Validate options don't use deprecated style options
  checkForRemovedStyleOptions(options);
  
  // Get the container element for mounting
  const container = getContainerEl();
  
  // Mount your component
  container.innerHTML = `<div id="component-root"></div>`;
  
  return cy.wrap(document.querySelector("#component-root"));
}

Architecture

@cypress/mount-utils is designed as a foundation library for Cypress component testing adapters. It provides:

• DOM Management: Constants and utilities for finding and managing the component mounting container
• Lifecycle Integration: Hooks that integrate with Cypress's test lifecycle to ensure proper cleanup
• Safety Measures: Validation to prevent usage of deprecated options and ensure component testing constraints
• Backward Compatibility: Deprecated functions that throw helpful errors for migration guidance

Capabilities

DOM Container Management

Core functionality for locating and accessing the DOM element where components are mounted.

/**
 * CSS selector constant for the root DOM element where components are mounted
 */
const ROOT_SELECTOR: "[data-cy-root]";

/**
 * Gets the root element used to mount the component
 * @returns The root element for mounting components
 * @throws Error if the root element is not found
 */
function getContainerEl(): HTMLElement;

The ROOT_SELECTOR constant defines the CSS selector used to locate the mounting container. The getContainerEl() function searches for this element and throws a descriptive error if not found, guiding users to add the proper root element to their component-index.html file.

Lifecycle Management

Integration with Cypress test lifecycle to ensure proper setup and cleanup between tests.

/**
 * Utility function to register CT side effects and run cleanup code during the "test:before:run" Cypress hook
 * @param optionalCallback - Optional callback to be called before the next test runs
 */
function setupHooks(optionalCallback?: Function): void;

The setupHooks() function registers essential Cypress lifecycle hooks. It:

• Prevents cy.visit() from being used in component tests (throws error)
• Executes the optional callback before each test runs
• Only operates in component testing mode, not e2e testing

Usage Example:

// Basic setup
setupHooks();

// With cleanup callback
setupHooks(() => {
  // Clear previous test artifacts
  getContainerEl().innerHTML = "";
  
  // Reset any global state
  window.myGlobalState = {};
});

Options Validation

Validation to ensure deprecated style-related mounting options are not used.

/**
 * Validates mounting options and throws error if deprecated style-related options are detected
 * @param mountingOptions - Object containing mounting configuration options
 * @throws Uses Cypress.utils.throwErrByPath() if removed style options are found
 */
function checkForRemovedStyleOptions(mountingOptions: Record<string, any>): void;

This function checks for deprecated style injection options (cssFile, cssFiles, style, styles, stylesheet, stylesheets) and throws descriptive errors directing users to the Cypress 11.0.0 migration guide.

Usage Example:

function mount(component, options = {}) {
  // Validate options before mounting
  checkForRemovedStyleOptions(options);
  
  // Proceed with mounting...
}

Deprecated Functions

Legacy functions maintained for backward compatibility that provide migration guidance.

/**
 * @deprecated Removed as of Cypress 11.0.0
 * @see https://on.cypress.io/migration-11-0-0-component-testing-updates
 * @throws Always throws deprecation error via Cypress.utils.throwErrByPath()
 */
function cleanupStyles(): void;

/**
 * @deprecated Removed as of Cypress 11.0.0  
 * @see https://on.cypress.io/migration-11-0-0-component-testing-updates
 * @throws Always throws deprecation error via Cypress.utils.throwErrByPath()
 */
function injectStylesBeforeElement(
  options: Partial<StyleOptions & { log: boolean }>,
  document: Document,
  el: HTMLElement | null
): void;

These functions exist solely to provide helpful error messages for users upgrading from older versions of Cypress.

Types

/**
 * @deprecated Type definition for style injection options, removed as of Cypress 11.0.0
 */
type StyleOptions = unknown;

Environment Requirements

• Runtime: Browser environment with DOM API
• Framework: Requires Cypress testing framework with Cypress global object
• Testing Mode: Designed for Cypress component testing (not e2e testing)
• DOM Setup: Requires element with data-cy-root attribute in component-index.html

Error Handling

The library provides detailed error messages for common issues:

• Missing root element: getContainerEl() throws error with setup instructions
• Deprecated options: checkForRemovedStyleOptions() throws errors with migration guidance
• Wrong testing mode: setupHooks() prevents cy.visit() in component tests
• Deprecated functions: All deprecated functions throw helpful migration errors

Real-World Usage

This package is used by all first-party Cypress mount adapters:

• @cypress/react: Uses getContainerEl() for DOM cleanup and mounting
• @cypress/vue: Uses getContainerEl(), setupHooks(), and checkForRemovedStyleOptions()
• @cypress/angular: Integrates mount utilities for Angular component testing
• @cypress/svelte: Uses utilities for Svelte component mounting and lifecycle management

Third-party mount adapters can use these utilities to ensure consistent behavior with the official adapters.