npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@zokugun/vitest-toolkit

v0.2.0

Published

A toolkit for vitest

Readme

@zokugun/vitest-toolkit

License: MIT NPM Version NodeJS Version Modules Ko-fi Liberapay PayPal

This toolkit provides utilities for vitest

Features

  • YAML Fixtures: Generate tests automatically from external configuration files.
  • Virtual Filesystem: Use in-memory storage to avoid slow disk I/O.
  • Output Validation: Compare resulting file content against expected values.
  • Error Testing: Verify that specific error messages are thrown as defined.

Installation

npm add @zokugun/vitest-toolkit

Requirements

  • Node.js: v18.20 or higher
  • Modules: ECMAScript Modules (ESM)

Quick Start

API Reference

Functions

The fixture-based test helpers read YAML files from test/fixtures/. Use fixture to select a subdirectory. The shared FixtureOptions shown below represents the fixture selection, timeout, and validation options accepted by these helpers.

defineGroupedTests

Creates a Vitest describe group for each YAML fixture. Each fixture must contain an array of manifest objects; each object generates an individual test.

function defineGroupedTests<Manifest extends Record<string, unknown>>(
  action: (manifest: Manifest) => MaybePromise<void>,
  options?: {
    fixture?: (basename: string) => boolean;
    groupName?: (basename: string) => string;
    testName?: (manifest: Manifest) => string;
  }
): Promise<void>;

By default, the group name is the fixture filename without its first extension, and each test name comes from manifest.name.

defineTestsWithValue

Runs an action for each fixture and passes its result and manifest to a test callback.

function defineTestsWithValue<Manifest extends Record<string, unknown>, Value>(
  action: (manifest: Manifest) => MaybePromise<Value>,
  assert: (value: Value, manifest: Manifest) => MaybePromise<void>,
  options?: FixtureOptions
): Promise<void>;

defineTestsWithResult

Tests an action that returns a Result. A fixture with a top-level error string is expected to fail; otherwise, assertSuccess checks the successful value. Use assertFailure to customize failure assertions.

function defineTestsWithResult<Manifest extends Record<string, unknown>, Value>(
  action: (manifest: Manifest) => MaybePromise<Result<Value, unknown>>,
  assertSuccess: (value: Value, manifest: Manifest) => MaybePromise<void>,
  options?: FixtureOptions & {
    assertFailure?: (error: unknown, manifest: Manifest) => MaybePromise<void>;
  }
): Promise<void>;

defineTestsWithFiles

Runs an action in a temporary working directory and checks expected files after it completes. Fixture keys use /input/<path> for input files and /output/<path> for expected output files. An output value can be { error: "..." } to assert that the file is missing with that error.

function defineTestsWithFiles(
  action: (manifest: Record<string, unknown>, root: string) => MaybePromise<void>,
  options?: FileFixtureOptions
): Promise<void>;

defineTestsWithExec

Runs an action in a temporary working directory and verifies its ExecResult. A fixture's top-level error string checks for a failed result and matching fatal output; output checks stdout; otherwise success and expected output files are checked.

function defineTestsWithExec(
  action: (manifest: Record<string, unknown>, root: string) => MaybePromise<ExecResult | undefined>,
  options?: FileFixtureOptions & { stripAnsi?: boolean }
): Promise<void>;

defineTestsWithCommand

Runs a command for each fixture using defineTestsWithExec. The command receives the optional name followed by any string arguments in manifest.args, runs in the fixture's temporary directory, and gets stdin from manifest.input.

function defineTestsWithCommand(
  command: Command,
  name: string | null | undefined,
  commandOptions?: Partial<CommandOptions>,
  options?: FileFixtureOptions & { stripAnsi?: boolean }
): Promise<void>;

Command and CommandOptions are provided by @zokugun/exec-lite. The file fixture options extend these common fixture options:

type FixtureOptions = {
  fixture?: string;
  timeout?: number;
  validate?: (name: string, manifest: Record<string, unknown>) => boolean;
};

