Registry / testing / jest-environment-emit

jest-environment-emit

library1.2.0jsnpmunverified

jest-environment-emit is a utility package for Jest that overcomes the limitation of having only one test environment per project. It provides a mechanism to add multiple event handlers to any Jest test environment, acting similarly to multiple test reporters. The package offers `WithEmitter`, a higher-order function to wrap custom environments, and pre-wrapped `TestEnvironment` classes for `jest-environment-node` and `jest-environment-jsdom` via subpath exports. Currently at version 1.2.0, released in June 2025, the package maintains a steady release cadence, frequently addressing compatibility with new Jest versions (e.g., Jest 30 support in v1.2.0) and refining import/export mechanisms for robust ESM and CJS interoperability. Its primary differentiator is enabling modular, composable event-driven logic within the Jest testing lifecycle, which is otherwise restricted to a single environment definition. It ships with full TypeScript types, enhancing developer experience.

testing

npm install jest-environment-emit

github ↗package ↗

INSTALL

IMPORT

SIG · JEST-ENVIRONMENT-E

jest-environment-emit

testingjavascriptv1.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

WithEmitter

✓ import { WithEmitter } from 'jest-environment-emit';

✗ const WithEmitter = require('jest-environment-emit').WithEmitter;

The primary higher-order function to create custom environments with event emitting capabilities. Recommended for wrapping your own base environment.

TestEnvironment (Node)

✓ import { TestEnvironment } from 'jest-environment-emit/node';

✗ import { TestEnvironment } from 'jest-environment-emit';

This specifically exports a `TestEnvironment` class wrapped around `jest-environment-node`. Use the subpath import `/node` for this variant.

TestEnvironment (JSDOM)

✓ import { TestEnvironment } from 'jest-environment-emit/jsdom';

✗ import { TestEnvironment } from 'jest-environment-emit';

This specifically exports a `TestEnvironment` class wrapped around `jest-environment-jsdom`. Use the subpath import `/jsdom` for this variant.

EnvironmentListenerFn

✓ import type { EnvironmentListenerFn } from 'jest-environment-emit';

Type definition for the event listener function. Crucial for TypeScript users to correctly type their subscription modules.

Demonstrates configuring Jest to use `jest-environment-emit/node` and attaching multiple event listener modules. It includes an example listener module showing how to subscribe to various Jest lifecycle events to perform custom setup, teardown, or other actions.

/** @type {import('jest').Config} */ module.exports = { testEnvironment: 'jest-environment-emit/node', testEnvironmentOptions: { eventListeners: [ './jest-setup-listener.js', ['./jest-parametrized-listener.js', { some: 'options', token: process.env.API_TOKEN ?? '' }], ] }, }; // jest-setup-listener.js /** @type {import('jest-environment-emit').EnvironmentListenerFn} */ const setupListener = function (context, options) { context.testEvents .on('test_environment_setup', async ({ env }) => { console.log('Test environment setup initiated!'); env.global.__MY_CUSTOM_GLOBAL__ = 'initialized from listener'; }) .on('test_start', ({ event, state }) => { console.log(`Starting test: ${event.test.name}`); }) .on('test_environment_teardown', async ({ env }) => { console.log('Test environment teardown completed!'); delete env.global.__MY_CUSTOM_GLOBAL__; }); }; export default setupListener;

Debug

Known issues

breakingVersion 1.2.0 introduced support for Jest 30. While this is a feature, environments relying on older Jest versions or custom Jest configurations might require updates to ensure full compatibility. Always verify your Jest setup when upgrading.

fix

Ensure your `jest` peer dependency is `>=30.0.0` or compatible. Review Jest's own breaking changes between your previous version and Jest 30.

affects: >=1.2.0

gotchaIncorrect subpath imports for built-in environments. Trying to `import { TestEnvironment } from 'jest-environment-emit'` will fail as the main export is `WithEmitter`.

fix

Always use specific subpath imports like `jest-environment-emit/node` or `jest-environment-emit/jsdom` for the pre-wrapped `TestEnvironment` classes.

affects: >=1.0.0

gotchaEarlier versions (prior to 1.0.8) could have listeners that were not resilient to errors, potentially causing entire test runs to fail if an individual listener threw an unhandled exception.

fix

Upgrade to `jest-environment-emit@1.0.8` or newer, which includes fixes to make listeners resilient to errors. Ensure your listener functions handle their own errors gracefully.

affects: <1.0.8

gotchaVersions prior to 1.0.3/1.0.5 had issues with ESM/CJS export collisions and quirky import patterns, potentially leading to 'undefined' imports or incorrect module resolution, especially in mixed environments.

fix

Upgrade to `jest-environment-emit@1.0.5` or newer. This version introduced fixes for `module.exports.default` fallback and ensured exclusive use of default and named exports, improving import reliability.

affects: <1.0.5

Errors

Common errors & fixes

TypeError: (0, jest_environment_emit_1.TestEnvironment) is not a constructor

Attempting to import `TestEnvironment` directly from the main `jest-environment-emit` package, which only exports `WithEmitter` by default.

fix

Use the correct subpath import for the desired environment, e.g., `import { TestEnvironment } from 'jest-environment-emit/node';`.

Jest: `testEnvironment` must be a path to a Node module. Error: Cannot find module 'jest-environment-emit'

The package `jest-environment-emit` or its specific subpath export is not correctly resolved by Node/Jest.

fix

Ensure `jest-environment-emit` is installed. If using a specific subpath (e.g., `jest-environment-emit/node`), verify the path is correct and accessible from your Jest configuration file. This often happens if the package isn't in `node_modules` or a symlink is broken.

TypeError: Cannot read properties of undefined (reading 'on') at subscription (my-listener.js)

The `context.testEvents` object within your event listener function is `undefined` because the listener function was not called by `jest-environment-emit`.

fix

Verify that your listener module is correctly listed in `testEnvironmentOptions.eventListeners` in your Jest config and that it exports the listener function as a `default` export.

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

@jest/environmentrequiredPeer dependency required by Jest test environments.

@jest/typesrequiredPeer dependency for Jest's type definitions.

jestrequiredCore Jest framework peer dependency.

jest-environment-jsdomoptionalOptional peer dependency if using the 'jest-environment-emit/jsdom' variant.

jest-environment-nodeoptionalOptional peer dependency if using the 'jest-environment-emit/node' variant.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/wix-incubator/jest-environment-emit ↗

packagehttps://www.npmjs.com/package/jest-environment-emit ↗