@vitest/utils 4.1.10: processError

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify @vitest/utils.processError in pkg:npm/%40vitest/utils@4.1.10
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40vitest/utils@4.1.10
Demonstrate these symbols/APIs:
  - @vitest/utils.processError

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:0d9e6c8a85071675203a348a565fde15aeb92014b2d9f51012e3fe4bf5deff45","contract":["processError converts non-object primitive error inputs into an object with string message property","processError normalizes Error instances preserving name and message with serialized stack trace","processError formats visual diffs and prettifies expected and actual properties when assertions mismatch","processError suppresses visual diff generation when showDiff is explicitly false","processError customizes diff rendering when diffOptions are provided","processError recursively processes and serializes nested error causes while preventing circular reference loops","processError preserves custom and non-standard properties attached to the input error object"],"goal":"verify @vitest/utils.processError in pkg:npm/%40vitest/utils@4.1.10","kind":"HOW","packages":["pkg:npm/%40vitest/utils@4.1.10"],"schemaVersion":1,"symbols":["@vitest/utils.processError"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40vitest/utils@4.1.10"],"schemaVersion":1,"subject":"pkg:npm/%40vitest/utils@4.1.10","symbols":["@vitest/utils.processError"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-vitest-utils-process-error",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-vitest-utils-process-error",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@vitest/utils": "4.1.10"
      }
    },
    "node_modules/@vitest/pretty-format": {
      "version": "4.1.10",
      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.10.tgz",
      "integrity": "sha512-W1HsjSH4MXQ9YfmmhLAoIYf1HRfekQCGngeIgcei6MP5QQGWUe0gkopdZQaVCFO+JDJMrAJGwa5pRpNpvy4P8Q==",
      "license": "MIT",
      "dependencies": {
        "tinyrainbow": "^3.1.0"
      },
      "funding": {
        "url": "https://opencollective.com/vitest"
      }
    },
    "node_modules/@vitest/utils": {
      "version": "4.1.10",
      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.10.tgz",
      "integrity": "sha512-fy9am/HWxbaGt/Sawrp90vt6Y6jQwf1RX77cz3uwoJwJVMli/e1IEwRPnMNJ7vKfPTwo0diXifkpPvwH9v7nGA==",
      "license": "MIT",
      "dependencies": {
        "@vitest/pretty-format": "4.1.10",
        "convert-source-map": "^2.0.0",
        "tinyrainbow": "^3.1.0"
      },
      "funding": {
        "url": "https://opencollective.com/vitest"
      }
    },
    "node_modules/convert-source-map": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz",
      "integrity": "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==",
      "license": "MIT"
    },
    "node_modules/tinyrainbow": {
      "version": "3.1.1",
      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-3.1.1.tgz",
      "integrity": "sha512-yau8yJdTt989Mm0Bd/236QnzEiPf2xLLTqUZRUJOo/3CB078LSwzei343DgtJVmfJKJE3TMINY1u42SQsP6mXw==",
      "license": "MIT",
      "engines": {
        "node": ">=14.0.0"
      }
    }
  }
}

{
  "name": "sample-vitest-utils-process-error",
  "version": "1.0.0",
  "description": "Clean-room verification sample for @vitest/utils.processError",
  "type": "module",
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@vitest/utils": "4.1.10"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify @vitest/utils.processError in pkg:npm/%40vitest/utils@4.1.10",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40vitest/utils@4.1.10"
  ],
  "symbols": [
    "@vitest/utils.processError"
  ]
}

import { processError } from '@vitest/utils/error';

/**
 * Format and serialize any error into a standardized test error structure.
 *
 * @param {unknown} err - The error to process
 * @param {object} [diffOptions] - Formatting and diff options
 * @returns {object} Processed test error
 */
export function formatTestError(err, diffOptions) {
  return processError(err, diffOptions);
}

/**
 * Normalize an assertion failure error with expected and actual values into a diffed error.
 *
 * @param {string} message - Error message
 * @param {unknown} actual - Actual received value
 * @param {unknown} expected - Expected target value
 * @param {object} [diffOptions] - Diff customization options
 * @returns {object} Processed error with formatted diff
 */
