Registry / testing / netlify-plugin-cypress

netlify-plugin-cypress

library2.2.1jsnpmunverified

The `netlify-plugin-cypress` package integrates Cypress end-to-end testing directly into the Netlify build pipeline. It allows developers to run Cypress tests against their deployed site (default), or earlier in the build process (preBuild, postBuild) to prevent broken deployments. The current stable version is 2.2.1, with recent updates in February 2023. This plugin differentiates itself by automating the setup and execution of Cypress within the Netlify environment, including automatically installing a Chromium browser via Puppeteer, and providing options to control when tests run relative to the deployment lifecycle. It is primarily configured via `netlify.toml`, offering a declarative way to incorporate E2E testing into continuous deployment workflows.

testing devops

npm install netlify-plugin-cypress

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NETLIFY-PLUGIN-CYP

netlify-plugin-cypress

testingjavascriptv2.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

netlify-plugin-cypress

✓ [[plugins]] package = "netlify-plugin-cypress"

✗ import 'netlify-plugin-cypress'

Netlify Build plugins are configured declaratively in `netlify.toml`, not imported as JavaScript/TypeScript modules into application code.

configFile (input)

✓ [[plugins]] package = "netlify-plugin-cypress" [plugins.inputs] configFile = "cypress.config.ts"

✗ [[plugins.inputs]] configFile = "cypress.config.ts"

Plugin inputs, such as `configFile`, must be nested under the `[plugins.inputs]` table directly within the plugin's `[[plugins]]` definition in `netlify.toml`.

start (input)

✓ [[plugins]] package = "netlify-plugin-cypress" [plugins.inputs] start = "npm run dev"

✗ startCommand = "npm run dev"

The `start` input specifies a command to run a local web server (e.g., development server) before Cypress tests, particularly useful for dynamic sites or when running tests in 'preBuild' or 'postBuild' phases.

This quickstart demonstrates installing the plugin and Cypress as dev dependencies, then configuring the plugin in `netlify.toml` to run tests after a successful deployment.

npm install --save-dev cypress netlify-plugin-cypress # or yarn add -D cypress netlify-plugin-cypress # netlify.toml [[plugins]] # This configuration runs Cypress tests against the deployed URL # after a successful build and deployment (onSuccess event). # For blocking deploys, consider configuring 'preBuild' or 'postBuild' hooks. package = "netlify-plugin-cypress"

Debug

Known issues

breakingStarting with v2.0.0, the plugin's default behavior changed to run Cypress tests during the `onSuccess` event (after deployment). This means that if tests fail at this stage, the Netlify deploy will still be marked as successful, and the broken site will be live.

fix

To prevent broken deploys, configure the plugin to run tests during the `preBuild` or `postBuild` phases in your `netlify.toml`. For example: `[[plugins]]
package = "netlify-plugin-cypress"
  [plugins.inputs]
    preBuild = "npm run cy:verify"` or leverage Cypress GitHub/GitLab/Bitbucket integration for PR status checks.

affects: >=2.0.0

gotchaThe plugin assumes Cypress is already installed as a development dependency in your project. It does not install Cypress itself.

fix

Ensure you have `cypress` installed as a dev dependency: `npm install --save-dev cypress` or `yarn add -D cypress`.

affects: >=1.0.0

gotchaRunning Cypress tests during the `onSuccess` phase, while the default, will not cause your Netlify build to fail if tests do not pass. The site will already be deployed.

fix

If E2E test failures should block deployment, explicitly configure the plugin to run tests during the `preBuild` or `postBuild` phases in your `netlify.toml`. For example: `[[plugins]]
package = "netlify-plugin-cypress"
  [plugins.inputs]
    postBuild = "npm run cy:run"`.

affects: >=2.0.0

Errors

Common errors & fixes

Cannot find module 'cypress' or 'cypress/bin/cypress'

The Cypress package is not installed or not discoverable in the build environment.

fix

Ensure `cypress` is listed as a `devDependency` in your `package.json` and run `npm install` or `yarn install` during the Netlify build process. Also, verify `cypress` itself runs locally.

Error: Command failed with exit code 1: cypress run

Cypress tests failed during the build process, leading to the plugin exiting with a non-zero status.

fix

Review the Cypress test logs in your Netlify build output to identify which tests failed and why. Fix the failing tests in your codebase.

Error: Missing `package` property in a plugin declaration. Please add a `package` property to your plugin declaration in `netlify.toml`.

The `netlify.toml` plugin configuration is malformed, specifically missing the `package` key for the plugin.

fix

Correct your `netlify.toml` to include `package = "netlify-plugin-cypress"` within the `[[plugins]]` section, ensuring correct TOML syntax.

Upgrade

Version history

2.2.1latest on npm

Audit

Dependencies

cypressrequiredCypress itself is required to run the tests; this plugin orchestrates its execution.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/cypress-io/netlify-plugin-cypress ↗

packagehttps://www.npmjs.com/package/netlify-plugin-cypress ↗

homepagehttps://www.npmjs.com/package/netlify-plugin-cypress ↗