feat(plugin-axe): add authentication support via setup script

code-pushup.preset.ts

@@ -5,7 +5,10 @@ import type {
   CoreConfig,
   PluginUrls,
 } from './packages/models/src/index.js';
-import axePlugin, { axeCategories } from './packages/plugin-axe/src/index.js';
+import axePlugin, {
+  type AxePluginOptions,
+  axeCategories,
+} from './packages/plugin-axe/src/index.js';
 import coveragePlugin, {
   type CoveragePluginConfig,
   getNxCoveragePaths,
@@ -226,8 +229,11 @@ export async function configureLighthousePlugin(
   };
 }
 
-export function configureAxePlugin(urls: PluginUrls): CoreConfig {
-  const axe = axePlugin(urls);
+export function configureAxePlugin(
+  urls: PluginUrls,
+  options?: AxePluginOptions,
+): CoreConfig {
+  const axe = axePlugin(urls, options);
   return {
     plugins: [axe],
     categories: axeCategories(axe),

e2e/plugin-axe-e2e/tests/collect.e2e.test.ts

@@ -7,6 +7,7 @@ import {
   E2E_ENVIRONMENTS_DIR,
   TEST_OUTPUT_DIR,
   omitVariableReportData,
+  restoreNxIgnoredFiles,
   teardownTestFolder,
 } from '@code-pushup/test-utils';
 import { executeProcess, readJsonFile } from '@code-pushup/utils';
@@ -22,17 +23,17 @@ function sanitizeReportPaths(report: Report): Report {
 }
 
 describe('PLUGIN collect report with axe-plugin NPM package', () => {
+  const fixturesDir = path.join('e2e', nxTargetProject(), 'mocks', 'fixtures');
   const testFileDir = path.join(
     E2E_ENVIRONMENTS_DIR,
     nxTargetProject(),
     TEST_OUTPUT_DIR,
     'collect',
   );
-  const defaultSetupDir = path.join(testFileDir, 'default-setup');
-  const fixturesDir = path.join('e2e', nxTargetProject(), 'mocks', 'fixtures');
 
   beforeAll(async () => {
     await cp(fixturesDir, testFileDir, { recursive: true });
+    await restoreNxIgnoredFiles(testFileDir);
   });
 
   afterAll(async () => {
@@ -43,13 +44,13 @@ describe('PLUGIN collect report with axe-plugin NPM package', () => {
     const { code } = await executeProcess({
       command: 'npx',
       args: ['@code-pushup/cli', 'collect'],
-      cwd: defaultSetupDir,
+      cwd: testFileDir,
     });
 
     expect(code).toBe(0);
 
-    const report: Report = await readJsonFile(
-      path.join(defaultSetupDir, '.code-pushup', 'report.json'),
+    const report = await readJsonFile<Report>(
+      path.join(testFileDir, '.code-pushup', 'report.json'),
     );
 
     expect(() => reportSchema.parse(report)).not.toThrow();

package.json

@@ -45,7 +45,7 @@
     "wrap-ansi": "^9.0.2",
     "yaml": "^2.5.1",
     "yargs": "^17.7.2",
-    "zod": "^4.0.5"
+    "zod": "^4.2.1"
   },
   "devDependencies": {
     "@actions/core": "^1.11.1",

packages/ci/package.json

@@ -33,7 +33,7 @@
     "glob": "^11.0.1",
     "simple-git": "^3.20.0",
     "yaml": "^2.5.1",
-    "zod": "^4.0.5"
+    "zod": "^4.2.1"
   },
   "files": [
     "src",

packages/models/package.json

@@ -29,7 +29,7 @@
   "dependencies": {
     "ansis": "^3.3.2",
     "vscode-material-icons": "^0.1.0",
-    "zod": "^4.0.5"
+    "zod": "^4.2.1"
   },
   "files": [
     "src",

packages/models/src/index.ts

@@ -164,3 +164,4 @@ export {
   type Tree,
 } from './lib/tree.js';
 export { uploadConfigSchema, type UploadConfig } from './lib/upload-config.js';
+export { convertAsyncZodFunctionToSchema } from './lib/implementation/function.js';

packages/models/src/lib/implementation/schemas.ts

@@ -1,12 +1,5 @@
 import { MATERIAL_ICONS } from 'vscode-material-icons';
-import {
-  ZodError,
-  type ZodIssue,
-  type ZodObject,
-  type ZodOptional,
-  type ZodString,
-  z,
-} from 'zod';
+import { type ZodObject, type ZodOptional, type ZodString, z } from 'zod';
 import {
   MAX_DESCRIPTION_LENGTH,
   MAX_SLUG_LENGTH,
@@ -65,28 +58,24 @@ export const descriptionSchema = z
   .optional();
 
 /* Schema for a URL */
-export const urlSchema = z.string().url().meta({ title: 'URL' });
+export const urlSchema = z.url().meta({ title: 'URL' });
 
 /**  Schema for a docsUrl */
-export const docsUrlSchema = urlSchema
+export const docsUrlSchema = z
+  .union([
+    z.literal(''), // allow empty string (no URL validation)
+    // eslint-disable-next-line unicorn/prefer-top-level-await, unicorn/catch-error-name
+    urlSchema.optional().catch(ctx => {
+      const issue = ctx.issues[0];
+      if (issue?.code === 'invalid_format' && issue?.format === 'url') {
+        console.warn(`Ignoring invalid docsUrl: ${ctx.value}`);
+        return '';
+      }
+      // re-parse to throw formatted error for non-URL issues
+      return urlSchema.parse(ctx.value);
+    }),
+  ])
   .optional()
-  .or(z.literal('')) // allow empty string (no URL validation)
-  // eslint-disable-next-line unicorn/prefer-top-level-await, unicorn/catch-error-name
-  .catch(ctx => {
-    // if only URL validation fails, supress error since this metadata is optional anyway
-    if (
-      ctx.issues.length === 1 &&
-      (ctx.issues[0]?.errors as ZodIssue[][])
-        .flat()
-        .some(
-          error => error.code === 'invalid_format' && error.format === 'url',
-        )
-    ) {
-      console.warn(`Ignoring invalid docsUrl: ${ctx.value}`);
-      return '';
-    }
-    throw new ZodError(ctx.error.issues);
-  })
   .meta({ title: 'DocsUrl', description: 'Documentation site' });
 
 /** Schema for a title of a plugin, category and audit */

packages/models/src/lib/implementation/schemas.unit.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
 import {
   type TableCellValue,
   docsUrlSchema,

packages/plugin-axe/README.md

@@ -68,9 +68,10 @@ axePlugin(urls: PluginUrls, options?: AxePluginOptions)
 | Property       | Type        | Default      | Description                               |
 | -------------- | ----------- | ------------ | ----------------------------------------- |
 | `preset`       | `AxePreset` | `'wcag21aa'` | Accessibility ruleset preset              |
+| `setupScript`  | `string`    | `undefined`  | Path to authentication setup script       |
 | `scoreTargets` | `object`    | `undefined`  | Pass/fail thresholds for audits or groups |
 
-See [Presets](#presets) for the list of available presets and [Preset details](#preset-details) for what each preset includes.
+See [Presets](#presets) and [Authentication](#authentication) sections below.
 
 ## Multiple URLs
 
@@ -92,6 +93,56 @@ axePlugin({
 
 URLs with higher weights contribute more to overall scores. For example, a URL with weight 3 has three times the influence of a URL with weight 1.
 
+## Authentication
+
+To test login-protected pages, provide a `setupScript` that authenticates before analysis:
+
+```ts
+axePlugin('https://example.com/dashboard', {
+  setupScript: './axe-setup.ts',
+});
+```
+
+The setup script must export a default async function that receives a Playwright `Page` instance:
+
+```ts
+// axe-setup.ts
+import type { Page } from 'playwright-core';
+
+export default async function (page: Page): Promise<void> {
+  await page.goto('https://example.com/login');
+  await page.fill('#username', process.env.USERNAME);
+  await page.fill('#password', process.env.PASSWORD);
+  await page.click('button[type="submit"]');
+  await page.waitForURL('**/dashboard');
+}
+```
+
+The script runs once before analyzing URLs. Authentication state (cookies, localStorage) is automatically shared across all URL analyses.
+
+<details>
+<summary>Alternative: Cookie-based authentication</summary>
+
+If you have a session token, you can inject it directly via cookies:
+
+```ts
+// axe-setup.ts
+import type { Page } from 'playwright-core';
+
+export default async function (page: Page): Promise<void> {
+  await page.context().addCookies([
+    {
+      name: 'session_token',
+      value: process.env.SESSION_TOKEN,
+      domain: 'example.com',
+      path: '/',
+    },
+  ]);
+}
+```
+
+</details>
+
 ## Presets
 
 Choose which accessibility ruleset to test against using the `preset` option:

packages/plugin-axe/mocks/fixtures/invalid-setup-no-default.ts

@@ -0,0 +1,5 @@
+import type { Page } from 'playwright-core';
+
+export async function setup(page: Page): Promise<void> {
+  await page.goto('about:blank');
+}

packages/plugin-axe/mocks/fixtures/invalid-setup-wrong-type.ts

@@ -0,0 +1 @@
+export default 'not a function';

packages/plugin-axe/mocks/fixtures/valid-setup.ts

@@ -0,0 +1,5 @@
+import type { Page } from 'playwright-core';
+
+export default async function setup(page: Page): Promise<void> {
+  await page.goto('about:blank');
+}

packages/plugin-axe/package.json

@@ -46,7 +46,7 @@
     "@code-pushup/utils": "0.100.1",
     "axe-core": "^4.11.0",
     "playwright-core": "^1.56.1",
-    "zod": "^4.1.12"
+    "zod": "^4.2.1"
   },
   "files": [
     "src",

packages/plugin-axe/src/lib/axe-plugin.ts

@@ -22,7 +22,7 @@ export function axePlugin(
   urls: PluginUrls,
   options: AxePluginOptions = {},
 ): PluginConfig {
-  const { preset, scoreTargets, timeout } = validate(
+  const { preset, scoreTargets, timeout, setupScript } = validate(
     axePluginOptionsSchema,
     options,
   );
@@ -49,7 +49,7 @@ export function axePlugin(
     version: packageJson.version,
     audits,
     groups,
-    runner: createRunnerFunction(normalizedUrls, ruleIds, timeout),
+    runner: createRunnerFunction(normalizedUrls, ruleIds, timeout, setupScript),
     context,
     ...(scoreTargets && { scoreTargets }),
   };

packages/plugin-axe/src/lib/categories.ts

@@ -58,6 +58,7 @@ function expandCategories(
   );
 }
 
+/** Creates an aggregated accessibility category from Axe groups. */
 export function createAggregatedCategory(
   groups: Group[],
   context: PluginUrlContext,
@@ -72,6 +73,7 @@ export function createAggregatedCategory(
   };
 }
 
+/** Expands category refs for multiple URLs. */
 export function expandAggregatedCategory(
   category: CategoryConfig,
   context: PluginUrlContext,
@@ -84,6 +86,7 @@ export function expandAggregatedCategory(
   };
 }
 
+/** Extracts unique group slugs from Axe groups. */
 export function extractGroupSlugs(groups: Group[]): AxeCategoryGroupSlug[] {
   const slugs = groups.map(({ slug }) => removeIndex(slug));
   return [...new Set(slugs)].filter(isAxeGroupSlug);

packages/plugin-axe/src/lib/config.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import {
+  filePathSchema,
   pluginScoreTargetsSchema,
   positiveIntSchema,
 } from '@code-pushup/models';
@@ -21,6 +22,7 @@ export const axePluginOptionsSchema = z
       description:
         'Accessibility ruleset preset (default: wcag21aa for WCAG 2.1 Level AA compliance)',
     }),
+    setupScript: filePathSchema.optional(),
     scoreTargets: pluginScoreTargetsSchema.optional(),
     timeout: positiveIntSchema.default(DEFAULT_TIMEOUT_MS).meta({
       description:

packages/plugin-axe/src/lib/config.unit.test.ts

@@ -17,6 +17,12 @@ describe('axePluginOptionsSchema', () => {
     },
   );
 
+  it('should accept setupScript as a file path', () => {
+    expect(() =>
+      axePluginOptionsSchema.parse({ setupScript: 'src/axe-setup.js' }),
+    ).not.toThrow();
+  });
+
   it('should accept scoreTargets as a number between 0 and 1', () => {
     expect(() =>
       axePluginOptionsSchema.parse({ scoreTargets: 0.99 }),

packages/plugin-axe/src/lib/constants.ts

@@ -1,12 +1,18 @@
 import type { AxePreset } from './config.js';
 
+/** Unique identifier for the Axe plugin. */
 export const AXE_PLUGIN_SLUG = 'axe';
+
+/** Display title for the Axe plugin. */
 export const AXE_PLUGIN_TITLE = 'Axe';
 
+/** Default WCAG preset used when none is specified. */
 export const AXE_DEFAULT_PRESET = 'wcag21aa';
 
+/** Default timeout in milliseconds for page operations. */
 export const DEFAULT_TIMEOUT_MS = 30_000;
 
+/** Human-readable names for each Axe preset. */
 export const AXE_PRESET_NAMES: Record<AxePreset, string> = {
   wcag21aa: 'WCAG 2.1 AA',
   wcag22aa: 'WCAG 2.2 AA',

packages/plugin-axe/src/lib/groups.ts

@@ -27,6 +27,7 @@ const WCAG_PRESET_TAGS: Record<AxeWcagPreset, AxeWcagTag[]> = {
   wcag22aa: ['wcag2a', 'wcag21a', 'wcag2aa', 'wcag21aa', 'wcag22aa'],
 };
 
+/** Returns the WCAG tags for a given preset. */
 export function getWcagPresetTags(preset: AxeWcagPreset): AxeWcagTag[] {
   return WCAG_PRESET_TAGS[preset];
 }
@@ -54,6 +55,7 @@ export const axeCategoryGroupSlugSchema = z
 
 export type AxeCategoryGroupSlug = z.infer<typeof axeCategoryGroupSlugSchema>;
 
+/** Maps category group slugs to human-readable titles. */
 export const CATEGORY_GROUPS: Record<AxeCategoryGroupSlug, string> = {
   aria: 'ARIA',
   color: 'Color & Contrast',
@@ -70,6 +72,7 @@ export const CATEGORY_GROUPS: Record<AxeCategoryGroupSlug, string> = {
   'time-and-media': 'Media',
 };
 
+/** Type guard for valid Axe group slugs. */
 export function isAxeGroupSlug(slug: unknown): slug is AxeCategoryGroupSlug {
   return axeCategoryGroupSlugSchema.safeParse(slug).success;
 }

packages/plugin-axe/src/lib/meta/format.ts

@@ -1,4 +1,5 @@
 import { pluginMetaLogFormatter } from '@code-pushup/utils';
 import { AXE_PLUGIN_TITLE } from '../constants.js';
 
+/** Formats log messages with the Axe plugin prefix. */
 export const formatMetaLog = pluginMetaLogFormatter(AXE_PLUGIN_TITLE);