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

Author: hanna-skryl

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),

…ures/default-setup/code-pushup.config.ts …e2e/mocks/fixtures/code-pushup.config.tse2e/plugin-axe-e2e/mocks/fixtures/default-setup/code-pushup.config.ts renamed to e2e/plugin-axe-e2e/mocks/fixtures/code-pushup.config.ts e2e/plugin-axe-e2e/mocks/fixtures/default-setup/code-pushup.config.ts renamed to e2e/plugin-axe-e2e/mocks/fixtures/code-pushup.config.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();

…/mocks/fixtures/default-setup/index.html …plugin-axe-e2e/mocks/fixtures/index.htmle2e/plugin-axe-e2e/mocks/fixtures/default-setup/index.html renamed to e2e/plugin-axe-e2e/mocks/fixtures/index.html e2e/plugin-axe-e2e/mocks/fixtures/default-setup/index.html renamed to e2e/plugin-axe-e2e/mocks/fixtures/index.html

@@ -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';

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

@@ -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/models/src/index.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/README.md

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

packages/plugin-axe/mocks/fixtures/invalid-setup-no-default.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/mocks/fixtures/invalid-setup-wrong-type.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 }),
   };