How to Run Cypress Tests on Netlify

To run Cypress tests as part of a Netlify build, install the netlify-plugin-cypress package and configure it in the repository’s netlify.toml. Choose which deploy contexts should run the tests and whether they should record to Cypress Dashboard. If you prefer to keep testing separate from deployment, run Cypress in another CI pipeline and make the Netlify deploy job depend on its result.

These approaches answer different workflow needs: a Netlify Build Plugin runs in the deploy build, while a separate CI job can test before it invokes Netlify CLI to deploy prebuilt output. A Deploy Preview, branch deploy, and production deploy are distinct contexts, so decide explicitly which ones should be tested.

1. Choose where Cypress runs

Approach	Where tests run	Context control	Good fit when
Netlify Build Plugin	During the Netlify build	Configure plugin behavior by deploy context in `netlify.toml`	You want test results to be part of the Netlify build outcome and logs
Separate CI pipeline	In a CI job before or alongside deployment	Configure CI triggers and job dependencies in that provider	You already run tests in CI or want a distinct test and deploy workflow

There is no source-backed claim that one is universally faster, cheaper, or more reliable. Pick based on where you want the test status to live, what should trigger it, and whether tests must pass before deployment.

2. Prepare Cypress and the application server

Make sure Cypress can run locally and that the application it tests is available at the URL used by your specs. Cypress’s CI guidance says the basic setup is similar to running Cypress locally. The critical detail is server readiness: launching a server in the background and immediately running Cypress creates a race, because the server may not yet be accepting requests.

Install Cypress as a development dependency if the project does not already have it:

npm install cypress --save-dev

Run the test command with:

npx cypress run

When the tests need a locally started application, use a readiness check before Cypress starts. Cypress documents start-server-and-test and wait-on as options. The exact command depends on your app’s start script and test URL; for example, with a project script called start and an app listening at http://localhost:8888:

npx start-server-and-test start http://localhost:8888 "npx cypress run"

Use a URL that actually becomes reachable in your environment. Do not rely on an arbitrary sleep when a readiness check is available.

3. Run Cypress through a Netlify Build Plugin

Install the plugin

Netlify’s plugin guidance says an npm-published plugin must be added as a project dependency as well as configured in Netlify’s configuration. Add it as a development dependency with your package manager:

npm install netlify-plugin-cypress --save-dev

Configure the deploy contexts

Put this example in the netlify.toml at your site’s base directory. It follows Netlify’s documented example: recording is enabled in the global plugin configuration and disabled specifically for Deploy Previews. The more specific Deploy Preview entry overrides the global one.

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

  [plugins.inputs]
    record = true

[[context.deploy-preview.plugins]]
  package = "netlify-plugin-cypress"

  [context.deploy-preview.plugins.inputs]
    record = false

In this configuration, the plugin is configured globally, with a Deploy Preview override. Netlify’s example describes recording results and artifacts to Cypress Dashboard for production and branch deploys while turning recording off for Deploy Previews. That is an example choice, not a universal Netlify default.

Plugin inputs can vary with the installed plugin version. Check the package’s own documentation for the version you install before relying on any input or adding more settings. Keep Dashboard recording keys and other secrets in environment variables managed through Netlify’s UI, CLI, or API; do not commit secret values in netlify.toml.

Decide which deploys should be tested

Deploy Preview: associated with a pull or merge request. Netlify creates previews by default unless preview controls are changed.
Branch deploy: associated with a configured branch and uses that branch’s deploy URL. Branch deploys require setup.
Production deploy: the production context for the site.

Before adding context overrides, decide which of these should run Cypress and which should record to Dashboard. A preview can run tests with recording disabled, as in the example, while branch and production builds record. If you want different behavior, update the context-specific configuration and verify the plugin’s supported inputs.

Trigger and inspect a build

Commit the dependency and netlify.toml changes.
Push the branch or open a pull request that triggers the deploy context you want to check.
Open the Netlify deploy log and confirm the plugin runs in the expected context.
Review the Cypress output and, where recording is enabled and configured, the Dashboard results and artifacts.

4. Run Cypress in a separate CI pipeline

A separate CI job can install project dependencies, start the app, wait for it to respond, and then run Cypress. If the tests must gate publication, make the deployment job depend on the successful test job. Netlify documents manual deploys as a common pattern when using another CI tool: the external pipeline can build and test, then use Netlify CLI to deploy the prebuilt output.

The core test commands are:

npm install
npx cypress run