export function createAssertionError(message, actual, expected, diffOptions) {
  const err = new Error(message);
  err.actual = actual;
  err.expected = expected;
  return processError(err, diffOptions);
}

/**
 * Process an error chain containing nested causes.
 *
 * @param {string} message - High-level error message
 * @param {unknown} cause - Underlying root cause error
 * @returns {object} Processed error with recursively serialized cause
 */
export function createChainedError(message, cause) {
  const err = new Error(message, { cause });
  return processError(err);
}

export { processError };
export default processError;

import assert from 'node:assert/strict';
import { processError } from '@vitest/utils/error';
import {
  formatTestError,
  createAssertionError,
  createChainedError,
} from '../src/index.mjs';

// 1. processError converts non-object primitive error inputs into an object with string message property
{
  const p1 = processError('string error');
  assert.equal(p1.message, 'string error');

  const p2 = processError(404);
  assert.equal(p2.message, '404');

  const p3 = processError(null);
  assert.equal(p3.message, 'null');

  const p4 = processError(undefined);
  assert.equal(p4.message, 'undefined');

  const p5 = formatTestError('via helper');
  assert.equal(p5.message, 'via helper');
}

// 2. processError normalizes Error instances preserving name and message with serialized stack trace
{
  const err = new TypeError('invalid argument type');
  const processed = processError(err);
  assert.equal(processed.name, 'TypeError');
  assert.equal(processed.message, 'invalid argument type');
  assert.equal(typeof processed.stack, 'string');
  assert.ok(processed.stack.includes('invalid argument type'));
}

// 3. processError formats visual diffs and prettifies expected and actual properties when assertions mismatch
{
  const err = new Error('assertion mismatch');
  err.expected = { id: 100, active: true };
  err.actual = { id: 100, active: false };
  const processed = processError(err);
  assert.equal(typeof processed.diff, 'string');
  assert.ok(processed.diff.length > 0);
  assert.ok(processed.expected.includes('"active": true'));
  assert.ok(processed.actual.includes('"active": false'));
}

// 4. processError suppresses visual diff generation when showDiff is explicitly false
{
  const err = new Error('diff disabled');
  err.expected = 10;
  err.actual = 20;
  err.showDiff = false;
  const processed = processError(err);
  assert.equal(processed.diff, undefined);
  assert.equal(processed.expected, 10);
  assert.equal(processed.actual, 20);
}

// 5. processError customizes diff rendering when diffOptions are provided
{
  const err = new Error('multiline diff');
  err.expected = 'line-alpha\nline-beta\nline-gamma';
  err.actual = 'line-alpha\nline-beta-modified\nline-gamma';
  const processed = processError(err, { expand: false });
  assert.ok(processed.diff.includes('- Expected'));
  assert.ok(processed.diff.includes('+ Received'));

  const assertion = createAssertionError('diff helper', 'expected val', 'received val');
  assert.equal(typeof assertion.diff, 'string');
}

// 6. processError recursively processes and serializes nested error causes while preventing circular reference loops
{
  const rootCause = new Error('network timeout');
  const chained = createChainedError('service unavailable', rootCause);
  assert.equal(chained.name, 'Error');
  assert.equal(chained.message, 'service unavailable');
  assert.equal(chained.cause.name, 'Error');
  assert.equal(chained.cause.message, 'network timeout');

  const err1 = new Error('circular error 1');
  const err2 = new Error('circular error 2');
  err1.cause = err2;
  err2.cause = err1;
  const processedCircular = processError(err1);
  assert.equal(processedCircular.message, 'circular error 1');
  assert.equal(processedCircular.cause.message, 'circular error 2');
}

// 7. processError preserves custom and non-standard properties attached to the input error object
{
  const customErr = new Error('database failure');
  customErr.code = 'ERR_DB_QUERY';
  customErr.metadata = { table: 'users', queryId: 42 };
  const processed = processError(customErr);
  assert.equal(processed.code, 'ERR_DB_QUERY');
  assert.equal(processed.metadata.table, 'users');
  assert.equal(processed.metadata.queryId, 42);
}

console.log('Contract assertions verified successfully.');