@vitest/snapshot 4.1.11: SnapshotState

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/snapshot.SnapshotState in pkg:npm/%40vitest/snapshot@4.1.11
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40vitest/snapshot@4.1.11
Demonstrate these symbols/APIs:
  - @vitest/snapshot.SnapshotState
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:77667a44a8ea7913a40add3efbf6808cc4268a06a876859ab6831b4d6ad3f9ed","constraints":{"executionContext":"node"},"contract":["SnapshotState.create initializes a state with given testFilePath and snapshot environment options","SnapshotState.prototype.match records new snapshots and increments added counter when updating snapshots","SnapshotState.prototype.match verifies matching snapshot values and records mismatches","SnapshotState.prototype.save persists snapshot file content via the snapshot environment","SnapshotState.prototype.pack returns structured summary with added, matched, unmatched, and unchecked counts"],"goal":"verify @vitest/snapshot.SnapshotState in pkg:npm/%40vitest/snapshot@4.1.11","kind":"HOW","packages":["pkg:npm/%40vitest/snapshot@4.1.11"],"schemaVersion":1,"symbols":["@vitest/snapshot.SnapshotState"]},"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/snapshot@4.1.11"],"schemaVersion":1,"subject":"pkg:npm/%40vitest/snapshot@4.1.11","symbols":["@vitest/snapshot.SnapshotState"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-vitest-snapshot-snapshot-state",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-vitest-snapshot-snapshot-state",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@vitest/snapshot": "4.1.11"
      }
    },
    "node_modules/@jridgewell/sourcemap-codec": {
      "version": "1.6.0",
      "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.6.0.tgz",
      "integrity": "sha512-T7jf+5zgsZHwNJ4lvQ7/aezbyk0nNX+zJVWpmHA7VYsEx7a7qr5Rg5IbtJFqkgze5Y2sruq1RUY8Q837Od7iFw==",
      "license": "MIT"
    },
    "node_modules/@vitest/pretty-format": {
      "version": "4.1.11",
      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.11.tgz",
      "integrity": "sha512-yiZzPbGTS9Sr/JpFl8zHrcIkAofNbFV6k21vIgQN/cY/oxZeXhJv5sc/MBJ5jFKWmWs+oJHw0UXLZjmf931+Vw==",
      "license": "MIT",
      "dependencies": {
        "tinyrainbow": "^3.1.0"
      },
      "funding": {
        "url": "https://opencollective.com/vitest"
      }
    },
    "node_modules/@vitest/snapshot": {
      "version": "4.1.11",
      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.11.tgz",
      "integrity": "sha512-pN7ikn1ON7h8ee4gIAp4AzyK+zBtJPzVbqOgu5LCEh4VaJVbPQcgYQYJIMGQPXVeJJq1fnfazis7a5pFNPahog==",
      "license": "MIT",
      "dependencies": {
        "@vitest/pretty-format": "4.1.11",
        "@vitest/utils": "4.1.11",
        "magic-string": "^0.30.21",
        "pathe": "^2.0.3"
      },
      "funding": {
        "url": "https://opencollective.com/vitest"
      }
    },
    "node_modules/@vitest/utils": {
      "version": "4.1.11",
      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.11.tgz",
      "integrity": "sha512-zTCVGpyFsGWBhllOyKlTw/vnr6D9qxsfSDyfbyZmTyjHw5N/VuvzHpHoQjm2ZJzn4RJgx5w4r7V0er69CmLgPQ==",
      "license": "MIT",
      "dependencies": {
        "@vitest/pretty-format": "4.1.11",
        "convert-source-map": "^2.0.0",
        "tinyrainbow": "^3.1.0"
      },
      "funding": {
        "url": "https://opencollective.com/vitest"
      }
    },
    "node_modules/convert-source-map": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz",
      "integrity": "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==",
      "license": "MIT"
    },
    "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/pathe": {
      "version": "2.0.3",
      "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
      "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
      "license": "MIT"
    },
    "node_modules/tinyrainbow": {
      "version": "3.1.1",
      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-3.1.1.tgz",
      "integrity": "sha512-yau8yJdTt989Mm0Bd/236QnzEiPf2xLLTqUZRUJOo/3CB078LSwzei343DgtJVmfJKJE3TMINY1u42SQsP6mXw==",
      "license": "MIT",
      "engines": {
        "node": ">=14.0.0"
      }
    }
  }
}

{
  "name": "sample-vitest-snapshot-snapshot-state",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "@vitest/snapshot": "4.1.11"
  }
}

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

import { SnapshotState } from "@vitest/snapshot";

export async function createSnapshotState(testFilePath, options) {
  return await SnapshotState.create(testFilePath, options);
}

export function matchSnapshot(state, options) {
  return state.match(options);
}

export async function saveSnapshotState(state) {
  return await state.save();
}

export async function packSnapshotResult(state) {
  return await state.pack();
}

export { SnapshotState };

import assert from "node:assert/strict";
import { SnapshotState } from "@vitest/snapshot";
import {
  createSnapshotState,
  matchSnapshot,
  saveSnapshotState,
  packSnapshotResult
} from "../src/index.mjs";

