{
  "doc": {
    "id": "api/cypress-api/stop",
    "title": "Cypress.stop() | Cypress Documentation",
    "description": "Stop Cypress on failure or any other conditions",
    "section": "api",
    "source_path": "/llm/markdown/api/cypress-api/stop.md",
    "version": "e6988a974973e9090ce70406c38cb2b9e0eac9fa",
    "updated_at": "2026-05-15T15:50:22.536Z",
    "headings": [
      {
        "id": "api/cypress-api/stop#cypress-stop",
        "text": "Cypress.stop",
        "level": 1
      },
      {
        "id": "api/cypress-api/stop#syntax",
        "text": "Syntax",
        "level": 2
      },
      {
        "id": "api/cypress-api/stop#examples",
        "text": "Examples",
        "level": 2
      },
      {
        "id": "api/cypress-api/stop#stop-tests-when-a-test-fails",
        "text": "Stop tests when a test fails",
        "level": 3
      },
      {
        "id": "api/cypress-api/stop#abort-tests-when-a-condition-is-met",
        "text": "Abort tests when a condition is met",
        "level": 3
      },
      {
        "id": "api/cypress-api/stop#notes",
        "text": "Notes",
        "level": 2
      },
      {
        "id": "api/cypress-api/stop#cypress-run-vs-cypress-open-behavior",
        "text": "cypress run vs cypress open behavior",
        "level": 3
      },
      {
        "id": "api/cypress-api/stop#why-choose-auto-cancellation",
        "text": "Why choose Auto Cancellation?",
        "level": 3
      },
      {
        "id": "api/cypress-api/stop#see-also",
        "text": "See also",
        "level": 2
      }
    ]
  },
  "content": {
    "type": "root",
    "children": [
      {
        "type": "heading",
        "depth": 1,
        "children": [
          {
            "type": "text",
            "value": "Cypress.stop"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Stop the Cypress App on the current machine while tests are running. This can be useful for stopping test execution upon failures or other predefined conditions."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Auto Cancellation: If you're looking to automatically stop all tests across multiple machines when a test fails, consider using the "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/cloud/features/smart-orchestration/run-cancellation.md",
            "children": [
              {
                "type": "text",
                "value": "Auto Cancellation feature"
              }
            ]
          },
          {
            "type": "text",
            "value": " in Cypress Cloud."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Benefits: Stopping a test run on the first failure across parallelized machines will:"
          }
        ]
      },
      {
        "type": "list",
        "ordered": true,
        "start": 1,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Save time. Identify failures early and resolve issues faster."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Reduce CI costs. Cut down on unnecessary test execution, leading to significant savings for large test suites."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Free up CI resources. Prioritize critical tests and keep CI pipelines available for validating fixes."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Optimize future runs. With "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/cloud/features/smart-orchestration/spec-prioritization.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "Spec Prioritization"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " and Auto Cancellation, failed tests run first in the next attempt, stopping early if issues persist to maximize efficiency."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Syntax"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "Cypress.stop()"
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Examples"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Stop tests when a test fails"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "To ensure tests stop immediately after a failure across any spec file, add the following snippet to your `support/index.js` file:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "afterEach(function () {  if (this.currentTest.state === 'failed') {    Cypress.stop()    return  }})"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Abort tests when a condition is met"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "beforeEach(() => {  if (env !== 'expected-condition') {    cy.log('Stop tests - environment is not setup correctly')    Cypress.stop()    return  }})"
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Notes"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Calling `Cypress.stop()` will stop the execution of remaining tests, but any code after `Cypress.stop()` in the same container block (such as `beforeEach` or `afterEach`) will still run. To prevent additional logic from executing after `Cypress.stop()`, add a `return` statement immediately after it:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "if (someCondition) {  Cypress.stop()  return // Prevents further code execution in this block}"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "`cypress run` vs `cypress open` behavior"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Calling `Cypress.stop()` during `cypress run` will skip any remaining tests in the current specfile. If recording to Cypress Cloud, all screenshots, videos, and "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/cloud/features/test-replay.md",
            "children": [
              {
                "type": "text",
                "value": "Test Replay"
              }
            ]
          },
          {
            "type": "text",
            "value": " will still successfully upload."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Calling `Cypress.stop()` during `cypress open` will stop execution of the Cypress App, but remain open for inspection. The remaining tests will not run."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Why choose Auto Cancellation?"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/cloud/features/smart-orchestration/run-cancellation.md",
            "children": [
              {
                "type": "text",
                "value": "Auto Cancellation"
              }
            ]
          },
          {
            "type": "text",
            "value": " is available with Cypress Cloud's Business+ plan. It offers several advantages over `Cypress.stop` for stopping tests on failure:"
          }
        ]
      },
      {
        "type": "list",
        "ordered": true,
        "start": 1,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Scope of Cancellation: `Cypress.stop` halts only the current spec file, skipping remaining tests within it. Auto Cancellation, however, stops all tests across all machines and marks the entire run as cancelled in Cypress Cloud for better visibility."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Configurable Thresholds: Auto Cancellation allows you to define failure thresholds. `Cypress.stop` executes immediately when the specified condition is met."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Simplified Configuration: Auto Cancellation settings can be managed in Cypress Cloud, whereas `Cypress.stop` requires manual code changes."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Optimization with Spec Prioritization: Combined with "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/cloud/features/smart-orchestration/spec-prioritization.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "Spec Prioritization"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " (another Business+ feature), Auto Cancellation helps efficiently allocate resources by running previously failing specs first in a new run."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "To get started with Cypress Cloud, "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://cloud.cypress.io/signup",
            "children": [
              {
                "type": "text",
                "value": "sign up"
              }
            ]
          },
          {
            "type": "text",
            "value": " to start your 30 day free trial - including all premium Cypress Cloud features and plenty of test results to let you experience the power of Cypress Cloud!"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "See also"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/cloud/features/smart-orchestration/run-cancellation.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "Auto Cancellation"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/cypress-api/currenttest.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`Cypress.currentTest`"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/cypress-api/currentretry.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`Cypress.currentRetry`"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/cloud/features/smart-orchestration/load-balancing.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "Load Balancing"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/cloud/features/smart-orchestration/parallelization.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "Parallelization"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/cloud/features/smart-orchestration/spec-prioritization.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "Spec Prioritization"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "token_estimate": 685
}