@vitest/expect 2.1.9: JestExtend

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.JestExtend 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.JestExtend

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:abe5ab23f0071ffd5bb77db11b8517bf97d237cdce923592a5c215fdd34a2ffd","contract":["assert JestExtend is a Chai plugin function that registers extend method onto chai.expect","assert expect.extend registers custom synchronous matchers supporting pass and custom message generation","assert custom matchers throw JestExtendError when assertions fail under standard and inverted .not execution","assert expect.extend registers custom asynchronous matchers returning promises with pass and message","assert custom matchers provide matcher context including this.equals and this.isNot","assert expect.extend automatically creates asymmetric matchers on expect and expect.not","assert asymmetric matchers created by expect.extend integrate with toEqual for deep structural matching"],"goal":"verify @vitest/expect.JestExtend in pkg:npm/%40vitest/expect@2.1.9","kind":"HOW","packages":["pkg:npm/%40vitest/expect@2.1.9"],"schemaVersion":1,"symbols":["@vitest/expect.JestExtend"]},"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.JestExtend"],"verifierAdapter":"node-typescript@1"}

import * as chai from 'chai';
import {
  JestChaiExpect,
  JestAsymmetricMatchers,
  JestExtend,
  getState,
  setState,
} from '@vitest/expect';

// Register required plugins on chai
chai.use(JestChaiExpect);
chai.use(JestAsymmetricMatchers);
chai.use(JestExtend);

export const expect = chai.expect;

/**
 * Registers the JestExtend plugin on a given Chai instance.
 *
 * @param {object} chaiInstance - The Chai instance to register the plugin with.
 * @returns {object} The Chai instance with the extend method attached.
 */
export function registerJestExtend(chaiInstance) {
  chaiInstance.use(JestExtend);
  return chaiInstance;
}

export {
  JestExtend,
  JestChaiExpect,
  JestAsymmetricMatchers,
  getState,
  setState,
};

{
  "name": "sample-vitest-expect-jest-extend",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-vitest-expect-jest-extend",
      "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-jest-extend",
  "version": "1.0.0",
  "description": "Clean-room verification sample for @vitest/expect JestExtend",
  "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.JestExtend in pkg:npm/%40vitest/expect@2.1.9",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40vitest/expect@2.1.9"
  ],
  "symbols": [
    "@vitest/expect.JestExtend"
  ]
}

import assert from 'node:assert/strict';
import {
  expect,
  JestExtend,
  registerJestExtend,
} from '../index.mjs';

