Jest Environment Emitter

Common errors

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

  cause 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'

  cause 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)

  cause 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.

Warnings

• breaking Version 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.
• gotcha Incorrect 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.
• gotcha Earlier 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.
• gotcha Versions 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.

Install

• npm install jest-environment-emit npm
• yarn add jest-environment-emit yarn
• pnpm add jest-environment-emit pnpm

Imports

• WithEmitter
  wrong:

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

  correct:

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

  The primary higher-order function to create custom environments with event emitting capabilities. Recommended for wrapping your own base environment.
• TestEnvironment (Node)
  wrong:

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

  correct:

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

  This specifically exports a `TestEnvironment` class wrapped around `jest-environment-node`. Use the subpath import `/node` for this variant.
• TestEnvironment (JSDOM)
  wrong:

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

  correct:

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

  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.

Quickstart

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;