@vitest/runner 4.1.10: beforeEach

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

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:67fa054bb07a81a718753a60a866ef12249fde9791be600547ae7fb727df23e0","constraints":{"executionContext":"node"},"contract":["beforeEach registers a setup hook that executes once before each test in a suite","errors thrown in beforeEach prevent the test body from running and mark the test task as failed","multiple beforeEach hooks execute sequentially in registration order before each test","beforeEach supports asynchronous setup functions and startTests awaits their completion before starting the test","nested suite beforeEach hooks execute enclosing parent suite hooks before child hooks for each test","beforeEach receives a TestContext object providing task metadata and lifecycle utilities","beforeEach can extend or mutate the TestContext to share state with the following test","beforeEach supports returning a teardown cleanup function that executes after test completion","beforeEach accepts a custom timeout and fails the test when execution exceeds that limit"],"goal":"verify @vitest/runner.beforeEach in pkg:npm/%40vitest/runner@4.1.10","kind":"HOW","packages":["pkg:npm/%40vitest/runner@4.1.10"],"schemaVersion":1,"symbols":["@vitest/runner.beforeEach"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","runtime":"node","runtimeVersion":"22.23.2","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.beforeEach"],"verifierAdapter":"node-typescript@1"}

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

/**
 * Creates a minimal VitestRunner instance configured for in-memory 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: "vitest-runner-beforeeach",
      passWithNoTests: true,
      testNamePattern: undefined,
      allowOnly: true,
      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,
    },
    importFile: async (filepath) => {
      if (typeof importHandler === "function") {
        await importHandler(filepath);
      }
    },
  };
}

/**
 * Executes an in-memory suite definition using @vitest/runner startTests.
 *
 * @param {Function} suiteDefinition - Function defining describe/test/beforeEach blocks
 * @param {string} [specName='spec.test.js'] - Virtual test spec name
 * @param {Object} [configOverrides] - Optional runner configuration 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 {
  startTests,
  describe,
  it,
  test,
  suite,
  beforeAll,
  afterAll,
  beforeEach,
  afterEach,
};

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

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

// 1. Exported symbol verification
{
  assert.equal(typeof beforeEach, "function", "beforeEach must be an exported function");
  assert.equal(typeof runSuite, "function", "runSuite helper must be an exported function");
  assert.equal(typeof createRunner, "function", "createRunner must be an exported function");
}

// 2. beforeEach registers a setup hook that executes once before each test in a suite
{
  const events = [];
  const files = await runSuite(() => {
    describe("Suite 1", () => {
      beforeEach((context) => {
        events.push(`beforeEach:${context.task.name}`);
      });
      test("test 1", () => {
        events.push("test-1");
      });
      test("test 2", () => {
        events.push("test-2");
      });
    });
  }, "suite1.test.js");

  assert.equal(files.length, 1);
  assert.equal(files[0].result?.state, "pass");
  assert.deepEqual(events, [
    "beforeEach:test 1",
    "test-1",
    "beforeEach:test 2",
    "test-2",
  ]);
}

// 3. errors thrown in beforeEach prevent the test body from running and mark the test task as failed
{
  const events = [];
  const files = await runSuite(() => {
    describe("Suite with throwing beforeEach", () => {
      beforeEach(() => {
        events.push("throwing-hook");
        throw new Error("setup error in beforeEach hook");
      });
      test("should be skipped", () => {
        events.push("test-body-ran");
      });
    });
  }, "suite-fail.test.js");

  const task = files[0].tasks[0].tasks[0];
  assert.equal(task.result?.state, "fail");
  assert.ok(task.result?.errors && task.result.errors.length > 0);
  assert.match(task.result.errors[0].message, /setup error in beforeEach hook/);
  assert.deepEqual(events, ["throwing-hook"]);
}

// 4. multiple beforeEach hooks execute sequentially in registration order before each test
{
  const events = [];
  await runSuite(() => {
    describe("Hook ordering", () => {
      beforeEach(() => {
        events.push("first-hook");
      });
      beforeEach(() => {
        events.push("second-hook");
      });
      test("run test", () => {
        events.push("test");
      });
    });
  }, "order.test.js");

  assert.deepEqual(events, ["first-hook", "second-hook", "test"]);
}

// 5. beforeEach supports asynchronous setup functions and startTests awaits their completion before starting the test
{
  let asyncFinished = false;
  const files = await runSuite(() => {
    describe("Async setup", () => {
      beforeEach(async () => {
        await new Promise((resolve) => setTimeout(resolve, 20));
        asyncFinished = true;
      });
      test("async test", () => {
        assert.equal(asyncFinished, true);
      });
    });
  }, "async.test.js");

  assert.equal(files[0].result?.state, "pass");
  assert.equal(asyncFinished, true);
}

// 6. nested suite beforeEach hooks execute enclosing parent suite hooks before child hooks for each test
{
  const events = [];
  const files = await runSuite(() => {
    describe("Parent Suite", () => {
      beforeEach(() => {
        events.push("parent-beforeEach");
      });
      describe("Child Suite", () => {
        beforeEach(() => {
          events.push("child-beforeEach");
        });
        test("child test", () => {
          events.push("child-test");
        });
      });
      test("parent test", () => {
        events.push("parent-test");
      });
    });
  }, "nested.test.js");

  assert.equal(files[0].result?.state, "pass");
  assert.deepEqual(events, [
    "parent-beforeEach",
    "child-beforeEach",
    "child-test",
    "parent-beforeEach",
    "parent-test",
  ]);
}

// 7. beforeEach receives a TestContext object providing task metadata and lifecycle utilities
{
  let capturedTaskName = null;
  let hasSignal = false;
  const files = await runSuite(() => {
    describe("Context Suite", () => {
      beforeEach((context) => {
        capturedTaskName = context.task?.name;
        hasSignal = typeof context.signal === "object" && context.signal !== null;
      });
      test("context validation test", () => {
        assert.ok(true);
      });
    });
  }, "context.test.js");

  assert.equal(files[0].result?.state, "pass");
  assert.equal(capturedTaskName, "context validation test");
  assert.equal(hasSignal, true);
}

// 8. beforeEach can extend or mutate the TestContext to share state with the following test
{
  const files = await runSuite(() => {
    describe("State sharing Suite", () => {
      beforeEach((context) => {
        context.injectedValue = "initialized-state";
      });
      test("reads injected state", (context) => {
        assert.equal(context.injectedValue, "initialized-state");
      });
    });
  }, "state.test.js");

  assert.equal(files[0].result?.state, "pass");
}

// 9. beforeEach supports returning a teardown cleanup function that executes after test completion
{
  const events = [];
  const files = await runSuite(() => {
    describe("Cleanup Suite", () => {
      beforeEach(() => {
        events.push("setup");
        return () => {
          events.push("teardown");
        };
      });
      test("cleanup test", () => {
        events.push("test");
      });
    });
  }, "cleanup.test.js");

  assert.equal(files[0].result?.state, "pass");
  assert.deepEqual(events, ["setup", "test", "teardown"]);
}

// 10. beforeEach accepts a custom timeout and fails the test when execution exceeds that limit
{
  const files = await runSuite(() => {
    describe("Suite with timed out beforeEach", () => {
      beforeEach(async () => {
        await new Promise((resolve) => setTimeout(resolve, 60));
      }, 10);
      test("fast test", () => {
        assert.ok(true);
      });
    });
  }, "timeout-beforeeach.test.js");

  const task = files[0].tasks[0].tasks[0];
  assert.equal(task.result?.state, "fail");
  assert.ok(task.result?.errors && task.result.errors.length > 0);
  assert.match(task.result.errors[0].message, /Hook timed out in 10ms/);
}

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