# create-jest-runner

> A simple way of creating a Jest runner

Latest version **1.0.0** (published 2025-06-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install create-jest-runner
pnpm add create-jest-runner
yarn add create-jest-runner
bun add create-jest-runner
```

Provides the command `create-jest-runner`.

## Health

**Score 55/100 (C)** — status: stable.

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

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2025-06-19 |
| First published | 2017-10-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | ^18.14.0 \|\| ^20.0.0 \|\| ^22.0.0 \|\| >=24.0.0 |
| Dependencies | 3 |
| Unpacked size | 24.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 137 |
| Author | Rogelio Guzman |
| Maintainers | simenb, rickhanlonii, thymikee, jsonp, orta, rogeliog, mattphillips, jeysal |

## Links

- npm: https://www.npmjs.com/package/create-jest-runner
- Repository: https://github.com/jest-community/create-jest-runner
- Issues: https://github.com/jest-community/create-jest-runner/issues
- npm.io page: https://npm.io/package/create-jest-runner

## Dependencies (3)

- [chalk](https://npm.io/package/chalk.md) ^4.1.0
- [p-limit](https://npm.io/package/p-limit.md) ^3.1.0
- [jest-worker](https://npm.io/package/jest-worker.md) ^30.0.0

## Recent versions

- 1.0.0 (latest) — 2025-06-19
- 0.2.0-0 (next) — 2018-01-23
- 0.12.3 — 2023-03-06
- 0.12.2 — 2022-09-14
- 0.12.1 — 2022-09-14
- 0.12.0 — 2022-08-26
- 0.11.2 — 2022-08-09
- 0.11.1 — 2022-05-15
- 0.11.0 — 2022-05-06
- 0.10.0 — 2022-03-08
- 0.9.0 — 2021-09-01
- 0.8.0 — 2021-08-26
- 0.7.1 — 2021-08-26
- 0.7.0 — 2020-08-21
- 0.6.0 — 2020-04-08
- … 10 more at https://npm.io/package/create-jest-runner/versions

## README

# create-jest-runner

[![Actions Status](https://github.com/jest-community/create-jest-runner/actions/workflows/nodejs.yml/badge.svg?branch=main)](https://github.com/jest-community/create-jest-runner/actions)

A highly opinionated way for creating Jest Runners

## Install

```bash
yarn add create-jest-runner
```

## Usage

create-jest-runner takes care of handling the appropriate parallelization and creating a worker farm for your runner.

You simply need two files:

- Entry file: Used by Jest as an entrypoint to your runner.
- Run file: Runs once per test file, and it encapsulates the logic of your runner

### 1) Create your entry file

```js
// index.js
const { createJestRunner } = require('create-jest-runner');
module.exports = createJestRunner(require.resolve('./run'));
```

#### createJestRunner(pathToRunFile, config?: { getExtraOptions })

- `pathToRunFile`: path to your run file. This must be an absolute path or a `file://` URL.
- `config`: Optional argument for configuring the runner.
  - `getExtraOptions`: `() => object` used for passing extra options to the runner. It needs to be a serializable object because it will be send to a different Node process.

### 2) Create your run file

```js
module.exports = options => {};
```

### Run File API

This file should export a function that receives one parameter with the options

#### `options: { testPath, config, globalConfig }`

- `testPath`: Path of the file that is going to be tests
- `config`: Jest Project config used by this file
- `globalConfig`: Jest global config
- `extraOptions`: The return value of the `{ getExtraOptions }` argument of `createJestRunner(...)` the entry file.

You can return one of the following values:

- `testResult`: Needs to be an object of type https://github.com/facebook/jest/blob/4d3c1a187bd429fd8611f6b0f19e4aa486fa2a85/packages/jest-test-result/src/types.ts#L103-L135
- `Promise<testResult|Error>`: needs to be of above type.
- `Error`: good for reporting system error, not failed tests.

## Example of a runner

This runner "blade-runner" makes sure that these two emojis `⚔️ 🏃` are present in every file

```js
// index.js
const { createJestRunner } = require('create-jest-runner');
module.exports = createJestRunner(require.resolve('./run'));
```

```js
// run.js
const fs = require('fs');
const { pass, fail } = require('create-jest-runner');

/** @type {import('create-jest-runner').RunTest} */
const runTest = ({ testPath }) => {
  const start = Date.now();
  const contents = fs.readFileSync(testPath, 'utf8');
  const end = Date.now();

  if (contents.includes('⚔️🏃')) {
    return pass({ start, end, test: { path: testPath } });
  }
  const errorMessage = 'Company policies require ⚔️ 🏃 in every file';
  return fail({
    start,
    end,
    test: { path: testPath, errorMessage, title: 'Check for ⚔️ 🏃' },
  });
};

module.exports = runTest;
```

## Create runner from binary

```shell
yarn create jest-runner my-runner

# Or with npm
npm init jest-runner my-runner
```

**Note:** You will have to update the package name in `package.json` of the generated runner.

## Add your runner to Jest config

Once you have your Jest runner you can add it to your Jest config.

In your `package.json`

```json
{
  "jest": {
    "runner": "/path/to/my-runner"
  }
}
```

Or in `jest.config.js`

```js
module.exports = {
  runner: '/path/to/my-runner',
};
```

### Run Jest

```bash
yarn jest
```

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