fix: Split wxt/testing into separate modules to fix issues with jsdom and happy-dom (#1844)

Co-authored-by: Aaron <[email protected]>

Author: marcellino-ornelas

docs/guide/essentials/unit-testing.md

@@ -9,7 +9,7 @@ WXT provides first class support for Vitest for unit testing:
 ```ts
 // vitest.config.ts
 import { defineConfig } from 'vitest/config';
-import { WxtVitest } from 'wxt/testing';
+import { WxtVitest } from 'wxt/testing/vitest-plugin';
 
 export default defineConfig({
   plugins: [WxtVitest()],
@@ -36,7 +36,7 @@ This example demonstrates that you don't have to mock `browser.storage` (used by
 
 ```ts
 import { describe, it, expect } from 'vitest';
-import { fakeBrowser } from 'wxt/testing';
+import { fakeBrowser } from 'wxt/testing/fake-browser';
 
 const accountStorage = storage.defineItem<Account>('local:account');
 

packages/wxt/package.json

@@ -179,6 +179,14 @@
       "types": "./dist/browser.d.ts",
       "default": "./dist/browser.mjs"
     },
+    "./testing/fake-browser": {
+      "types": "./dist/testing/fake-browser.d.ts",
+      "default": "./dist/testing/fake-browser.mjs"
+    },
+    "./testing/vitest-plugin": {
+      "types": "./dist/testing/wxt-vitest-plugin.d.ts",
+      "default": "./dist/testing/wxt-vitest-plugin.mjs"
+    },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "default": "./dist/testing/index.mjs"

packages/wxt/src/core/builders/vite/plugins/extensionApiMock.ts

@@ -43,7 +43,7 @@ export function extensionApiMock(config: ResolvedConfig): vite.PluginOption {
 
 const setupTemplate = `
   import { vi } from 'vitest';
-  import { fakeBrowser } from 'wxt/testing';
+  import { fakeBrowser } from 'wxt/testing/fake-browser';
 
   vi.stubGlobal("chrome", fakeBrowser);
   vi.stubGlobal("browser", fakeBrowser);

packages/wxt/src/testing/fake-browser.ts

@@ -1 +1,11 @@
+/**
+ * The fake browser is automatically used as a mock for the `wxt/browser` import
+ * when using `wxt/testing/vitest-plugin` with Vitest. It is also setup to
+ * reset all state before each test.
+ *
+ * This module is just a re-export of [@webext-core/fake-browser](https://webext-core.aklinker1.io/fake-browser/triggering-events).
+ *
+ * @module wxt/testing/fake-browser
+ */
+
 export { fakeBrowser, type FakeBrowser } from '@webext-core/fake-browser';

packages/wxt/src/testing/index.ts

@@ -1,5 +1,9 @@
 /**
  * Utilities for unit testing WXT extensions.
+ *
+ * @deprecated Use `wxt/testing/*` instead to prevent issues with JSDOM or
+ * HappyDOM environments. Will be removed in the next major version of WXT.
+ *
  * @module wxt/testing
  */
 export * from './fake-browser';

packages/wxt/src/testing/wxt-vitest-plugin.ts

@@ -1,3 +1,10 @@
+/**
+ * Contains a Vitest plugin that configures your test environment to work with
+ * WXT projects.
+ *
+ * @module wxt/testing/vitest
+ */
+
 import type * as vite from 'vite';
 import {
   download,
@@ -16,7 +23,7 @@ import { registerWxt, wxt } from '../core/wxt';
  * ```ts
  * // vitest.config.ts
  * import { defineConfig } from 'vitest/config';
- * import { WxtVitest } from 'wxt/testing';
+ * import { WxtVitest } from 'wxt/testing/vitest-plugin';
  *
  * export default defineConfig({
  *   plugins: [WxtVitest()],

packages/wxt/typedoc.json

@@ -17,6 +17,8 @@
     "src/utils/split-shadow-root-css.ts",
     "src/utils/storage.ts",
     "src/testing/index.ts",
+    "src/testing/fake-browser.ts",
+    "src/testing/wxt-vitest-plugin.ts",
     "src/modules.ts"
   ]
 }