Update Documentation to Include undici Compatibility Issues and Solutions

[KieraDOG]

Scope

Improves an existing behavior

Feature description

After updating undici from version 6.15.0 to 6.16.0, compatibility issues arose in our testing environment that utilizes jsdom and msw for network request mocking. Specifically, the errors involve markResourceTiming not being a function and issues accessing the location property on Window. These errors cause our unit tests to fail. A solution involving the manual addition of these properties to the global object has been identified and tested successfully.

Documentation Update Suggestion

The current Migration Guide from 1.x to 2.x could be expanded to include guidance on handling compatibility issues with undici and jsdom. It would be beneficial for users facing similar issues if the documentation could outline steps to manually add necessary properties to the global object in testing environments using msw and undici.

Proposed Changes

• Add a new section under the existing migration guide or in a relevant part of the documentation.
• Include an explanation of the potential errors when using undici with msw and jsdom.
• Provide code snippets like the following for quick fixes:

  globalThis.performance.markResourceTiming = () => {};
  // Additional properties might be needed depending on the specific errors encountered.

This documentation update would help prevent future issues for users upgrading undici in a similar setup and enhance the usability of msw in complex JavaScript testing environments.

References

GitHub issue in nodejs/undici discussing the problem: undici#3237

[kettanaito]

Hi, @KieraDOG. Thanks for proposing this. I have a few thoughts.

First, none of those issues are intrinsic to MSW. They exist simply due to how Undici and JSDOM are implemented, mostly being the fault of JSDOM relying on polyfills and patching globals where they shouldn't have. If you remove MSW from the equation, Undici will still fail to work in JSDOM due to the structuredClone() usage alone, which is broken in JSDOM.

That is why such a section wasn't added. In fact, I've decided to stop spending time on anything JSDOM-related, it's simply too much effort dedicated to a broken tool.

Neither is MSW tied to Undici. MSW uses any global fetch implementation you have, as long as that implementation is actually WHATWG Fetch compliant. In Node.js, that happened to be Undici, and they are doing a great job to keep the implementation stable and standard-compliant.

As an effort to breach the experience gap, we've created https://github.com/mswjs/jest-fixed-jsdom to provide a Jest configuration that already includes as much as for the needed "fixes" as possible. I think what you are proposing belongs there.