@koenvanbelle/cypress-soft-assertions 2.3.1 → 2.4.2

package/README.md

@@ -130,6 +130,23 @@ describe('Test Suite', () => {
 });
 ```
 
+### `soft_it.expectFailure`
+
+Use `soft_it.expectFailure()` for browser behavior specs that intentionally trigger
+soft failures but should still finish green overall.
+
+```typescript
+soft_it.expectFailure('captures a known soft failure without failing the spec', () => {
+  cy.get('#title').should('have.text', 'Wrong Title');
+  cy.get('#status').should('have.text', 'Ready');
+});
+```
+
+This mode still verifies that a final `SoftAssertionError` was produced. If the
+test completes without any soft failure, the test fails.
+
+`soft_it.expectFailure.only(...)` is also available.
+
 ## How it works
 
 1. `soft_it()` patches Chai's assertion mechanism for the duration of the test.
@@ -158,7 +175,7 @@ SOFT ASSERTION FAILURES (3 failed):
 - **Retriable assertions are retried**: `.should()` and `.and()` assertions are retried by Cypress before being captured as soft failures. Assertions that eventually pass are not reported.
 - **Non-assertion errors still stop execution**: Network errors, visit timeouts, and other command errors are captured as soft failures but may prevent subsequent commands from running.
 - **State resets between tests**: Each `soft_it()` test starts with a clean slate — failures from one test never leak into another.
-- **Timeout-aware retries**: The plugin respects Cypress's `defaultCommandTimeout` and per-command `{ timeout }` overrides. Retriable assertions (`.should()`, `.and()`) are retried for up to 75% of the effective timeout before being captured as soft failures. For slow applications, increase the timeout to give assertions more time to pass:
+- **Timeout-aware retries**: The plugin respects Cypress's `defaultCommandTimeout` and per-command `{ timeout }` overrides. Retriable assertions (`.should()`, `.and()`) are retried until just before the effective timeout expires, using `max(timeout - 100ms, timeout * 0.9)` as the swallow threshold. For slow applications, increase the timeout to give assertions more time to pass:
   ```typescript
   // Global: set in cypress.config.ts
   e2e: { defaultCommandTimeout: 10000 }

package/dist/index.d.ts

@@ -39,6 +39,14 @@ declare global {
          * Run only this test (like it.only)
          */
         function only(title: string, fn: Mocha.Func | Mocha.AsyncFunc): Mocha.Test;
+        /**
+         * Run a soft test that is expected to finish with a SoftAssertionError.
+         */
+        function expectFailure(title: string, fn: Mocha.Func | Mocha.AsyncFunc): Mocha.Test;
+        namespace expectFailure {
+            /** Run only this expected-failure soft test */
+            function only(title: string, fn: Mocha.Func | Mocha.AsyncFunc): Mocha.Test;
+        }
         /**
          * Skip this test (like it.skip)
          */

package/dist/index.js

@@ -20,6 +20,7 @@ let softAssertionErrors = [];
 let retryAssertionFailures = new Map();
 let retryFirstSeen = new Map();
 let isInSoftTest = false;
+let expectSoftFailureCurrentSoftTest = false;
 let activeFailHandler = null;
 let originalChaiAssert = null;
 // ---------------------------------------------------------------------------
@@ -208,19 +209,22 @@ function buildSoftAssertionError() {
 }
 function finalizeSoftTest() {
     isInSoftTest = false;
+    expectSoftFailureCurrentSoftTest = false;
     restoreAssertions();
     return buildSoftAssertionError();
 }
 function abortSoftTest() {
     isInSoftTest = false;
+    expectSoftFailureCurrentSoftTest = false;
     restoreAssertions();
     retryAssertionFailures.clear();
     retryFirstSeen.clear();
 }
-function createSoftIt(baseIt) {
+function createSoftIt(baseIt, options) {
     return function (title, fn) {
         return baseIt(title, function () {
             isInSoftTest = true;
+            expectSoftFailureCurrentSoftTest = Boolean(options === null || options === void 0 ? void 0 : options.expectFailure);
             softAssertionErrors = [];
             retryAssertionFailures.clear();
             retryFirstSeen.clear();
@@ -257,6 +261,15 @@ globalThis.soft_it = createSoftIt(it);
  * soft_it.only - Run only this soft test
  */
 globalThis.soft_it.only = createSoftIt(it.only);
+/**
+ * soft_it.expectFailure - Run a soft test that is expected to aggregate
+ * into a final SoftAssertionError without failing the enclosing behavior spec.
+ */
+globalThis.soft_it.expectFailure = createSoftIt(it, { expectFailure: true });
+/**
+ * soft_it.expectFailure.only - Run only this expected-failure soft test.
+ */
+globalThis.soft_it.expectFailure.only = createSoftIt(it.only, { expectFailure: true });
 /**
  * soft_it.skip - Skip this soft test
  */
@@ -265,29 +278,34 @@ globalThis.soft_it.skip = it.skip;
 // Registered at the root level so it applies to all suites.
 // For non-soft tests (isInSoftTest === false), this is a no-op.
 afterEach(function () {
-    var _a, _b, _c;
     if (!isInSoftTest)
         return;
+    const expectsSoftFailure = expectSoftFailureCurrentSoftTest;
     const finalError = finalizeSoftTest();
+    if (expectsSoftFailure) {
+        if (!finalError) {
+            throw new Error('Expected SoftAssertionError but soft_it.expectFailure test completed without one.');
+        }
+        return;
+    }
     if (finalError) {
         const test = this.currentTest;
-        const currentRetry = (_a = test === null || test === void 0 ? void 0 : test._currentRetry) !== null && _a !== void 0 ? _a : 0;
-        const maxRetries = (_b = test === null || test === void 0 ? void 0 : test._retries) !== null && _b !== void 0 ? _b : 0;
-        if (currentRetry < maxRetries) {
-            // Intermediate retry attempt — throw so Cypress triggers the next retry.
-            // Cypress's retry machinery intercepts hook failures during non-final
-            // attempts and does NOT abort the suite, so this is safe here.
-            throw finalError;
-        }
-        // Last (or only) attempt — use runner.fail() to mark the TEST as failed
-        // rather than the hook. Throwing from afterEach on the final attempt
-        // would skip remaining tests in the suite.
-        const runner = (_c = Cypress.mocha) === null || _c === void 0 ? void 0 : _c.getRunner();
-        if (runner && test) {
-            runner.fail(test, finalError);
-        }
-        else {
-            throw finalError;
+        if (test) {
+            test.err = finalError;
+            test._cypressTestStatusInfo = {
+                outerStatus: 'failed',
+                shouldAttemptsContinue: false,
+                attempts: typeof test.currentRetry === 'function' ? test.currentRetry() + 1 : 1,
+                strategy: 'detect-flake-and-pass-on-threshold',
+            };
+            const prevAttempts = Array.isArray(test.prevAttempts) ? test.prevAttempts : [];
+            if (!prevAttempts.some((attempt) => (attempt === null || attempt === void 0 ? void 0 : attempt.state) === 'failed' && (attempt === null || attempt === void 0 ? void 0 : attempt.err))) {
+                prevAttempts.unshift({
+                    state: 'failed',
+                    err: finalError,
+                });
+            }
+            test.prevAttempts = prevAttempts;
         }
     }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koenvanbelle/cypress-soft-assertions",
-  "version": "2.3.1",
+  "version": "2.4.2",
   "description": "A Cypress plugin that provides soft_it() for soft assertions - all assertions continue on failure and are reported together",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",