@koenvanbelle/cypress-soft-assertions 2.2.1 → 2.3.2

package/README.md

@@ -168,6 +168,117 @@ SOFT ASSERTION FAILURES (3 failed):
   ```
 - **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.
 
+## Compatibility: cypress-translation-checker
+
+`@koenvanbelle/cypress-soft-assertions` is compatible with `cypress-translation-checker` (verified with `cypress-translation-checker@1.3.4` and Cypress 15).
+
+### Install
+
+```bash
+npm install --save-dev @koenvanbelle/cypress-soft-assertions cypress-translation-checker
+```
+
+### 1. Register translation-checker tasks in Cypress config
+
+`cypress-translation-checker` uses Cypress tasks to persist collected page results. Add these in `setupNodeEvents`.
+
+```typescript
+import { defineConfig } from 'cypress';
+
+const translationResults = new Map<string, { url: string; errors: any[]; testContext: string }>();
+
+export default defineConfig({
+  e2e: {
+    setupNodeEvents(on, config) {
+      on('task', {
+        storeTranslationResult({
+          url,
+          errors,
+          testContext,
+        }: {
+          url: string;
+          errors: any[];
+          testContext: string;
+        }) {
+          translationResults.set(url, { url, errors, testContext });
+          return null;
+        },
+        getTranslationResults() {
+          return Array.from(translationResults.values());
+        },
+        clearTranslationResults() {
+          translationResults.clear();
+          return null;
+        },
+      });
+
+      return config;
+    },
+  },
+});
+```
+
+### 2. Import both plugins in support file
+
+Enable soft assertions and then enable automatic translation checks.
+
+```typescript
+import '@koenvanbelle/cypress-soft-assertions';
+import { enableAutoTranslationCheck } from 'cypress-translation-checker/commands';
+
+enableAutoTranslationCheck({
+  waitTime: 500,
+});
+```
+
+### 3. Write tests normally with `soft_it`
+
+Soft assertion failures are still aggregated into one `SoftAssertionError` at test end.
+
+```typescript
+soft_it('works with automatic translation checks', () => {
+  cy.visit('/');
+  cy.get('h1').should('have.text', 'Expected title');
+  cy.get('#status').should('have.text', 'Ready');
+});
+```
+
+### Notes
+
+- If translation-checker tasks are missing, Cypress will fail with unknown task errors.
+- Both plugins register hooks/events, but they can run together safely with the setup above.
+- Keep translation-checker in non-invasive mode (`failOnError: false` in auto mode) so functional assertions remain the source of test pass/fail behavior.
+
+## Force-Fail Hook (strict mode)
+
+If your project (or another plugin) mutates test state in hooks (for example in `test:after:run`) and soft-failed tests appear as passed, enable strict mode per test:
+
+```typescript
+soft_it.strict('fails hard when soft assertions are captured', () => {
+  cy.visit('/');
+  cy.get('#title').should('have.text', 'Wrong Title');
+  cy.get('#status').should('have.text', 'Ready');
+});
+```
+
+You can also use `soft_it.strict.only(...)` and `soft_it.strict.skip(...)`.
+
+To force strict mode for all soft tests in a run, use env flags:
+
+```bash
+cypress run --env softAssertForceFail=true
+```
+
+You can also use:
+
+```bash
+cypress run --env SOFT_ASSERT_FORCE_FAIL=true
+```
+
+When strict mode is enabled (per test or via env), the plugin throws the final `SoftAssertionError` from `afterEach` on the last attempt, preventing downstream hook-based recovery from turning the test green.
+
+Note: strict mode may abort remaining tests in the same suite after the first forced soft failure (standard Cypress hook-failure behavior).
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -39,6 +39,16 @@ declare global {
          * Run only this test (like it.only)
          */
         function only(title: string, fn: Mocha.Func | Mocha.AsyncFunc): Mocha.Test;
+        /**
+         * Run this soft test in strict mode (force unrecoverable failure)
+         */
+        function strict(title: string, fn: Mocha.Func | Mocha.AsyncFunc): Mocha.Test;
+        namespace strict {
+            /** Run only this strict soft test */
+            function only(title: string, fn: Mocha.Func | Mocha.AsyncFunc): Mocha.Test;
+            /** Skip this strict soft test */
+            function skip(title: string, fn: Mocha.Func | Mocha.AsyncFunc): void;
+        }
         /**
          * Skip this test (like it.skip)
          */

package/dist/index.js

@@ -15,12 +15,17 @@
  * - An afterEach hook finalizes: aggregates all failures and reports them.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("./utils");
 let softAssertionErrors = [];
 let retryAssertionFailures = new Map();
 let retryFirstSeen = new Map();
 let isInSoftTest = false;
+let forceFailCurrentSoftTest = false;
 let activeFailHandler = null;
 let originalChaiAssert = null;
+// ---------------------------------------------------------------------------
+// Module-level state
+// ---------------------------------------------------------------------------
 function getEffectiveTimeout() {
     var _a;
     try {
@@ -37,41 +42,34 @@ function getEffectiveTimeout() {
         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) {
-        softAssertionErrors.push({ message, stack });
-    }
-}
-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 selector = obj === null || obj === void 0 ? void 0 : obj.selector;
-    if (typeof selector === 'string' && selector.length > 0) {
-        return selector;
-    }
-    return '';
+function isTruthy(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number')
+        return value !== 0;
+    const normalized = String(value !== null && value !== void 0 ? value : '').trim().toLowerCase();
+    return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on';
 }
-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);
+function shouldForceFailSoftAssertions() {
+    var _a;
     try {
-        return JSON.stringify(value);
+        const env = (_a = Cypress.env) === null || _a === void 0 ? void 0 : _a.bind(Cypress);
+        if (!env)
+            return false;
+        return isTruthy(env('softAssertForceFail')) || isTruthy(env('SOFT_ASSERT_FORCE_FAIL'));
     }
-    catch (_a) {
-        return String(value);
+    catch (_b) {
+        return false;
     }
 }
+// ---------------------------------------------------------------------------
+// Internal helpers (Cypress-dependent — not unit-testable in isolation)
+// ---------------------------------------------------------------------------
+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;
+    (0, utils_1.appendUniqueError)(softAssertionErrors, message, stack);
+}
 function getRetryableCommandId() {
     var _a, _b, _c, _d, _e, _f, _g;
     try {
@@ -91,13 +89,6 @@ function getRetryableCommandId() {
     catch ( /* ignore */_h) { /* ignore */ }
     return '';
 }
-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 patchChaiAssertions() {
     var _a;
     const assertionProto = (_a = chai === null || chai === void 0 ? void 0 : chai.Assertion) === null || _a === void 0 ? void 0 : _a.prototype;
@@ -110,13 +101,18 @@ function patchChaiAssertions() {
     assertionProto.assert = patchedAssertionAssert;
 }
 function resolveStableToken(assertionContext, args) {
-    const token = getAssertionToken(assertionContext, args);
-    if (token)
-        return token;
-    const retryableCid = getRetryableCommandId();
-    if (retryableCid)
-        return `__cmd__|${retryableCid}|${toTokenPart(args === null || args === void 0 ? void 0 : args[3])}`;
-    return '';
+    return (0, utils_1.resolveToken)((0, utils_1.getAssertionToken)(assertionContext, args), getRetryableCommandId(), args);
+}
+function isRunningHookContext() {
+    var _a;
+    try {
+        const runnable = cy.state('runnable');
+        const type = (_a = runnable === null || runnable === void 0 ? void 0 : runnable.type) !== null && _a !== void 0 ? _a : runnable === null || runnable === void 0 ? void 0 : runnable._type;
+        return type === 'hook';
+    }
+    catch (_b) {
+        return false;
+    }
 }
 function patchedAssertionAssert(...args) {
     if (!originalChaiAssert)
@@ -136,6 +132,8 @@ function patchedAssertionAssert(...args) {
     catch (error) {
         if (!isInSoftTest)
             throw error;
+        if (isRunningHookContext())
+            throw error;
         const errorEntry = {
             message: String((error === null || error === void 0 ? void 0 : error.message) || error),
             stack: error === null || error === void 0 ? void 0 : error.stack,
@@ -178,6 +176,8 @@ function setupSoftAssertions() {
         activeFailHandler = (error) => {
             if (!isInSoftTest)
                 throw error;
+            if (isRunningHookContext())
+                throw error;
             // Final aggregated error must propagate to fail the test.
             if (String((error === null || error === void 0 ? void 0 : error.name) || '') === 'SoftAssertionError')
                 throw error;
@@ -215,27 +215,11 @@ function restoreAssertions() {
 function buildSoftAssertionError() {
     // Promote any remaining retry-tracked failures that weren't already
     // captured by the fail handler (dedup by message).
-    for (const entry of retryAssertionFailures.values()) {
-        const isDuplicate = softAssertionErrors.some(e => e.message === entry.message);
-        if (!isDuplicate) {
-            softAssertionErrors.push(entry);
-        }
-    }
+    softAssertionErrors = (0, utils_1.mergeRetryFailures)(softAssertionErrors, retryAssertionFailures);
     retryAssertionFailures.clear();
     retryFirstSeen.clear();
-    if (softAssertionErrors.length > 0) {
-        const errorMessages = softAssertionErrors
-            .map((entry, index) => `  ${index + 1}. ${entry.message}`)
-            .join('\n');
-        const finalMessage = [
-            '',
-            '='.repeat(80),
-            `SOFT ASSERTION FAILURES (${softAssertionErrors.length} failed):`,
-            '='.repeat(80),
-            errorMessages,
-            '='.repeat(80),
-            '',
-        ].join('\n');
+    const finalMessage = (0, utils_1.formatSoftAssertionErrors)(softAssertionErrors);
+    if (finalMessage !== null) {
         softAssertionErrors = [];
         const error = new Error(finalMessage);
         error.name = 'SoftAssertionError';
@@ -245,19 +229,22 @@ function buildSoftAssertionError() {
 }
 function finalizeSoftTest() {
     isInSoftTest = false;
+    forceFailCurrentSoftTest = false;
     restoreAssertions();
     return buildSoftAssertionError();
 }
 function abortSoftTest() {
     isInSoftTest = false;
+    forceFailCurrentSoftTest = false;
     restoreAssertions();
     retryAssertionFailures.clear();
     retryFirstSeen.clear();
 }
-function createSoftIt(baseIt) {
+function createSoftIt(baseIt, options) {
     return function (title, fn) {
         return baseIt(title, function () {
             isInSoftTest = true;
+            forceFailCurrentSoftTest = Boolean(options === null || options === void 0 ? void 0 : options.strict) || shouldForceFailSoftAssertions();
             softAssertionErrors = [];
             retryAssertionFailures.clear();
             retryFirstSeen.clear();
@@ -294,23 +281,53 @@ globalThis.soft_it = createSoftIt(it);
  * soft_it.only - Run only this soft test
  */
 globalThis.soft_it.only = createSoftIt(it.only);
+/**
+ * soft_it.strict - Run this soft test in strict mode.
+ *
+ * Strict mode throws the final SoftAssertionError from afterEach on the
+ * last attempt, making the failure unrecoverable by downstream hooks.
+ */
+globalThis.soft_it.strict = createSoftIt(it, { strict: true });
+/**
+ * soft_it.strict.only - Run only this strict soft test
+ */
+globalThis.soft_it.strict.only = createSoftIt(it.only, { strict: true });
 /**
  * soft_it.skip - Skip this soft test
  */
 globalThis.soft_it.skip = it.skip;
+/**
+ * soft_it.strict.skip - Skip this strict soft test
+ */
+globalThis.soft_it.strict.skip = it.skip;
 // Global afterEach hook: finalize soft assertions after each test.
 // 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;
+    var _a, _b, _c;
     if (!isInSoftTest)
         return;
     const finalError = finalizeSoftTest();
     if (finalError) {
-        // Use runner.fail() to mark the TEST as failed rather than the hook.
-        // Throwing from afterEach would skip remaining tests in the suite.
-        const runner = (_a = Cypress.mocha) === null || _a === void 0 ? void 0 : _a.getRunner();
         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.
+        if (forceFailCurrentSoftTest) {
+            // Strict mode: force an unrecoverable hook failure.
+            // This guarantees a failed result even when other plugins mutate
+            // test state in test:after:run.
+            throw finalError;
+        }
+        const runner = (_c = Cypress.mocha) === null || _c === void 0 ? void 0 : _c.getRunner();
         if (runner && test) {
             runner.fail(test, finalError);
         }

package/dist/utils.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Pure utility functions for the soft assertions plugin.
+ *
+ * These are free of Cypress/Chai globals and module-level state, making them
+ * suitable for fast, isolated unit testing without a running Cypress instance.
+ */
+export interface ErrorEntry {
+    message: string;
+    stack?: string;
+}
+/**
+ * Converts any value to a stable string token component.
+ * Used when building assertion identity tokens for retry-tracking.
+ */
+export declare function toTokenPart(value: any): string;
+/**
+ * Extracts a stable key from a Chai assertion context's subject.
+ * Returns '#<id>' for elements with an id, the jQuery selector string if available,
+ * or '' when nothing stable can be derived.
+ */
+export declare function getSubjectKey(assertionContext: any): string;
+/**
+ * Builds a stable token that uniquely identifies a retryable assertion by
+ * combining the subject key with the expected value.
+ * Returns '' when no stable key can be derived (token-less assertion).
+ */
+export declare function getAssertionToken(assertionContext: any, args: any[]): string;
+/**
+ * Appends an error to the list only if it is not a consecutive duplicate.
+ * "Duplicate" means the immediately preceding entry has an identical message
+ * AND identical stack. Non-consecutive duplicates are always appended.
+ *
+ * Mutates the provided array in place (matching the original behaviour of
+ * captureSoftAssertion).
+ */
+export declare function appendUniqueError(errors: ErrorEntry[], message: string, stack?: string): void;
+/**
+ * Promotes entries from retryFailures into softErrors, skipping any entry
+ * whose message already appears in softErrors (message-only dedup).
+ *
+ * Returns a new array — does not mutate either input. The retry map is also
+ * left untouched; callers are responsible for clearing it afterwards.
+ */
+export declare function mergeRetryFailures(softErrors: ErrorEntry[], retryFailures: Map<string, ErrorEntry>): ErrorEntry[];
+/**
+ * Resolves the stable token that identifies a retryable assertion.
+ *
+ * Priority:
+ *  1. assertionToken (derived from subject id / selector + expected value)
+ *  2. commandId-based token (used when the subject has no stable id/selector)
+ *  3. '' (token-less — assertion will be captured immediately instead of tracked)
+ */
+export declare function resolveToken(assertionToken: string, commandId: string, args: any[]): string;
+/**
+ * Formats a list of captured soft assertion errors into the final
+ * SoftAssertionError message string.
+ * Returns null when the list is empty (no failures to report).
+ */
+export declare function formatSoftAssertionErrors(errors: ErrorEntry[]): string | null;

package/dist/utils.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * Pure utility functions for the soft assertions plugin.
+ *
+ * These are free of Cypress/Chai globals and module-level state, making them
+ * suitable for fast, isolated unit testing without a running Cypress instance.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toTokenPart = toTokenPart;
+exports.getSubjectKey = getSubjectKey;
+exports.getAssertionToken = getAssertionToken;
+exports.appendUniqueError = appendUniqueError;
+exports.mergeRetryFailures = mergeRetryFailures;
+exports.resolveToken = resolveToken;
+exports.formatSoftAssertionErrors = formatSoftAssertionErrors;
+/**
+ * Converts any value to a stable string token component.
+ * Used when building assertion identity tokens for retry-tracking.
+ */
+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);
+    }
+    catch (_a) {
+        return String(value);
+    }
+}
+/**
+ * Extracts a stable key from a Chai assertion context's subject.
+ * Returns '#<id>' for elements with an id, the jQuery selector string if available,
+ * or '' when nothing stable can be derived.
+ */
+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 selector = obj === null || obj === void 0 ? void 0 : obj.selector;
+    if (typeof selector === 'string' && selector.length > 0) {
+        return selector;
+    }
+    return '';
+}
+/**
+ * Builds a stable token that uniquely identifies a retryable assertion by
+ * combining the subject key with the expected value.
+ * Returns '' when no stable key can be derived (token-less assertion).
+ */
+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)}`;
+}
+/**
+ * Appends an error to the list only if it is not a consecutive duplicate.
+ * "Duplicate" means the immediately preceding entry has an identical message
+ * AND identical stack. Non-consecutive duplicates are always appended.
+ *
+ * Mutates the provided array in place (matching the original behaviour of
+ * captureSoftAssertion).
+ */
+function appendUniqueError(errors, message, stack) {
+    const lastEntry = errors[errors.length - 1];
+    if (!lastEntry || lastEntry.message !== message || lastEntry.stack !== stack) {
+        errors.push({ message, stack });
+    }
+}
+/**
+ * Promotes entries from retryFailures into softErrors, skipping any entry
+ * whose message already appears in softErrors (message-only dedup).
+ *
+ * Returns a new array — does not mutate either input. The retry map is also
+ * left untouched; callers are responsible for clearing it afterwards.
+ */
+function mergeRetryFailures(softErrors, retryFailures) {
+    const result = [...softErrors];
+    for (const entry of retryFailures.values()) {
+        const isDuplicate = result.some(e => e.message === entry.message);
+        if (!isDuplicate) {
+            result.push(entry);
+        }
+    }
+    return result;
+}
+/**
+ * Resolves the stable token that identifies a retryable assertion.
+ *
+ * Priority:
+ *  1. assertionToken (derived from subject id / selector + expected value)
+ *  2. commandId-based token (used when the subject has no stable id/selector)
+ *  3. '' (token-less — assertion will be captured immediately instead of tracked)
+ */
+function resolveToken(assertionToken, commandId, args) {
+    if (assertionToken)
+        return assertionToken;
+    if (commandId)
+        return `__cmd__|${commandId}|${toTokenPart(args === null || args === void 0 ? void 0 : args[3])}`;
+    return '';
+}
+/**
+ * Formats a list of captured soft assertion errors into the final
+ * SoftAssertionError message string.
+ * Returns null when the list is empty (no failures to report).
+ */
+function formatSoftAssertionErrors(errors) {
+    if (errors.length === 0)
+        return null;
+    const errorMessages = errors
+        .map((entry, index) => `  ${index + 1}. ${entry.message}`)
+        .join('\n');
+    return [
+        '',
+        '='.repeat(80),
+        `SOFT ASSERTION FAILURES (${errors.length} failed):`,
+        '='.repeat(80),
+        errorMessages,
+        '='.repeat(80),
+        '',
+    ].join('\n');
+}

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@koenvanbelle/cypress-soft-assertions",
-  "version": "2.2.1",
+  "version": "2.3.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",
   "scripts": {
     "build": "tsc",
+    "prepare": "npm run build",
     "prepublishOnly": "npm run build",
     "cy:open": "cypress open",
     "cy:run": "cypress run",
-    "test": "npm run build && cypress run && npm run test:runner",
+    "test": "npm run build && npm run test:unit && cypress run && npm run test:runner",
+    "test:unit": "node --test test/unit.test.mjs",
     "test:runner": "node --test test/runner.test.mjs"
   },
   "keywords": [
@@ -37,9 +39,10 @@
     "cypress": ">=10.0.0"
   },
   "devDependencies": {
+    "@types/mocha": "^10.0.10",
     "cypress": "^15.9.0",
-    "typescript": "^5.9.3",
-    "@types/mocha": "^10.0.10"
+    "cypress-translation-checker": "^1.3.4",
+    "typescript": "^5.9.3"
   },
   "files": [
     "dist",