@koenvanbelle/cypress-soft-assertions 1.0.9 → 2.0.1

package/README.md

@@ -1,130 +1,90 @@
 # Cypress Soft Assertions
 
-A Cypress plugin that provides `soft_it()` - a drop-in replacement for `it()` that makes all assertions soft. Assertions continue execution on failure, and all failures are aggregated and reported at the end of the test.
+A Cypress plugin that provides `soft_it()` — a drop-in replacement for `it()` that makes all assertions soft. Assertions continue execution on failure, and all failures are aggregated and reported together at the end of the test.
 
-## Overview
+## Why?
 
 Standard Cypress assertions stop test execution at the first failure. With `soft_it()`:
 
-- All assertions run even if some fail
-- See all failures at once - no need to fix one issue and rerun to find the next
-- Drop-in replacement - just change `it()` to `soft_it()`
-- No manual tracking - failures automatically aggregated and reported
+- **All assertions run** even if some fail
+- **See all failures at once** — no need to fix one issue and rerun to find the next
+- **Drop-in replacement** — just change `it()` to `soft_it()`
+- **No manual tracking** — failures are automatically aggregated and reported
 
 ## Installation
 
-Install the plugin as a development dependency:
-
 ```bash
 npm install @koenvanbelle/cypress-soft-assertions --save-dev
 ```
 
-or using Yarn:
-
-```bash
-yarn add @koenvanbelle/cypress-soft-assertions --dev
-```
-
-## Integration
-
-### Step 1: Import the Plugin
+## Setup
 
-Add the import to your Cypress support file. This registers the `soft_it()` function globally.
+### 1. Import the plugin
 
-**For TypeScript projects** - Edit `cypress/support/e2e.ts` (or `cypress/support/commands.ts`):
+Add the import to your Cypress support file (`cypress/support/e2e.ts` or `cypress/support/e2e.js`):
 
 ```typescript
 import '@koenvanbelle/cypress-soft-assertions';
 ```
 
-**For JavaScript projects** - Edit `cypress/support/e2e.js` (or `cypress/support/commands.js`):
+Or for JavaScript:
 
 ```javascript
 require('@koenvanbelle/cypress-soft-assertions');
 ```
 
-### Step 2: Add Type Definitions (TypeScript only)
+### 2. Add type definitions (TypeScript only)
 
-If you're using TypeScript, ensure your `tsconfig.json` includes the plugin types:
+Add a reference directive at the top of your test files:
+
+```typescript
+/// <reference types="@koenvanbelle/cypress-soft-assertions" />
+```
+
+Or include the types in your `tsconfig.json`:
 
 ```json
 {
   "compilerOptions": {
-    "types": ["cypress", "cypress-soft-assertions"]
+    "types": ["cypress", "@koenvanbelle/cypress-soft-assertions"]
   }
 }
 ```
 
-Alternatively, add a reference directive at the top of your test files:
-
-```typescript
-/// <reference types="cypress-soft-assertions" />
-```
-
-### Step 3: Use in Tests
+## Usage
 
 Replace `it()` with `soft_it()` in any test where you want soft assertion behavior:
 
 ```typescript
 describe('Product Page', () => {
   soft_it('validates all product details', () => {
-    cy.visit('https://example.com/product/123');
-    
-    // All these assertions will run even if some fail
+    cy.visit('/product/123');
+
+    // All assertions run even if some fail
     cy.get('.product-name').should('have.text', 'Awesome Product');
     cy.get('.product-price').should('have.text', '$99.99');
     cy.get('.stock-status').should('have.text', 'In Stock');
-    Supported Assertion Types
+    cy.get('.rating').should('have.attr', 'data-stars', '5');
+  });
+});
+```
+
+### Supported assertion styles
 
 `soft_it()` works with all Cypress assertion styles:
 
 ```typescript
 soft_it('supports all assertion types', () => {
-  cy.visit('/page');
-  
   // .should() assertions
   cy.get('.title').should('be.visible');
   cy.get('.title').should('have.text', 'Welcome');
-  
-  // .should() with callback
-  cy.get('.items').should(($items) => {
-    expect($items).to.have.length(5);
-    expect($items.first()).to.contain('Item 1');
-  });
-  
+
   // expect() in .then()
-  cy.get('.price').then($el => {
+  cy.get('.price').then(($el) => {
     expect($el.text()).to.equal('$99.99');
   });
-  
-  // Chained assertions
-  cy.get('.button')
-    .should('be.visible')
-    .and('have.class', 'active')
-    .and('contain', 'Submit');
-});
-```
 
