@vitest/expect 2.1.9: StringMatching

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.StringMatching 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.StringMatching
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:cc7e8a6691e97d4be50357fc037861e2a2932a6a195a99bf9d138973d660fb5d","constraints":{"executionContext":"node"},"contract":["StringMatching accepts string patterns and matches matching substrings via asymmetricMatch","StringMatching accepts RegExp patterns and matches with regular expression flags","StringMatching throws Error when instantiated with non-string and non-RegExp expected values","asymmetricMatch returns false when the matching candidate is not a string","StringMatching supports inverse matching when the inverse flag is true","toString returns StringMatching for standard matchers and StringNotMatching for inverted matchers","getExpectedType returns string as the expected type indicator","StringMatching integrates with Vitest equals for deep asymmetric assertions on objects and arrays"],"goal":"verify @vitest/expect.StringMatching in pkg:npm/%40vitest/expect@2.1.9","kind":"HOW","packages":["pkg:npm/%40vitest/expect@2.1.9"],"schemaVersion":1,"symbols":["@vitest/expect.StringMatching"]},"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.StringMatching"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-vitest-expect-string-matching",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-vitest-expect-string-matching",
      "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-string-matching",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room code sample for @vitest/expect StringMatching",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "@vitest/expect": "2.1.9"
  }
}

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

const { StringMatching, equals } = require('@vitest/expect');

/**
 * Creates an instance of Vitest StringMatching asymmetric matcher.
 *
 * @param {string | RegExp} pattern - The string or regular expression pattern to match.
 * @param {boolean} [inverse=false] - Whether to invert the match logic.
 * @returns {StringMatching} The asymmetric matcher instance.
 */
function createStringMatcher(pattern, inverse = false) {
  return new StringMatching(pattern, inverse);
}

/**
 * Tests whether a given value matches the string pattern using StringMatching.
 *
 * @param {string | RegExp} pattern - Pattern to match against.
 * @param {*} value - The candidate value to test.
 * @param {boolean} [inverse=false] - Whether to invert the match logic.
 * @returns {boolean} True if matched (or inverted match), false otherwise.
 */
function matchesPattern(pattern, value, inverse = false) {
  const matcher = new StringMatching(pattern, inverse);
  return matcher.asymmetricMatch(value);
}

/**
 * Verifies if an asymmetric matcher matches a target value using Vitest equals.
 *
 * @param {string | RegExp} pattern - Expected pattern.
 * @param {*} actual - Actual value or structure containing strings.
 * @returns {boolean} True if equals accepts the asymmetric match.
 */
function checkEquals(pattern, actual) {
  return equals(actual, new StringMatching(pattern));
}

module.exports = {
  StringMatching,
  equals,
  createStringMatcher,
  matchesPattern,
  checkEquals
};

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const {
  StringMatching,
  equals,
  createStringMatcher,
  matchesPattern,
  checkEquals
} = require('../src/index.js');

async function runContract() {
  // 1. StringMatching accepts string patterns and matches matching substrings via asymmetricMatch
  const matcherStr = new StringMatching('world');
  assert.equal(typeof matcherStr.asymmetricMatch, 'function');
  assert.equal(matcherStr.asymmetricMatch('hello world'), true);
  assert.equal(matcherStr.asymmetricMatch('hello planet'), false);
  assert.equal(matchesPattern('world', 'hello world'), true);
  assert.equal(matchesPattern('world', 'hello planet'), false);

  // 2. StringMatching accepts RegExp patterns and matches with regular expression flags
  const matcherRegex = new StringMatching(/^hello\s+[a-z]+$/i);
  assert.equal(matcherRegex.asymmetricMatch('Hello WORLD'), true);
  assert.equal(matcherRegex.asymmetricMatch('Goodbye WORLD'), false);
  assert.equal(matchesPattern(/test-\d{3}/, 'test-042'), true);
  assert.equal(matchesPattern(/test-\d{3}/, 'test-abc'), false);

  // 3. StringMatching throws Error when instantiated with non-string and non-RegExp expected values
  assert.throws(
    () => new StringMatching(123),
    {
      name: 'Error',
      message: 'Expected is not a String or a RegExp'
    }
  );
  assert.throws(
    () => new StringMatching(null),
    {
      name: 'Error',
      message: 'Expected is not a String or a RegExp'
    }
  );
  assert.throws(
    () => new StringMatching({}),
    {
      name: 'Error',
      message: 'Expected is not a String or a RegExp'
    }
  );

  // 4. asymmetricMatch returns false when the matching candidate is not a string
  assert.equal(matcherStr.asymmetricMatch(123), false);
  assert.equal(matcherStr.asymmetricMatch(null), false);
  assert.equal(matcherStr.asymmetricMatch(undefined), false);
  assert.equal(matcherStr.asymmetricMatch({ text: 'world' }), false);
  assert.equal(matcherStr.asymmetricMatch(['world']), false);

  // 5. StringMatching supports inverse matching when the inverse flag is true
  const inverseMatcher = new StringMatching('forbidden', true);
  assert.equal(inverseMatcher.asymmetricMatch('allowed content'), true);
  assert.equal(inverseMatcher.asymmetricMatch('contains forbidden content'), false);
  assert.equal(inverseMatcher.asymmetricMatch(12345), true);
  assert.equal(matchesPattern('forbidden', 'allowed content', true), true);
  assert.equal(matchesPattern('forbidden', 'contains forbidden content', true), false);

  // 6. toString returns StringMatching for standard matchers and StringNotMatching for inverted matchers
  const normalMatcher = createStringMatcher('abc');
  const invertedMatcher = createStringMatcher('abc', true);
  assert.equal(normalMatcher.toString(), 'StringMatching');
  assert.equal(invertedMatcher.toString(), 'StringNotMatching');

  // 7. getExpectedType returns string as the expected type indicator
  assert.equal(normalMatcher.getExpectedType(), 'string');
  assert.equal(invertedMatcher.getExpectedType(), 'string');

  // 8. StringMatching integrates with Vitest equals for deep asymmetric assertions on objects and arrays
  assert.equal(checkEquals('success', 'operation status: success'), true);
  assert.equal(checkEquals('success', 'operation status: failure'), false);

  const actualPayload = {
    id: 101,
    status: 'ok',
    traceId: 'trace-98765-prod'
  };
  const expectedStructure = {
    id: 101,
    status: 'ok',
    traceId: new StringMatching(/^trace-\d+-\w+$/)
  };
  assert.equal(equals(actualPayload, expectedStructure), true);

  const actualList = ['apple', 'order-2026-xyz', 'banana'];
  const expectedList = ['apple', new StringMatching(/^order-\d{4}/), 'banana'];
  assert.equal(equals(actualList, expectedList), true);

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

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