async function runContract() {
  // 1. assert JestExtend is a Chai plugin function that registers extend method onto chai.expect
  assert.strictEqual(typeof JestExtend, 'function');
  assert.strictEqual(typeof expect.extend, 'function');

  // Verify custom Chai instance registration with JestExtend plugin
  const customUtils = {
    addMethod(ctx, name, fn) {
      ctx[name] = fn;
    },
  };
  const customChai = {
    use(plugin) {
      plugin(this, customUtils);
      return this;
    },
    expect: {},
  };
  registerJestExtend(customChai);
  assert.strictEqual(typeof customChai.expect.extend, 'function');

  // 2. assert expect.extend registers custom synchronous matchers supporting pass and custom message generation
  expect.extend(expect, {
    toBeEven(received) {
      const pass = typeof received === 'number' && received % 2 === 0;
      return {
        pass,
        message: () => `expected ${received} ${pass ? 'not ' : ''}to be even`,
        actual: received,
        expected: 'even number',
      };
    },
    toBeWithinRange(received, floor, ceiling) {
      const pass = typeof received === 'number' && received >= floor && received <= ceiling;
      return {
        pass,
        message: () => `expected ${received} ${pass ? 'not ' : ''}to be within range [${floor}, ${ceiling}]`,
        actual: received,
        expected: [floor, ceiling],
      };
    },
  });

  expect(4).toBeEven();
  expect(5).not.toBeEven();
  expect(10).toBeWithinRange(5, 15);
  expect(20).not.toBeWithinRange(5, 15);

  // 3. assert custom matchers throw JestExtendError when assertions fail under standard and inverted .not execution
  let syncFailed = false;
  try {
    expect(7).toBeEven();
  } catch (err) {
    syncFailed = true;
    assert.strictEqual(err.actual, 7);
    assert.strictEqual(err.expected, 'even number');
    assert.match(err.message, /expected 7 to be even/);
  }
  assert.strictEqual(syncFailed, true, 'expect(7).toBeEven() should fail');

  let notFailed = false;
  try {
    expect(8).not.toBeEven();
  } catch (err) {
    notFailed = true;
    assert.match(err.message, /expected 8 not to be even/);
  }
  assert.strictEqual(notFailed, true, 'expect(8).not.toBeEven() should fail');

  // 4. assert expect.extend registers custom asynchronous matchers returning promises with pass and message
  expect.extend(expect, {
    async toBeAsyncPositive(received) {
      const pass = typeof received === 'number' && received > 0;
      return {
        pass,
        message: () => `expected ${received} ${pass ? 'not ' : ''}to be positive`,
        actual: received,
        expected: 'positive number',
      };
    },
  });

  await expect(42).toBeAsyncPositive();
  await expect(-5).not.toBeAsyncPositive();

  let asyncFailed = false;
  try {
    await expect(-1).toBeAsyncPositive();
  } catch (err) {
    asyncFailed = true;
    assert.strictEqual(err.actual, -1);
    assert.strictEqual(err.expected, 'positive number');
    assert.match(err.message, /expected -1 to be positive/);
  }
  assert.strictEqual(asyncFailed, true, 'await expect(-1).toBeAsyncPositive() should fail');

  // 5. assert custom matchers provide matcher context including this.equals and this.isNot
  expect.extend(expect, {
    toMatchCustomStructure(received, expected) {
      const pass = this.equals(received, expected);
      return {
        pass,
        message: () => `structure mismatch with isNot=${this.isNot}`,
        actual: received,
        expected,
      };
    },
  });

  expect({ key: 'val', num: 1 }).toMatchCustomStructure({ key: 'val', num: 1 });
  expect({ key: 'val', num: 1 }).not.toMatchCustomStructure({ key: 'different' });

  // 6. assert expect.extend automatically creates asymmetric matchers on expect and expect.not
  assert.strictEqual(typeof expect.toBeEven, 'function');
  assert.strictEqual(typeof expect.not.toBeEven, 'function');
  assert.strictEqual(typeof expect.toBeWithinRange, 'function');
  assert.strictEqual(typeof expect.not.toBeWithinRange, 'function');

  const evenAsymmetric = expect.toBeEven();
  assert.strictEqual(evenAsymmetric.asymmetricMatch(100), true);
  assert.strictEqual(evenAsymmetric.asymmetricMatch(101), false);
  assert.strictEqual(evenAsymmetric.toString(), 'toBeEven');

  const notEvenAsymmetric = expect.not.toBeEven();
  assert.strictEqual(notEvenAsymmetric.asymmetricMatch(101), true);
  assert.strictEqual(notEvenAsymmetric.asymmetricMatch(100), false);
  assert.strictEqual(notEvenAsymmetric.toString(), 'not.toBeEven');

  const rangeAsymmetric = expect.toBeWithinRange(10, 50);
  assert.strictEqual(rangeAsymmetric.asymmetricMatch(25), true);
  assert.strictEqual(rangeAsymmetric.asymmetricMatch(5), false);

  // 7. assert asymmetric matchers created by expect.extend integrate with toEqual for deep structural matching
  const dataset = {
    id: 10,
    score: 88,
    nested: {
      count: 24,
    },
  };

  expect(dataset).toEqual({
    id: expect.toBeEven(),
    score: expect.toBeWithinRange(80, 90),
    nested: {
      count: expect.toBeEven(),
    },
  });

  expect(dataset).toEqual({
    id: expect.not.toBeWithinRange(100, 200),
    score: expect.toBeEven(),
    nested: {
      count: expect.not.toBeWithinRange(1, 10),
    },
  });

  console.log('Contract assertions passed successfully.');
}

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