@vitest/runner 4.1.10: startTests

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

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:638cd729e6c97bdbcbb39ac9f1ba1df50a4fd0516c26216bf5002a715273652e","contract":["startTests accepts test file specifications and a runner instance, executes collected tests, and returns an array of File objects","startTests records pass or fail task results with execution state and duration for executed test cases","startTests invokes runner lifecycle hooks including onBeforeCollect, onCollectStart, onCollected, onBeforeRunFiles, onBeforeRunTask, onAfterRunTask, and onAfterRunFiles in exact lifecycle order","startTests awaits completion of asynchronous test functions before completing task execution","startTests executes nested describe and suite blocks and preserves task hierarchy in the returned File results","startTests captures thrown exceptions in failed tasks and marks task and suite state as fail with error details","startTests accepts FileSpecification objects specifying custom file paths and file metadata"],"goal":"verify @vitest/runner.startTests in pkg:npm/%40vitest/runner@4.1.10","kind":"HOW","packages":["pkg:npm/%40vitest/runner@4.1.10"],"schemaVersion":1,"symbols":["@vitest/runner.startTests"]},"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.startTests"],"verifierAdapter":"node-typescript@1"}

import {
  startTests,
  describe,
  it,
  test,
  suite,
  beforeAll,
  afterAll,
  beforeEach,
  afterEach,
} from "@vitest/runner";

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

/**
 * Runs test specifications with the Vitest runner.
 *
 * @param {Array<string|Object>} specs - Array of file paths or file specifications
 * @param {Object} runner - VitestRunner instance
 * @returns {Promise<Array>} Array of executed File result objects
 */
export async function runStartTests(specs, runner) {
  return await startTests(specs, runner);
}

export {
  startTests,
  describe,
  it,
  test,
  suite,
  beforeAll,
  afterAll,
  beforeEach,
  afterEach,
};

{
  "name": "sample-vitest-runner-starttests",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-vitest-runner-starttests",
      "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-starttests",
  "version": "1.0.0",
  "description": "Clean-room verification of @vitest/runner.startTests in @vitest/runner@4.1.10",
  "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.startTests in pkg:npm/%40vitest/runner@4.1.10",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40vitest/runner@4.1.10"
  ],
  "symbols": [
    "@vitest/runner.startTests"
  ]
}

import assert from "node:assert/strict";
import {
  startTests,
  createRunner,
  test,
  describe,
  it,
  suite,
} from "../index.mjs";

