@vitest/expect 2.1.9: equals

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/expect.equals in pkg:npm/%40vitest/expect@2.1.9
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40vitest/expect@2.1.9
Demonstrate these symbols/APIs:
  - @vitest/expect.equals

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:566ef2c1d58e8d98613e681c4fd8bf6d59be5eca8f8dd1566bff4b47bc490fce","contract":["assert equals performs value equality comparison on primitives following Object.is semantics including NaN and signed zeros","assert equals compares deep nested objects and arrays by structural equality","assert equals compares special object types including Date, RegExp, Error, and URL by value","assert equals handles circular references without infinite recursion","assert equals invokes asymmetric matchers on received or expected operands","assert equals supports custom equality testers with contextual equals helper","assert equals supports strictCheck parameter to distinguish absent keys from undefined properties"],"goal":"verify @vitest/expect.equals in pkg:npm/%40vitest/expect@2.1.9","kind":"HOW","packages":["pkg:npm/%40vitest/expect@2.1.9"],"schemaVersion":1,"symbols":["@vitest/expect.equals"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","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/expect@2.1.9"],"schemaVersion":1,"subject":"pkg:npm/%40vitest/expect@2.1.9","symbols":["@vitest/expect.equals"],"verifierAdapter":"node-typescript@1"}

import { equals } from '@vitest/expect';

/**
 * Compares two values for deep equality using @vitest/expect's equals algorithm.
 *
 * @param {unknown} a - First value to compare.
 * @param {unknown} b - Second value to compare.
 * @param {Array<Function>} [customTesters] - Optional list of custom equality tester functions.
 * @param {boolean} [strictCheck] - Whether to strictly distinguish absent keys from undefined properties.
 * @returns {boolean} True if values are considered equal.
 */
export function areEqual(a, b, customTesters, strictCheck) {
  return equals(a, b, customTesters, strictCheck);
}

/**
 * Creates a case-insensitive string equality tester for use with equals.
 *
 * @returns {Function} Custom equality tester.
 */
export function createCaseInsensitiveTester() {
  return function caseInsensitiveTester(a, b) {
    if (typeof a === 'string' && typeof b === 'string') {
      return a.toLowerCase() === b.toLowerCase();
    }
  };
}

export { equals };

