jest-environment.md

Integrating jest-metadata into test envirornment

Quick start

If you're running tests in Node.js environment, add the following line to your Jest config:

{
+  "testEnvironment": "jest-metadata/environment-node",
}

If you need to use jest-metadata in a JSDOM environment, you need change your test environment to:

{
+  "testEnvironment": "jest-metadata/environment-jsdom",
}

If you already have a custom test environment, you can extend it via composition:

+ import { WithMetadata } from 'jest-metadata/environment-decorator';

- class MyCustomEnvironment extends NodeEnvironment {
+ class MyCustomEnvironment extends WithMetadata(NodeEnvironment) {

Manual integration

If your use case is not covered by the above, you can rewrite your test environment into a listener of jest-environment-emit events. Here is an example of how to do it:

/** @type {import('jest').Config} */
module.exports = {
  testEnvironment: 'jest-environment-emit',
  testEnvironmentOptions: {
    listeners: [
      'jest-metadata/environment-listener',
      ['your-project/listener', { /* options */ }],
    ],
  },
};

where your-project/listener file contains the following code:

import * as jee from 'jest-environment-emit';

const listener: jee.EnvironmentListenerFn = (context, yourOptions) => {
  context.testEvents
    .on('test_environment_setup', ({ env }: jee.TestEnvironmentSetupEvent) => {
      // ...
    })
    .on('test_start', ({ event, state }: jee.TestEnvironmentCircusEvent) => {
      // ...
    })
    .on('test_done', ({ event, state }: jee.TestEnvironmentCircusEvent) => {
      // ...
    })
    .on('test_environment_teardown', ({ env }: jee.TestEnvironmentTeardownEvent) => {
      // ...
    });
};

export default listener;

Lifecycle of jest-metadata test environment

Here is a brief description of each lifecycle method:

• test_environment_setup:
  • injects __JEST_METADATA__ context into this.global object to eliminate sandboxing issues;
  • initializes jest-metadata IPC client if Jest is running in a multi-worker mode to enable communication with the main process where the reporters reside;
• all jest-circus events coming to handleTestEvent – building a metadata tree, parallel to jest-circus State tree, and for sending test events to the main process.
• test_environment_teardown – responsible for shutting down the IPC client and for sending the final test event to the main process.