feat: add happy-dom support alongside jsdom

.github/workflows/ci.yml

@@ -20,17 +20,18 @@ jobs:
   main:
     # ignore all-contributors PRs
     if: ${{ !contains(github.head_ref, 'all-contributors') }}
-    name: Node ${{ matrix.node }}, Qwik ${{ matrix.qwik }}, ${{ matrix.check }}
+    name: Node ${{ matrix.node }}, Qwik ${{ matrix.qwik }}, ${{ matrix.dom }}, ${{ matrix.check }}
     runs-on: ubuntu-latest
 
     strategy:
       fail-fast: false
       matrix:
         node: ["18", "20", "22"]
-        qwik: ["1.12", "1.14.1", "1.15", "1.16"]
+        qwik: ["1.12", "1.14.1", "1.15", "1.16", "1.17"]
+        dom: ["jsdom", "happy-dom"]
         check: ["test"]
         include:
-          - { node: "22", qwik: "1.16", check: "lint" }
+          - { node: "22", qwik: "1.17", check: "lint" }
 
     steps:
       - name: ⬇️ Checkout repo
@@ -59,6 +60,8 @@ jobs:
 
       - name: ▶️ Run ${{ matrix.check }}
         run: pnpm ${{ matrix.check }}
+        env:
+          TEST_DOM: ${{ matrix.dom }}
 
   build:
     runs-on: ubuntu-latest

README.md

@@ -141,10 +141,12 @@ npm install --save-dev @testing-library/jest-dom @testing-library/user-event
 ```
 
 Finally, we need a DOM environment to run the tests in.
-This library was tested (for now) only with `jsdom` so we recommend using it:
+This library is tested with both `jsdom` and `happy-dom`:
 
 ```shell
 npm install --save-dev jsdom
+# or
+npm install --save-dev happy-dom
 ```
 
 [npm]: https://www.npmjs.com/
@@ -192,7 +194,7 @@ export default defineConfig((configEnv) =>
       },
       // configure your test environment
       test: {
-        environment: "jsdom",
+        environment: "jsdom", // or "happy-dom"
         setupFiles: ["./vitest.setup.ts"],
         globals: true,
       },

apps/qwik-testing-library-e2e-tests/package.json

@@ -37,8 +37,8 @@
   },
   "devDependencies": {
     "@builder.io/qwik": "^1.16.0",
-    "@noma.to/qwik-testing-library": "workspace:*",
     "@noma.to/qwik-mock": "workspace:*",
+    "@noma.to/qwik-testing-library": "workspace:*",
     "@testing-library/jest-dom": "^6.9.0",
     "@testing-library/user-event": "^14.6.1",
     "@types/eslint": "8.56.10",
@@ -48,6 +48,7 @@
     "@vitest/ui": "^3.2.4",
     "eslint": "8.57.1",
     "eslint-plugin-qwik": "1.16.0",
+    "happy-dom": "^20.0.11",
     "jsdom": "^26.1.0",
     "prettier": "3.6.2",
     "typescript": "5.9.2",

apps/qwik-testing-library-e2e-tests/vite.config.ts

@@ -7,6 +7,9 @@ const { dependencies = {}, peerDependencies = {} } = pkg as any;
 const makeRegex = (dep) => new RegExp(`^${dep}(/.*)?$`);
 const excludeAll = (obj) => Object.keys(obj).map(makeRegex);
 
+// Support both jsdom and happy-dom via TEST_DOM env variable
+const testEnvironment = process.env.TEST_DOM || "happy-dom";
+
 export default defineConfig(() => {
   return {
     build: {
@@ -32,7 +35,7 @@ export default defineConfig(() => {
     },
     plugins: [qwikVite(), tsconfigPaths()],
     test: {
-      environment: "jsdom",
+      environment: testEnvironment,
       setupFiles: ["./vitest.setup.ts"],
       globals: true,
     },

packages/qwik-testing-library/src/lib/qwik-testing-library.tsx

@@ -3,6 +3,32 @@ import { JSXOutput } from "@builder.io/qwik";
 import { getQwikLoaderScript } from "@builder.io/qwik/server";
 import type { ComponentRef, Options, Result } from "./types";
 
+// Patch HTMLTemplateElement.childNodes for happy-dom compatibility
+//
+// Qwik's VirtualElementImpl uses a <template> element as temporary storage for detached content.
+// It calls `template.insertBefore(node)` to store nodes and reads them back via `template.childNodes`.
+//
+// In real browsers and jsdom, `insertBefore` on a template adds direct children.
+// However, happy-dom redirects insertions to `template.content`, leaving `childNodes` empty.
+//
+// This patch makes `template.childNodes` return `template.content.childNodes` for happy-dom.
+if (typeof HTMLTemplateElement !== "undefined") {
+  // Detect if this DOM implementation needs the patch by testing behavior
+  const testTemplate = document.createElement("template");
+  const testNode = document.createComment("test");
+  testTemplate.insertBefore(testNode, null);
+  const needsPatch = testTemplate.childNodes.length === 0;
+  testNode.remove();
+
+  if (needsPatch) {
+    Object.defineProperty(HTMLTemplateElement.prototype, "childNodes", {
+      get() {
+        return this.content.childNodes;
+      },
+    });
+  }
+}
+
 // if we're running in a test runner that supports afterEach
 // then we'll automatically run cleanup afterEach test
 // this ensures that tests run in isolation from each other