{
  "name": "sample-vitest-expect-equals",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-vitest-expect-equals",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@vitest/expect": "2.1.9"
      }
    },
    "node_modules/@vitest/expect": {
      "version": "2.1.9",
      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-2.1.9.tgz",
      "integrity": "sha512-UJCIkTBenHeKT1TTlKMJWy1laZewsRIzYighyYiJKZreqtdxSos/S1t+ktRMQWu2CKqaarrkeszJx1cgC5tGZw==",
      "license": "MIT",
      "dependencies": {
        "@vitest/spy": "2.1.9",
        "@vitest/utils": "2.1.9",
        "chai": "^5.1.2",
        "tinyrainbow": "^1.2.0"
      },
      "funding": {
        "url": "https://opencollective.com/vitest"
      }
    },
    "node_modules/@vitest/pretty-format": {
      "version": "2.1.9",
      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-2.1.9.tgz",
      "integrity": "sha512-KhRIdGV2U9HOUzxfiHmY8IFHTdqtOhIzCpd8WRdJiE7D/HUcZVD0EgQCVjm+Q9gkUXWgBvMmTtZgIG48wq7sOQ==",
      "license": "MIT",
      "dependencies": {
        "tinyrainbow": "^1.2.0"
      },
      "funding": {
        "url": "https://opencollective.com/vitest"
      }
    },
    "node_modules/@vitest/spy": {
      "version": "2.1.9",
      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-2.1.9.tgz",
      "integrity": "sha512-E1B35FwzXXTs9FHNK6bDszs7mtydNi5MIfUWpceJ8Xbfb1gBMscAnwLbEu+B44ed6W3XjL9/ehLPHR1fkf1KLQ==",
      "license": "MIT",
      "dependencies": {
        "tinyspy": "^3.0.2"
      },
      "funding": {
        "url": "https://opencollective.com/vitest"
      }
    },
    "node_modules/@vitest/utils": {
      "version": "2.1.9",
      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-2.1.9.tgz",
      "integrity": "sha512-v0psaMSkNJ3A2NMrUEHFRzJtDPFn+/VWZ5WxImB21T9fjucJRmS7xCS3ppEnARb9y11OAzaD+P2Ps+b+BGX5iQ==",
      "license": "MIT",
      "dependencies": {
        "@vitest/pretty-format": "2.1.9",
        "loupe": "^3.1.2",
        "tinyrainbow": "^1.2.0"
      },
      "funding": {
        "url": "https://opencollective.com/vitest"
      }
    },
    "node_modules/assertion-error": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
      "integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==",
      "license": "MIT",
      "engines": {
        "node": ">=12"
      }
    },
    "node_modules/chai": {
      "version": "5.3.3",
      "resolved": "https://registry.npmjs.org/chai/-/chai-5.3.3.tgz",
      "integrity": "sha512-4zNhdJD/iOjSH0A05ea+Ke6MU5mmpQcbQsSOkgdaUMJ9zTlDTD/GYlwohmIE2u0gaxHYiVHEn1Fw9mZ/ktJWgw==",
      "license": "MIT",
      "dependencies": {
        "assertion-error": "^2.0.1",
        "check-error": "^2.1.1",
        "deep-eql": "^5.0.1",
        "loupe": "^3.1.0",
        "pathval": "^2.0.0"
      },
      "engines": {
        "node": ">=18"
      }
    },
    "node_modules/check-error": {
      "version": "2.1.3",
      "resolved": "https://registry.npmjs.org/check-error/-/check-error-2.1.3.tgz",
      "integrity": "sha512-PAJdDJusoxnwm1VwW07VWwUN1sl7smmC3OKggvndJFadxxDRyFJBX/ggnu/KE4kQAB7a3Dp8f/YXC1FlUprWmA==",
      "license": "MIT",
      "engines": {
        "node": ">= 16"
      }
    },
    "node_modules/deep-eql": {
      "version": "5.0.2",
      "resolved": "https://registry.npmjs.org/deep-eql/-/deep-eql-5.0.2.tgz",
      "integrity": "sha512-h5k/5U50IJJFpzfL6nO9jaaumfjO/f2NjK/oYB2Djzm4p9L+3T9qWpZqZ2hAbLPuuYq9wrU08WQyBTL5GbPk5Q==",
      "license": "MIT",
      "engines": {
        "node": ">=6"
      }
    },
    "node_modules/loupe": {
      "version": "3.2.1",
      "resolved": "https://registry.npmjs.org/loupe/-/loupe-3.2.1.tgz",
      "integrity": "sha512-CdzqowRJCeLU72bHvWqwRBBlLcMEtIvGrlvef74kMnV2AolS9Y8xUv1I0U/MNAWMhBlKIoyuEgoJ0t/bbwHbLQ==",
      "license": "MIT"
    },
    "node_modules/pathval": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/pathval/-/pathval-2.0.1.tgz",
      "integrity": "sha512-//nshmD55c46FuFw26xV/xFAaB5HF9Xdap7HJBBnrKdAd6/GxDBaNA1870O79+9ueg61cZLSVc+OaFlfmObYVQ==",
      "license": "MIT",
      "engines": {
        "node": ">= 14.16"
      }
    },
    "node_modules/tinyrainbow": {
      "version": "1.2.0",
      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-1.2.0.tgz",
      "integrity": "sha512-weEDEq7Z5eTHPDh4xjX789+fHfF+P8boiFB+0vbWzpbnbsEr/GRaohi/uMKxg8RZMXnl1ItAi/IUHWMsjDV7kQ==",
      "license": "MIT",
      "engines": {
        "node": ">=14.0.0"
      }
    },
    "node_modules/tinyspy": {
      "version": "3.0.2",
      "resolved": "https://registry.npmjs.org/tinyspy/-/tinyspy-3.0.2.tgz",
      "integrity": "sha512-n1cw8k1k0x4pgA2+9XrOkFydTerNcJ1zWCO5Nn9scWHTD+5tp8dghT2x1uduQePZTZgd3Tupf+x9BxJjeJi77Q==",
      "license": "MIT",
      "engines": {
        "node": ">=14.0.0"
      }
    }
  }
}

{
  "name": "sample-vitest-expect-equals",
  "version": "1.0.0",
  "description": "Clean-room verification sample for equals in @vitest/expect",
  "type": "module",
  "main": "index.mjs",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "license": "MIT-0",
  "dependencies": {
    "@vitest/expect": "2.1.9"
  }
}

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

import assert from 'node:assert/strict';
import { equals, areEqual, createCaseInsensitiveTester } from '../index.mjs';
import { Any, Anything, ArrayContaining } from '@vitest/expect';

