@vitest/expect 2.1.9: StringContaining

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

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:9e9563b5aa5ffd8638b7f86c1fa847c87a74e72258ba12ef59288b669d35c3e6","contract":["assert StringContaining constructor creates an asymmetric matcher instance with sample and inverse properties","assert StringContaining matches strings containing expected substring regardless of position","assert StringContaining rejects strings missing expected substring","assert StringContaining rejects non-string values including numbers, objects, booleans, null, and undefined","assert StringContaining with inverse flag inverts match results via StringNotContaining toString","assert StringContaining supports nested data structures and integrates with equals"],"goal":"verify @vitest/expect.StringContaining in pkg:npm/%40vitest/expect@2.1.9","kind":"HOW","packages":["pkg:npm/%40vitest/expect@2.1.9"],"schemaVersion":1,"symbols":["@vitest/expect.StringContaining"]},"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.StringContaining"],"verifierAdapter":"node-typescript@1"}

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

/**
 * Creates a StringContaining asymmetric matcher instance.
 *
 * @param {string} sample - Expected substring that must be present in the target string.
 * @param {boolean} [inverse=false] - Whether to invert the matching logic.
 * @returns {StringContaining} The asymmetric matcher instance.
 */
export function createStringContaining(sample, inverse = false) {
  return new StringContaining(sample, inverse);
}

/**
 * Evaluates whether a received value satisfies the StringContaining condition.
 *
 * @param {unknown} received - The value under test.
 * @param {string} sample - Expected substring.
 * @param {boolean} [inverse=false] - Whether to invert the matching logic.
 * @returns {boolean} True if the matching condition passes.
 */
export function matchesStringContaining(received, sample, inverse = false) {
  const matcher = new StringContaining(sample, inverse);
  return matcher.asymmetricMatch(received);
}

/**
 * Evaluates structural equality of a data structure containing matchers.
 *
 * @param {unknown} actual - The actual data structure.
 * @param {unknown} expected - The expected structure containing asymmetric matchers.
 * @returns {boolean} True if values match structurally.
 */
export function matchStructure(actual, expected) {
  return equals(actual, expected);
}

export { StringContaining, equals };

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

import assert from 'node:assert/strict';
import {
  StringContaining,
  equals,
  createStringContaining,
  matchesStringContaining,
  matchStructure,
} from '../index.mjs';

async function runContract() {
  // 1. assert StringContaining constructor creates an asymmetric matcher instance with sample and inverse properties
  const matcher = createStringContaining('expected');
  assert.strictEqual(matcher instanceof StringContaining, true);
  assert.strictEqual(matcher.toString(), 'StringContaining');
  assert.strictEqual(matcher.getExpectedType(), 'string');
  assert.strictEqual(matcher.sample, 'expected');
  assert.strictEqual(matcher.inverse, false);

  const invMatcher = createStringContaining('expected', true);
  assert.strictEqual(invMatcher instanceof StringContaining, true);
  assert.strictEqual(invMatcher.toString(), 'StringNotContaining');
  assert.strictEqual(invMatcher.inverse, true);

  // 2. assert StringContaining matches strings containing expected substring regardless of position
  assert.strictEqual(matcher.asymmetricMatch('expected'), true);
  assert.strictEqual(matcher.asymmetricMatch('prefixed expected'), true);
  assert.strictEqual(matcher.asymmetricMatch('expected postfixed'), true);
  assert.strictEqual(matcher.asymmetricMatch('prefixed expected postfixed'), true);
  assert.strictEqual(matchesStringContaining('abc expected xyz', 'expected'), true);

  const emptyMatcher = new StringContaining('');
  assert.strictEqual(emptyMatcher.asymmetricMatch(''), true);
  assert.strictEqual(emptyMatcher.asymmetricMatch('any string value'), true);

  // 3. assert StringContaining rejects strings missing expected substring
  assert.strictEqual(matcher.asymmetricMatch('other value'), false);
  assert.strictEqual(matcher.asymmetricMatch('EXPECTED'), false);
  assert.strictEqual(matcher.asymmetricMatch(''), false);
  assert.strictEqual(matchesStringContaining('completely different', 'expected'), false);

  // 4. assert StringContaining rejects non-string values including numbers, objects, booleans, null, and undefined
  assert.strictEqual(matcher.asymmetricMatch(12345), false);
  assert.strictEqual(matcher.asymmetricMatch({ text: 'expected' }), false);
  assert.strictEqual(matcher.asymmetricMatch(['expected']), false);
  assert.strictEqual(matcher.asymmetricMatch(true), false);
  assert.strictEqual(matcher.asymmetricMatch(false), false);
  assert.strictEqual(matcher.asymmetricMatch(null), false);
  assert.strictEqual(matcher.asymmetricMatch(undefined), false);
  assert.strictEqual(matcher.asymmetricMatch(Symbol('expected')), false);

  // 5. assert StringContaining with inverse flag inverts match results via StringNotContaining toString
  assert.strictEqual(invMatcher.toString(), 'StringNotContaining');
  assert.strictEqual(invMatcher.asymmetricMatch('prefixed expected postfixed'), false);
  assert.strictEqual(invMatcher.asymmetricMatch('completely different'), true);
  assert.strictEqual(invMatcher.asymmetricMatch(12345), true);
  assert.strictEqual(invMatcher.asymmetricMatch(null), true);
  assert.strictEqual(invMatcher.asymmetricMatch(undefined), true);
  assert.strictEqual(matchesStringContaining('different string', 'expected', true), true);
  assert.strictEqual(matchesStringContaining('contains expected string', 'expected', true), false);

  // 6. assert StringContaining supports nested data structures and integrates with equals
  const payload = {
    statusCode: 200,
    message: 'Operation succeeded with status: OK',
    details: {
      url: 'https://example.com/api/v1/resource',
      error: null,
    },
  };
  const expectedStructure = {
    statusCode: 200,
    message: new StringContaining('status: OK'),
    details: {
      url: new StringContaining('/api/v1/'),
      error: null,
    },
  };
  assert.strictEqual(matchStructure(payload, expectedStructure), true);
  assert.strictEqual(equals(payload, expectedStructure), true);

  const mismatchedPayload = {
    statusCode: 200,
    message: 'Operation failed with status: ERROR',
    details: {
      url: 'https://example.com/api/v1/resource',
      error: null,
    },
  };
  assert.strictEqual(equals(mismatchedPayload, expectedStructure), false);

  const arrayPayload = ['item-alpha-123', 'item-beta-456'];
  const expectedArray = [new StringContaining('alpha'), new StringContaining('beta')];
  assert.strictEqual(equals(arrayPayload, expectedArray), true);

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

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