refactor: add axe-core polyfill

BioPhoton · BioPhoton · commit 515577c36a2b · 2026-02-01T00:05:23.000+01:00
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -74,6 +74,7 @@
     "@types/benchmark": "^2.1.5",
     "@types/debug": "^4.1.12",
     "@types/eslint": "^8.44.2",
+    "@types/jsdom": "^27.0.0",
     "@types/node": "^22.13.4",
     "@types/react": "18.3.1",
     "@types/react-dom": "18.3.0",
diff --git a/packages/plugin-axe/src/lib/axe-core-polyfilled.ts b/packages/plugin-axe/src/lib/axe-core-polyfilled.ts
@@ -0,0 +1,34 @@
+/**
+ * Axe-core Polyfilled Import
+ *
+ * This file ensures the jsdom polyfill runs BEFORE axe-core is imported.
+ * Due to ES module import hoisting, we must import the polyfill explicitly
+ * at the top of this file, then import axe-core. This guarantees the correct
+ * execution order: polyfill setup → axe-core import.
+ *
+ * IMPORT CHAIN:
+ * 1. jsdom.polyfill.ts (sets globalThis.window and globalThis.document)
+ * 2. This file (imports polyfill, then imports axe-core)
+ * 3. safe-axe-core-import.ts (re-exports for clean imports)
+ *
+ * USAGE:
+ * Do NOT import from this file directly. Use safe-axe-core-import.ts instead.
+ */
+// Import polyfill FIRST to ensure globals are set before axe-core loads
+// eslint-disable-next-line import/no-unassigned-import
+// Now safe to import axe-core - globals exist due to polyfill import above
+import axe from 'axe-core';
+import './jsdom.polyfill.js';
+
+// Re-export axe default and all types used throughout the codebase
+export default axe;
+
+export type {
+  AxeResults,
+  NodeResult,
+  Result,
+  IncompleteResult,
+  RuleMetadata,
+  ImpactValue,
+  CrossTreeSelector,
+} from 'axe-core';
diff --git a/packages/plugin-axe/src/lib/groups.int.test.ts b/packages/plugin-axe/src/lib/groups.int.test.ts
@@ -1,5 +1,5 @@
-import axe from 'axe-core';
 import { axeCategoryGroupSlugSchema, axeWcagTagSchema } from './groups.js';
