{"id":13511080,"url":"https://github.com/cypress-io/netlify-plugin-cypress","last_synced_at":"2025-05-16T04:00:24.758Z","repository":{"id":37024563,"uuid":"248347951","full_name":"cypress-io/netlify-plugin-cypress","owner":"cypress-io","description":"Runs Cypress end-to-end tests after Netlify builds the site but before it is deployed","archived":false,"fork":false,"pushed_at":"2025-05-14T12:47:04.000Z","size":24772,"stargazers_count":90,"open_issues_count":26,"forks_count":37,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-05-14T13:56:18.431Z","etag":null,"topics":["cypress","netlify","netlify-plugin"],"latest_commit_sha":null,"homepage":"https://www.cypress.io/blog/2020/03/30/run-cypress-tests-on-netlify-using-a-single-line/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cypress-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-03-18T21:34:31.000Z","updated_at":"2025-05-09T16:05:44.000Z","dependencies_parsed_at":"2023-12-08T15:25:48.220Z","dependency_job_id":"9ecbe823-a5ba-4f0b-8ea7-dc79da2f5e8d","html_url":"https://github.com/cypress-io/netlify-plugin-cypress","commit_stats":null,"previous_names":[],"tags_count":47,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypress-io%2Fnetlify-plugin-cypress","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypress-io%2Fnetlify-plugin-cypress/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypress-io%2Fnetlify-plugin-cypress/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypress-io%2Fnetlify-plugin-cypress/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cypress-io","download_url":"https://codeload.github.com/cypress-io/netlify-plugin-cypress/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254180391,"owners_count":22027968,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cypress","netlify","netlify-plugin"],"created_at":"2024-08-01T03:00:34.014Z","updated_at":"2025-05-16T04:00:24.721Z","avatar_url":"https://github.com/cypress-io.png","language":"JavaScript","funding_links":[],"categories":["Testing","JavaScript"],"sub_categories":["Included Default Testing"],"readme":"# netlify-plugin-cypress\n[![CircleCI](https://circleci.com/gh/cypress-io/netlify-plugin-cypress.svg?style=shield)](https://circleci.com/gh/cypress-io/netlify-plugin-cypress/tree/master) [![renovate-app badge][renovate-badge]][renovate-app] [![netlify-plugin-cypress](https://img.shields.io/endpoint?url=https://dashboard.cypress.io/badge/simple/ixroqc/master\u0026style=flat\u0026logo=cypress)](https://dashboard.cypress.io/projects/ixroqc/runs) [![Netlify Status](https://api.netlify.com/api/v1/badges/76892baf-2ad8-4642-b283-f2135963ff51/deploy-status)](https://app.netlify.com/sites/sad-lumiere-6a00a5/deploys)\n\u003e Runs Cypress end-to-end tests on Netlify Build\n\n## Install and use\n\nYou can install this plugin in the Netlify UI from this [direct in-app installation link](https://app.netlify.com/plugins/netlify-plugin-cypress/install) or from the [Plugins directory](https://app.netlify.com/plugins).\n\nFor file based installation, add `netlify-plugin-cypress` NPM package as a dev dependency to your repository.\n\n```shell\nnpm install --save-dev netlify-plugin-cypress\n# or\nyarn add -D netlify-plugin-cypress\n```\n\nAnd then add the plugin's name to the list of build plugins in `netlify.toml` file as shown in the examples below.\n\n*note:* this plugin assumes you have already installed Cypress as a dev NPM dependency.\n\n### Chromium install\n\nThis plugin installs [via Puppeteer](https://github.com/puppeteer/puppeteer) Chromium browser, which is also cached inside `./node_modules` folder.\n\n## How does it work\n\n### Build steps\n\nWhen Netlify Build system runs it performs 2 steps essentially:\n\n1. builds the site\n2. deploys the site\n\nEvery plugin that wants to perform some actions can do so before the build, after the build (but before the deploy), and after the deploy. The Netlify uses the following names for these events\n\n```\n\"preBuild\"\n1. builds the site\n\"postBuild\"\n2. deploys the site\n\"onSuccess\"\n\"onFailure\"\n```\n\nThus every plugin can register itself to be executed before a site is built using \"preBuild\" event, or after a successful deploy using \"onSuccess\" event name, etc.\n\n### This plugin\n\nThis plugin `netlify-plugin-cypress` by default runs during the \"onSuccess\" event, testing the deployed site. The Netlify Build system gives the URL to the plugin and it runs Cypress against that URL using the [Cypress NPM module API](https://on.cypress.io/module-api).\n\nOptionally, you can also run tests during \"preBuild\" and \"postBuild\" steps. This is useful if you want to ensure the site is working even before deploying it to Netlify servers. Finally, this plugin does not use \"onFailure\" event which happens only if Netlify fails to deploy the site.\n\n### Failing the deploy\n\nRunning Cypress tests by default uses the \"onSuccess\" step of the build pipeline. By this point Netlify has already deployed the site. Even if the tests fail now, the Netlify shows the successful deployment - the site is live! To really prevent the broken deploys, we suggest using [Cypress GitHub / GitLab / Bitbucket integration](https://on.cypress.io/github-integration) to fail the _status checks_ on a pull request.\n\nWe also suggest running tests during the \"preBuild\" and/or \"postBuild\" steps. If the tests fail during these steps, the Netlify fails the entire build and does not deploy the broken site.\n\nFinally, you can set up [Slack notifications](https://on.cypress.io/slack-integration) on failed tests against the deployed site. At least you will quickly find out if the deployed site fails the E2E tests and would be able to roll back the deploy.\n\n## Examples\n\n### basic\n\nHere is the most basic [Netlify config file](https://docs.netlify.com/configure-builds/file-based-configuration/) `netlify.toml` with just the Cypress plugin\n\n```toml\n[[plugins]]\n  # runs Cypress tests against the deployed URL\n  package = \"netlify-plugin-cypress\"\n```\n\nThe example file above should be enough to run Cypress tests in any existing Netlify project.\n\n### recommended\n\nWe strongly recommend setting `CYPRESS_CACHE_FOLDER` to place the Cypress binary _inside the node_modules_ folder to [cache it between builds](https://on.cypress.io/caching)\n\n```toml\n# explicit commands for building the site\n# and the folder to publish\n[build]\ncommand = \"npm run build\"\npublish = \"build\"\n\n[build.environment]\n# cache Cypress binary in local \"node_modules\" folder\n# so Netlify caches it\nCYPRESS_CACHE_FOLDER = \"./node_modules/CypressBinary\"\n# set TERM variable for terminal output\nTERM = \"xterm\"\n\n[[plugins]]\n# runs Cypress tests against the deployed URL\npackage = \"netlify-plugin-cypress\"\n```\n\nSee [netlify-plugin-cypress-example](https://github.com/cypress-io/netlify-plugin-cypress-example) repo.\n\nTypescript users may need to add a `install` before the build command. For a yarn user with a typescript app, the build section of the Netlify configuration might look like this:\n\n```toml\n[build]\ncommand = \"yarn install \u0026\u0026 yarn build\"\npublish = \"build\"\n\n# ...remaining configuration...\n```\n\n### tutorial\n\nRead the full tutorial at [Test Sites Deployed To Netlify Using netlify-plugin-cypress](https://glebbahmutov.com/blog/test-netlify/).\n\n**Note:** if any tests against the deployed URL fail, the Netlify build still considers it a success. Thus if you want to have a test check against the deploy, install [Cypress GitHub App](https://on.cypress.io/github-integration). The app will provide its own failing status check in this case.\n\n### options\n\nYou can control the browser, the specs to run, record tests on Cypress Dashboard, etc, see [manifest.yml](./manifest.yml) file.\n\n### recording\n\nTo record test results and artifacts on Cypress Dashboard, set `record: true` plugin input and set `CYPRESS_RECORD_KEY` as an environment variable via Netlify Deploy settings.\n\n```yaml\n[build]\ncommand = \"npm run build\"\npublish = \"build\"\n  [build.environment]\n  # cache Cypress binary in local \"node_modules\" folder\n  # so Netlify caches it\n  CYPRESS_CACHE_FOLDER = \"./node_modules/CypressBinary\"\n  # set TERM variable for terminal output\n  TERM = \"xterm\"\n\n[[plugins]]\n# runs Cypress tests against the deployed URL\npackage = \"netlify-plugin-cypress\"\n  [plugins.inputs]\n  record = true\n```\n\nSee [cypress-example-kitchensink](https://github.com/cypress-io/cypress-example-kitchensink) and recorded results at Cypress Dashboard [![netlify-plugin-cypress](https://img.shields.io/endpoint?url=https://dashboard.cypress.io/badge/simple/ixroqc/master\u0026style=flat\u0026logo=cypress)](https://dashboard.cypress.io/projects/ixroqc/runs)\n\n**Security note 🔐:** you should keep your `CYPRESS_RECORD_KEY` secret. You can control how Netlify builds external pull requests, see [the doc](https://docs.netlify.com/configure-builds/environment-variables/) - you never want to expose sensitive environment variables to outside builds.\n\n#### status checks\n\nIf you are recording test results to Cypress Dashboard, you should also install [Cypress GitHub Integration App](https://on.cypress.io/github-integration) to see status checks from individual groups or from individual specs per commit. See [netlify-plugin-prebuild-example PR #8](https://github.com/cypress-io/netlify-plugin-prebuild-example/pull/8) pull request for an example.\n\n![Netlify to Cypress Dashboard to GH Integration checks](./images/netlify-to-cy-gh-app-checks.png)\n\n#### group\n\nYou can change the group name for the recorded run using `group` parameter\n\n```toml\n[[plugins]]\n# runs Cypress tests against the deployed URL\npackage = \"netlify-plugin-cypress\"\n  [plugins.inputs]\n  record = true\n  group = \"built site\"\n```\n\n#### tag\n\nYou can give recorded run [tags](https://on.cypress.io/module-api#cypress-run) using a comma-separated string. If the tag is not specified, Netlify context will be used (`production`, `deploy-preview` or `branch-deploy`)\n\n```toml\n[[plugins]]\n# runs Cypress tests against the deployed URL\npackage = \"netlify-plugin-cypress\"\n  [plugins.inputs]\n  record = true\n  group = \"built site\"\n  tag = \"nightly,production\"\n```\n\n### spec\n\nRun only a single spec or specs matching a wildcard\n\n```toml\n[build]\ncommand = \"npm run build\"\npublish = \"build\"\n  [build.environment]\n  # cache Cypress binary in local \"node_modules\" folder\n  # so Netlify caches it\n  CYPRESS_CACHE_FOLDER = \"./node_modules/CypressBinary\"\n  # set TERM variable for terminal output\n  TERM = \"xterm\"\n\n[[plugins]]\n# runs Cypress tests against the deployed URL\npackage = \"netlify-plugin-cypress\"\n  [plugins.inputs]\n  spec = \"cypress/integration/smoke*.js\"\n```\n\nSee [cypress-example-kitchensink](https://github.com/cypress-io/cypress-example-kitchensink) for instance.\n\n### browser\n\nBy default all tests run using the Chromium browser. If you want to use Electron:\n\n```toml\n[build]\ncommand = \"npm run build\"\npublish = \"build\"\n  [build.environment]\n  # cache Cypress binary in local \"node_modules\" folder\n  # so Netlify caches it\n  CYPRESS_CACHE_FOLDER = \"./node_modules/CypressBinary\"\n  # set TERM variable for terminal output\n  TERM = \"xterm\"\n\n[[plugins]]\npackage = \"netlify-plugin-cypress\"\n  [plugins.inputs]\n  # allowed values: electron, chromium\n  browser = \"electron\"\n```\n\n### configFile\n\nIf you would like to use a different Cypress config file instead of `cypress.json`, specify it using the `configFile` option\n\n```toml\n[build]\ncommand = \"npm run build\"\npublish = \"build\"\n  [build.environment]\n  # cache Cypress binary in local \"node_modules\" folder\n  # so Netlify caches it\n  CYPRESS_CACHE_FOLDER = \"./node_modules/CypressBinary\"\n  # set TERM variable for terminal output\n  TERM = \"xterm\"\n\n[[plugins]]\npackage = \"netlify-plugin-cypress\"\n  [plugins.inputs]\n  configFile = \"cypress.netlify.config.js\"\n```\n\n### testing SPA routes\n\nSPAs need catch-all redirect setup to make non-root paths accessible by tests. You can enable this with `spa` parameter.\n\n```\n[[plugins]]\n# local Cypress plugin will test our site after it is built\npackage = \"netlify-plugin-cypress\"\n  [plugins.inputs]\n  # can also use \"spa = true\" to use \"index.html\" by default\n  spa = \"index.html\"\n```\n\nSee [lws-spa](https://github.com/lwsjs/spa) for more options and [tests/routing](tests/routing) example.\n\n### testing the site before build\n\nBy default this plugin tests static site _after deploy_. But maybe you want to run end-to-end tests against the _local development server_. You can start the local server, wait for it to respond and then run Cypress tests by passing parameters to this plugin. Here is a sample config file\n\n```toml\n[[plugins]]\n  package = \"netlify-plugin-cypress\"\n  # let's run tests against development server\n  # before building it (and testing the built site)\n  [plugins.inputs.preBuild]\n    enable = true\n    start = 'npm start'\n    wait-on = 'http://localhost:3000'\n    wait-on-timeout = '30' # seconds\n```\n\nParameters you can place into `preBuild` inputs: `start`, `wait-on`, `wait-on-timeout`, `spec`, `record`, `group`, and `tag`.\n\nSee [netlify-plugin-prebuild-example](https://github.com/cypress-io/netlify-plugin-prebuild-example) repo\n\n### testing the site after build\n\nBy default this plugin tests static site _after deploy_. But maybe you want to run end-to-end tests locally after building the static site. Cypress includes a local static server for this case but you can specify your own command if needed by using the `start` argument. Here is a sample config file\n\n```toml\n[[plugins]]\n  package = \"netlify-plugin-cypress\"\n  # let's run tests against the built site\n  [plugins.inputs.postBuild]\n    enable = true\n```\n\nParameters you can place into `postBuild` inputs: `spec`, `record`, `group`, `tag`, `start` and `spa`.\n\n#### The SPA parameter\n\nIf your site requires all unknown URLs to redirect back to the index page, use the `spa` parameter\n\n```toml\n[[plugins]]\n  package = \"netlify-plugin-cypress\"\n  # let's run tests against the built site\n  [plugins.inputs.postBuild]\n    enable = true\n    # must allow our test server to redirect unknown routes to \"/\"\n    # so that client-side routing can correctly route them\n    # can be set to true or \"index.html\" (or similar fallback filename in the built folder)\n    spa = true\n    start = 'npm start'\n```\n\nSee [the routing example](./tests/routing/netlify.toml).\n\n### using Netlify CLI\n\nEven better when testing the prebuilt site is to run the [Netlify CLI](https://cli.netlify.com/) to make sure the local API redirects and Netlify functions work in addition to the web site. Add `netlify-cli` as a dev dependency and start it during testing.\n\n```shell\n$ npm i -D netlify-cli\n```\n\n```toml\n[[plugins]]\n  package = \"netlify-plugin-cypress\"\n  # start Netlify server\n  [plugins.inputs.preBuild]\n    start = 'npx netlify dev'\n    wait-on = 'http://localhost:8888'\n```\n\nFor more, see [tests/test-netlify-dev](./tests/test-netlify-dev) example and read [Testing Netlify Function](https://glebbahmutov.com/blog/test-netlify/#testing-netlify-functions) section.\n\n### skipping tests\n\nIf you are testing the site before building it and want to skip testing the deployed URL\n\n```toml\n[[plugins]]\n  package = \"netlify-plugin-cypress\"\n  # do not test the deployed URL\n  [plugins.inputs]\n    enable = false\n  # test the local site\n  [plugins.inputs.preBuild]\n    enable = true\n```\n\n### parallelization\n\nRunning tests in parallel **is not supported** because Netlify plugin system runs on a single machine. Thus you can record the tests on Cypress Dashboard, but not run tests in parallel. If Netlify expands its build offering by allowing multiple build machines, we could take advantage of it and run tests in parallel.\n\n### HTML files\n\nWhen serving the built folder, we automatically serve `.html` files. For example, if your folder has the following structure:\n\n```\npublic/\n  index.html\n  pages/\n    about.html\n```\n\nThe `public` folder is served automatically and the following test successfully visits both the root and the `about.html` pages:\n\n```js\ncy.visit('/')\ncy.visit('/pages/about') // visits the about.html\n```\n\n## Example repos\n\nName | Description\n--- | ---\n[netlify-plugin-cypress-example](https://github.com/cypress-io/netlify-plugin-cypress-example) | Runs Cypress tests on Netlify and records their results to Cypress Dashboard\n[netlify-plugin-prebuild-example](https://github.com/cypress-io/netlify-plugin-prebuild-example) | Runs tests twice, first using the development version of the site, then after Netlify builds the production bundles, runs the tests again\n[cypress-example-kitchensink](https://github.com/cypress-io/cypress-example-kitchensink) | Runs only a subset of all tests before publishing the folder to Netlify\n[bahmutov/eleventyone](https://github.com/bahmutov/eleventyone) | Example used in [Test Sites Deployed To Netlify Using netlify-plugin-cypress](https://glebbahmutov.com/blog/test-netlify/) tutorial\n[gatsby-starter-portfolio-cara](https://github.com/bahmutov/gatsby-starter-portfolio-cara) | A Gatsby site example\n\n## Major upgrades\n\n### v1 to v2\n\n- The default browser has been switched to Chromium. If you want to use the built-in Electron use an explicit option [browser](#browser)\n- We have changed the default testing phase. In v1 the tests executed after building the site by default. In v2 the tests run against the deployed URL by default, and you need to enable the testing during `preBuild` or `postBuild` steps.\n\n## Debugging\n\nSet environment variable `DEBUG=netlify-plugin-cypress` to see the debug logs. To see even more information, set `DEBUG=netlify-plugin-cypress,netlify-plugin-cypress:verbose`\n\n**Warning:** be careful with verbose logging, since it can print all environment variables passed to the plugin, including tokens, API keys, and other secrets.\n\n## Common problems\n\n\u003cdetails\u003e\n  \u003csummary\u003eToo many progress messages while installing Cypress\u003c/summary\u003e\n  If you see A LOT of progress messages during \"npm install\" step, set an environment\n  variable during build \u003ccode\u003eCI = 1\u003c/code\u003e to remove them.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eCypress binary is installed on every build\u003c/summary\u003e\n  By default Cypress binary is installed in the home folder, see \u003ca href=\"\"\u003ecaching\u003c/a\u003e.\n  Netlify build does NOT cache this folder, but it DOES cache the local \"node_modules\" folder.\n  Tell Cypress to install its binary in the \"node_modules\" folder by setting build environment\n  variable \u003ccode\u003eCYPRESS_CACHE_FOLDER = \"./node_modules/CypressBinary\"\u003c/code\u003e.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eSeveral versions of Cypress are installed according to the build logs\u003c/summary\u003e\n  From the Netlify UI under Deploys, pick \"Trigger Deploy\" and select \"Clear cache and deploy site\". This should cleanly install new \"node_modules\" and remove old Cypress versions.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eTerm message warnings in the Cypress output\u003c/summary\u003e\n  If you see messages like \u003ccode\u003etput: No value for $TERM and no -T specified\u003c/code\u003e during\n  Cypress run, add an environment variable \u003ccode\u003eTERM = xterm\u003c/code\u003e.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eElectron browser crashes while running tests\u003c/summary\u003e\n  Switch to using Chromium browser that seems to be a bit more reliable. Use \u003ccode\u003ebrowser = \"chromium\"\u003c/code\u003e setting.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eYou want to skip Puppeteer download\u003c/summary\u003e\n  If you do not plan on using Chromium to run the tests, if you want to use the built-in Electron browser, you can save time by skipping the Puppeteer download. Set the environment variable \u003ccode\u003ePUPPETEER_SKIP_DOWNLOAD = 1\u003c/code\u003e on your CI.\n\u003c/details\u003e\n\n## License\n\nThis project is licensed under the terms of the [MIT license](LICENSE.md).\n\n## Contributing\n\nRead the [contributing guide](CONTRIBUTING.md)\n\n[renovate-badge]: https://img.shields.io/badge/renovate-app-blue.svg\n[renovate-app]: https://renovateapp.com/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcypress-io%2Fnetlify-plugin-cypress","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcypress-io%2Fnetlify-plugin-cypress","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcypress-io%2Fnetlify-plugin-cypress/lists"}