@vitest/mocker 3.2.7: AutomockedModule

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/mocker.AutomockedModule in pkg:npm/%40vitest/mocker@3.2.7
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40vitest/mocker@3.2.7
Demonstrate these symbols/APIs:
  - @vitest/mocker.AutomockedModule

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:2380c772b9da197146672ed1d94b4f79c8180fed022e5d367c78b1ae8e008654","contract":["AutomockedModule instantiation sets type to 'automock' and preserves raw, id, url properties","AutomockedModule.toJSON returns structured object with type, raw, id, and url","MockerRegistry registers automocked module and retrieves it by URL and ID","MockerRegistry adds standalone AutomockedModule and deletes entries","MockerRegistry throws TypeError on invalid arguments when registering automock","Passing an existing AutomockedModule instance to registry.register throws TypeError"],"goal":"verify @vitest/mocker.AutomockedModule in pkg:npm/%40vitest/mocker@3.2.7","kind":"HOW","packages":["pkg:npm/%40vitest/mocker@3.2.7"],"schemaVersion":1,"symbols":["@vitest/mocker.AutomockedModule"]},"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","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40vitest/mocker@3.2.7"],"schemaVersion":1,"subject":"pkg:npm/%40vitest/mocker@3.2.7","symbols":["@vitest/mocker.AutomockedModule"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-vitest-mocker-automocked-module",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-vitest-mocker-automocked-module",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@vitest/mocker": "3.2.7"
      }
    },
    "node_modules/@jridgewell/sourcemap-codec": {
      "version": "1.5.5",
      "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz",
      "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==",
      "license": "MIT"
    },
    "node_modules/@types/estree": {
      "version": "1.0.9",
      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",
      "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==",
      "license": "MIT"
    },
    "node_modules/@vitest/mocker": {
      "version": "3.2.7",
      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-3.2.7.tgz",
      "integrity": "sha512-Trr0hYO9CM3Wj6ksWHRhK9IZpIY6wTMO5u/MqXurMxT57sWBaOPEtP3Oq60ihZuh5JsiagKfz95OcxdEP6dBrA==",
      "license": "MIT",
      "dependencies": {
        "@vitest/spy": "3.2.7",
        "estree-walker": "^3.0.3",
        "magic-string": "^0.30.17"
      },
      "funding": {
        "url": "https://opencollective.com/vitest"
      },
      "peerDependencies": {
        "msw": "^2.4.9",
        "vite": "^5.0.0 || ^6.0.0 || ^7.0.0-0"
      },
      "peerDependenciesMeta": {
        "msw": {
          "optional": true
        },
        "vite": {
          "optional": true
        }
      }
    },
    "node_modules/@vitest/spy": {
      "version": "3.2.7",
      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-3.2.7.tgz",
      "integrity": "sha512-Q2eQGI6d2L/hBtZ0qNuKcAGid68XK6cv1xsoaIma6PaJhHPoqcEJhYpXZ/5myCMqkNgtP6UKuBhbc0nHKnrkuQ==",
      "license": "MIT",
      "dependencies": {
        "tinyspy": "^4.0.3"
      },
      "funding": {
        "url": "https://opencollective.com/vitest"
      }
    },
    "node_modules/estree-walker": {
      "version": "3.0.3",
      "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
      "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",
      "license": "MIT",
      "dependencies": {
        "@types/estree": "^1.0.0"
      }
    },
    "node_modules/magic-string": {
      "version": "0.30.21",
      "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
      "integrity": "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==",
      "license": "MIT",
      "dependencies": {
        "@jridgewell/sourcemap-codec": "^1.5.5"
      }
    },
    "node_modules/tinyspy": {
      "version": "4.0.4",
      "resolved": "https://registry.npmjs.org/tinyspy/-/tinyspy-4.0.4.tgz",
      "integrity": "sha512-azl+t0z7pw/z958Gy9svOTuzqIk6xq+NSheJzn5MMWtWTFywIacg2wUlzKFGtt3cthx0r2SxMK0yzJOR0IES7Q==",
      "license": "MIT",
      "engines": {
        "node": ">=14.0.0"
      }
    }
  }
}

{
  "name": "sample-vitest-mocker-automocked-module",
  "version": "1.0.0",
  "description": "Clean-room sample verifying @vitest/mocker AutomockedModule",
  "type": "module",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "@vitest/mocker": "3.2.7"
  }
}

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

import { AutomockedModule, MockerRegistry } from '@vitest/mocker';

