fs-fixture

library2.13.0jsnpmunverified

fs-fixture is a JavaScript/TypeScript library designed to simplify the creation and management of temporary file system fixtures for testing purposes. Currently at version 2.13.0, the library is under active development with frequent minor and patch releases, indicating a robust and responsive maintenance schedule. Key differentiators include its extremely small footprint (1.1 kB gzipped) with no external dependencies, a simple object-based API for defining file structures, automatic resource cleanup via TypeScript 5.2+ `using` keyword, and built-in support for JSON serialization/deserialization. It inherits `fs/promises` type signatures for file operations, ensuring strong type safety and familiar API patterns. The library also supports advanced features like symlinks, binary file handling with Buffers, and a pluggable filesystem interface for custom `fs/promises`-compatible implementations.

testing

npm install fs-fixture

github ↗package ↗

INSTALL

IMPORT

SIG · FS-FIXTURE

fs-fixture

testingjavascriptv2.13.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createFixture

✓ import { createFixture } from 'fs-fixture'

✗ const { createFixture } = require('fs-fixture')

fs-fixture is primarily designed for ESM environments, especially given its Node.js >=18.0.0 requirement. Named imports are correct; CommonJS `require()` may fail.

Fixture

✓ import type { Fixture } from 'fs-fixture'

This is the TypeScript interface for the object returned by `createFixture`, providing methods like `readFile`, `rm`, `path`, etc. Always import as a type.

FileTree

✓ import type { FileTree } from 'fs-fixture'

This type represents the object structure used to define the file system fixture, allowing you to specify nested files and directories.

Demonstrates creating a file system fixture with nested files, reading a file's content, writing a JSON file, and explicitly cleaning up the temporary directory.

import { createFixture } from 'fs-fixture' async function main() { // Create a temporary fixture const fixture = await createFixture({ 'package.json': JSON.stringify({ name: 'my-app' }), 'src/index.js': 'console.log("Hello world")' }) // Read files const content = await fixture.readFile('src/index.js', 'utf8') console.log('Content of src/index.js:', content); // Write a JSON file await fixture.writeJson('config.json', { port: 3000 }); console.log('config.json written.'); // Cleanup when done await fixture.rm() console.log('Fixture cleaned up.'); } main();

Debug

Known issues

gotchaResource cleanup with `fs-fixture` is asynchronous. If not using the `using` keyword, you must explicitly call `await fixture.rm()` to prevent temporary files and directories from persisting after your tests or operations complete. Forgetting this can lead to disk space consumption and unintended side effects in subsequent runs.

fix

Always use `await fixture.rm()` in a `finally` block or utilize the `await using fixture = ...` syntax (requires TypeScript 5.2+ and compatible runtime) for automatic disposal.

affects: >=2.0.0

breakingfs-fixture requires Node.js version >=18.0.0. Using the package with older Node.js versions may lead to runtime errors due to reliance on modern Node.js APIs and ECMAScript module (ESM) features.

fix

Ensure your project's Node.js runtime is version 18 or higher. Update `nvm use 18` or adjust CI/CD configurations accordingly.

affects: >=2.0.0

gotchaThe `using` keyword for automatic resource management is a TypeScript 5.2+ feature. If your project uses an older TypeScript version or a Node.js runtime that does not yet fully support Explicit Resource Management (ERM), this syntax will cause compilation or runtime errors.

fix

Upgrade TypeScript to 5.2 or later. If using Node.js, ensure you're running a version with stable ERM support, or explicitly call `await fixture.rm()` instead.

affects: >=2.0.0

gotchaWhile `fs-fixture` can accept a custom `fs/promises`-compatible API for virtual filesystems, template directory sources (string paths) are generally not supported with custom filesystems as most virtual `fs` implementations lack recursive copy (`cp`) functionality.

fix

When using a custom `fs` option, always define your fixture structure using a `FileTree` object instead of a string path to an existing directory.

affects: >=2.13.0

Errors

Common errors & fixes

TypeError: (intermediate value).createFixture is not a function

Attempting to import `createFixture` using CommonJS `require()` syntax in a project that is configured for ES modules, or if the package itself is ESM-only.

fix

Ensure your project uses ES modules (`"type": "module"` in `package.json`) and import `createFixture` using `import { createFixture } from 'fs-fixture'`.

ReferenceError: using is not defined

The `using` keyword is a feature of TypeScript 5.2+ and Node.js with Explicit Resource Management (ERM). This error occurs if your environment does not support it.

fix

Upgrade your TypeScript version to 5.2 or newer. If in Node.js, ensure your Node.js version supports ERM or fall back to explicitly calling `await fixture.rm()`.

Error: ENOENT: no such file or directory, open '/tmp/fs-fixture-xxxx/non-existent.txt'

Attempting to access a file or directory within the fixture that was not defined when the fixture was created, or an incorrect path was provided.

fix

Verify that the path you are trying to access (`e.g., fixture.readFile('non-existent.txt')`) corresponds exactly to a file or directory specified in your `createFixture` object or template. Use `await fixture.exists('path')` to check for its presence.

Upgrade

Version history

2.13.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/privatenumber/fs-fixture ↗

packagehttps://www.npmjs.com/package/fs-fixture ↗