-### Mixing soft_it() with Regular it()
-
-You can use both `soft_it()` and regular `it()` in the same test suite:
-
-```typescript
-describe('User Profile', () => {
-  // Regular test - stops on first failure
-  it('loads the page', () => {
-    cy.visit('/profile');
-    cy.get('h1').should('be.visible');
-  });
-  
-  // Soft test - all assertions run
-  soft_it('validates profile fields', () => {
-    cy.get('.username').should('have.text', 'john_doe');
-    cy.get('.email').should('have.text', 'john@example.com');
-    cy.get('.member-since').should('contain', '2023');
-    cy.get('.posts-count').should('have.text', '42');
-  
-  // Chained assertions
+  // Chained assertions with .and()
   cy.get('.button')
     .should('be.visible')
     .and('have.class', 'active')
@@ -132,158 +92,82 @@ describe('User Profile', () => {
 });
 ```
 
-### Multiple Tests
+### Mixing `soft_it()` with regular `it()`
 
-You can mix `soft_it()` with regular `it()` tests:
+You can use both in the same suite. Regular `it()` tests are unaffected:
 
 ```typescript
 describe('User Profile', () => {
-  // Regular test - stops on first failure
+  // Regular test — stops on first failure
   it('loads the page', () => {
     cy.visit('/profile');
     cy.get('h1').should('be.visible');
   });
-  
-  // Soft test - all assertions run
+
+  // Soft test — all assertions run
   soft_it('validates profile fields', () => {
     cy.get('.username').should('have.text', 'john_doe');
     cy.get('.email').should('have.text', 'john@example.com');
     cy.get('.member-since').should('contain', '2023');
     cy.get('.posts-count').should('have.text', '42');
   });
-  
-  // Another soft test
-  soft_it('validates account settings', () => {
-    cy.get('[data-test=notifications]').should('be.checked');
-    cy.get('[data-test=newsletter]').should('not.be.checked');
-    cy.get('[data-test=theme]').should('have.value', 'dark');
-  });
 });
 ```
 
-### Using soft_it.only and soft_it.skip
+### `soft_it.only` and `soft_it.skip`
 
-Just like regular `it()`:
+Works just like regular `it()`:
 
 ```typescript
 describe('Test Suite', () => {
-  // Run only this test
-  soft_it.only('validates important fields', () => {
+  soft_it.only('run only this test', () => {
     cy.get('.field1').should('exist');
-```
-
-The plugin supports `.only` and `.skip` modifiers just like regular `it()`:
-
-```typescript
-describe('Test Suite', () => {
-  // Run only this test
-  soft_it.only('validates important fields', () => {
-    cy.get('.field1').should('exist');
-    cy.get('.field2').should('exist');
   });
-  
-  // Skip this test
-  soft_it.skip('validates optional fields', () => {
+
+  soft_it.skip('skip this test', () => {
     cy.get('.optional').should('exist');
   });
 });
 ```
 
-## How It Works
-
-`soft_it()` intercepts Chai assertions within the test block and captures failures instead of throwing them immediately. At the end of the test, all captured failures are aggregated and reported in a single error message.
-
-The plugin works with:
-- `.should()` assertions
-- `expect()` assertions
-- `assert()` assertions
-- Custom Cypress commands that use assertions
-- Assertion chains (`.and()`)
-
-## Important Notes
-
-### When Assertions Are Reported
+## How it works
 
