# @natlibfi/fixura

> Loading test fixtures is as easy as ABC

Latest version **5.0.0** (published 2026-08-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install @natlibfi/fixura
pnpm add @natlibfi/fixura
yarn add @natlibfi/fixura
bun add @natlibfi/fixura
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 5.0.0 |
| Published | 2026-08-25 |
| First published | 2019-04-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=24 |
| Dependencies | 1 |
| Unpacked size | 41.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 0 |
| Author | The National Library of Finland |
| Maintainers | drone-melinda, natlibfi-jonollil |
| Keywords | fixture, test, unit |

## Links

- npm: https://www.npmjs.com/package/@natlibfi/fixura
- Repository: https://github.com/NatLibFi/fixura-js
- Homepage: https://www.npmjs.com/package/@natlibfi/fixura
- Issues: https://github.com/natlibfi/fixura-js/issues
- npm.io page: https://npm.io/package/@natlibfi/fixura

## Dependencies (1)

- [debug](https://npm.io/package/debug.md) ^4.4.3

## Alternatives

- [duck](https://npm.io/package/duck.md) — 4.2M weekly downloads
- [ava](https://npm.io/package/ava.md) — 560.2K weekly downloads
- [storybook-addon-module-mock](https://npm.io/package/storybook-addon-module-mock.md) — 71.7K weekly downloads
- [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) — 40.0K weekly downloads
- [aws-elasticsearch-connector](https://npm.io/package/aws-elasticsearch-connector.md) — 37.4K weekly downloads

## Recent versions

- 5.0.0 (latest) — 2026-08-25
- 5.0.0-alpha.8 (next) — 2026-07-07
- 5.0.0-alpha.7 — 2026-05-13
- 5.0.0-alpha.5 — 2026-05-07
- 5.0.0-alpha.4 — 2026-04-21
- 5.0.0-alpha.3 — 2026-04-10
- 4.0.1 — 2026-03-05
- 4.0.1-alpha.1 — 2026-03-05
- 4.0.0 — 2025-11-05
- 4.0.0-alpha.17 — 2025-10-22
- 4.0.0-alpha.13 — 2025-08-29
- 4.0.0-alpha.12 — 2025-07-14
- 4.0.0-alpha.11 — 2025-07-14
- 4.0.0-alpha.9 — 2025-07-10
- 4.0.0-alpha.8 — 2025-07-10
- … 50 more at https://npm.io/package/@natlibfi/fixura/versions

## README

# Loading test fixtures is as easy as ABC [![NPM Version](https://img.shields.io/npm/v/@natlibfi/fixura.svg)](https://npmjs.org/package/@natlibfi/fixura)

Fixura loads test fixtures.

## Workflow status
| Branch | Workflow status                                                                                                                                            |
|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| main   | ![Workflow status badge for branch main](https://github.com/NatLibFi/fixura-js/actions/workflows/melinda-node-tests-and-publish.yml/badge.svg?branch=main) |
| test   | ![Workflow status badge for branch test](https://github.com/NatLibFi/fixura-js/actions/workflows/melinda-node-tests-and-publish.yml/badge.svg?branch=test) |

# Usage

## ES modules

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

```js
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](#configuration):

```js
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 `object` (JSON), or a `ReadStream` (STREAM). See [Readers](#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`:

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

Pass a default reader to the factory:

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

Set a fixture-specific reader:

```js
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 an object.
- **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:

```js
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.

## License and copyright

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

This project uses the MIT license.

---
_Source: https://npm.io/package/@natlibfi/fixura · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._