type FileFixtureOptions = FixtureOptions & {
  input?: string;
  output?: string;
  transformFile?: (
    type: 'additional' | 'input' | 'output',
    path: string,
    content: string
  ) => string;
};

defineTestsWithInMemoryFiles

Generates Vitest tests using an in-memory filesystem. Each YAML fixture maps to one test case.

function defineTestsWithInMemoryFiles(
  action: (manifest: Record<string, unknown>) => MaybePromise<void>,
  options?: FixtureOptions & FileFixtureOptions & { additionals?: string[] }
): Promise<void>;

Options:

| Property | Type | Default | Description | |---|---|---|---| | fixture | string | '' | Fixture directory name under test/fixtures/ | | timeout | number | — | Vitest test timeout | | validate | (name, manifest) => boolean | () => true | Select fixtures to run | | input | string | 'input' | Key prefix for input files in YAML | | output | string | 'output' | Key prefix for expected output files in YAML | | additionals | string[] | [] | Extra key prefixes to treat as input files | | transformFile | (type, path, content) => string | identity | Transform file content before loading into the mock FS |

YAML manifest format:

# Test name is derived from the .yml filename without its extension
/input/some-file.txt: "file contents"
/output/result.txt: "expected output"
error: "expected error message" # optional; if present, the test expects a throw

Input files are loaded into the in-memory filesystem at /working/<path>. Output keys are checked after action() runs. Additional input prefixes are loaded at their original virtual paths.

If the manifest contains a top-level error string, the test expects action(manifest) to reject with that message. Otherwise it checks output files exist and match expected content.

Set DEBUG=1 or DEBUG=vol in your environment to log filesystem state before/after the action runs.


mockForInMemoryFiles / unmockForInMemoryFiles

Replaces real file system and process modules with an in-memory mock for testing CLI tools.

function mockForInMemoryFiles(workingDirectory?: string): void;
function unmockForInMemoryFiles(): void;

mockForInMemoryFiles() swaps:

  • node:fs / node:fs/promises → memfs-backed mock
  • node:process → fake process with cwd() set to workingDirectory (default /working) and empty env
  • @zokugun/cli-utils → stripped logger that swallows output, throws on fatal, logs to console when DEBUG is set

Call mockForInMemoryFiles() before your test suite and unmockForInMemoryFiles() after.

Caveat: These use vi.doMock / vi.doUnmock, which only affect modules loaded after the mock is set. If a module was already imported before calling mockForInMemoryFiles(), it won't be affected. Call these at the top of your test file or in beforeEach.


makeTempDir / withTemp

makeTempDir() creates and returns a temporary directory path. withTemp() runs an asynchronous callback in a temporary directory and removes it afterward, even if the callback fails.

function makeTempDir(): Promise<string>;
function withTemp(run: (root: string) => Promise<void>): Promise<void>;
await withTemp(async (root) => {
  // process.cwd() is root
});

Exec matchers

The package installs these Vitest/Chai matchers when imported:

| Matcher | Assertion | |---|---| | toFail() / toSucceed() | A Result is failed or successful | | toExitWith(code) | An ExecResult has the given exit code (number or null) | | toHaveStdout(expected) / toHaveStderr(expected) | Output contains a string or matches a regular expression |

Mocks

mocks.memfs.fs

A drop-in replacement for Node's standard fs module, backed entirely by memory. Use it when you need manual control over the virtual filesystem.

mocks.stdin

Creates a readable stdin stream from a string or an array of strings. The tokens <up>, <down>, <enter>, and <escape> are encoded as terminal key sequences.

Contributions

Contributions are most welcome. Please:

  • Open issues and feature requests under the repository discussions.
  • Follow the CONTRIBUTING.md.

Donations

Support this project by becoming a financial contributor.

License

Copyright © 2026-present Baptiste Augrain

Licensed under the MIT license.