@vitest/runner 4.1.10: suite

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

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

import { startTests, suite, describe, it, test } 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 suite 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 {
  suite,
  describe,
  it,
  test,
  startTests,
};

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

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';
import {
  suite,
  describe,
  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.10');

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

// 1. suite defines named test suites and nested suite hierarchies as an alias of describe
{
  const files = await runSuite(() => {
    suite('Root Suite', () => {
      suite('Nested Child Suite', () => {
        it('inner test case', () => {
          assert.equal(2 * 3, 6);
        });
      });
      it('direct test case', () => {
        assert.equal(true, true);
      });
    });
  }, 'suite-hierarchy.spec.js');

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

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

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

  const innerTest = nestedChild.tasks[0];
  assert.equal(innerTest.name, 'inner test case');
  assert.equal(innerTest.result?.state, 'pass');

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

// 2. suite.skip marks a test suite and its child tasks with skip mode
{
  let skippedBodyRan = false;
  const files = await runSuite(() => {
    suite.skip('Ignored Suite', () => {
      it('must not run', () => {
        skippedBodyRan = true;
      });
    });
    suite('Active Suite', () => {
      it('must run', () => {});
    });
  }, 'suite-skip.spec.js');

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

  const skippedSuite = files[0].tasks[0];
  assert.equal(skippedSuite.name, 'Ignored 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 Suite');
  assert.equal(activeSuite.mode, 'run');
  assert.equal(activeSuite.result?.state, 'pass');
}

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

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

    suite.only('Target Suite', () => {
      it('should execute when marked with only', () => {
        focusedRan = true;
      });
    });
  }, 'suite-only.spec.js');

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

  const unfocusedSuite = files[0].tasks[0];
  const targetSuite = files[0].tasks[1];

  assert.equal(unfocusedSuite.name, 'Unfocused Suite');
  assert.equal(unfocusedSuite.mode, 'skip');
  assert.equal(unfocusedSuite.result?.state, 'skip');

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

// 4. suite.todo defines pending placeholder suites with todo mode and state
{
  const files = await runSuite(() => {
    suite.todo('Upcoming Features Suite', () => {
      it('future test', () => {});
    });
  }, 'suite-todo.spec.js');

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

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

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

// 5. suite.each generates parameterized suites for each entry in a data table
{
  const matrix = [
    { a: 3, b: 4, sum: 7 },
    { a: 10, b: 20, sum: 30 },
  ];

  const calculatedSums = [];
  const files = await runSuite(() => {
    suite.each(matrix)('sum($a, $b)', ({ a, b, sum }) => {
      it(`evaluates sum as ${sum}`, () => {
        const result = a + b;
        assert.equal(result, sum);
        calculatedSums.push(result);
      });
    });
  }, 'suite-each.spec.js');

  assert.deepEqual(calculatedSums, [7, 30]);
  assert.equal(files[0].tasks.length, 2);

  for (let i = 0; i < matrix.length; i++) {
    const s = files[0].tasks[i];
    assert.equal(s.name, `sum(${matrix[i].a}, ${matrix[i].b})`);
    assert.equal(s.result?.state, 'pass');
    assert.equal(s.tasks[0].name, `evaluates sum as ${matrix[i].sum}`);
    assert.equal(s.tasks[0].result?.state, 'pass');
  }
}

// 6. suite.skipIf and suite.runIf conditionally toggle suite execution based on boolean flags
{
  const files = await runSuite(() => {
    suite.skipIf(true)('skipIf True Suite', () => {
      it('noop', () => {});
    });
    suite.skipIf(false)('skipIf False Suite', () => {
      it('noop', () => {});
    });
    suite.runIf(true)('runIf True Suite', () => {
      it('noop', () => {});
    });
    suite.runIf(false)('runIf False Suite', () => {
      it('noop', () => {});
    });
  }, 'suite-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. suite.concurrent and suite.shuffle configure suite concurrency and shuffle execution flags
{
  const files = await runSuite(() => {
    suite.concurrent('Concurrent Suite', () => {
      it('concurrent test', () => {});
    });
    suite.shuffle('Shuffled Suite', () => {
      it('shuffled test', () => {});
    });
  }, 'suite-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.suite contract assertions passed.');