@vitest/runner 4.1.11: describe

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

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:ca9a24cc420ada706db9ebd127e99a54c6b29c6b763c6a2871ea9550989b62c3","contract":["describe defines named test suites and nested suite hierarchies","describe.skip marks a test suite and its child tasks with skip mode","describe.only executes the focused suite and skips unselected sibling suites","describe.todo defines pending placeholder suites with todo mode and state","describe.each generates parameterized suites for each entry in a data table","describe.skipIf and describe.runIf conditionally toggle suite execution based on boolean flags","describe.concurrent and describe.shuffle configure suite concurrency and shuffle execution flags"],"goal":"verify @vitest/runner.describe in pkg:npm/%40vitest/runner@4.1.11","kind":"HOW","packages":["pkg:npm/%40vitest/runner@4.1.11"],"schemaVersion":1,"symbols":["@vitest/runner.describe"]},"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.describe"],"verifierAdapter":"node-typescript@1"}

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

/**
 * Creates an in-memory VitestRunner configuration for programmatic test execution.
 *
 * @param {Function} importHandler - Function or async function executing suite definitions
 * @param {Object} [configOverrides] - Additional runner config options
 * @returns {Object} Configured VitestRunner 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 a test suite definition using @vitest/runner startTests.
 *
 * @param {Function} suiteDefinition - Function defining describe/it blocks
 * @param {string} [specName='spec.test.js'] - Virtual spec file name
 * @param {Object} [configOverrides] - Optional runner configuration overrides
 * @returns {Promise<Array>} Array of executed File task results
 */
