@vitest/runner 4.1.11: it

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

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

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:007d97aae66160f59a52568d9f17397a59ee5f76c825016ff720b7c2a30b9294","contract":["it registers and executes standard synchronous and asynchronous test cases","it receives task context with task metadata and custom context properties","it.skip marks a test case with skip mode without executing the test body","it.todo marks a test case with todo mode as an unimplemented specification","it.fails expects test body failure and passes when an error is thrown","it.each generates parameterized test cases for each entry in a table"],"goal":"verify @vitest/runner.it in pkg:npm/%40vitest/runner@4.1.11","kind":"HOW","packages":["pkg:npm/%40vitest/runner@4.1.11"],"schemaVersion":1,"symbols":["@vitest/runner.it"]},"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.11"],"schemaVersion":1,"subject":"pkg:npm/%40vitest/runner@4.1.11","symbols":["@vitest/runner.it"],"verifierAdapter":"node-typescript@1"}

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

/**
 * Creates a VitestRunner-compatible configuration object 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: 'in-memory-runner',
      passWithNoTests: true,
      testNamePattern: undefined,
      allowOnly: true,
      sequence: {
        seed: 12345,
        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 suite definition using @vitest/runner startTests.
 *
 * @param {Function} suiteDefinition - Function defining describe/it blocks
 * @param {string} [specName='spec.test.js'] - Virtual test spec name
 * @param {Object} [configOverrides] - Optional runner configuration overrides
 * @returns {Promise<Array>} Array of collected and executed File tasks
 */
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-it",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-vitest-runner-it",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@vitest/runner": "4.1.11"
      }
    },
    "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/runner": {
      "version": "4.1.11",
      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.11.tgz",
      "integrity": "sha512-LztvUgdwMNJMIkj3hQnnxiC2Xy1zNxq928W/xhjCLaNCzqTZOudjwbQf6v9IntZGPw132i2Lq2rgTRZHD3JHNw==",
      "license": "MIT",
      "dependencies": {
        "@vitest/utils": "4.1.11",
        "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/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-it",
  "version": "1.0.0",
  "description": "Clean-room verification sample for @vitest/runner it",
  "type": "module",
  "private": true,
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@vitest/runner": "4.1.11"
  }
}

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

import assert from 'node:assert/strict';
import {
  runSuite,
  it,
} from '../index.mjs';

// 1. it registers and executes standard synchronous and asynchronous test cases
{
  const events = [];
  const files = await runSuite(() => {
    it('synchronous test execution', () => {
      events.push('sync');
    });

    it('asynchronous test execution', async () => {
      await new Promise((resolve) => setTimeout(resolve, 5));
      events.push('async');
    });
  }, 'standard.test.js');

  assert.equal(files.length, 1);
  assert.equal(files[0].result?.state, 'pass');
  assert.equal(files[0].tasks.length, 2);
  assert.equal(files[0].tasks[0].name, 'synchronous test execution');
  assert.equal(files[0].tasks[0].result?.state, 'pass');
  assert.equal(files[0].tasks[1].name, 'asynchronous test execution');
  assert.equal(files[0].tasks[1].result?.state, 'pass');
  assert.deepEqual(events, ['sync', 'async']);
}

// 2. it receives task context with task metadata and custom context properties
{
  let contextTaskName = null;
  const files = await runSuite(() => {
    it('task context inspection', (context) => {
      assert.ok(context.task, 'context should include task');
      contextTaskName = context.task.name;
    });
  }, 'context.test.js');

  assert.equal(files.length, 1);
  assert.equal(files[0].result?.state, 'pass');
  assert.equal(contextTaskName, 'task context inspection');
}

// 3. it.skip marks a test case with skip mode without executing the test body
{
  let executed = false;
  const files = await runSuite(() => {
    it.skip('skipped test case', () => {
      executed = true;
    });
  }, 'skip.test.js');

  assert.equal(files.length, 1);
  assert.equal(files[0].tasks.length, 1);
  assert.equal(files[0].tasks[0].mode, 'skip');
  assert.equal(files[0].tasks[0].result?.state, undefined);
  assert.equal(executed, false);
}

// 4. it.todo marks a test case with todo mode as an unimplemented specification
{
  const files = await runSuite(() => {
    it.todo('unimplemented feature specification');
  }, 'todo.test.js');

  assert.equal(files.length, 1);
  assert.equal(files[0].tasks.length, 1);
  assert.equal(files[0].tasks[0].mode, 'todo');
  assert.equal(files[0].tasks[0].result?.state, undefined);
}

// 5. it.fails expects test body failure and passes when an error is thrown
{
  let executed = false;
  const files = await runSuite(() => {
    it.fails('failing test passes when assertion fails', () => {
      executed = true;
      throw new Error('expected intentional test failure');
    });
  }, 'fails.test.js');

  assert.equal(files.length, 1);
  assert.equal(files[0].result?.state, 'pass');
  assert.equal(files[0].tasks.length, 1);
  assert.equal(files[0].tasks[0].result?.state, 'pass');
  assert.equal(executed, true);
}

// 6. it.each generates parameterized test cases for each entry in a table
{
  const accumulated = [];
  const files = await runSuite(() => {
    it.each([
      [1, 2, 3],
      [4, 5, 9],
    ])('adds %i and %i to %i', (a, b, expected) => {
      assert.equal(a + b, expected);
      accumulated.push(expected);
    });
  }, 'each.test.js');

  assert.equal(files.length, 1);
  assert.equal(files[0].result?.state, 'pass');
  assert.equal(files[0].tasks.length, 2);
  assert.equal(files[0].tasks[0].result?.state, 'pass');
  assert.equal(files[0].tasks[1].result?.state, 'pass');
  assert.deepEqual(accumulated, [3, 9]);
}

console.log('All @vitest/runner.it contract assertions passed successfully.');