+import axe from './safe-axe-core-import.js';
 
 describe('axeCategoryGroupSlugSchema', () => {
   const axeCategoryTags = axe
diff --git a/packages/plugin-axe/src/lib/jsdom.polyfill.ts b/packages/plugin-axe/src/lib/jsdom.polyfill.ts
@@ -0,0 +1,31 @@
+/**
+ * JSDOM Polyfill Setup
+ *
+ * WHY THIS EXISTS:
+ * axe-core has side effects on import - it expects global `window` and `document` objects
+ * to be available when the module is loaded. In Node.js environments, these don't exist
+ * by default. This polyfill creates a virtual DOM using JSDOM and sets these globals
+ * before axe-core is imported.
+ *
+ * HOW IT WORKS:
+ * - Creates a minimal JSDOM instance with a basic HTML document
+ * - Sets globalThis.window and globalThis.document to the JSDOM window/document
+ * - This must be imported BEFORE any axe-core imports to ensure globals exist
+ *
+ * IMPORT CHAIN:
+ * This file is imported first by axe-core-polyfilled.ts, which then safely imports
+ * axe-core. All other files should import from safe-axe-core-import.ts, not directly
+ * from this file or from 'axe-core'.
+ *
+ * @see https://github.com/dequelabs/axe-core/issues/3962
+ */
+import { JSDOM } from 'jsdom';
+
+const html = `<!DOCTYPE html>\n<html></html>`;
+const { window: jsdomWindow } = new JSDOM(html);
+
+// Set globals for axe-core compatibility
+// eslint-disable-next-line  functional/immutable-data
+globalThis.window = jsdomWindow;
+// eslint-disable-next-line  functional/immutable-data
+globalThis.document = jsdomWindow.document;
diff --git a/packages/plugin-axe/src/lib/meta/transform.ts b/packages/plugin-axe/src/lib/meta/transform.ts
@@ -1,4 +1,3 @@
-import axe from 'axe-core';
 import type { Audit, Group } from '@code-pushup/models';
 import { objectToEntries, wrapTags } from '@code-pushup/utils';
 import type { AxePreset } from '../config.js';
@@ -7,6 +6,7 @@ import {
   CATEGORY_GROUPS,
   getWcagPresetTags,
 } from '../groups.js';
+import axe from '../safe-axe-core-import.js';
 
 /** Loads Axe rules filtered by the specified preset. */
 export function loadAxeRules(preset: AxePreset): axe.RuleMetadata[] {
diff --git a/packages/plugin-axe/src/lib/runner/run-axe.ts b/packages/plugin-axe/src/lib/runner/run-axe.ts
@@ -1,6 +1,5 @@
 import { AxeBuilder } from '@axe-core/playwright';
 import ansis from 'ansis';
-import type { AxeResults } from 'axe-core';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import {
@@ -17,6 +16,7 @@ import {
   logger,
   pluralizeToken,
 } from '@code-pushup/utils';
+import type { AxeResults } from '../safe-axe-core-import.js';
 import { type SetupFunction, runSetup } from './setup.js';
 import { toAuditOutputs } from './transform.js';
 
diff --git a/packages/plugin-axe/src/lib/runner/runner.unit.test.ts b/packages/plugin-axe/src/lib/runner/runner.unit.test.ts
@@ -1,5 +1,9 @@
-import type { AxeResults, IncompleteResult, Result } from 'axe-core';
 import { type AuditOutput, DEFAULT_PERSIST_CONFIG } from '@code-pushup/models';
+import type {
+  AxeResults,
+  IncompleteResult,
+  Result,
+} from '../safe-axe-core-import.js';
 import type { AxeUrlResult } from './run-axe.js';
 import { createRunnerFunction } from './runner.js';
 import * as setup from './setup.js';
diff --git a/packages/plugin-axe/src/lib/runner/transform.ts b/packages/plugin-axe/src/lib/runner/transform.ts
@@ -1,4 +1,3 @@
-import axe from 'axe-core';
 import type {
   AuditOutput,
   AuditOutputs,
@@ -11,6 +10,7 @@ import {
   pluralizeToken,
   truncateIssueMessage,
 } from '@code-pushup/utils';
+import axe from '../safe-axe-core-import.js';
 
 /**
  * Transforms Axe results into audit outputs.
diff --git a/packages/plugin-axe/src/lib/runner/transform.unit.test.ts b/packages/plugin-axe/src/lib/runner/transform.unit.test.ts
@@ -1,5 +1,9 @@
-import type { AxeResults, NodeResult, Result } from 'axe-core';
 import type { AuditOutput } from '@code-pushup/models';
+import type {
+  AxeResults,
+  NodeResult,
+  Result,
+} from '../safe-axe-core-import.js';
 import { toAuditOutputs } from './transform.js';
 
 function createMockNode(overrides: Partial<NodeResult> = {}): NodeResult {
diff --git a/packages/plugin-axe/src/lib/safe-axe-core-import.ts b/packages/plugin-axe/src/lib/safe-axe-core-import.ts
@@ -0,0 +1,33 @@
+/**
+ * Safe Axe-core Import Entry Point
+ *
+ * This is the ONLY safe way to import axe-core in this codebase.
+ * All files should import from this module instead of importing directly from 'axe-core'.
+ *
+ * WHY THIS EXISTS:
+ * axe-core requires global `window` and `document` objects to exist when imported.
+ * Due to ES module import hoisting, we need a fixed import chain to ensure the
+ * jsdom polyfill runs before axe-core loads.
+ *
+ * IMPORT CHAIN:
+ * jsdom.polyfill.ts → axe-core-polyfilled.ts → safe-axe-core-import.ts → your code
+ *
+ * USAGE:
+ * Instead of: import axe from 'axe-core';
+ * Use:        import axe from './safe-axe-core-import.js';
+ *
+ * Instead of: import type { AxeResults } from 'axe-core';
+ * Use:        import type { AxeResults } from './safe-axe-core-import.js';
+ */
+
+// Re-export everything from the polyfilled version
+export { default } from './axe-core-polyfilled.js';
+export type {
+  AxeResults,
+  NodeResult,
+  Result,
+  IncompleteResult,
+  RuleMetadata,
+  ImpactValue,
+  CrossTreeSelector,
+} from './axe-core-polyfilled.js';
