fs-fixture

Simple API to create disposable test fixtures on disk. Tiny (`560 B` gzipped) and no dependencies! ### Example ```ts import fs from 'node:fs/promises' import { createFixture } from 'fs-fixture' const fixture = await createFixture({ 'dir-a': { 'file-b': 'hello world' } }) const content = await fs.readFile(fixture.getPath('dir-a/file-b')) console.log(content) ```

Already a sponsor? Join the discussion in the Development repo!

## Usage Pass in an object representing the file structure: ```ts import { createFixture } from 'fs-fixture' const fixture = await createFixture({ // Nested directory syntax 'dir-a': { 'file-a.txt': 'hello world', 'dir-b': { 'file-b.txt': ({ fixturePath }) => `Fixture path: ${fixturePath}`, 'symlink-c': ({ symlink }) => symlink('../file-a.txt') } }, // Alternatively, use the directory path syntax - Same as above 'dir-a/dir-b/file-b.txt': 'goodbye world' }) // Interact with the fixture console.log(fixture.path) // Cleanup fixture await fixture.rm() ``` ### Template path input Pass in a path to a test fixture template directory to make a copy of it. ```ts // Pass in a path to a fixture template path, and it will make a copy of it const fixture = await createFixture('./fixtures/template-a') /* Your test code here... */ // Cleanup fixture await fixture.rm() ``` ### `using` keyword (Explicit Resource Management) [TypeScript 5.2](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html) supports the [Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management) feature, which allows you to instantiate the fixture via `using`. When the fixture is declared this way, it gets automatically cleaned up when exiting the scope. ```ts await using fixture = await createFixture({ file: 'hello' }) // No need to run fixture.rm() ``` ## API ### createFixture(source, options) An async function that creates a fixture from the `source` you pass in, and returns a `FsFixture` instance. #### source Type: `string | FileTree` Path to a template fixture path, or a `FileTree` object that represents the fixture content. #### options ##### tempDir Type: `string` Default: `os.tmpdir()` The directory where the fixture will be created. ##### templateFilter Type: `(source: string, destination: string) => boolean | Promise` Function to filter files to copy when using a template path. Return `true` to copy the item, `false` to ignore it. ### Types #### FileTree ```ts type FileTree = { [path: string]: string | FileTree | ((api: Api) => string) } type Api = { // Fixture root path fixturePath: string // Current file path filePath: string // Get path from the root of the fixture getPath: (...subpaths: string[]) => string // Create a symlink symlink: (target: string) => Symlink } ``` #### FsFixture ```ts class FsFixture { /** Path to the fixture directory. */ readonly path: string /** Create a Fixture instance from a path. Does not create the fixture directory. */ constructor(fixturePath: string) /** Get the full path to a subpath in the fixture directory. */ getPath(...subpaths: string[]): string /** Check if the fixture exists. Pass in a subpath to check if it exists. */ exists(subpath?: string): Promise /** Delete the fixture directory. Pass in a subpath to delete it. */ rm(subpath?: string): Promise /** Copy a path into the fixture directory. */ cp(sourcePath: string, destinationSubpath?: string): Promise /** Create a file in the fixture directory. */ writeFile(filePath: string, content: string): Promise /** Create a JSON file in the fixture directory. */ writeJson(filePath: string, json: unknown): Promise /** Read a file from the fixture directory. */ readFile(filePath: string, encoding?: BufferEncoding): Promise } ``` ## Related ### [manten](https://github.com/privatenumber/manten) Lightweight testing library for Node.js