@vitest/runner 4.1.10: test

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/runner.test in pkg:npm/%40vitest/runner@4.1.10
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40vitest/runner@4.1.10
Demonstrate these symbols/APIs:
  - @vitest/runner.test

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:7622c7867487116572f8a38de90211e0c8aedeff4bd57656feb241c3d1295a3c","contract":["test defines and executes test cases that pass when assertions succeed","test captures thrown assertion errors and records fail state with error details","test.skip marks test task with skip mode without executing the test body","test.todo defines placeholder test tasks in todo mode without execution","test.fails expects test failure and marks the task as pass when assertions throw","test.each parameterizes tests across datasets to create individual test tasks","test callback receives test context and getCurrentTest resolves the active task"],"goal":"verify @vitest/runner.test in pkg:npm/%40vitest/runner@4.1.10","kind":"HOW","packages":["pkg:npm/%40vitest/runner@4.1.10"],"schemaVersion":1,"symbols":["@vitest/runner.test"]},"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/runner@4.1.10"],"schemaVersion":1,"subject":"pkg:npm/%40vitest/runner@4.1.10","symbols":["@vitest/runner.test"],"verifierAdapter":"node-typescript@1"}

import {
  test,
  describe,
  it,
  suite,
  startTests,
  getCurrentTest,
  getCurrentSuite,
} from "@vitest/runner";

/**
 * Creates a minimal VitestRunner instance configured for programmatic test execution.
 *
 * @param {Function} importHandler - Async function called to define or import tests
 * @param {Object} [configOverrides] - Optional configuration overrides
 * @returns {Object} A VitestRunner-compatible runner object
 */
export function createRunner(importHandler, configOverrides = {}) {
  return {
    config: {
      root: process.cwd(),
      setupFiles: [],
      name: "runner-test",
      passWithNoTests: true,
      testNamePattern: undefined,
      allowOnly: true,
      sequence: {
        seed: 42,
        hooks: "stack",
        setupFiles: "list",
      },
      chaiConfig: undefined,
      maxConcurrency: 5,
      testTimeout: 5000,
      hookTimeout: 5000,
      retry: 0,
      includeTaskLocation: false,
      tags: [],
      tagsFilter: undefined,
      strictTags: false,
      ...configOverrides,
    },
    importFile: async (filepath) => {
      if (typeof importHandler === "function") {
        await importHandler(filepath);
      }
    },
  };
}

/**
 * Executes an in-memory test suite using @vitest/runner startTests.
 *
 * @param {Function} suiteDefinition - Callback defining tests and suites
 * @param {string} [specName='spec.test.js'] - Virtual test spec name
 * @param {Object} [configOverrides] - Optional runner config overrides
 * @returns {Promise<Array>} Array of executed test file results
 */
export async function runSuite(suiteDefinition, specName = "spec.test.js", configOverrides = {}) {
  const runner = createRunner(async () => {
    suiteDefinition();
  }, configOverrides);

  return await startTests([specName], runner);
}

export {
  test,
  describe,
  it,
  suite,
  startTests,
  getCurrentTest,
  getCurrentSuite,
};

{
  "name": "sample-vitest-runner-test",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-vitest-runner-test",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@vitest/runner": "4.1.10"
      }
    },
    "node_modules/@vitest/pretty-format": {
      "version": "4.1.10",
      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.10.tgz",
      "integrity": "sha512-W1HsjSH4MXQ9YfmmhLAoIYf1HRfekQCGngeIgcei6MP5QQGWUe0gkopdZQaVCFO+JDJMrAJGwa5pRpNpvy4P8Q==",
      "license": "MIT",
      "dependencies": {
        "tinyrainbow": "^3.1.0"
      },
      "funding": {
        "url": "https://opencollective.com/vitest"
      }
    },
    "node_modules/@vitest/runner": {
      "version": "4.1.10",
      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.10.tgz",
      "integrity": "sha512-IKI6kpIH+LmpROplyLwBBaCfMgOZOMsygVa6BARD6ahA04VRuJSa6OaVG7kRvSEMD870Vd91rSSw0eegtWyLGg==",
      "license": "MIT",
      "dependencies": {
        "@vitest/utils": "4.1.10",
        "pathe": "^2.0.3"
      },
      "funding": {
        "url": "https://opencollective.com/vitest"
      }
    },
    "node_modules/@vitest/utils": {
      "version": "4.1.10",
      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.10.tgz",
      "integrity": "sha512-fy9am/HWxbaGt/Sawrp90vt6Y6jQwf1RX77cz3uwoJwJVMli/e1IEwRPnMNJ7vKfPTwo0diXifkpPvwH9v7nGA==",
      "license": "MIT",
      "dependencies": {
        "@vitest/pretty-format": "4.1.10",
        "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/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-runner-test",
  "version": "1.0.0",
  "description": "Clean-room verification sample for @vitest/runner.test",
  "type": "module",
  "private": true,
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@vitest/runner": "4.1.10"
  }
}

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