async function runContract() {
  // 1. assert equals performs value equality comparison on primitives following Object.is semantics including NaN and signed zeros
  assert.strictEqual(equals(42, 42), true);
  assert.strictEqual(equals('hello', 'hello'), true);
  assert.strictEqual(equals(true, true), true);
  assert.strictEqual(equals(null, null), true);
  assert.strictEqual(equals(undefined, undefined), true);
  assert.strictEqual(equals(NaN, NaN), true);
  assert.strictEqual(equals(0, -0), false);
  assert.strictEqual(equals(10, 20), false);
  assert.strictEqual(equals('foo', 'bar'), false);
  assert.strictEqual(areEqual(null, undefined), false);

  // 2. assert equals compares deep nested objects and arrays by structural equality
  assert.strictEqual(equals([1, 2, 3], [1, 2, 3]), true);
  assert.strictEqual(equals([1, 2], [1, 3]), false);
  assert.strictEqual(equals([1, 2], [1, 2, 3]), false);
  assert.strictEqual(
    equals(
      { a: 1, b: { c: [10, 20], d: 'nested' } },
      { a: 1, b: { c: [10, 20], d: 'nested' } }
    ),
    true
  );
  assert.strictEqual(
    equals(
      { a: 1, b: { c: [10, 20] } },
      { a: 1, b: { c: [10, 99] } }
    ),
    false
  );

  // 3. assert equals compares special object types including Date, RegExp, Error, and URL by value
  assert.strictEqual(equals(new Date('2026-01-01T00:00:00Z'), new Date('2026-01-01T00:00:00Z')), true);
  assert.strictEqual(equals(new Date('2026-01-01T00:00:00Z'), new Date('2026-01-02T00:00:00Z')), false);
  assert.strictEqual(equals(/pattern/i, /pattern/i), true);
  assert.strictEqual(equals(/pattern/i, /pattern/g), false);
  assert.strictEqual(equals(new Error('something broke'), new Error('something broke')), true);
  assert.strictEqual(equals(new Error('err A'), new Error('err B')), false);
  assert.strictEqual(equals(new URL('https://example.com/api'), new URL('https://example.com/api')), true);
  assert.strictEqual(equals(new URL('https://example.com/api'), new URL('https://example.com/other')), false);

  // 4. assert equals handles circular references without infinite recursion
  const cyclicA = { id: 1 };
  cyclicA.self = cyclicA;
  const cyclicB = { id: 1 };
  cyclicB.self = cyclicB;
  assert.strictEqual(equals(cyclicA, cyclicB), true);

  const cyclicC = { id: 2 };
  cyclicC.self = cyclicC;
  assert.strictEqual(equals(cyclicA, cyclicC), false);

  // 5. assert equals invokes asymmetric matchers on received or expected operands
  assert.strictEqual(equals('sample string', new Any(String)), true);
  assert.strictEqual(equals(99, new Any(String)), false);
  assert.strictEqual(equals({ id: 1, label: 'test' }, new Anything()), true);
  assert.strictEqual(equals([1, 2, 3], new ArrayContaining([2, 1])), true);
  assert.strictEqual(equals([1, 2, 3], new ArrayContaining([4])), false);

  // 6. assert equals supports custom equality testers with contextual equals helper
  const caseInsensitiveTester = createCaseInsensitiveTester();
  assert.strictEqual(equals('Hello World', 'hello world', [caseInsensitiveTester]), true);
  assert.strictEqual(equals('Hello World', 'goodbye', [caseInsensitiveTester]), false);

  const nestedCustomTester = function (a, b) {
    if (a && b && a.customCompare && b.customCompare) {
      return this.equals(a.val, b.val);
    }
  };
  assert.strictEqual(
    equals(
      { customCompare: true, val: { nested: 1 } },
      { customCompare: true, val: { nested: 1 } },
      [nestedCustomTester]
    ),
    true
  );

  // 7. assert equals supports strictCheck parameter to distinguish absent keys from undefined properties
  const objWithUndefined = { a: undefined };
  const emptyObj = {};
  assert.strictEqual(equals(objWithUndefined, emptyObj, [], false), true);
  assert.strictEqual(equals(objWithUndefined, emptyObj, [], true), false);

  console.log('All @vitest/expect.equals contract assertions passed successfully.');
}

runContract().catch((err) => {
  console.error('Contract test failed:', err);
  process.exit(1);
});