@vitest/snapshot 4.1.11: NodeSnapshotEnvironment

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

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:788fa9b5b0b5f55963985f680b10eb1dab017296f3884d17a13febcb41412a38","contract":["NodeSnapshotEnvironment instantiates with default and custom options and returns snapshot version and header","NodeSnapshotEnvironment resolves snapshot path with default and custom snapshot directory names","NodeSnapshotEnvironment resolves raw snapshot paths for relative and absolute paths","NodeSnapshotEnvironment saves reads and removes snapshot files and prepares directories","SnapshotState creates snapshot state backed by NodeSnapshotEnvironment"],"goal":"verify @vitest/snapshot.NodeSnapshotEnvironment in pkg:npm/%40vitest/snapshot@4.1.11","kind":"HOW","packages":["pkg:npm/%40vitest/snapshot@4.1.11"],"schemaVersion":1,"symbols":["@vitest/snapshot.NodeSnapshotEnvironment"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","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.NodeSnapshotEnvironment"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-vitest-snapshot-node-snapshot-environment",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-vitest-snapshot-node-snapshot-environment",
      "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-node-snapshot-environment",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "@vitest/snapshot": "4.1.11"
  }
}

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

import { NodeSnapshotEnvironment } from "@vitest/snapshot/environment";

export function createSnapshotEnvironment(options) {
  return new NodeSnapshotEnvironment(options);
}

export async function resolveSnapshotPath(env, filepath) {
  return env.resolvePath(filepath);
}

export async function resolveRawSnapshotPath(env, testPath, rawPath) {
  return env.resolveRawPath(testPath, rawPath);
}

export async function writeAndReadSnapshot(env, filepath, content) {
  await env.saveSnapshotFile(filepath, content);
  return env.readSnapshotFile(filepath);
}

export async function deleteSnapshot(env, filepath) {
  return env.removeSnapshotFile(filepath);
}

export { NodeSnapshotEnvironment };

import assert from "node:assert/strict";
import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { NodeSnapshotEnvironment } from "@vitest/snapshot/environment";
import { SnapshotState } from "@vitest/snapshot";
import {
  createSnapshotEnvironment,
  resolveSnapshotPath,
  resolveRawSnapshotPath,
  writeAndReadSnapshot,
  deleteSnapshot
} from "../src/index.mjs";

// Test 1: NodeSnapshotEnvironment instantiates with default and custom options and returns snapshot version and header
{
  const defaultEnv = createSnapshotEnvironment();
  assert.equal(defaultEnv instanceof NodeSnapshotEnvironment, true);
  assert.equal(defaultEnv.getVersion(), "1");
  assert.equal(defaultEnv.getHeader(), "// Snapshot v1");

  const customEnv = new NodeSnapshotEnvironment({ snapshotsDirName: "__custom_snapshots__" });
  assert.equal(customEnv instanceof NodeSnapshotEnvironment, true);
  assert.equal(customEnv.getVersion(), "1");
  assert.equal(customEnv.getHeader(), "// Snapshot v1");
}

// Test 2: NodeSnapshotEnvironment resolves snapshot path with default and custom snapshot directory names
{
  const defaultEnv = new NodeSnapshotEnvironment();
  const testFile = "/workspace/project/tests/example.test.js";
  const resolvedDefault = await resolveSnapshotPath(defaultEnv, testFile);
  assert.equal(resolvedDefault, "/workspace/project/tests/__snapshots__/example.test.js.snap");

  const customEnv = new NodeSnapshotEnvironment({ snapshotsDirName: "snaps" });
  const resolvedCustom = await customEnv.resolvePath(testFile);
  assert.equal(resolvedCustom, "/workspace/project/tests/snaps/example.test.js.snap");
}

// Test 3: NodeSnapshotEnvironment resolves raw snapshot paths for relative and absolute paths
{
  const env = new NodeSnapshotEnvironment();
  const testFile = "/workspace/project/tests/suite.test.js";

  const relPath = "fixtures/output.json";
  const resolvedRel = await resolveRawSnapshotPath(env, testFile, relPath);
  assert.equal(resolvedRel, "/workspace/project/tests/fixtures/output.json");

  const absPath = "/workspace/shared/fixtures/golden.json";
  const resolvedAbs = await env.resolveRawPath(testFile, absPath);
  assert.equal(resolvedAbs, absPath);
}

// Test 4: NodeSnapshotEnvironment saves reads and removes snapshot files and prepares directories
{
  const env = new NodeSnapshotEnvironment();
  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "vitest-snap-test-"));
  const snapFilePath = path.join(tempDir, "subdir", "component.test.js.snap");

  try {
    // Reading non-existent file returns null
    const initialContent = await env.readSnapshotFile(snapFilePath);
    assert.equal(initialContent, null);

    // Prepare directory creates path recursively
    const newDir = path.join(tempDir, "nested", "dir");
    await env.prepareDirectory(newDir);
    const dirStat = await fs.stat(newDir);
    assert.equal(dirStat.isDirectory(), true);

    // Save and read snapshot file
    const sampleSnapshot = "// Snapshot v1\n\nexports[`test 1`] = `42`;\n";
    const readBack = await writeAndReadSnapshot(env, snapFilePath, sampleSnapshot);
    assert.equal(readBack, sampleSnapshot);

    // Remove snapshot file
    await deleteSnapshot(env, snapFilePath);
    const afterDelete = await env.readSnapshotFile(snapFilePath);
    assert.equal(afterDelete, null);

    // Removing non-existent file is a no-op and does not throw
    await env.removeSnapshotFile(snapFilePath);
  } finally {
    await fs.rm(tempDir, { recursive: true, force: true });
  }
}

// Test 5: SnapshotState creates snapshot state backed by NodeSnapshotEnvironment
{
  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "vitest-state-test-"));
  const testFilePath = path.join(tempDir, "example.spec.js");
  const env = new NodeSnapshotEnvironment();

  try {
    const snapshotState = await SnapshotState.create(testFilePath, {
      updateSnapshot: "all",
      snapshotEnvironment: env
    });

    assert.equal(snapshotState.environment, env);
    assert.equal(
      snapshotState.snapshotPath,
      path.join(tempDir, "__snapshots__", "example.spec.js.snap")
    );
  } finally {
    await fs.rm(tempDir, { recursive: true, force: true });
  }
}

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