# @cypress/mount-utils

> Shared utilities for the various component testing adapters

Latest version **5.0.0** (published 2026-08-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install @cypress/mount-utils
pnpm add @cypress/mount-utils
yarn add @cypress/mount-utils
bun add @cypress/mount-utils
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; no vulnerabilities; recently updated; high maintenance score; popular repo; extremely popular.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 5.0.0 |
| Published | 2026-08-26 |
| First published | 2021-04-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 7.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 51017 |
| Maintainers | cypress-npm-publisher |

## Links

- npm: https://www.npmjs.com/package/@cypress/mount-utils
- Repository: https://github.com/cypress-io/cypress
- Homepage: https://github.com/cypress-io/cypress/tree/develop/npm/mount-utils#readme
- Issues: https://github.com/cypress-io/cypress/issues/new?template=1-bug-report.md
- npm.io page: https://npm.io/package/@cypress/mount-utils

## Recent versions

- 5.0.0 (latest) — 2026-08-26
- 4.1.2 — 2025-01-08
- 4.1.1 — 2024-06-07
- 4.1.0 — 2024-03-12
- 4.0.0 — 2022-12-02
- 3.0.0 — 2022-11-07
- 2.1.0 — 2022-08-30
- 2.0.1 — 2022-08-11
- 2.0.0 — 2022-06-13
- 1.0.2 — 2021-04-30
- 1.0.1 — 2021-04-26
- 1.0.0 — 2021-04-21

## README

# @cypress/mount-utils

> **Note** this package is not meant to be used outside of cypress component testing.

This library exports some shared types and utility functions designed to build adapters for components frameworks.

It is used in:

- [`@cypress/react`](https://github.com/cypress-io/cypress/tree/develop/npm/react)
- [`@cypress/vue`](https://github.com/cypress-io/cypress/tree/develop/npm/vue)
- [`@cypress/svelte`](https://github.com/cypress-io/cypress/tree/develop/npm/svelte)
- [`@cypress/angular`](https://github.com/cypress-io/cypress/tree/develop/npm/angular)

## What is a Mount Adapter?

All Component Tests require a component to be **mounted**. This is generally done with a custom command, `cy.mount` by default.


### Requirements

All the functionality used to create the first party Mount adapters is available to support third parties adapters. At minimum, a Mount Adapter must:

- Receive a component as the first argument. This could be class, function etc - depends on the framework.
- Return a Cypress Chainable (for example using `cy.wrap`) that resolves whatever is idiomatic for your framework
- Call `getContainerEl` to access the root DOM element

In addition, we recommend that Mount Adapters:

- call `setupHooks` to register the required lifecycle hooks for `@cypress/mount-utils` to work

### Example Mount Adapter: Web Components 

Here's a simple yet realistic example of Mount Adapter targeting Web Components. It uses utilities from this package (`@cypress/mount-utils`) This is recommended, so your adapter behaves similar to the first party Mount Adapters.

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

Cypress.on("run:start", () => {
  // Consider doing a check to ensure your adapter only runs in Component Testing mode.
  if (Cypress.testingType !== "component") {
    return;
  }

  Cypress.on("test:before:run", () => {
    // Do some cleanup from previous test - for example, clear the DOM.
    getContainerEl().innerHTML = "";
  });
});

function maybeRegisterComponent<T extends CustomElementConstructor>(
  name: string,
  webComponent: T
) {
  // Avoid double-registering a Web Component.
  if (window.customElements.get(name)) {
    return;
  }

  window.customElements.define(name, webComponent);
}

export function mount(
  webComponent: CustomElementConstructor
): Cypress.Chainable {
  // Get root selector defined in `cypress/support.component-index.html
  const $root = document.querySelector(ROOT_SELECTOR)!;

  // Change to kebab-case to comply with Web Component naming convention
  const name = webComponent.name
    .replace(/([a-z0–9])([A-Z])/g, "$1-$2")
    .toLowerCase();

  /// Register Web Component
  maybeRegisterComponent(name, webComponent);

  // Render HTML containing component.
  $root.innerHTML = `<${name} id="root"></${name}>`;

  // Log a messsage in the Command Log.
  Cypress.log({
    name: "mount",
    message: [`<${name} ... />`],
  });

  // Return a `Cypress.Chainable` that returns whatever is idiomatic
  // in the framework your mount adapter targets.
  return cy.wrap(document.querySelector("#root"), { log: false });
}

// Setup Cypress lifecycle hooks.
setupHooks();
```

Usage:

```ts
// User will generally register a `cy.mount` command in `cypress/support/component.js`:

import { mount } from '@package/cypress-web-components'

Cypress.Commands.add('mount', mount)

// Test
export class WebCounter extends HTMLElement {
  constructor() {
    super();
  }

  connectedCallback() {
    this.innerHTML = `
      <div>
        <button>Counter</button>
      </div>`;
  }
}


describe('web-component.cy.ts', () => {
  it('playground', () => {
    cy.mount(WebCounter)
  })
})
```

For more robust, production ready examples, check out our first party adapters.

## Compatibility

| @cypress/mount-utils | cypress |
| -------------------- | ------- |
| <= v1                | <= v9   |
| >= v2                | >= v10  |

## Changelog

[Changelog](./CHANGELOG.md)

---
_Source: https://npm.io/package/@cypress/mount-utils · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._