jest-jsdom: use jest-fixed-jsdom (#124)

Author: kettanaito

examples/with-jest-jsdom/README.md

@@ -13,12 +13,11 @@ Using MSW with JSDOM requires additional configuration. Unfortunately, JSDOM (`j
 
 Please see the setup steps below to properly configure Jest when using in combination with JSDOM.
 
-### Module resolution
+## Custom Jest environment
 
-Opt-out from the browser module resolution in JSDOM by setting the `testEnvironmentOptions.customExportConditions` option in [`jest.config.ts`](./jest.config.ts). This will force JSDOM to use Node.js module resolution, correctly resolving export conditions of third-party packages.
+Use the [`jest-fixed-jsdom`](https://github.com/mswjs/jest-fixed-jsdom) custom environment for your JSDOM tests. That environment is a superset of JSDOM with a few important modifications:
 
-> Despite JSDOM predenting to be a browser environment, your code _still runs in Node.js_. Using the browser module resolution can cause all sorts of import issues with third-party packages that depend on the standard Node.js API.
+- Ensures the module resolution is set to Node.js, not the browser (`customExporConditions`);
+- Restores the global functions and classes present in the browser (e.g. `fetch`, `structuredClone`, etc.).
 
-### Polyfills
-
-Create a [jest.polyfills.ts](./jest.polyfills.ts) file in your project (you can copy it) and include it in the `setupFiles` option in `jest.config.ts`. This will re-add some of the Node.js globals (and browser) missing in JSDOM, like `fetch`, `Request`, `Response`, etc.
+See [`jest.config.ts`](./jest.config.ts) for the configuration reference.

examples/with-jest-jsdom/example.test.ts

@@ -1,7 +1,3 @@
-/**
- * @jest-environment jsdom
- */
-
 it('receives a mocked response to a REST API request', async () => {
   const response = await fetch('https://api.example.com/user')
 

examples/with-jest-jsdom/jest.config.ts

@@ -2,25 +2,15 @@ import type { Config } from 'jest'
 
 export default {
   rootDir: __dirname,
-  setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
-  /**
-   * @note Include the polyfills in the "setupFiles"
-   * to apply them BEFORE the test environment.
-   */
-  setupFiles: ['<rootDir>/jest.polyfills.ts'],
+
+  // Use a custom environment to fix missing globals in jsdom.
+  testEnvironment: 'jest-fixed-jsdom',
+
+  // Provide a setup file to enable MSW.
+  setupFilesAfterEnv: ['./jest.setup.ts'],
+
+  // (Optional) Add suppor for TypeScript in Jest.
   transform: {
     '^.+\\.tsx?$': '@swc/jest',
   },
-  testEnvironmentOptions: {
-    /**
-     * @note Opt-out from JSDOM using browser-style resolution
-     * for dependencies. This is simply incorrect, as JSDOM is
-     * not a browser, and loading browser-oriented bundles in
-     * Node.js will break things.
-     *
-     * Consider migrating to a more modern test runner if you
-     * don't want to deal with this.
-     */
-    customExportConditions: [''],
-  },
 } satisfies Config

examples/with-jest-jsdom/jest.polyfills.ts

@@ -10,9 +10,9 @@
     "@types/node": "^18",
     "jest": "^29.5.0",
     "jest-environment-jsdom": "^29.5.0",
-    "msw": "2.2.2",
+    "jest-fixed-jsdom": "^0.0.9",
+    "msw": "2.6.4",
     "ts-node": "^10.9.2",
-    "typescript": "^5.0.4",
-    "undici": "^5.22.0"
+    "typescript": "^5.0.4"
   }
 }