-Failures are reported at the end of the test after all Cypress commands complete. The test will be marked as failed, and all assertion failures will be listed together.
+1. `soft_it()` patches Chai's assertion mechanism for the duration of the test.
+2. When an assertion fails inside a retriable command (`.should()`, `.and()`), the error is staged under a stable token and rethrown so Cypress can retry. If the assertion eventually passes, the staged failure is cleared.
+3. After a bounded number of retries, the assertion is swallowed and the failure is recorded so the test can continue to the next command.
+4. Non-retriable assertion failures (`expect()` in `.then()` callbacks) are captured immediately.
+5. Command-level failures (e.g. element-not-found timeouts) are caught by a `Cypress.on('fail')` handler and recorded as soft failures.
+6. At the end of the test, all recorded failures are aggregated into a single `SoftAssertionError`.
 
-### Regular vs Soft Tests
+## Error output
 
-- **Regular `it()`**: Stops at first assertion failure
-- **Soft `soft_it()`**: Runs all assertions, reports all failures at the end
+When soft assertions fail, you get a single formatted report:
 
-### Non-Assertion Errors
-
-Non-assertion errors (network errors, timeouts, command errors) will still stop test execution immediately. `soft_it()` only makes assertions soft.
-
-```typescript
-soft_it('example', () => {
-  cy.visit('/page');  // If this fails (timeout, 404), test stops immediately
-  cy.get('.missing').should('exist');  // This assertion is soft
-  cy.get('.other').should('exist');    // This assertion is soft
-});
 ```
-
-## Best Practices
-
-### Use for Validation-Heavy Tests
-
-`soft_it()` is ideal for tests that validate many fields:
-
-```typescript
-soft_it('validates user profile completeness', () => {
-  cy.get('.name').should('not.be.empty');
-  cy.get('.email').should('match', /@/);
-  cy.get('.phone').should('have.length.at.least', 10);
-  cy.get('.address').should('not.be.empty');
-  cy.get('.city').should('not.be.empty');
-  cy.get('.avatar').should('be.visible');
-});
-```
-
-### Use Regular it() for Critical Setup
-
-Use regular `it()` for setup steps that must succeed:
-
-```typescript
-it('logs in successfully', () => {
-  cy.visit('/login');
-  cy.get('#username').type('user');
-  cy.get('#password').type('pass');
-  cy.get('button[type=submit]').click();
-  cy.url().should('include', '/dashboard');
-});
-
-soft_it('validates dashboard widgets', () => {
-  cy.get('.widget-1').should('be.visible');
-  cy.get('.widget-2').should('be.visible');
-  cy.get('.widget-3').should('be.visible');
-});
+================================================================================
+SOFT ASSERTION FAILURES (3 failed):
+================================================================================
+  1. expected '<h1.title>' to have text 'Wrong Title', but the text was 'Products'
+  2. expected '<div.count>' to have text '999', but the text was '42'
+  3. expected '<div.missing>' to exist in the DOM
+================================================================================
 ```
 
-### Group Related Validations
-
-Use `soft_it()` to group validations of related elements:
+## Important notes
 
-```typescript
-soft_it('validates navigation menu', () => {
-  cy.get('nav a').eq(0).should('have.text', 'Home');
-  cy.get('nav a').eq(1).should('have.text', 'Products');
-  cy.get('nav a').eq(2).should('have.text', 'About');
-  cy.get('nav a').eq(3).should('have.text', 'Contact');
-});
-```
+- **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:
+  ```typescript
+  // Global: set in cypress.config.ts
+  e2e: { defaultCommandTimeout: 10000 }
 
-## Error Output Format
+  // Per-command: override on individual commands
+  cy.get('.slow-element', { timeout: 15000 }).should('be.visible');
+  ```
+- **Cypress Studio / Command Log**: When a soft assertion fails definitively, the plugin swallows the error so the test can continue. Cypress treats the command as resolved, which means it may not appear as a failed step in the Cypress Studio command log or may look like the assertion was skipped. The assertions **do** execute and failures **are** captured — they just don't show visually in the command log. Check the final `SoftAssertionError` report for the complete list of failures.
 
