jest-circus

What is jest-circus?

The jest-circus package is a test runner for Jest that aims to be a foundation for building testing frameworks. It provides a feature-rich API for defining tests, handling test execution, and setting up and tearing down test environments. It's designed to be more extensible and maintainable than Jest's default test runner.

What are jest-circus's main functionalities?

Defining Tests

This feature allows you to define individual test cases using the `test` function. The code sample demonstrates a simple test that checks if the addition of 1 and 2 equals 3.

test('adds 1 + 2 to equal 3', () => {
  expect(1 + 2).toBe(3);
});

Setup and Teardown

Jest-circus provides lifecycle methods like `beforeEach` and `afterEach` for setting up and tearing down your test environment before and after each test, respectively.

beforeEach(() => {
  initializeCityDatabase();
});

afterEach(() => {
  clearCityDatabase();
});

Test Suites

Organize tests into test suites using the `describe` block. This allows grouping of related tests, making tests easier to manage and understand.

describe('matching cities to foods', () => {
  test('Vienna <3 sausage', () => {
    expect(matchCityToFood('Vienna')).toBe('sausage');
  });
});

Asynchronous Testing

Support for testing asynchronous code using async/await syntax or promises, allowing for straightforward testing of asynchronous operations.

test('the data is peanut butter', async () => {
  await expect(fetchData()).resolves.toBe('peanut butter');
});

Other packages similar to jest-circus

mocha

Mocha is a feature-rich JavaScript test framework running on Node.js and in the browser, making asynchronous testing simple. It's similar to jest-circus in providing a flexible and extensible testing framework, but differs in its execution model and default assertion library integration.

jasmine

Jasmine is a behavior-driven development framework for testing JavaScript code. It does not require a DOM, and it has a clean, obvious syntax so that you can easily write tests. Jasmine is similar to jest-circus in its syntax and approach to defining tests but operates independently of Jest and has its own assertion library.

ava

AVA is a test runner for Node.js with a concise API, detailed error output, and process isolation that lets you develop with confidence. It's similar to jest-circus in its focus on modern JavaScript features and concurrency but differs in its minimalistic approach and focus on speed.

README

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. See the type definitions for more information on the events and state data currently available.

import {Event, State} from 'jest-circus';
import 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). 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:

yarn add --dev jest-circus

Or via npm:

npm install --save-dev jest-circus

Configure

Configure Jest to use jest-circus via the testRunner option:

{
  "testRunner": "jest-circus/runner"
}

Or via CLI:

jest --testRunner='jest-circus/runner'

Changelog

28.1.1

Features

• [jest] Expose Config type (#12848)
• [@jest/reporters] Improve GitHubActionsReporters annotation format (#12826)
• [@jest/types] Infer argument types passed to test and describe callback functions from each tables (#12885, #12905)

Fixes

• [@jest/expect-utils] Fix deep equality of ImmutableJS OrderedMaps (#12899)
• [jest-docblock] Handle multiline comments in parseWithComments (#12845)
• [jest-mock] Improve spyOn error messages (#12901)
• [jest-runtime] Correctly report V8 coverage with resetModules: true (#12912)
• [jest-worker] Make JestWorkerFarm helper type to include methods of worker module that take more than one argument (#12839)

Chore & Maintenance

• [docs] Updated docs to indicate that jest-environment-jsdom is a separate package #12828
• [docs] Document the comments used by coverage providers #12835
• [docs] Use docusaurus-remark-plugin-tab-blocks to format tabs with code examples (#12859)
• [jest-haste-map] Bump walker version (#12324)