^fs-fixture

Simple API to create disposable test fixtures on disk. Tiny (1.1 kB gzipped) with zero dependencies!

$3

- 📁 Create files & directories from simple objects
- 🧹 Automatic cleanup with using keyword
- 📝 Built-in JSON read/write support
- 🔗 Symlink support
- 💾 Binary file support with Buffers
- 🎯 TypeScript-first with full type safety
- 🔄 File methods inherit types directly from Node.js fs module

Installation

``sh
npm install fs-fixture
`

Quick start

`ts
import { createFixture } from 'fs-fixture'

// 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')

// Cleanup when done
await fixture.rm()
`

$3

Uses TypeScript 5.2+ Explicit Resource Management for automatic cleanup:

`ts
await using fixture = await createFixture({
'config.json': '{ "setting": true }'
})

// Fixture is automatically cleaned up when exiting scope
`






^{Already a sponsor? Join the discussion in the Development repo!}

Usage

$3

From an object:
`ts
const fixture = await createFixture({
'package.json': '{ "name": "test" }',
'src/index.js': 'export default () => {}',
'src/utils': {
'helper.js': 'export const help = () => {}'
}
})
`

From a template directory:
`ts
// Copies an existing directory structure
const fixture = await createFixture('./test-templates/basic')
`

Empty fixture:
`ts
// Create an empty temporary directory
const fixture = await createFixture()
`

$3

File methods (readFile, writeFile, readdir) inherit their type signatures directly from Node.js fs/promises, preserving all overloads and type narrowing behavior.

Read files:
`ts
// Read as string (type: Promise)
const text = await fixture.readFile('config.txt', 'utf8')

// Read as buffer (type: Promise)
const binary = await fixture.readFile('image.png')
`

Write files:
`ts
await fixture.writeFile('output.txt', 'Hello world')
await fixture.writeFile('data.bin', Buffer.from([0x89, 0x50]))
`

JSON operations:
`ts
// Write JSON with formatting
await fixture.writeJson('config.json', { port: 3000 })

// Read and parse JSON with type safety
type Config = { port: number }
const config = await fixture.readJson('config.json')
`

$3

`ts
// Create directories
await fixture.mkdir('nested/folders')

// List directory contents
const files = await fixture.readdir('src')

// Copy files into fixture
await fixture.cp('/path/to/file.txt', 'copied-file.txt')

// Move or rename files
await fixture.mv('old-name.txt', 'new-name.txt')
await fixture.mv('file.txt', 'src/file.txt')

// Check if path exists
if (await fixture.exists('optional-file.txt')) {
// ...
}
`

$3

Dynamic content with functions:
`ts
const fixture = await createFixture({
'target.txt': 'original file',
'info.txt': ({ fixturePath }) => Created at: ${fixturePath},
'link.txt': ({ symlink }) => symlink('./target.txt')
})
`

Binary files:
`ts
const fixture = await createFixture({
'image.png': Buffer.from(imageData),
'generated.bin': () => Buffer.from('dynamic binary content')
})
`

Path syntax:
`ts
const fixture = await createFixture({
// Nested object syntax
src: {
utils: {
'helper.js': 'export const help = () => {}'
}
},

// Or path syntax (creates same structure)
'src/utils/helper.js': 'export const help = () => {}'
})
`

API

$3

Creates a temporary fixture directory and returns a FsFixture instance.

Parameters:
- source (optional): String path to template directory, or FileTree object defining the structure
- options.tempDir (optional): Custom temp directory. Defaults to os.tmpdir()
- options.templateFilter (optional): Filter function when copying from template directory

Returns: Promise

`ts
const fixture = await createFixture()
const fixture = await createFixture({ 'file.txt': 'content' })
const fixture = await createFixture('./template-dir')
const fixture = await createFixture({}, { tempDir: './custom-temp' })
`

$3

| Method | Description |
|--------|-------------|
| fixture.path | Absolute path to the fixture directory |
| getPath(...paths) | Get absolute path to file/directory in fixture |
| exists(path?) | Check if file/directory exists |
| rm(path?) | Delete file/directory (or entire fixture if no path) |
| readFile(path, encoding?) | Read file as string or Buffer |
| writeFile(path, content) | Write string or Buffer to file |
| readJson(path) | Read and parse JSON file |
| writeJson(path, data, space?) | Write JSON with optional formatting |
| readdir(path, options?) | List directory contents |
| mkdir(path) | Create directory (recursive) |
| cp(source, dest?) | Copy file/directory into fixture |
| mv(source, dest) | Move or rename file/directory |

$3

FileTree

`ts
type FileTree = {
[path: string]: string | Buffer | FileTree | ((api: Api) => string | Buffer | Symlink)
}

type Api = {
fixturePath: string // Fixture root path
filePath: string // Current file path
getPath: (...paths: string[]) => string // Get path from fixture root
symlink: (target: string) => Symlink // Create a symlink
}
``

Related

$3

Lightweight testing library for Node.js