Skip to main content
Cypress App

How to Use Cypress Plugins

Plugins add capabilities that don't ship with Cypress itself: visual testing, custom commands, code coverage, richer reporters, framework integrations, and more. They're versioned npm packages, so you can add one to your project in a couple of minutes and update it independently of Cypress.

info

What you'll learn

  • Where to find plugins and what they can do
  • Where plugin code runs: in Node, in the browser, or both
  • How to install a plugin with npm, Yarn, pnpm, or Bun
  • Where to register a plugin: setupNodeEvents, your support file, or both
  • How to verify a plugin works and fix common setup mistakes
  • How to tell whether a bug belongs to a plugin or to Cypress, and where to report it

Find a plugin​

Browse the list of plugins maintained by Cypress. It curates official and community plugins across categories like custom commands, visual testing, network and API helpers, reporters, and CI integrations. Each entry shows its latest version, supported Cypress versions, and how recently it was updated, so you can pick one with confidence.

Where plugin code runs​

Code registered in setupNodeEvents runs in Node, where it can access the file system, the network, and environment variables. Code registered in your support file runs in the browser alongside your tests and your application under test.

Beyond that, a plugin is a regular npm dependency, so the habits you already use for other packages apply here too.

Installing a plugin​

Install the plugin as a dev dependency with your package manager:

npm install <plugin name> --save-dev

Before installing, check the plugin's supported Cypress versions, shown as a badge on the list of plugins and usually stated in the plugin's README.

Using a plugin​

Installing the package isn't enough on its own: you also need to register the plugin with Cypress. Where you register it depends on where the plugin's code needs to run, and the plugin's README will tell you which it needs:

  • In setupNodeEvents in your Cypress configuration for plugins that run in Node: preprocessors, browser launch handling, tasks, and anything that touches the file system or test results.
  • In your support file for plugins that run in the browser alongside your tests: custom commands, assertion libraries, and overrides of built-in behavior.
  • In both, for plugins with a Node piece and a browser piece.

Register in the Cypress configuration​

Node-side plugins typically export a setup function that you call inside setupNodeEvents, passing along on and config so the plugin can bind to Node events:

const { defineConfig } = require('cypress')
const { configurePlugin } = require('my-cypress-plugin')

module.exports = defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      configurePlugin(on, config)

      // return the config so any changes the plugin makes take effect
      return config
    },
  },
})

Register in the support file​

Browser-side plugins are imported (or registered with a function call) in your support file, which loads before every spec:

cypress/support/e2e.js
import 'my-cypress-plugin'

Any custom commands the plugin adds are then available in all of your tests.

Example: setting up @cypress/grep​

@cypress/grep filters which tests run by title or tag, and is a good example of a plugin that registers in both places. Install it:

npm install @cypress/grep --save-dev

Register it in your support file so it can filter tests in the browser:

cypress/support/e2e.js
import { register as registerCypressGrep } from '@cypress/grep'

registerCypressGrep()

Add its Node plugin to your configuration so it can skip loading specs with no matching tests:

const { defineConfig } = require('cypress')
const { plugin } = require('@cypress/grep/plugin')

module.exports = defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      plugin(config)

      return config
    },
  },
})

Then verify it works by running only tests with "login" in the title:

npx cypress run --expose grep=login

Troubleshooting​

If a plugin doesn't seem to do anything, or errors on startup, work through these checks:

  • Follow the plugin's own README. Registration details vary between plugins, and some require extra configuration beyond the patterns shown above.
  • Confirm you registered it in the right place. An error like cy is not defined inside setupNodeEvents means browser-side code is running in Node; move that registration to your support file.
  • Return the config object from setupNodeEvents if the plugin modifies configuration. Forgetting to return it silently discards the plugin's changes.
  • Restart Cypress after configuration changes. Changes to the Cypress configuration file, including newly registered plugins, require restarting cypress open.
  • Check version compatibility. A plugin built for an older Cypress major version may fail on the current one. Compare the supported versions badge on the list of plugins with your installed Cypress version.

Plugin issue or Cypress issue?​

When something breaks in a project that uses plugins, isolate which side owns the problem before reporting it, so your issue lands where it can be fixed:

  1. Read the error and stack trace. A stack trace that points into the plugin's package in node_modules is a strong signal the plugin is involved.
  2. Disable the plugin and run again. Comment out its registration in setupNodeEvents and your support file, then re-run the failing command or test.
  3. Report it where it reproduces:
    • If the problem still occurs with the plugin disabled, it isn't caused by the plugin. Work through the troubleshooting guide, search existing Cypress issues, and if it's new, open an issue against Cypress with a reproducible example.
    • If the problem only occurs with the plugin registered, report it on the plugin's own repository, not the Cypress repository. Search its existing issues first, and include your Cypress version, the plugin version, and a minimal reproduction. The Cypress team doesn't maintain community plugins and can't fix bugs in them.

If the failure started right after a Cypress upgrade, first check that the plugin supports the new version. A compatibility gap is a plugin issue: the plugin's repository is the right place to report it, even though the Cypress upgrade surfaced it.

Writing your own plugin​

Anyone can create and publish a plugin. If no existing plugin covers your use case, read the Node Events Overview to learn how plugins hook into Cypress, then submit it to the plugins list so others can find it.

See also​

Contents