import assert from "node:assert/strict";
import { createRequire } from "node:module";
import {
  test,
  describe,
  startTests,
  createRunner,
  runSuite,
  getCurrentTest,
} from "../index.mjs";

const require = createRequire(import.meta.url);

// 0. Verify package metadata and symbols
{
  const pkg = require("@vitest/runner/package.json");
  assert.equal(pkg.name, "@vitest/runner");
  assert.equal(pkg.version, "4.1.10");

  assert.equal(typeof test, "function");
  assert.equal(typeof test.skip, "function");
  assert.equal(typeof test.todo, "function");
  assert.equal(typeof test.fails, "function");
  assert.equal(typeof test.each, "function");
  assert.equal(typeof startTests, "function");
  assert.equal(typeof getCurrentTest, "function");
}

// 1. test defines and executes test cases that pass when assertions succeed
{
  let executed = false;
  const files = await runSuite(() => {
    describe("passing suite", () => {
      test("basic passing test", () => {
        executed = true;
        assert.equal(2 + 2, 4);
      });
    });
  }, "passing.test.js");

  assert.equal(executed, true, "test function should execute");
  assert.equal(files.length, 1);
  const suite = files[0].tasks[0];
  const task = suite.tasks[0];
  assert.equal(task.name, "basic passing test");
  assert.equal(task.result?.state, "pass", "successful assertion results in pass state");
  assert.equal(task.mode, "run");
}

// 2. test captures thrown assertion errors and records fail state with error details
{
  const files = await runSuite(() => {
    describe("failure suite", () => {
      test("failing assertion test", () => {
        assert.equal("actualValue", "expectedValue", "custom error message");
      });
    });
  }, "failure.test.js");

  const task = files[0].tasks[0].tasks[0];
  assert.equal(task.name, "failing assertion test");
  assert.equal(task.result?.state, "fail", "thrown assertion marks test as fail");
  assert.ok(task.result?.errors && task.result.errors.length > 0, "errors array populated");
  assert.ok(
    task.result.errors[0].message.includes("custom error message"),
    "error message preserved"
  );
}

// 3. test.skip marks test task with skip mode without executing the test body
{
  let skippedExecuted = false;
  const files = await runSuite(() => {
    describe("skip suite", () => {
      test.skip("skipped test", () => {
        skippedExecuted = true;
      });
    });
  }, "skip.test.js");

  assert.equal(skippedExecuted, false, "skipped test body must not execute");
  const task = files[0].tasks[0].tasks[0];
  assert.equal(task.name, "skipped test");
  assert.equal(task.mode, "skip", "task mode must be skip");
}

// 4. test.todo defines placeholder test tasks in todo mode without execution
{
  const files = await runSuite(() => {
    describe("todo suite", () => {
      test.todo("unimplemented feature test");
    });
  }, "todo.test.js");

  const task = files[0].tasks[0].tasks[0];
  assert.equal(task.name, "unimplemented feature test");
  assert.equal(task.mode, "todo", "task mode must be todo");
}

// 5. test.fails expects test failure and marks the task as pass when assertions throw
{
  const files = await runSuite(() => {
    describe("fails suite", () => {
      test.fails("expected failure test", () => {
        assert.equal(1, 2, "intentional failure");
      });
    });
  }, "fails.test.js");

  const task = files[0].tasks[0].tasks[0];
  assert.equal(task.name, "expected failure test");
  assert.equal(task.result?.state, "pass", "test.fails converts failure into pass state");
}

// 6. test.each parameterizes tests across datasets to create individual test tasks
{
  const cases = [
    [1, 2, 3],
    [5, 5, 10],
  ];
  const files = await runSuite(() => {
    describe("parameterized suite", () => {
      test.each(cases)("sums %i and %i to %i", (a, b, expected) => {
        assert.equal(a + b, expected);
      });
    });
  }, "each.test.js");

  const tasks = files[0].tasks[0].tasks;
  assert.equal(tasks.length, 2, "test.each should generate one task per row");
  assert.equal(tasks[0].name, "sums 1 and 2 to 3");
  assert.equal(tasks[0].result?.state, "pass");
  assert.equal(tasks[1].name, "sums 5 and 5 to 10");
  assert.equal(tasks[1].result?.state, "pass");
}

// 7. test callback receives test context and getCurrentTest resolves the active task
{
  let contextTaskName = null;
  let activeTaskName = null;

  const files = await runSuite(() => {
    describe("context suite", () => {
      test("context inspection test", (context) => {
        contextTaskName = context?.task?.name;
        const current = getCurrentTest();
        activeTaskName = current?.name;
      });
    });
  }, "context.test.js");

  assert.equal(files[0].tasks[0].tasks[0].result?.state, "pass");
  assert.equal(contextTaskName, "context inspection test", "context provides current task");
  assert.equal(activeTaskName, "context inspection test", "getCurrentTest returns current task");
}

console.log("All @vitest/runner.test contract assertions passed successfully.");