export async function runSuite(suiteDefinition, specName = 'spec.test.js', configOverrides = {}) {
  const runner = createRunner(async () => {
    suiteDefinition();
  }, configOverrides);

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

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

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

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

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

// 0. Module and package verification
{
  const pkg = require('@vitest/runner/package.json');
  assert.equal(pkg.name, '@vitest/runner');
  assert.equal(pkg.version, '4.1.11');

  assert.equal(typeof describe, 'function');
  assert.equal(typeof suite, 'function');
  assert.equal(describe, suite, 'suite must be an alias for describe');
  assert.equal(typeof describe.skip, 'function');
  assert.equal(typeof describe.only, 'function');
  assert.equal(typeof describe.todo, 'function');
  assert.equal(typeof describe.each, 'function');
  assert.equal(typeof describe.skipIf, 'function');
  assert.equal(typeof describe.runIf, 'function');
  assert.equal(typeof describe.concurrent, 'function');
  assert.equal(typeof describe.shuffle, 'function');
}

// 1. describe defines named test suites and nested suite hierarchies
{
  const files = await runSuite(() => {
    describe('Parent Suite', () => {
      describe('Child Suite', () => {
        it('nested test case', () => {
          assert.equal(1 + 1, 2);
        });
      });
      it('direct test case', () => {
        assert.equal(true, true);
      });
    });
  }, 'hierarchy.spec.js');

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

  const parentSuite = files[0].tasks[0];
  assert.equal(parentSuite.type, 'suite');
  assert.equal(parentSuite.name, 'Parent Suite');
  assert.equal(parentSuite.result?.state, 'pass');
  assert.equal(parentSuite.tasks.length, 2);

  const childSuite = parentSuite.tasks[0];
  assert.equal(childSuite.type, 'suite');
  assert.equal(childSuite.name, 'Child Suite');
  assert.equal(childSuite.result?.state, 'pass');
  assert.equal(childSuite.tasks.length, 1);

  const nestedTest = childSuite.tasks[0];
  assert.equal(nestedTest.name, 'nested test case');
  assert.equal(nestedTest.result?.state, 'pass');

  const directTest = parentSuite.tasks[1];
  assert.equal(directTest.name, 'direct test case');
  assert.equal(directTest.result?.state, 'pass');
}

// 2. describe.skip marks a test suite and its child tasks with skip mode
{
  let innerExecuted = false;
  const files = await runSuite(() => {
    describe.skip('Skipped Suite', () => {
      it('should not execute', () => {
        innerExecuted = true;
      });
    });
    describe('Active Sibling Suite', () => {
      it('should execute', () => {});
    });
  }, 'skipped.spec.js');

  assert.equal(innerExecuted, false);
  assert.equal(files[0].result?.state, 'pass');

  const skippedSuite = files[0].tasks[0];
  assert.equal(skippedSuite.name, 'Skipped Suite');
  assert.equal(skippedSuite.mode, 'skip');
  assert.equal(skippedSuite.result?.state, 'skip');

  const childTask = skippedSuite.tasks[0];
  assert.equal(childTask.mode, 'skip');

  const activeSuite = files[0].tasks[1];
  assert.equal(activeSuite.name, 'Active Sibling Suite');
  assert.equal(activeSuite.mode, 'run');
  assert.equal(activeSuite.result?.state, 'pass');
}

// 3. describe.only executes the focused suite and skips unselected sibling suites
{
  let unselectedRan = false;
  let focusedRan = false;

  const files = await runSuite(() => {
    describe('Unselected Suite', () => {
      it('should be skipped when sibling uses only', () => {
        unselectedRan = true;
      });
    });

    describe.only('Focused Suite', () => {
      it('should run because it is selected with only', () => {
        focusedRan = true;
      });
    });
  }, 'only.spec.js');

  assert.equal(unselectedRan, false);
  assert.equal(focusedRan, true);

  const unselectedSuite = files[0].tasks[0];
  const focusedSuite = files[0].tasks[1];

  assert.equal(unselectedSuite.name, 'Unselected Suite');
  assert.equal(unselectedSuite.mode, 'skip');
  assert.equal(unselectedSuite.result?.state, 'skip');

  assert.equal(focusedSuite.name, 'Focused Suite');
  assert.equal(focusedSuite.mode, 'run');
  assert.equal(focusedSuite.result?.state, 'pass');
}

// 4. describe.todo defines pending placeholder suites with todo mode and state
{
  const files = await runSuite(() => {
    describe.todo('Pending Feature Suite', () => {
      it('planned test', () => {});
    });
  }, 'todo.spec.js');

  assert.equal(files[0].result?.state, 'skip');

  const todoSuite = files[0].tasks[0];
  assert.equal(todoSuite.name, 'Pending Feature Suite');
  assert.equal(todoSuite.type, 'suite');
  assert.equal(todoSuite.mode, 'todo');

  const todoChild = todoSuite.tasks[0];
  assert.equal(todoChild.name, 'planned test');
  assert.equal(todoChild.mode, 'todo');
}

// 5. describe.each generates parameterized suites for each entry in a data table
{
  const table = [
    { input: 2, expected: 4 },
    { input: 3, expected: 9 },
    { input: 5, expected: 25 },
  ];

  const executedSquares = [];
  const files = await runSuite(() => {
    describe.each(table)('square($input)', ({ input, expected }) => {
      it(`calculates ${expected}`, () => {
        const sq = input * input;
        assert.equal(sq, expected);
        executedSquares.push(sq);
      });
    });
  }, 'each.spec.js');

  assert.deepEqual(executedSquares, [4, 9, 25]);
  assert.equal(files[0].tasks.length, 3);

  for (let i = 0; i < table.length; i++) {
    const s = files[0].tasks[i];
    assert.equal(s.name, `square(${table[i].input})`);
    assert.equal(s.result?.state, 'pass');
    assert.equal(s.tasks[0].name, `calculates ${table[i].expected}`);
    assert.equal(s.tasks[0].result?.state, 'pass');
  }
}

// 6. describe.skipIf and describe.runIf conditionally toggle suite execution based on boolean flags
{
  const files = await runSuite(() => {
    describe.skipIf(true)('skipIf True Suite', () => {
      it('noop', () => {});
    });
    describe.skipIf(false)('skipIf False Suite', () => {
      it('noop', () => {});
    });
    describe.runIf(true)('runIf True Suite', () => {
      it('noop', () => {});
    });
    describe.runIf(false)('runIf False Suite', () => {
      it('noop', () => {});
    });
  }, 'conditional.spec.js');

  const [skipIfTrue, skipIfFalse, runIfTrue, runIfFalse] = files[0].tasks;

  assert.equal(skipIfTrue.mode, 'skip');
  assert.equal(skipIfTrue.result?.state, 'skip');

  assert.equal(skipIfFalse.mode, 'run');
  assert.equal(skipIfFalse.result?.state, 'pass');

  assert.equal(runIfTrue.mode, 'run');
  assert.equal(runIfTrue.result?.state, 'pass');

  assert.equal(runIfFalse.mode, 'skip');
  assert.equal(runIfFalse.result?.state, 'skip');
}

// 7. describe.concurrent and describe.shuffle configure suite concurrency and shuffle execution flags
{
  const files = await runSuite(() => {
    describe.concurrent('Concurrent Suite', () => {
      it('concurrent test', () => {});
    });
    describe.shuffle('Shuffled Suite', () => {
      it('shuffled test', () => {});
    });
  }, 'flags.spec.js');

  const concurrentSuite = files[0].tasks[0];
  const shuffledSuite = files[0].tasks[1];

  assert.equal(concurrentSuite.concurrent, true);
  assert.equal(concurrentSuite.result?.state, 'pass');

  assert.equal(shuffledSuite.shuffle, true);
  assert.equal(shuffledSuite.result?.state, 'pass');
}

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