@vitest/expect 2.1.9: setState

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.setState 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.setState
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:8dbbe759025d19724d2448584251a52cf37e35b24f1ef73ac6240e82218d7d50","constraints":{"executionContext":"node"},"contract":["setState initializes matcher execution state on the expect instance when previously undefined","getState retrieves current matcher state associated with the expect instance","setState performs shallow property merging preserving previously defined state properties","setState overwrites existing property values when called with updated keys","custom matchers registered via expect.extend access matcher state updated by setState via this context","setState updates state dynamically during matcher execution across assertions","isolated expect instances maintain independent state contexts via setState","expect.setState helper binds state updates directly to the expect instance"],"goal":"verify @vitest/expect.setState in pkg:npm/%40vitest/expect@2.1.9","kind":"HOW","packages":["pkg:npm/%40vitest/expect@2.1.9"],"schemaVersion":1,"symbols":["@vitest/expect.setState"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","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.setState"],"verifierAdapter":"node-typescript@1"}

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

chai.use(JestChaiExpect);
chai.use(JestAsymmetricMatchers);
chai.use(JestExtend);

export const expect = chai.expect;

// Provide convenience helper bindings on expect
expect.setState = (state) => setState(state, expect);
expect.getState = () => getState(expect);

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

{
  "name": "sample-vitest-expect",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-vitest-expect",
      "version": "1.0.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",
  "version": "1.0.0",
  "description": "Clean-room verification sample for @vitest/expect.setState in @vitest/expect",
  "type": "module",
  "main": "index.mjs",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@vitest/expect": "2.1.9"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify @vitest/expect.setState in pkg:npm/%40vitest/expect@2.1.9",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40vitest/expect@2.1.9"
  ],
  "symbols": [
    "@vitest/expect.setState"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

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

// 1. setState initializes matcher execution state on the expect instance when previously undefined
{
  assert.equal(getState(expect), undefined);
  setState({ currentTestName: 'test_initial', assertionCount: 0 }, expect);
  assert.equal(getState(expect).currentTestName, 'test_initial');
  assert.equal(getState(expect).assertionCount, 0);
}

// 2. getState retrieves current matcher state associated with the expect instance
{
  const state = getState(expect);
  assert.equal(typeof state, 'object');
  assert.equal(state.currentTestName, 'test_initial');
  assert.equal(state.assertionCount, 0);
}

// 3. setState performs shallow property merging preserving previously defined state properties
{
  setState({ testTimeout: 5000 }, expect);
  const state = getState(expect);
  assert.equal(state.currentTestName, 'test_initial');
  assert.equal(state.assertionCount, 0);
  assert.equal(state.testTimeout, 5000);
}

// 4. setState overwrites existing property values when called with updated keys
{
  setState({ assertionCount: 5, currentTestName: 'test_updated' }, expect);
  const state = getState(expect);
  assert.equal(state.currentTestName, 'test_updated');
  assert.equal(state.assertionCount, 5);
  assert.equal(state.testTimeout, 5000);
}

// 5. custom matchers registered via expect.extend access matcher state updated by setState via this context
{
  expect.extend(expect, {
    toHaveMatchingTestName(received, expectedName) {
      const pass = this.currentTestName === expectedName;
      return {
        pass,
        message: () => `expected ${this.currentTestName} to be ${expectedName}`,
        actual: this.currentTestName,
        expected: expectedName,
      };
    },
  });

  expect('sample-received-value').toHaveMatchingTestName('test_updated');
}

// 6. setState updates state dynamically during matcher execution across assertions
{
  expect.extend(expect, {
    toTrackAssertion(received) {
      const count = this.assertionCount || 0;
      setState({ assertionCount: count + 1 }, expect);
      return {
        pass: true,
        message: () => 'tracked assertion',
      };
    },
  });

  expect('first').toTrackAssertion();
  assert.equal(getState(expect).assertionCount, 6);
  expect('second').toTrackAssertion();
  assert.equal(getState(expect).assertionCount, 7);
}

// 7. isolated expect instances maintain independent state contexts via setState
{
  const secondaryExpect = Object.assign(() => {}, expect);
  setState({ instanceId: 'primary-context' }, expect);
  setState({ instanceId: 'secondary-context' }, secondaryExpect);

  assert.equal(getState(expect).instanceId, 'primary-context');
  assert.equal(getState(secondaryExpect).instanceId, 'secondary-context');
}

// 8. expect.setState helper binds state updates directly to the expect instance
{
  expect.setState({ helperBound: true, runId: 42 });
  const boundState = expect.getState();
  assert.equal(boundState.helperBound, true);
  assert.equal(boundState.runId, 42);
  assert.equal(boundState.instanceId, 'primary-context');
}

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