-When soft assertions fail, you receive a formatted error report:
+## License
 
-```
-================================================================================
-SOFT ASSERTION FAILURES (4 failed):
-================================================================================
-  1. expected '<input#email>' to have value 'test@example.com', but the value was 'wrong@example.com'
-  2. expected '<div.order-total>' to contain '$99.99', but it contained '$89.99'
-  3. expected '<div.tax>' to contain '$8.75', but it contained '$7.50'
-  4. expected '<div.grand-total>' to contain '$113.74', but it contained '$102.49'
-================================================================================
-```
+MIT

package/dist/index.js

@@ -8,114 +8,166 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 let softAssertionErrors = [];
+let retryAssertionFailures = new Map();
+let retryFirstSeen = new Map();
 let isInSoftTest = false;
 let activeFailHandler = null;
-let activeSoftTestTitle = null;
-let finalizerInstalled = false;
-/**
- * Track a soft assertion failure so it can be reported at test end.
- */
+let originalChaiAssert = null;
+function getEffectiveTimeout() {
+    var _a;
+    try {
+        const current = cy.state('current');
+        const perCommand = (_a = current === null || current === void 0 ? void 0 : current.get) === null || _a === void 0 ? void 0 : _a.call(current, 'timeout');
+        if (typeof perCommand === 'number')
+            return perCommand;
+    }
+    catch ( /* ignore */_b) { /* ignore */ }
+    try {
+        return Cypress.config('defaultCommandTimeout') || 4000;
+    }
+    catch (_c) {
+        return 4000;
+    }
+}
 function captureSoftAssertion(error) {
     const message = (error === null || error === void 0 ? void 0 : error.message) || String(error);
     const stack = error === null || error === void 0 ? void 0 : error.stack;
     const lastEntry = softAssertionErrors[softAssertionErrors.length - 1];
-    if (lastEntry && lastEntry.message === message && lastEntry.stack === stack) {
-        return;
+    if (!lastEntry || lastEntry.message !== message || lastEntry.stack !== stack) {
+        softAssertionErrors.push({ message, stack });
     }
-    softAssertionErrors.push({
-        message,
-        stack
-    });
 }
-function getCurrentCommandName() {
-    var _a;
-    const state = cy === null || cy === void 0 ? void 0 : cy.state;
-    if (typeof state !== 'function') {
-        return '';
+function getSubjectKey(assertionContext) {
+    const obj = assertionContext === null || assertionContext === void 0 ? void 0 : assertionContext._obj;
+    const first = Array.isArray(obj) ? obj[0] : obj === null || obj === void 0 ? void 0 : obj[0];
+    if (first && typeof first.id === 'string' && first.id.length > 0) {
+        return `#${first.id}`;
     }
-    const current = state('current');
-    if (!current) {
-        return '';
+    const selector = obj === null || obj === void 0 ? void 0 : obj.selector;
+    if (typeof selector === 'string' && selector.length > 0) {
+        return selector;
+    }
+    return '';
+}
+function toTokenPart(value) {
+    if (value === undefined)
+        return 'undefined';
+    if (value === null)
+        return 'null';
+    const kind = typeof value;
+    if (kind === 'string' || kind === 'number' || kind === 'boolean')
+        return String(value);
+    try {
+        return JSON.stringify(value);
     }
-    if (typeof current.get === 'function') {
-        return String(current.get('name') || '');
+    catch (_a) {
+        return String(value);
     }
-    return String(current.name || ((_a = current.attributes) === null || _a === void 0 ? void 0 : _a.name) || '');
 }
-function isRetryTimeoutError(error) {
-    const message = String((error === null || error === void 0 ? void 0 : error.message) || '');
-    return /Timed out retrying after/i.test(message);
+function getAssertionToken(assertionContext, args) {
+    const subjectKey = getSubjectKey(assertionContext);
+    if (!subjectKey)
+        return '';
+    const expected = args === null || args === void 0 ? void 0 : args[3];
+    return `${subjectKey}|${toTokenPart(expected)}`;
 }
-function isRetriableAssertionCommand(commandName) {
-    return commandName === 'should' || commandName === 'and';
+function patchChaiAssertions() {
+    var _a;
+    const assertionProto = (_a = chai === null || chai === void 0 ? void 0 : chai.Assertion) === null || _a === void 0 ? void 0 : _a.prototype;
+    if (!assertionProto || typeof assertionProto.assert !== 'function')
+        return;
+    if (!originalChaiAssert)
+        originalChaiAssert = assertionProto.assert;
+    if (assertionProto.assert === patchedAssertionAssert)
+        return;
+    assertionProto.assert = patchedAssertionAssert;
+}
+function patchedAssertionAssert(...args) {
+    if (!originalChaiAssert)
+        return;
+    try {
+        const result = originalChaiAssert.apply(this, args);
+        // Assertion passed — clear any staged failure for this token.
+        if (isInSoftTest) {
+            const token = getAssertionToken(this, args);
+            if (token) {
+                retryAssertionFailures.delete(token);
+                retryFirstSeen.delete(token);
+            }
+        }
+        return result;
+    }
+    catch (error) {
+        if (!isInSoftTest)
+            throw error;
+        const token = getAssertionToken(this, args);
+        if (token) {
+            // Stage the failure under a stable token so it can be cleared if
+            // a later retry succeeds.
+            retryAssertionFailures.set(token, {
+                message: String((error === null || error === void 0 ? void 0 : error.message) || error),
+                stack: error === null || error === void 0 ? void 0 : error.stack,
+            });
+            const now = Date.now();
+            if (!retryFirstSeen.has(token)) {
+                retryFirstSeen.set(token, now);
+            }
+            const elapsed = now - retryFirstSeen.get(token);
+            const timeout = getEffectiveTimeout();
+            // Use 75% of the timeout as the retry window. This ensures the plugin
+            // swallows the error before Cypress's own timeout fires (which would
+            // route through the fail handler and prevent finalization).
+            if (elapsed < timeout * 0.75) {
+                // Still within the command timeout window — rethrow to let Cypress
+                // retry the assertion. If it eventually passes, the token is cleared.
+                throw error;
+            }
+            // Past the timeout budget — swallow so the command "succeeds" and
+            // Cypress moves on to the next queued command. The token stays in the
+            // Map and will be promoted to softAssertionErrors at finalization.
+            return;
+        }
+        // No identifiable subject — capture directly (e.g. bare expect() calls
+        // in .then() callbacks).
+        captureSoftAssertion(error);
+    }
 }
-/**
- * Intercept Cypress failures and make assertion failures soft in soft_it() tests.
- */
 function setupSoftAssertions() {
+    patchChaiAssertions();
     if (!activeFailHandler) {
         activeFailHandler = (error) => {
-            if (!isInSoftTest) {
+            if (!isInSoftTest)
                 throw error;
-            }
-            const commandName = getCurrentCommandName();
-            if (isRetriableAssertionCommand(commandName) && !isRetryTimeoutError(error)) {
-                // Let Cypress continue polling/retrying for retriable assertions.
+            // Final aggregated error must propagate to fail the test.
+            if (String((error === null || error === void 0 ? void 0 : error.name) || '') === 'SoftAssertionError')
                 throw error;
-            }
+            // Non-assertion command failures (e.g. element not found timeouts)
+            // are captured as soft failures.
             captureSoftAssertion(error);
             return false;
         };
         Cypress.on('fail', activeFailHandler);
     }
 }
-function getTestTitle(test) {
-    if (test && typeof test.fullTitle === 'function') {
-        return test.fullTitle();
-    }
-    return String((test === null || test === void 0 ? void 0 : test.title) || '');
-}
-function installFinalizer() {
-    if (finalizerInstalled) {
-        return;
-    }
-    afterEach(function () {
-        var _a, _b;
-        if (!isInSoftTest) {
-            return;
-        }
-        const currentTest = (this.currentTest || this.test);
-        if (!currentTest || getTestTitle(currentTest) !== activeSoftTestTitle) {
-            return;
-        }
-        const finalError = finalizeSoftTest();
-        if (!finalError) {
-            return;
-        }
-        currentTest.err = finalError;
-        currentTest.state = 'failed';
-        const runner = (_b = (_a = Cypress === null || Cypress === void 0 ? void 0 : Cypress.mocha) === null || _a === void 0 ? void 0 : _a.getRunner) === null || _b === void 0 ? void 0 : _b.call(_a);
-        if (runner && typeof runner.fail === 'function') {
-            runner.fail(currentTest, finalError);
-            return;
-        }
-        throw finalError;
-    });
-    finalizerInstalled = true;
-}
-/**
- * Restore original Chai assertion behavior.
- */
 function restoreAssertions() {
+    var _a;
     if (activeFailHandler) {
         Cypress.off('fail', activeFailHandler);
         activeFailHandler = null;
     }
+    if (originalChaiAssert) {
+        const assertionProto = (_a = chai === null || chai === void 0 ? void 0 : chai.Assertion) === null || _a === void 0 ? void 0 : _a.prototype;
+        if (assertionProto)
+            assertionProto.assert = originalChaiAssert;
+    }
 }
-/**
- * Report all collected soft assertion failures
- */
 function buildSoftAssertionError() {
+    // Promote any remaining retry-tracked failures.
+    for (const entry of retryAssertionFailures.values()) {
+        captureSoftAssertion(entry);
+    }
+    retryAssertionFailures.clear();
+    retryFirstSeen.clear();
     if (softAssertionErrors.length > 0) {
         const errorMessages = softAssertionErrors
             .map((entry, index) => `  ${index + 1}. ${entry.message}`)
@@ -127,9 +179,8 @@ function buildSoftAssertionError() {
             '='.repeat(80),
             errorMessages,
             '='.repeat(80),
-            ''
+            '',
         ].join('\n');
-        // Clear errors
         softAssertionErrors = [];
         const error = new Error(finalMessage);
         error.name = 'SoftAssertionError';
@@ -137,49 +188,50 @@ function buildSoftAssertionError() {
     }
     return null;
 }
-/**
- * Cleanup soft assertion state and report accumulated failures.
- */
 function finalizeSoftTest() {
     isInSoftTest = false;
     restoreAssertions();
-    activeSoftTestTitle = null;
     return buildSoftAssertionError();
 }
-/**
- * Cleanup soft assertion state without reporting (used on hard failures).
- */
 function abortSoftTest() {
     isInSoftTest = false;
     restoreAssertions();
-    activeSoftTestTitle = null;
+    retryAssertionFailures.clear();
+    retryFirstSeen.clear();
 }
-/**
- * Create a soft_it variant from a Mocha it function.
- */
 function createSoftIt(baseIt) {
-    installFinalizer();
     return function (title, fn) {
         return baseIt(title, function () {
             isInSoftTest = true;
             softAssertionErrors = [];
-            activeSoftTestTitle = getTestTitle(this.currentTest || this.test);
+            retryAssertionFailures.clear();
+            retryFirstSeen.clear();
             setupSoftAssertions();
+            let result;
             try {
-                const result = fn.call(this);
-                if (result && typeof result.then === 'function') {
-                    return result
-                        .catch((error) => {
-                        abortSoftTest();
-                        throw error;
-                    });
-                }
-                return result;
+                result = fn.call(this);
             }
             catch (error) {
                 abortSoftTest();
                 throw error;
             }
+            // Finalize from inside the test chain (not from hooks) so Cypress counts
+            // the failure on the test itself.
+            return cy.then(() => {
+                return Cypress.Promise.resolve(result)
+                    .catch((error) => {
+                    if (isInSoftTest) {
+                        abortSoftTest();
+                    }
+                    throw error;
+                })
+                    .then(() => {
+                    const finalError = finalizeSoftTest();
+                    if (finalError) {
+                        throw finalError;
+                    }
+                });
+            });
         });
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koenvanbelle/cypress-soft-assertions",
-  "version": "1.0.9",
+  "version": "2.0.1",
   "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",