Use a Custom Jest Environment

Oct 13, 2025 by wbrum.org 90 views

Introduction

When working with Node.js and TypeScript, integrating Jest for unit testing is a common practice. However, sometimes you might encounter errors that are not immediately apparent. In this article, we will discuss a specific error that can occur when using Jest with Node.js and TypeScript: ReferenceError: structuredClone is not defined.

Understanding the Error

The error ReferenceError: structuredClone is not defined typically occurs when Jest tries to use the structuredClone function, which is part of the Web API. This function is used to create a deep copy of an object, preserving its structure and properties.

However, Jest does not automatically include the Web API in its environment. As a result, when Jest tries to use structuredClone, it throws a ReferenceError because the function is not defined.

Why is this Happening?

There are several reasons why you might encounter this error:

Missing polyfills: Jest does not include polyfills for the Web API by default. This means that if your code relies on structuredClone, Jest will throw an error.
Incorrect configuration: Your Jest configuration might not be set up correctly to include the necessary polyfills.
Outdated dependencies: If you're using outdated dependencies, they might not be compatible with the latest version of Jest.

Solutions

Here are a few solutions to resolve the ReferenceError: structuredClone is not defined error:

1. Add Polyfills

You can add polyfills for the Web API to your Jest configuration. This will ensure that Jest includes the necessary functions, including structuredClone.

module.exports = {
    // ... other configurations ...
    setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
};

Create a new file called jest.setup.js in the root of your project:

import 'web-standards-fetch';
import 'web-standards-fetch/polyfills/structured-clone';

This will add the necessary polyfills for the Web API, including structuredClone.

2. Use a Custom Jest Environment

You can create a custom Jest environment that includes the necessary polyfills. This will ensure that your tests run in an environment that includes the necessary functions.

Create a new file called jest-environment.js in the root of your project:

import { Environment } from '@jest/environment';
import 'web-standards-fetch';
import 'web-standards-fetch/polyfills/structured-clone';
class CustomEnvironment extends Environment {
async setup() {
// Add any additional setup code here
}
async teardown() {
    // Add any additional teardown code here
}

}
export default CustomEnvironment;

Then, update your Jest configuration to use the custom environment:

module.exports = {
    // ... other configurations ...
    testEnvironment: './jest-environment',
};

3. Upgrade Dependencies

Make sure that your dependencies are up-to-date. You can use a package manager like npm or yarn to check for updates.

npm outdated

Or:

yarn outdated

This will list any outdated dependencies. You can then update them using the following commands:

npm install <package-name>@latest

Or:

yarn add <package-name>@latest

Conclusion

The ReferenceError: structuredClone is not defined error can be frustrating to resolve, but it's often a simple configuration issue. By adding polyfills, creating a custom Jest environment, or upgrading dependencies, you can resolve this error and ensure that your tests run smoothly.

Additional Resources

Example Use Case

Here's an example use case that demonstrates how to use structuredClone in a Jest test:

import { structuredClone } from 'web-standards-fetch/polyfills/structured-clone';
describe('structuredClone', () => 
it('should create a deep copy of an object', () => {
const originalObject = { foo 'bar', baz: 'qux' ;
const clonedObject = structuredClone(originalObject);
    expect(clonedObject).not.toBe(originalObject);
    expect(clonedObject).toEqual(originalObject);
});

});

Q: What is the `structuredClone` function?

A: The structuredClone function is a part of the Web API that creates a deep copy of an object, preserving its structure and properties.

Q: Why is Jest throwing a `ReferenceError: structuredClone is not defined` error?

A: Jest does not automatically include the Web API in its environment, so when it tries to use structuredClone, it throws a ReferenceError because the function is not defined.

Q: How can I add polyfills for the Web API to my Jest configuration?

A: You can add polyfills for the Web API to your Jest configuration by creating a new file called jest.setup.js in the root of your project and importing the necessary polyfills.

import 'web-standards-fetch';
import 'web-standards-fetch/polyfills/structured-clone';

Q: Can I create a custom Jest environment that includes the necessary polyfills?

A: Yes, you can create a custom Jest environment that includes the necessary polyfills. This will ensure that your tests run in an environment that includes the necessary functions.

Create a new file called jest-environment.js in the root of your project:

import { Environment } from '@jest/environment';
import 'web-standards-fetch';
import 'web-standards-fetch/polyfills/structured-clone';
class CustomEnvironment extends Environment {
async setup() {
// Add any additional setup code here
}
async teardown() {
    // Add any additional teardown code here
}

}
export default CustomEnvironment;

Then, update your Jest configuration to use the custom environment:

module.exports = {
    // ... other configurations ...
    testEnvironment: './jest-environment',
};

Q: How can I upgrade my dependencies to the latest version?

A: You can use a package manager like npm or yarn to check for updates:

npm outdated

Or:

yarn outdated

This will list any outdated dependencies. You can then update them using the following commands:

npm install <package-name>@latest

Or:

yarn add <package-name>@latest

Q: What are some additional resources for learning more about Jest and the Web API?

A: Here are some additional resources for learning more about Jest and the Web API:

Q: Can you provide an example use case for using `structuredClone` in a Jest test?

A: Here's an example use case that demonstrates how to use structuredClone in a Jest test:

import { structuredClone } from 'web-standards-fetch/polyfills/structured-clone';
describe('structuredClone', () => 
it('should create a deep copy of an object', () => {
const originalObject = { foo 'bar', baz: 'qux' ;
const clonedObject = structuredClone(originalObject);
    expect(clonedObject).not.toBe(originalObject);
    expect(clonedObject).toEqual(originalObject);
});

});

This example uses structuredClone to create a deep copy of an object. The test checks that the cloned object is not the same as the original object, but has the same properties and values.