Loading test fixtures is as easy as ABC

Fixura loads test fixtures.

Workflow status

Branch	Workflow status
main
test

Usage

ES modules

The factory takes the fixture root as one or more path components. It returns {getFixture, getFixtures}:

import fixturesFactory from '@natlibfi/fixura';
const {getFixture, getFixtures} = fixturesFactory(import.meta.dirname, '..', 'test-fixtures');

// Load a single fixture
const fixture = getFixture('foo.txt');

// Load all .txt files in one directory
const fixtures = getFixtures(/\.txt$/u, 'some-dir');

You can also pass the root as an options object. See Configuration:

const {getFixture} = fixturesFactory({
    root: [import.meta.dirname, '..', 'test-fixtures'],
});

API

fixturesFactory(...)

Two call shapes:

• Variadic root components: fixturesFactory(dir, '..', 'test-fixtures')
• Options object: fixturesFactory({root, reader, failWhenNotFound})

The function returns {getFixture, getFixtures}.

getFixture(components, ...components) | getFixture({components, reader})

Loads a single fixture. The path uses one or more components joined to the root. A per-call reader can override the factory default in the object form.

The function returns a string (TEXT), an unknown (JSON), or a ReadStream (STREAM). When the fixture is not found and failWhenNotFound is false, it returns undefined. See Readers.

getFixtures(regex, ...dirComponents) | getFixtures(components, ...components)

Loads multiple fixtures. The function always returns an array.

• With a regex: Lists the directory given by dirComponents. It loads every entry whose file name matches the regex. Matching uses entry names only, not joined paths. It does not recurse into subdirectories. The array can be empty if nothing matches.
• Without a regex: Loads the single fixture from the path components. It returns the fixture as a one-element array.

Configuration

Readers

The readers are exported as READERS:

import fixturesFactory, {READERS} from '@natlibfi/fixura'

Pass a default reader to the factory:

const {getFixture} = fixturesFactory({
    root: [import.meta.dirname, '..', 'test-fixtures'],
    reader: READERS.JSON
});

Set a fixture-specific reader:

getFixture({components: ['foo', 'bar.json'], reader: READERS.JSON})

Built-in readers

• TEXT: Returns the fixture as text. This is the default reader.
• JSON: Parses the fixture as JSON. Returns unknown — the parsed value. Narrow or assert the type before using it.
• STREAM: Returns a read stream to the fixture. The stream emits error asynchronously. Always attach an error listener.

CAUTION: failWhenNotFound does not apply to streams. A missing file returns a ReadStream that emits ENOENT as an error event. This is an uncaught exception if no listener exists.

failWhenNotFound

Set failWhenNotFound to false to prevent the function from throwing an error when a fixture file is not found. The function returns undefined instead:

const {getFixture} = fixturesFactory({
    root: [import.meta.dirname, '..', 'test-fixtures'],
    failWhenNotFound: false
});

const foo = getFixture('foo', 'bar.txt'); // undefined

Only ENOENT (file not found) is suppressed. Other read errors, such as invalid JSON, always throw. Streams are not covered.

TypeScript

The package is written in TypeScript and ships its type declarations. Beyond READERS, it exports the Reader type and the Fixura<DR> interface describing the returned {getFixture, getFixtures} object.

The factory is generic over its default reader, so the return types of getFixture and getFixtures follow the reader you configure:

import fixturesFactory, {READERS} from '@natlibfi/fixura';

const {getFixture} = fixturesFactory({
    root: [import.meta.dirname, '..', 'test-fixtures'],
    reader: READERS.JSON,
});

const data = getFixture('foo', 'bar.json'); // unknown

Per-call reader overrides are typed as well: getFixture({components: ['foo.txt'], reader: READERS.TEXT}) returns string | undefined.

License and copyright

Copyright (c) 2019-2020, 2022-2026 University Of Helsinki (The National Library Of Finland)

This project uses the MIT license.