# jest-circus
> [type-definitions]: https://github.com/jestjs/jest/blob/main/packages/jest-types/src/Circus.ts
Latest version **30.5.1** (published 2026-09-01) · MIT license · 0 weekly downloads
## Install
```sh
npm install jest-circus
pnpm add jest-circus
yarn add jest-circus
bun add jest-circus
```
## Health
**Score 70/100 (B)** — status: active.
Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; popular repo.
Warnings: low downloads.
## Facts
| | |
|---|---|
| Version | 30.5.1 |
| Published | 2026-09-01 |
| First published | 2017-06-02 |
| 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 | 20 |
| Unpacked size | 162.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 45468 |
| Maintainers | aaronabramov, simenb, rickhanlonii, openjs-operations, cpojer |
## Links
- npm: https://www.npmjs.com/package/jest-circus
- Repository: https://github.com/jestjs/jest
- Homepage: https://github.com/jestjs/jest#readme
- Issues: https://github.com/jestjs/jest/issues
- npm.io page: https://npm.io/package/jest-circus
## Dependencies (20)
- [co](https://npm.io/package/co.md) ^4.6.0
- [chalk](https://npm.io/package/chalk.md) ^4.1.2
- [slash](https://npm.io/package/slash.md) ^3.0.0
- [dedent](https://npm.io/package/dedent.md) ^1.6.0
- [p-limit](https://npm.io/package/p-limit.md) ^3.1.0
- [jest-each](https://npm.io/package/jest-each.md) 30.5.1
- [jest-util](https://npm.io/package/jest-util.md) 30.5.1
- [pure-rand](https://npm.io/package/pure-rand.md) ^7.0.0
- [@jest/types](https://npm.io/package/@jest/types.md) 30.5.1
- [@types/node](https://npm.io/package/@types/node.md) *
- [stack-utils](https://npm.io/package/stack-utils.md) ^2.0.6
- [@jest/expect](https://npm.io/package/@jest/expect.md) 30.5.1
- [jest-runtime](https://npm.io/package/jest-runtime.md) 30.5.1
- [jest-snapshot](https://npm.io/package/jest-snapshot.md) 30.5.1
- [pretty-format](https://npm.io/package/pretty-format.md) 30.5.1
- [is-generator-fn](https://npm.io/package/is-generator-fn.md) ^2.1.0
- [@jest/environment](https://npm.io/package/@jest/environment.md) 30.5.1
- [@jest/test-result](https://npm.io/package/@jest/test-result.md) 30.5.1
- [jest-message-util](https://npm.io/package/jest-message-util.md) 30.5.1
- [jest-matcher-utils](https://npm.io/package/jest-matcher-utils.md) 30.5.1
## Recent versions
- 30.5.1 (latest) — 2026-09-01
- 30.0.0-rc.1 (next) — 2025-06-09
- 30.5.0 — 2026-08-28
- 30.4.2 — 2026-05-09
- 30.4.1 — 2026-05-08
- 30.4.0 — 2026-05-07
- 30.3.0 — 2026-03-10
- 30.2.0 — 2025-09-28
- 30.1.3 — 2025-09-02
- 30.1.2 — 2025-09-01
- 30.1.1 — 2025-08-27
- 30.1.0 — 2025-08-27
- 30.0.5 — 2025-07-22
- 30.0.4 — 2025-07-02
- 30.0.3 — 2025-06-25
- … 260 more at https://npm.io/package/jest-circus/versions
## README
[type-definitions]: https://github.com/jestjs/jest/blob/main/packages/jest-types/src/Circus.ts
jest-circus
The next-gen test runner for Jest
## Overview
Circus is a flux-based test runner for Jest that is fast, maintainable, and simple to extend.
Circus allows you to bind to events via an optional event handler on any [custom environment](https://jestjs.io/docs/configuration#testenvironment-string). See the [type definitions][type-definitions] for more information on the events and state data currently available.
```ts
import type {Event, State} from 'jest-circus';
import {TestEnvironment as NodeEnvironment} from 'jest-environment-node';
class MyCustomEnvironment extends NodeEnvironment {
//...
async handleTestEvent(event: Event, state: State) {
if (event.name === 'test_start') {
// ...
}
}
}
```
Mutating event or state data is currently unsupported and may cause unexpected behavior or break in a future release without warning. New events, event data, and/or state data will not be considered a breaking change and may be added in any minor release.
Note, that `jest-circus` test runner would pause until a promise returned from `handleTestEvent` gets fulfilled. **However, there are a few events that do not conform to this rule, namely**: `start_describe_definition`, `finish_describe_definition`, `add_hook`, `add_test` or `error` (for the up-to-date list you can look at [SyncEvent type in the types definitions][type-definitions]). That is caused by backward compatibility reasons and `process.on('unhandledRejection', callback)` signature, but that usually should not be a problem for most of the use cases.
## Installation
> Note: As of Jest 27, `jest-circus` is the default test runner, so you do not have to install it to use it.
Install `jest-circus` using yarn:
```bash
yarn add --dev jest-circus
```
Or via npm:
```bash
npm install --save-dev jest-circus
```
## Configure
Configure Jest to use `jest-circus` via the [`testRunner`](https://jestjs.io/docs/configuration#testrunner-string) option:
```json
{
"testRunner": "jest-circus/runner"
}
```
Or via CLI:
```bash
jest --testRunner='jest-circus/runner'
```
---
_Source: https://npm.io/package/jest-circus · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._