/**
 * Creates an instance of AutomockedModule with raw specifier, resolved ID, and URL.
 *
 * @param {string} raw - The raw module specifier.
 * @param {string} id - The resolved filesystem ID or path.
 * @param {string} url - The resolved module URL.
 * @returns {AutomockedModule} The automocked module descriptor.
 */
export function createAutomockedModule(raw, id, url) {
  return new AutomockedModule(raw, id, url);
}

/**
 * Serializes an AutomockedModule instance to its plain JSON representation.
 *
 * @param {AutomockedModule} mock - The automocked module instance.
 * @returns {{ type: string, raw: string, id: string, url: string }} The serialized representation.
 */
export function serializeAutomockedModule(mock) {
  return mock.toJSON();
}

/**
 * Registers an automocked module into a MockerRegistry instance.
 *
 * @param {MockerRegistry} registry - The mocker registry.
 * @param {string} raw - The raw module specifier.
 * @param {string} id - The resolved module ID.
 * @param {string} url - The resolved module URL.
 * @returns {AutomockedModule} The registered mock module.
 */
export function registerAutomock(registry, raw, id, url) {
  return registry.register('automock', raw, id, url);
}

export { AutomockedModule, MockerRegistry };

import assert from 'node:assert';
import {
  AutomockedModule,
  MockerRegistry,
  createAutomockedModule,
  serializeAutomockedModule,
  registerAutomock,
} from '../src/index.js';

async function runContract() {
  const rawSpecifier = 'mock-module';
  const resolvedId = '/virtual/modules/mock-module.js';
  const resolvedUrl = 'file:///virtual/modules/mock-module.js';

  // 1. AutomockedModule instantiation sets type to 'automock' and preserves raw, id, url properties
  const mock = createAutomockedModule(rawSpecifier, resolvedId, resolvedUrl);
  assert.strictEqual(mock.type, 'automock', 'mock type must be "automock"');
  assert.strictEqual(mock.raw, rawSpecifier, 'mock raw specifier must match');
  assert.strictEqual(mock.id, resolvedId, 'mock id must match');
  assert.strictEqual(mock.url, resolvedUrl, 'mock url must match');

  // 2. AutomockedModule.toJSON returns structured object with type, raw, id, and url
  const serialized = serializeAutomockedModule(mock);
  assert.deepStrictEqual(
    serialized,
    {
      type: 'automock',
      url: resolvedUrl,
      raw: rawSpecifier,
      id: resolvedId,
    },
    'serialized output must match expected JSON shape'
  );

  // 3. MockerRegistry registers automocked module and retrieves it by URL and ID
  const registry = new MockerRegistry();
  const registeredMock = registerAutomock(registry, rawSpecifier, resolvedId, resolvedUrl);
  assert.ok(registeredMock instanceof AutomockedModule, 'registered mock must be an instance of AutomockedModule');
  assert.strictEqual(registry.has(resolvedUrl), true, 'registry.has must return true for registered url');
  assert.strictEqual(registry.get(resolvedUrl), registeredMock, 'registry.get must return the registered mock');
  assert.strictEqual(registry.getById(resolvedId), registeredMock, 'registry.getById must return the registered mock');

  // 4. MockerRegistry adds standalone AutomockedModule and deletes entries
  const secondMock = new AutomockedModule('second-pkg', '/virtual/second.js', 'file:///virtual/second.js');
  registry.add(secondMock);
  assert.strictEqual(registry.get('file:///virtual/second.js'), secondMock, 'registry.add must store the mock');
  registry.delete('file:///virtual/second.js');
  assert.strictEqual(registry.has('file:///virtual/second.js'), false, 'registry.has must return false after delete');
  assert.strictEqual(registry.get('file:///virtual/second.js'), undefined, 'registry.get must return undefined after delete');

  // 5. MockerRegistry throws TypeError on invalid arguments when registering automock
  assert.throws(
    () => registry.register('automock', 123, resolvedId, resolvedUrl),
    TypeError,
    'registry.register must throw TypeError if raw is not a string'
  );
  assert.throws(
    () => registry.register('automock', rawSpecifier, 123, resolvedUrl),
    TypeError,
    'registry.register must throw TypeError if id is not a string'
  );
  assert.throws(
    () => registry.register('automock', rawSpecifier, resolvedId, 123),
    TypeError,
    'registry.register must throw TypeError if url is not a string'
  );

  // 6. Passing an existing AutomockedModule instance to registry.register throws TypeError
  assert.throws(
    () => registry.register(mock),
    TypeError,
    'registry.register must throw TypeError when passing existing mock instance'
  );

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

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