function createInMemorySnapshotEnvironment() {
  const store = new Map();
  return {
    store,
    env: {
      getVersion: () => "1",
      getHeader: () => "// Vitest Snapshot v1\n",
      resolveRawPath: async (testPath, rawPath) => `${testPath}.${rawPath}`,
      resolvePath: async (filepath) => `${filepath}.snap`,
      prepareDirectory: async () => {},
      saveSnapshotFile: async (filepath, snapshot) => {
        store.set(filepath, snapshot);
      },
      readSnapshotFile: async (filepath) => {
        return store.get(filepath) || null;
      },
      removeSnapshotFile: async (filepath) => {
        store.delete(filepath);
      },
    },
  };
}

// Test 1: SnapshotState.create initializes a state with given testFilePath and snapshot environment options
{
  const { env } = createInMemorySnapshotEnvironment();
  const testFilePath = "/workspace/example.test.js";
  const state = await createSnapshotState(testFilePath, {
    updateSnapshot: "all",
    snapshotEnvironment: env,
  });

  assert.equal(state instanceof SnapshotState, true);
  assert.equal(state.testFilePath, testFilePath);
  assert.equal(state.snapshotPath, `${testFilePath}.snap`);
  assert.equal(state.added.total(), 0);
  assert.equal(state.matched.total(), 0);
  assert.equal(state.unmatched.total(), 0);
}

// Test 2: SnapshotState.prototype.match records new snapshots and increments added counter when updating snapshots
{
  const { env } = createInMemorySnapshotEnvironment();
  const testFilePath = "/workspace/example.test.js";
  const state = await createSnapshotState(testFilePath, {
    updateSnapshot: "all",
    snapshotEnvironment: env,
  });

  const result = matchSnapshot(state, {
    testId: "suite > test1",
    testName: "suite > test1",
    received: { status: "success", count: 3 },
    isInline: false,
  });

  assert.equal(result.pass, true);
  assert.equal(result.key, "suite > test1 1");
  assert.equal(state.added.total(), 1);
  assert.equal(state.matched.total(), 0);
}

// Test 3: SnapshotState.prototype.match verifies matching snapshot values and records mismatches
{
  const { env } = createInMemorySnapshotEnvironment();
  const testFilePath = "/workspace/example.test.js";

  // First pass: create and save snapshot
  const state1 = await createSnapshotState(testFilePath, {
    updateSnapshot: "all",
    snapshotEnvironment: env,
  });
  state1.match({
    testId: "suite > test2",
    testName: "suite > test2",
    received: { message: "hello" },
    isInline: false,
  });
  await saveSnapshotState(state1);

  // Second pass: load saved snapshot with updateSnapshot: "none"
  const state2 = await createSnapshotState(testFilePath, {
    updateSnapshot: "none",
    snapshotEnvironment: env,
  });

  // Successful match
  const matchResult = state2.match({
    testId: "suite > test2",
    testName: "suite > test2",
    received: { message: "hello" },
    isInline: false,
  });
  assert.equal(matchResult.pass, true);
  assert.equal(state2.matched.total(), 1);
  assert.equal(state2.unmatched.total(), 0);

  // Mismatching received value
  const mismatchResult = state2.match({
    testId: "suite > test2",
    testName: "suite > test2",
    received: { message: "world" },
    isInline: false,
  });
  assert.equal(mismatchResult.pass, false);
  assert.equal(state2.unmatched.total(), 1);
}

// Test 4: SnapshotState.prototype.save persists snapshot file content via the snapshot environment
{
  const { env, store } = createInMemorySnapshotEnvironment();
  const testFilePath = "/workspace/save-test.test.js";
  const state = await createSnapshotState(testFilePath, {
    updateSnapshot: "all",
    snapshotEnvironment: env,
  });

  state.match({
    testId: "test_save",
    testName: "test_save",
    received: [1, 2, 3],
    isInline: false,
  });

  const saveStatus = await saveSnapshotState(state);
  assert.equal(saveStatus.saved, true);
  assert.equal(saveStatus.deleted, false);
  assert.equal(store.has(`${testFilePath}.snap`), true);
  assert.match(store.get(`${testFilePath}.snap`), /exports\[`test_save 1`\] = `\s*\[\s*1,\s*2,\s*3,\s*\]\s*`;/);
}

// Test 5: SnapshotState.prototype.pack returns structured summary with added, matched, unmatched, and unchecked counts
{
  const { env } = createInMemorySnapshotEnvironment();
  const testFilePath = "/workspace/pack-test.test.js";
  const state = await createSnapshotState(testFilePath, {
    updateSnapshot: "all",
    snapshotEnvironment: env,
  });

  state.match({
    testId: "test_pack",
    testName: "test_pack",
    received: "test-value",
    isInline: false,
  });

  const packResult = await packSnapshotResult(state);
  assert.equal(packResult.filepath, testFilePath);
  assert.equal(packResult.added, 1);
  assert.equal(packResult.matched, 0);
  assert.equal(packResult.unmatched, 0);
  assert.equal(packResult.fileDeleted, false);
  assert.equal(Array.isArray(packResult.uncheckedKeys), true);
}

console.log("All @vitest/snapshot.SnapshotState contract tests passed successfully.");