Overview

There can be only one test environment per a project config in Jest unlike test reporters, which can be multiple.

This limitation is not convenient, so this package provides a couple of pre-defined test environments and a way to create custom ones:

• jest-environment-emit – exports WithEmitter, a higher-order function to create custom environment classes
• jest-environment-emit/node – exports TestEnvironment, a wrapper over jest-environment-node
• jest-environment-emit/jsdom – exports TestEnvironment, a wrapper over jest-environment-jsdom

To wrap a custom environment, use WithEmitter:

1import { WithEmitter } from 'jest-environment-emit';
2// ...
3export default WithEmitter(MyEnvironment);

Usage

Assuming you have any test environment wrapped with jest-environment-emit, you can add as many event listeners as you want:

1/** @type {import('jest').Config} */
2module.exports = {
3  // ...
4  testEnvironment: 'jest-environment-emit/node',
5  testEnvironmentOptions: {
6    eventListeners: [
7      './simple-subscription-1.js',
8      ['./parametrized-subscription-2.js', { some: 'options' }],
9    ]
10  },
11};

The modules specified in eventListeners are required and should export a function with the following signature:

1/** @type {import('jest-environment-emit').EnvironmentListenerFn} */
2const subscription = function (context, options) {
3  context.testEvents
4    .on('test_environment_setup', async ({ env }) => {
5      // use like TestEnvironment#setup, e.g.:
6      env.global.__SOME__ = 'value';
7    })
8    .on('add_hook', ({ event, state }) => {
9      // use like TestEnvironment#handleTestEvent in jest-circus
10    })
11    .on('run_start', async ({ event, state }) => {
12      // use like TestEnvironment#handleTestEvent in jest-circus
13    })
14    .on('test_environment_teardown', async ({ env }) => {
15      // use like TestEnvironment#teardown
16    })
17    .on('*', ({ type }) => {
18        // wildcard listener
19        if (type === 'test_start') {
20            // ...
21        }
22    });
23};
24
25export default subscription; // module.exports = subscription;

For exact type definitions, see src/types.ts.

Library API

Deriving from classes

This higher-order function can also accept one subscriber function and custom class name:

1import { WithEmitter } from 'jest-environment-emit';
2// ...
3export default WithEmitter(MyEnvironment, 'WithMyListeners', (context, options) => {
4  context.testEvents.on('*', ({ type }) => {
5    // ...
6  });
7}); // -> class WithMyListeners(MyEnvironment) { ... }

The derived classes have a static method derive to continue derivation, e.g.:

1import { TestEnvironment } from 'jest-environment-emit/node';
2
3export default TestEnvironment.derive((context, options) => {
4  context.testEvents.on('*', ({ type }) => {
5    // ...
6  });
7}, 'WithMyListeners'); // -> class MyTestEnvironment(JestEnvironment) { ... }

All derived classes have also a protected property testEvents to access the event emitter.

1import { TestEnvironment } from 'jest-environment-emit/node';
2
3export class MyTestEnvironment extends TestEnvironment {
4  constructor(config, context) {
5    super(config, context);
6
7    this.testEvents.on('*', ({ type }) => {
8      // ...
9    });
10  }
11}

Using custom priorities

By default, all event listeners are appended to the list. If you need to guarantee the order of execution, you can specify a priority:

1/** @type {import('jest-environment-emit').EnvironmentListenerFn} */
2const subscription = function (context, options) {
3  context.testEvents
4    .on('test_environment_setup', async ({ env }) => {
5      // make sure this listener is executed first
6    }, -1)
7    .on('test_environment_teardown', async ({ env }) => {
8      // make sure this listener is executed last
9    }, 1E6)
10};

Try to avoid using priorities unless you really need them.

Troubleshooting

Use JEST_BUNYAMIN_DIR=path/to/dir to enable debug logging.

In your globalTeardown script, you can aggregate all the logs into a single file for convenience:

1// globalTeardown.js
2import { aggregateLogs } from 'jest-environment-emit/debug';
3
4module.exports = async () => {
5  await aggregateLogs();
6};

The logs, e.g. jest-bunyamin.log is a file viewable with Perfetto or chrome://tracing.

Support Policy: This package is officially tested on Jest 29 and 30. Jest 27/28 may work, but are not guaranteed or tested. Use at your own risk for those versions.