docs: Document Cypress.stop

docs/api/cypress-api/stop.mdx

@@ -0,0 +1,82 @@
+---
+title: 'Cypress.stop() | Cypress Documentation'
+description: Stop Cypress on failure or any other conditions
+sidebar_label: stop
+---
+
+<ProductHeading product="app" />
+
+# Cypress.stop
+
+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.
+
+:::tip
+
+**Auto Cancellation**: If you're looking to automatically stop _all tests_ across _multiple machines_ when a test fails, consider using the [Auto Cancellation feature](/cloud/features/smart-orchestration/run-cancellation) in Cypress Cloud.
+
+<AutoCancellationBenefits />
+
+:::
+
+## Syntax
+
+```javascript
+Cypress.stop()
+```
+
+## Examples
+
+### Stop tests when a test fails
+
+To ensure tests stop immediately after a failure across any spec file, add the following snippet to your `support/index.js` file:
+
+```javascript
+afterEach(function () {
+  if (this.currentTest.state === 'failed') {
+    Cypress.stop()
+  }
+})
+```
+
+### Abort tests when a condition is met
+
+```javascript
+beforeEach(() => {
+  if (env !== 'expected-condition') {
+    cy.log('Stop tests - environment is not setup correctly')
+    Cypress.stop()
+  }
+})
+```
+
+## Notes
+
+### `cypress run` vs `cypress open` behavior
+
+Calling `Cypress.stop()` during `cypress run` will skip any remaining tests in the current specfile. If recording to Cypress Cloud, all screenshots, videos, and [Test Replay](/cloud/features/test-replay) will still successfully upload.
+
+![Terminal output of a Cypress run displays running an `example.cy.ts` file with 1 test passing in green and 1 test passing in red with an error message. The Results table shows 4 tests, 1 passing, 1 failing, and 2 skipped.](/img/api/stop/cypress-stop-during-run-mode.png)
+
+Calling `Cypress.stop()` during `cypress open` will stop execution of the Cypress App, but remain open for inspection. The remaining tests will not run.
+
+![Cypress App shows an example.cy.ts file as running with 1 passing test collapsed, 1 failing test expanded with the assertion error and the remaining tests having not run, showing square neutral icons for their status.](/img/api/stop/cypress-stop-during-open-mode.png)
+
+### Why choose Auto Cancellation?
+
+[Auto Cancellation](/cloud/features/smart-orchestration/run-cancellation) is available with Cypress Cloud's Business+ plan. It offers several advantages over `Cypress.stop` for stopping tests on **failure**:
+
+1. **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.
+2. **Configurable Thresholds:** Auto Cancellation allows you to define failure thresholds. `Cypress.stop` executes immediately when the specified condition is met.
+3. **Simplified Configuration**: Auto Cancellation settings can be managed in Cypress Cloud, whereas `Cypress.stop` requires manual code changes.
+4. **Optimization with Spec Prioritization**: Combined with [Spec Prioritization](/cloud/features/smart-orchestration/spec-prioritization) (another Business+ feature), Auto Cancellation helps efficiently allocate resources by running previously failing specs first in a new run.
+
+<CloudFreePlan />
+
+## See also
+
+- [Auto Cancellation](/cloud/features/smart-orchestration/run-cancellation)
+- [`Cypress.currentTest`](/api/cypress-api/currenttest)
+- [`Cypress.currentRetry`](/api/cypress-api/currentretry)
+- [Load Balancing](/cloud/features/smart-orchestration/load-balancing)
+- [Parallelization](/cloud/features/smart-orchestration/parallelization)
+- [Spec Prioritization](/cloud/features/smart-orchestration/spec-prioritization)

docs/cloud/features/smart-orchestration/run-cancellation.mdx

@@ -26,13 +26,7 @@ changes. When Auto Cancellation is enabled, once the number of failed tests goes
 over a preset threshold, the entire test run is canceled. Note that any
 in-progress specs will continue to run to completion.
 
-<Icon name="check-circle" color="green" /> **Benefits:** Canceling an **entire**
-test run, even if parallelized, upon the first test failure will:
-
-1. **Save time**. Resolve test outcomes faster.
-2. **Reduce CI costs**. These cost savings can be significant for large test
-   suites.
-3. **Free-up CI resources** for validating fixes, and helping other users.
+<AutoCancellationBenefits />
 
 ### Activate Auto Cancellation in Cypress Cloud
 

docs/partials/_auto-cancellation-benefits.mdx

@@ -0,0 +1,7 @@
+<Icon name="check-circle" color="green" /> **Benefits:** Stopping a test run on the
+first failure across parallelized machines will:
+
+1. **Save time.** Identify failures early and resolve issues faster.
+2. **Reduce CI costs.** Cut down on unnecessary test execution, leading to significant savings for large test suites.
+3. **Free up CI resources.** Prioritize critical tests and keep CI pipelines available for validating fixes.
+4. **Optimize future runs.** With **[Spec Prioritization](/cloud/features/smart-orchestration/spec-prioritization)** and **Auto Cancellation**, failed tests run first in the next attempt, stopping early if issues persist to maximize efficiency.

src/theme/MDXComponents.js

@@ -2,6 +2,7 @@
 import MDXComponents from "@theme-original/MDXComponents";
 import AnatomyOfAnError from "@site/docs/partials/_anatomy-of-an-error.mdx";
 import AccessibilityAddon from "@site/docs/partials/_accessibility-addon.mdx";
+import AutoCancellationBenefits from "@site/docs/partials/_auto-cancellation-benefits.mdx";
 import Badge from "@site/src/components/badge";
 import Btn from "@site/src/components/button";
 import ComponentOnlyBadge from "@site/src/components/component-only-badge";
@@ -160,6 +161,7 @@ export default {
   ...MDXComponents,
   AnatomyOfAnError,
   AccessibilityAddon,
+  AutoCancellationBenefits,
   Badge,
   Btn,
   ComponentOnlyBadge,