feat(plugin-axe): implement runner with Playwright/Axe integration

feat(plugin-axe): implement runner with Playwright/Axe integration

Author: hanna-skryl

packages/plugin-axe/README.md

@@ -0,0 +1,7 @@
+# plugin-axe
+
+This library was generated with [Nx](https://nx.dev).
+
+## Running unit tests
+
+Run `nx test plugin-axe` to execute the unit tests via [Vitest](https://vitest.dev/).

packages/plugin-axe/src/index.ts

@@ -1 +1,3 @@
-export * from './lib/axe-plugin.js';
+import { axePlugin } from './lib/axe-plugin.js';
+
+export default axePlugin;

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

@@ -1,3 +1,47 @@
-export function axePlugin(): string {
-  return 'plugin-axe';
+import { createRequire } from 'node:module';
+import type { PluginConfig, PluginUrls } from '@code-pushup/models';
+import { normalizeUrlInput } from '@code-pushup/utils';
+import type { AxePluginOptions } from './config';
+import { AXE_DEFAULT_PRESET, AXE_PLUGIN_SLUG } from './constants';
+import { processAuditsAndGroups } from './processing';
+import { createRunnerFunction } from './runner/runner';
+
+/**
+ * Code PushUp plugin for accessibility testing using axe-core.
+ *
+ * @public
+ * @param urls - {@link PluginUrls} URL(s) to test
+ * @param options - {@link AxePluginOptions} Plugin options
+ * @returns Plugin configuration
+ */
+export function axePlugin(
+  urls: PluginUrls,
+  options?: AxePluginOptions,
+): PluginConfig {
+  const scoreTargets = options?.scoreTargets;
+  const preset = options?.preset ?? AXE_DEFAULT_PRESET;
+
+  const { urls: normalizedUrls, context } = normalizeUrlInput(urls);
+
+  const { audits, groups, ruleIds } = processAuditsAndGroups(
+    normalizedUrls,
+    preset,
+  );
+
+  const packageJson = createRequire(import.meta.url)(
+    '../../package.json',
+  ) as typeof import('../../package.json');
+
+  return {
+    slug: AXE_PLUGIN_SLUG,
+    packageName: packageJson.name,
+    version: packageJson.version,
+    title: 'Axe Accessibility',
+    icon: 'folder-syntax',
+    audits,
+    groups,
+    runner: createRunnerFunction(normalizedUrls, ruleIds),
+    context,
+    ...(scoreTargets && { scoreTargets }),
+  };
 }

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

@@ -0,0 +1,62 @@
+import AxeBuilder from '@axe-core/playwright';
+import { type Browser, chromium } from 'playwright-core';
+import type { AuditOutputs } from '@code-pushup/models';
+import { logger, stringifyError } from '@code-pushup/utils';
+import { toAuditOutputs } from './transform.js';
+
+let browser: Browser | undefined;
+
+export async function runAxeForUrl(
+  url: string,
+  ruleIds: string[],
+): Promise<AuditOutputs> {
+  try {
+    if (!browser) {
+      logger.debug('Launching Chromium browser...');
+      browser = await chromium.launch({ headless: true });
+    }
+
+    const context = await browser.newContext();
+
+    try {
+      const page = await context.newPage();
+      try {
+        await page.goto(url, {
+          waitUntil: 'networkidle',
+          timeout: 30_000,
+        });
+
+        const axeBuilder = new AxeBuilder({ page });
+
+        // Use withRules() to include experimental/deprecated rules
+        if (ruleIds.length > 0) {
+          axeBuilder.withRules(ruleIds);
+        }
+
+        const results = await axeBuilder.analyze();
+
+        if (results.incomplete.length > 0) {
+          logger.warn(
+            `Axe returned ${results.incomplete.length} incomplete result(s) for ${url}`,
+          );
+        }
+
+        return toAuditOutputs(results, url);
+      } finally {
+        await page.close();
+      }
+    } finally {
+      await context.close();
+    }
+  } catch (error) {
+    logger.error(`Axe execution failed for ${url}: ${stringifyError(error)}`);
+    throw error;
+  }
+}
+
+export async function closeBrowser(): Promise<void> {
+  if (browser) {
+    await browser.close();
+    browser = undefined;
+  }
+}

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

@@ -0,0 +1,65 @@
+import type {
+  AuditOutputs,
+  RunnerArgs,
+  RunnerFunction,
+} from '@code-pushup/models';
+import {
+  addIndex,
+  logger,
+  shouldExpandForUrls,
+  stringifyError,
+} from '@code-pushup/utils';
+import { closeBrowser, runAxeForUrl } from './run-axe.js';
+
+export function createRunnerFunction(
+  urls: string[],
+  ruleIds: string[],
+): RunnerFunction {
+  return async (_runnerArgs?: RunnerArgs): Promise<AuditOutputs> => {
+    const isSingleUrl = !shouldExpandForUrls(urls.length);
+
+    logger.info(
+      `Running Axe accessibility checks for ${urls.length} URL(s)...`,
+    );
+
+    try {
+      const allResults = await urls.reduce(async (prev, url, index) => {
+        const acc = await prev;
+
+        logger.debug(`Testing URL ${index + 1}/${urls.length}: ${url}`);
+
+        try {
+          const auditOutputs = await runAxeForUrl(url, ruleIds);
+
+          const processedOutputs = isSingleUrl
+            ? auditOutputs
+            : auditOutputs.map(audit => ({
+                ...audit,
+                slug: addIndex(audit.slug, index),
+              }));
+
+          return [...acc, ...processedOutputs];
+        } catch (error) {
+          logger.warn(stringifyError(error));
+          return acc;
+        }
+      }, Promise.resolve<AuditOutputs>([]));
+
+      if (allResults.length === 0) {
+        throw new Error(
+          isSingleUrl
+            ? 'Axe did not produce any results.'
+            : 'Axe failed to produce results for all URLs.',
+        );
+      }
+
+      logger.info(
+        `Completed Axe accessibility checks with ${allResults.length} audit(s)`,
+      );
+
+      return allResults;
+    } finally {
+      await closeBrowser();
+    }
+  };
+}

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

@@ -0,0 +1,141 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { type AuditOutput, DEFAULT_PERSIST_CONFIG } from '@code-pushup/models';
+import * as runAxe from './run-axe.js';
+import { createRunnerFunction } from './runner.js';
+
+vi.mock('./run-axe.js', () => ({
+  runAxeForUrl: vi.fn(),
+  closeBrowser: vi.fn(),
+}));
+
+describe('createRunnerFunction', () => {
+  const mockRunAxeForUrl = vi.mocked(runAxe.runAxeForUrl);
+  const mockCloseBrowser = vi.mocked(runAxe.closeBrowser);
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  const createMockAuditOutput = (slug: string, score = 1): AuditOutput => ({
+    slug,
+    score,
+    value: 0,
+    displayValue: 'No violations found',
+  });
+
+  it('should handle single URL without adding index to audit slugs', async () => {
+    const mockResults = [
+      createMockAuditOutput('image-alt'),
+      createMockAuditOutput('html-has-lang'),
+    ];
+    mockRunAxeForUrl.mockResolvedValue(mockResults);
+
+    const runnerFn = createRunnerFunction(['https://example.com'], []);
+    const results = await runnerFn({ persist: DEFAULT_PERSIST_CONFIG });
+
+    expect(mockRunAxeForUrl).toHaveBeenCalledWith('https://example.com', []);
+    expect(mockCloseBrowser).toHaveBeenCalled();
+    expect(results).toEqual(mockResults);
+  });
+
+  it('should handle multiple URLs and add index to audit slugs', async () => {
+    const mockResults1 = [
+      createMockAuditOutput('image-alt'),
+      createMockAuditOutput('html-has-lang'),
+    ];
+    const mockResults2 = [
+      createMockAuditOutput('image-alt'),
+      createMockAuditOutput('color-contrast'),
+    ];
+
+    mockRunAxeForUrl
+      .mockResolvedValueOnce(mockResults1)
+      .mockResolvedValueOnce(mockResults2);
+
+    const runnerFn = createRunnerFunction(
+      ['https://example.com', 'https://another-example.org'],
+      [],
+    );
+    const results = await runnerFn({ persist: DEFAULT_PERSIST_CONFIG });
+
+    expect(mockRunAxeForUrl).toHaveBeenCalledTimes(2);
+    expect(mockRunAxeForUrl).toHaveBeenNthCalledWith(
+      1,
+      'https://example.com',
+      [],
+    );
+    expect(mockRunAxeForUrl).toHaveBeenNthCalledWith(
+      2,
+      'https://another-example.org',
+      [],
+    );
+    expect(mockCloseBrowser).toHaveBeenCalled();
+
+    expect(results).toHaveLength(4);
+    expect(results.map(({ slug }) => slug)).toEqual([
+      'image-alt-1',
+      'html-has-lang-1',
+      'image-alt-2',
+      'color-contrast-2',
+    ]);
+  });
+
+  it('should pass ruleIds to runAxeForUrl', async () => {
+    const mockResults = [
+      createMockAuditOutput('image-alt'),
+      createMockAuditOutput('html-has-lang'),
+    ];
+    mockRunAxeForUrl.mockResolvedValue(mockResults);
+
+    const ruleIds = ['image-alt', 'html-has-lang'];
+    const runnerFn = createRunnerFunction(['https://example.com'], ruleIds);
+    await runnerFn({ persist: DEFAULT_PERSIST_CONFIG });
+
+    expect(mockRunAxeForUrl).toHaveBeenCalledWith(
+      'https://example.com',
+      ruleIds,
+    );
+  });
+
+  it('should continue with other URLs when one fails in multiple URL scenario', async () => {
+    const mockResults = [createMockAuditOutput('image-alt')];
+
+    mockRunAxeForUrl
+      .mockRejectedValueOnce(new Error('Failed to load page'))
+      .mockResolvedValueOnce(mockResults);
+
+    const runnerFn = createRunnerFunction(
+      ['https://broken.com', 'https://working.com'],
+      [],
+    );
+    const results = await runnerFn({ persist: DEFAULT_PERSIST_CONFIG });
+
+    expect(mockRunAxeForUrl).toHaveBeenCalledTimes(2);
+    expect(mockCloseBrowser).toHaveBeenCalled();
+    expect(results).toHaveLength(1);
+    expect(results[0]?.slug).toBe('image-alt-2');
+  });
+
+  it('should throw error if all URLs fail in multiple URL scenario', async () => {
+    mockRunAxeForUrl.mockRejectedValue(new Error('Failed to load page'));
+
+    const runnerFn = createRunnerFunction(
+      ['https://example.com', 'https://another-example.com'],
+      [],
+    );
+
+    await expect(runnerFn({ persist: DEFAULT_PERSIST_CONFIG })).rejects.toThrow(
+      'Axe failed to produce results for all URLs.',
+    );
+  });
+
+  it('should throw error when single URL fails', async () => {
+    mockRunAxeForUrl.mockRejectedValue(new Error('Failed to load page'));
+
+    const runnerFn = createRunnerFunction(['https://example.com'], []);
+
+    await expect(runnerFn({ persist: DEFAULT_PERSIST_CONFIG })).rejects.toThrow(
+      'Axe did not produce any results.',
+    );
+  });
+});