@avi770/testteam 1.2.0

package/agents/__tests__/08-a11y-guardian.test.ts

@@ -0,0 +1,530 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { ValidatedConfig } from '../../core/config';
+
+// ---------------------------------------------------------------------------
+// Stub config
+// ---------------------------------------------------------------------------
+
+const stubConfig: ValidatedConfig = {
+  schemaVersion: 1,
+  name: 'test',
+  auth: {
+    loginUrl: 'http://localhost/login',
+    credentials: { admin: { email: 'admin@test.com', password: 'secret' } },
+  },
+  modules: [
+    { id: 'dashboard', route: '/dashboard', sidebarIcon: true },
+    { id: 'invoices', route: '/invoices', sidebarIcon: true },
+  ],
+  environments: {
+    alpha: { baseUrl: 'http://localhost:3000', seed: false },
+  },
+  portals: [],
+  breakpoints: [],
+  integrations: [],
+  workers: [],
+  workflows: [],
+  accuracy: { enabled: false, decimalPrecision: 2, currencySymbol: '$', timezone: 'UTC' },
+  tenancy: { enabled: false, isolationField: 'firmId', testFirms: [] },
+  costBudget: { maxPerRun: 100, maxPerAgent: 10, alertThreshold: 0.8, onExceeded: 'abort' },
+  agentClassification: { blocking: [], advisory: [] },
+  thresholds: {
+    unitCoverage: { lines: 80, functions: 80, branches: 80, statements: 80 },
+    lighthouse: { accessibility: 90, performance: 90, bestPractices: 90, seo: 90 },
+    apiResponseTime: 2000,
+    bundleSizeLimit: 500000,
+    maxConsoleErrors: 0,
+  },
+  disabledAgents: [],
+  disabledAgentSet: new Set<number>(),
+};
+
+// ---------------------------------------------------------------------------
+// Mock child_process (preFlight playwright --version, lhci, pa11y-ci)
+// ---------------------------------------------------------------------------
+
+const execFileMock = vi.fn();
+vi.mock('child_process', () => ({
+  execFile: (...args: unknown[]) => execFileMock(...args),
+}));
+
+// ---------------------------------------------------------------------------
+// Mock navigation helpers
+// ---------------------------------------------------------------------------
+
+const loginMock = vi.fn().mockResolvedValue(undefined);
+const navigateToSectionMock = vi.fn().mockResolvedValue(undefined);
+const waitForSectionLoadMock = vi.fn().mockResolvedValue(undefined);
+
+vi.mock('../../helpers/navigation', () => ({
+  login: (...args: unknown[]) => loginMock(...args),
+  navigateToSection: (...args: unknown[]) => navigateToSectionMock(...args),
+  waitForSectionLoad: (...args: unknown[]) => waitForSectionLoadMock(...args),
+}));
+
+// ---------------------------------------------------------------------------
+// Mock screenshot helper
+// ---------------------------------------------------------------------------
+
+const captureScreenshotMock = vi.fn().mockResolvedValue('/tmp/test-run/screenshot.png');
+vi.mock('../../helpers/screenshot', () => ({
+  captureScreenshot: (...args: unknown[]) => captureScreenshotMock(...args),
+}));
+
+// ---------------------------------------------------------------------------
+// Mock AxeBuilder
+// ---------------------------------------------------------------------------
+
+const analyzeMock = vi.fn();
+
+vi.mock('@axe-core/playwright', () => ({
+  AxeBuilder: class MockAxeBuilder {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    constructor(..._args: unknown[]) {}
+    analyze = analyzeMock;
+  },
+}));
+
+// ---------------------------------------------------------------------------
+// Mock Playwright
+// ---------------------------------------------------------------------------
+
+interface MockPage {
+  close: ReturnType<typeof vi.fn>;
+}
+
+function makeMockPage(): MockPage {
+  return { close: vi.fn().mockResolvedValue(undefined) };
+}
+
+let currentMockPage: MockPage;
+let mockBrowser: { newPage: ReturnType<typeof vi.fn>; close: ReturnType<typeof vi.fn> };
+
+vi.mock('playwright', async () => ({
+  chromium: {
+    launch: vi.fn().mockImplementation(async () => mockBrowser),
+  },
+}));
+
+// ---------------------------------------------------------------------------
+// Dynamic import AFTER mocks
+// ---------------------------------------------------------------------------
+
+const { A11yGuardianAgent, mapAxeImpact } = await import('../08-a11y-guardian');
+
+function createAgent(): InstanceType<typeof A11yGuardianAgent> {
+  return new A11yGuardianAgent(stubConfig, 'beta', '/tmp/test-run');
+}
+
+function makeExecSuccess(): void {
+  execFileMock.mockImplementationOnce(
+    (_file: string, _args: string[], _opts: unknown, cb: (err: Error | null, stdout: string, stderr: string) => void) => {
+      cb(null, '1.40.0\n', '');
+    },
+  );
+}
+
+function makeExecFailure(): void {
+  execFileMock.mockImplementationOnce(
+    (_file: string, _args: string[], _opts: unknown, cb: (err: Error | null, stdout: string, stderr: string) => void) => {
+      cb(new Error('command not found'), '', '');
+    },
+  );
+}
+
+function makeCleanAxeResult(): object {
+  return { violations: [] };
+}
+
+function makeViolation(impact: string, id = 'button-name'): object {
+  return {
+    id,
+    description: `Ensure ${id} elements have discernible text`,
+    impact,
+    nodes: [{ html: '<button></button>', target: ['button'] }],
+    help: `https://dequeuniversity.com/rules/${id}`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('A11yGuardianAgent', () => {
+  beforeEach(() => {
+    execFileMock.mockReset();
+    loginMock.mockReset().mockResolvedValue(undefined);
+    navigateToSectionMock.mockReset().mockResolvedValue(undefined);
+    waitForSectionLoadMock.mockReset().mockResolvedValue(undefined);
+    captureScreenshotMock.mockReset().mockResolvedValue('/tmp/test-run/screenshot.png');
+    analyzeMock.mockReset().mockResolvedValue(makeCleanAxeResult());
+
+    currentMockPage = makeMockPage();
+    mockBrowser = {
+      newPage: vi.fn().mockResolvedValue(currentMockPage),
+      close: vi.fn().mockResolvedValue(undefined),
+    };
+
+    // Default: preFlight succeeds; lhci and pa11y-ci fail silently (not installed)
+    makeExecSuccess();           // playwright --version (preFlight)
+    execFileMock.mockImplementation(  // lhci and pa11y-ci: fail silently
+      (_file: string, _args: string[], _opts: unknown, cb: (err: Error | null, stdout: string, stderr: string) => void) => {
+        cb(new Error('not found'), '', '');
+      },
+    );
+  });
+
+  // -------------------------------------------------------------------------
+  // Identity
+  // -------------------------------------------------------------------------
+
+  it('has agentId 8 and agentName "A11y Guardian"', () => {
+    const agent = createAgent();
+    expect(agent.agentId).toBe(8);
+    expect(agent.agentName).toBe('A11y Guardian');
+  });
+
+  // -------------------------------------------------------------------------
+  // mapAxeImpact utility
+  // -------------------------------------------------------------------------
+
+  describe('mapAxeImpact()', () => {
+    it('maps "critical" → "critical"', () => {
+      expect(mapAxeImpact('critical')).toBe('critical');
+    });
+
+    it('maps "serious" → "high"', () => {
+      expect(mapAxeImpact('serious')).toBe('high');
+    });
+
+    it('maps "moderate" → "medium"', () => {
+      expect(mapAxeImpact('moderate')).toBe('medium');
+    });
+
+    it('maps "minor" → "low"', () => {
+      expect(mapAxeImpact('minor')).toBe('low');
+    });
+
+    it('maps null → "low"', () => {
+      expect(mapAxeImpact(null)).toBe('low');
+    });
+
+    it('maps unknown strings → "low"', () => {
+      expect(mapAxeImpact('unknown-impact')).toBe('low');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // preFlight
+  // -------------------------------------------------------------------------
+
+  describe('preFlight()', () => {
+    it('fails when playwright is not available', async () => {
+      execFileMock.mockReset();
+      makeExecFailure();
+
+      const agent = createAgent();
+      const result = await agent.run();
+
+      expect(result.status).toBe('failed');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // execute() — module iteration
+  // -------------------------------------------------------------------------
+
+  describe('execute()', () => {
+    it('logs in once before scanning modules', async () => {
+      const agent = createAgent();
+      await agent.run();
+
+      expect(loginMock).toHaveBeenCalledTimes(1);
+      expect(loginMock).toHaveBeenCalledWith(
+        currentMockPage,
+        stubConfig.auth.credentials!['admin'],
+        stubConfig.auth.loginUrl,
+      );
+    });
+
+    it('navigates to each configured module', async () => {
+      const agent = createAgent();
+      await agent.run();
+
+      expect(navigateToSectionMock).toHaveBeenCalledTimes(stubConfig.modules.length);
+    });
+
+    it('runs axe-core scan for each module', async () => {
+      const agent = createAgent();
+      await agent.run();
+
+      expect(analyzeMock).toHaveBeenCalledTimes(stubConfig.modules.length);
+    });
+
+    it('takes a screenshot for each module', async () => {
+      const agent = createAgent();
+      const result = await agent.run();
+
+      const screenshotEvidence = result.evidence.filter(e => e.type === 'screenshot');
+      expect(screenshotEvidence).toHaveLength(stubConfig.modules.length);
+    });
+
+    it('returns passed status with no findings when all modules are clean', async () => {
+      const agent = createAgent();
+      const result = await agent.run();
+
+      expect(result.status).toBe('passed');
+      expect(result.findings).toHaveLength(0);
+    });
+
+    it('creates a finding for each axe violation per module', async () => {
+      analyzeMock.mockResolvedValue({
+        violations: [
+          makeViolation('serious', 'button-name'),
+          makeViolation('moderate', 'color-contrast'),
+        ],
+      });
+
+      const agent = createAgent();
+      const result = await agent.run();
+
+      // 2 violations × 2 modules = 4 findings
+      expect(result.findings).toHaveLength(4);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Severity mapping
+  // -------------------------------------------------------------------------
+
+  describe('severity mapping', () => {
+    it('maps critical axe impact to critical finding severity', async () => {
+      analyzeMock.mockResolvedValueOnce({ violations: [makeViolation('critical')] });
+      analyzeMock.mockResolvedValueOnce({ violations: [] });
+
+      const agent = createAgent();
+      const result = await agent.run();
+
+      const criticalFinding = result.findings.find(f => f.severity === 'critical');
+      expect(criticalFinding).toBeDefined();
+    });
+
+    it('maps serious axe impact to high finding severity', async () => {
+      analyzeMock.mockResolvedValueOnce({ violations: [makeViolation('serious')] });
+      analyzeMock.mockResolvedValueOnce({ violations: [] });
+
+      const agent = createAgent();
+      const result = await agent.run();
+
+      const highFinding = result.findings.find(f => f.severity === 'high');
+      expect(highFinding).toBeDefined();
+      expect(highFinding!.type).toBe('code-bug-logic');
+    });
+
+    it('maps moderate axe impact to medium finding severity', async () => {
+      analyzeMock.mockResolvedValueOnce({ violations: [makeViolation('moderate')] });
+      analyzeMock.mockResolvedValueOnce({ violations: [] });
+
+      const agent = createAgent();
+      const result = await agent.run();
+
+      const medFinding = result.findings.find(f => f.severity === 'medium');
+      expect(medFinding).toBeDefined();
+    });
+
+    it('maps minor axe impact to low finding severity', async () => {
+      analyzeMock.mockResolvedValueOnce({ violations: [makeViolation('minor')] });
+      analyzeMock.mockResolvedValueOnce({ violations: [] });
+
+      const agent = createAgent();
+      const result = await agent.run();
+
+      const lowFinding = result.findings.find(f => f.severity === 'low');
+      expect(lowFinding).toBeDefined();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Navigation failure
+  // -------------------------------------------------------------------------
+
+  describe('navigation failure handling', () => {
+    it('creates an infra-issue finding when navigation fails and continues to next module', async () => {
+      navigateToSectionMock.mockImplementation(
+        async (_page: unknown, moduleId: string) => {
+          if (moduleId === 'dashboard') {
+            throw new Error('Timeout navigating to dashboard');
+          }
+        },
+      );
+
+      const agent = createAgent();
+      const result = await agent.run();
+
+      const navFinding = result.findings.find(f =>
+        f.id.includes('nav-dashboard'),
+      );
+      expect(navFinding).toBeDefined();
+      expect(navFinding!.type).toBe('infra-issue');
+
+      // Should still scan the 'invoices' module
+      expect(analyzeMock).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // axe failure handling
+  // -------------------------------------------------------------------------
+
+  describe('axe scan failure handling', () => {
+    it('creates a medium infra-issue finding when axe.analyze() throws', async () => {
+      analyzeMock.mockRejectedValueOnce(new Error('axe failed to inject'));
+
+      const agent = createAgent();
+      const result = await agent.run();
+
+      const axeErrorFinding = result.findings.find(f =>
+        f.id.includes('axe-error'),
+      );
+      expect(axeErrorFinding).toBeDefined();
+      expect(axeErrorFinding!.severity).toBe('medium');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Login failure handling
+  // -------------------------------------------------------------------------
+
+  describe('login failure handling', () => {
+    it('continues scanning anonymously when login fails', async () => {
+      loginMock.mockRejectedValue(new Error('Invalid credentials'));
+      // A11y agent needs page.goto for the anonymous fallback navigation
+      (currentMockPage as unknown as Record<string, unknown>).goto = vi.fn().mockResolvedValue(undefined);
+
+      const agent = createAgent();
+      const result = await agent.run();
+
+      const loginFinding = result.findings.find(f => f.id.includes('login-failed'));
+      expect(loginFinding).toBeDefined();
+      expect(loginFinding!.severity).toBe('medium');
+
+      // Should still run axe scans
+      expect(analyzeMock).toHaveBeenCalled();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Lighthouse CI (optional)
+  // -------------------------------------------------------------------------
+
+  describe('Lighthouse CI integration', () => {
+    it('adds report evidence when lhci autorun succeeds', async () => {
+      // Reset default mock first
+      execFileMock.mockReset();
+      // preFlight: playwright --version succeeds
+      makeExecSuccess();
+      // lhci autorun succeeds
+      execFileMock.mockImplementationOnce(
+        (_file: string, _args: string[], _opts: unknown, cb: (err: Error | null, stdout: string, stderr: string) => void) => {
+          cb(null, 'lhci done', '');
+        },
+      );
+      // pa11y-ci fails
+      execFileMock.mockImplementation(
+        (_file: string, _args: string[], _opts: unknown, cb: (err: Error | null, stdout: string, stderr: string) => void) => {
+          cb(new Error('not found'), '', '');
+        },
+      );
+
+      const agent = createAgent();
+      const result = await agent.run();
+
+      const lhEvidence = result.evidence.find(e => e.description.includes('Lighthouse'));
+      expect(lhEvidence).toBeDefined();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Pa11y CI (optional)
+  // -------------------------------------------------------------------------
+
+  describe('Pa11y CI integration', () => {
+    it('adds report evidence when pa11y-ci succeeds', async () => {
+      execFileMock.mockReset();
+      // preFlight
+      makeExecSuccess();
+      // lhci fails
+      execFileMock.mockImplementationOnce(
+        (_file: string, _args: string[], _opts: unknown, cb: (err: Error | null, stdout: string, stderr: string) => void) => {
+          cb(new Error('not found'), '', '');
+        },
+      );
+      // pa11y-ci succeeds
+      execFileMock.mockImplementationOnce(
+        (_file: string, _args: string[], _opts: unknown, cb: (err: Error | null, stdout: string, stderr: string) => void) => {
+          cb(null, 'pa11y done', '');
+        },
+      );
+
+      const agent = createAgent();
+      const result = await agent.run();
+
+      const pa11yEvidence = result.evidence.find(e => e.description.includes('Pa11y'));
+      expect(pa11yEvidence).toBeDefined();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Violation help URL included in suggestedFix
+  // -------------------------------------------------------------------------
+
+  describe('violation suggestedFix', () => {
+    it('includes violation help text in suggestedFix field', async () => {
+      analyzeMock.mockResolvedValueOnce({
+        violations: [{
+          id: 'image-alt',
+          impact: 'serious',
+          description: 'Images must have alt text',
+          help: 'Ensure images have alternative text',
+          helpUrl: 'https://dequeuniversity.com/rules/image-alt',
+          nodes: [{ html: '<img src="logo.png">' }],
+        }],
+      });
+      analyzeMock.mockResolvedValueOnce({ violations: [] });
+
+      const agent = createAgent();
+      const result = await agent.run();
+
+      const imgFinding = result.findings.find(f => f.id.includes('image-alt'));
+      expect(imgFinding).toBeDefined();
+      expect(imgFinding!.suggestedFix).toBe('Ensure images have alternative text');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Missing config
+  // -------------------------------------------------------------------------
+
+  describe('missing config handling', () => {
+    it('fails with critical finding when no environment is configured', async () => {
+      const cfg: ValidatedConfig = { ...stubConfig, environments: {} };
+      const agent = new A11yGuardianAgent(cfg, 'beta', '/tmp/test-run');
+      const result = await agent.run();
+
+      expect(result.findings[0].severity).toBe('critical');
+      expect(result.findings[0].description).toContain('No environment');
+    });
+
+    it('fails with critical finding when no credentials are configured', async () => {
+      const cfg: ValidatedConfig = {
+        ...stubConfig,
+        auth: { loginUrl: 'http://localhost/login', credentials: {} },
+      };
+      const agent = new A11yGuardianAgent(cfg, 'beta', '/tmp/test-run');
+      const result = await agent.run();
+
+      expect(result.findings[0].severity).toBe('critical');
+      expect(result.findings[0].description).toContain('credentials');
+    });
+  });
+});