If Cypress needs a local server, replace the direct test command with a readiness-gated command appropriate to your scripts and CI environment, such as:

npx start-server-and-test start http://localhost:8888 "npx cypress run"

Configure the CI workflow’s trigger rules to cover the desired pull requests, branches, or production changes. Keep Dashboard recording configuration and keys in the CI provider’s secret environment-variable store. Whether deployment waits for tests is a pipeline dependency decision; make it explicit rather than assuming that running both jobs means tests gate the deploy.

5. Verify Netlify build behavior locally

Use Netlify CLI from the root of the linked repository to reproduce the Netlify build, including configured Build Plugins:

netlify build

To apply Deploy Preview settings locally:

netlify build --context deploy-preview

Match your local Node.js version to the version configured for the Netlify build. A mismatch can produce different behavior or errors. Local CLI verification helps check configuration, but also inspect a real deploy log to confirm the context and environment used by the hosted build.

6. Troubleshoot common failures

Symptom	Likely cause	What to check or change
Cypress cannot visit the app	The server is not ready when Cypress starts, or the configured URL is wrong	Confirm the app’s start command and URL. Gate Cypress on a readiness check with `start-server-and-test`, `wait-on`, or another suitable method instead of starting the server and immediately invoking Cypress.
The plugin does not run in a build	The package is missing from project dependencies, the configuration file is misplaced, or the build is using an unexpected base directory	Confirm the npm plugin is installed as a project dependency and that `netlify.toml` is in the site’s base directory. Inspect the deploy log and run `netlify build` locally.
Deploy Preview behavior differs from production	The preview uses a separate deploy context and may have a more specific plugin configuration	Confirm the deploy is a Deploy Preview, branch deploy, or production deploy. Check the matching context section in `netlify.toml` and reproduce with `netlify build --context deploy-preview` when appropriate.
Dashboard recording is missing in a preview	The example configuration explicitly sets `record = false` for Deploy Previews	Check the context-specific inputs. If previews should record, adjust the setting according to the installed plugin version and provide required secrets through environment variables.
Recording fails or a key appears in a config diff	A required key may be missing, or a sensitive value may have been committed in `netlify.toml`	Store the key as a managed environment variable in Netlify or the CI provider. Remove committed secrets and rotate exposed credentials as appropriate.
Local build differs from Netlify	Local Node.js version or deploy context does not match the hosted build	Match the configured Node.js version and use Netlify CLI with the relevant context.
Plugin rejects an input or configuration	The setting may not exist in the installed plugin version	Check the package documentation for that exact version and remove or correct unsupported inputs.

7. Performance, reliability, and cost considerations

The reviewed documentation does not provide comparative measurements for build time, reliability, or cost between the plugin and separate CI patterns. Plan around your actual workflow: each test run executes as part of its configured job or build, and tests that depend on a server need a readiness check. Use context rules to avoid running or recording tests in deploys where they are not needed, while retaining the checks required to gate releases.

For reliability, make the test process’s start command, target URL, deploy context, and job dependency explicit. Check hosted deploy logs and local Netlify CLI output when diagnosing differences. For Dashboard recording, choose the contexts that should record and keep credentials out of committed configuration.

Or skip the browser setup

If you need screenshots of pages as part of debugging or documentation around a deploy, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF, without setting up a browser runner for that capture. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners are accepted and removed before capture; more than 60 known consent platforms, newsletter popups, and chat widgets can be removed, and each step can be turned off.
Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Responses identify the page verdict and billing status in headers.
An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
The free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots. Every feature is available on every plan.

8. Frequently asked questions

How do I stop a Netlify deploy when Cypress tests fail?

When Cypress runs as a Build Plugin, its result is part of the Netlify build workflow. For a separate CI pipeline, configure the deployment job to depend on the test job’s success if tests must gate publishing.

Can I run Cypress on a Netlify Deploy Preview?

Yes. Configure the plugin for the Deploy Preview context in netlify.toml, or configure your external CI workflow to test pull requests against the intended app URL. Deploy Previews are distinct from branch and production deploys.

Does the Deploy Preview example record to Cypress Dashboard?

No. The example above sets record = false for Deploy Previews and leaves recording enabled in the global configuration. Change that context-specific choice if previews should record, using inputs supported by your installed plugin version.

Can I run the Netlify build locally with preview settings?

Yes. Run netlify build --context deploy-preview from the repository. Use the same Node.js version configured for the hosted Netlify build for a closer match.