async function main() {
  // Assertion 1: startTests accepts test file specifications and a runner instance, executes collected tests, and returns an array of File objects
  {
    const runner = createRunner(() => {
      test("basic test", () => {
        assert.equal(1 + 1, 2);
      });
    });

    const files = await startTests(["spec-basic.js"], runner);
    assert.ok(Array.isArray(files));
    assert.equal(files.length, 1);
    assert.equal(files[0].filepath, "spec-basic.js");
    assert.equal(files[0].tasks.length, 1);
    assert.equal(files[0].tasks[0].name, "basic test");
    console.log("Assertion 1 passed");
  }

  // Assertion 2: startTests records pass or fail task results with execution state and duration for executed test cases
  {
    const runner = createRunner(() => {
      test("passing task", () => {
        assert.ok(true);
      });
    });

    const files = await startTests(["spec-result.js"], runner);
    const task = files[0].tasks[0];
    assert.equal(task.result?.state, "pass");
    assert.equal(typeof task.result?.duration, "number");
    assert.equal(files[0].result?.state, "pass");
    console.log("Assertion 2 passed");
  }

  // Assertion 3: startTests invokes runner lifecycle hooks including onBeforeCollect, onCollectStart, onCollected, onBeforeRunFiles, onBeforeRunTask, onAfterRunTask, and onAfterRunFiles in exact lifecycle order
  {
    const lifecycle = [];
    const runner = createRunner(
      () => {
        test("monitored task", () => {
          lifecycle.push("execute task");
        });
      },
      {
        onBeforeCollect(paths) {
          lifecycle.push(`onBeforeCollect:${paths.join(",")}`);
        },
        onCollectStart(file) {
          lifecycle.push(`onCollectStart:${file.name}`);
        },
        onCollected(files) {
          lifecycle.push(`onCollected:${files.length}`);
        },
        onBeforeRunFiles(files) {
          lifecycle.push(`onBeforeRunFiles:${files.length}`);
        },
        onBeforeRunTask(task) {
          lifecycle.push(`onBeforeRunTask:${task.name}`);
        },
        onAfterRunTask(task) {
          lifecycle.push(`onAfterRunTask:${task.name}:${task.result?.state}`);
        },
        onAfterRunFiles(files) {
          lifecycle.push(`onAfterRunFiles:${files.length}`);
        },
      }
    );

    const files = await startTests(["lifecycle.spec.js"], runner);
    assert.equal(files[0].result?.state, "pass");
    assert.deepEqual(lifecycle, [
      "onBeforeCollect:lifecycle.spec.js",
      "onCollectStart:lifecycle.spec.js",
      "onCollected:1",
      "onBeforeRunFiles:1",
      "onBeforeRunTask:monitored task",
      "execute task",
      "onAfterRunTask:monitored task:pass",
      "onAfterRunFiles:1",
    ]);
    console.log("Assertion 3 passed");
  }

  // Assertion 4: startTests awaits completion of asynchronous test functions before completing task execution
  {
    let asyncCompleted = false;
    const runner = createRunner(() => {
      test("async task", async () => {
        await new Promise((resolve) => setTimeout(resolve, 25));
        asyncCompleted = true;
      });
    });

    const files = await startTests(["async.spec.js"], runner);
    assert.equal(asyncCompleted, true);
    assert.equal(files[0].tasks[0].result?.state, "pass");
    assert.ok(files[0].tasks[0].result?.duration >= 20);
    console.log("Assertion 4 passed");
  }

  // Assertion 5: startTests executes nested describe and suite blocks and preserves task hierarchy in the returned File results
  {
    const runner = createRunner(() => {
      describe("parent suite", () => {
        suite("child suite", () => {
          it("hierarchical test", () => {
            assert.ok(true);
          });
        });
      });
    });

    const files = await startTests(["hierarchy.spec.js"], runner);
    const parentSuite = files[0].tasks[0];
    assert.equal(parentSuite.type, "suite");
    assert.equal(parentSuite.name, "parent suite");
    const childSuite = parentSuite.tasks[0];
    assert.equal(childSuite.type, "suite");
    assert.equal(childSuite.name, "child suite");
    const testTask = childSuite.tasks[0];
    assert.equal(testTask.type, "test");
    assert.equal(testTask.name, "hierarchical test");
    assert.equal(testTask.result?.state, "pass");
    assert.equal(parentSuite.result?.state, "pass");
    console.log("Assertion 5 passed");
  }

  // Assertion 6: startTests captures thrown exceptions in failed tasks and marks task and suite state as fail with error details
  {
    const runner = createRunner(() => {
      describe("suite with deliberate failure", () => {
        test("passing test", () => {});
        test("failing test", () => {
          throw new Error("Deliberate error for startTests contract verification");
        });
      });
    });

    const files = await startTests(["failure.spec.js"], runner);
    const suiteTask = files[0].tasks[0];
    assert.equal(suiteTask.result?.state, "fail");
    assert.equal(suiteTask.tasks[0].result?.state, "pass");
    assert.equal(suiteTask.tasks[1].result?.state, "fail");
    assert.ok(suiteTask.tasks[1].result?.errors?.length > 0);
    assert.match(
      suiteTask.tasks[1].result.errors[0].message,
      /Deliberate error for startTests contract verification/
    );
    console.log("Assertion 6 passed");
  }

  // Assertion 7: startTests accepts FileSpecification objects specifying custom file paths and file metadata
  {
    const runner = createRunner(() => {
      test("custom spec test", () => {
        assert.equal(typeof "sample", "string");
      });
    });

    const spec = {
      filepath: "custom-file-spec.test.js",
      fileTags: [],
    };
    const files = await startTests([spec], runner);
    assert.equal(files.length, 1);
    assert.equal(files[0].filepath, "custom-file-spec.test.js");
    assert.equal(files[0].tasks[0].result?.state, "pass");
    console.log("Assertion 7 passed");
  }

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

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