From 95d553501c283d5c0753ddae80ac6e0f2b846bde Mon Sep 17 00:00:00 2001
From: waterWang <water.wang@users.noreply.github.com>
Date: Fri, 21 Aug 2026 17:26:42 +0800
Subject: [PATCH] feat: add automated axe-core accessibility scan in CI (Closes
 #175)

Add @axe-core/playwright to scan all frontend pages (landing, login,
register, dashboard, marketplace, invoice detail, portfolio, settings,
transactions, profile) for serious/critical accessibility violations.

The scan runs as a new `frontend-a11y` job in the CI pipeline on every
PR, with known-waiver violations documented in a waiver list.

Signed-off-by: waterWang <water.wang@users.noreply.github.com>
---
 .github/workflows/ci.yml               |  28 +++-
 invofi/apps/frontend/e2e/a11y.spec.ts  | 175 +++++++++++++++++++++++++
 invofi/apps/frontend/package-lock.json |  16 ++-
 invofi/apps/frontend/package.json      |   8 +-
 4 files changed, 222 insertions(+), 5 deletions(-)
 create mode 100644 invofi/apps/frontend/e2e/a11y.spec.ts

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index f859c2151..530fc6747 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -44,6 +44,32 @@ jobs:
       - run: npm ci
       - run: npm test
 
+  frontend-a11y:
+    name: Frontend / Accessibility Scan
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: invofi/apps/frontend
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: invofi/apps/frontend/package-lock.json
+      - run: npm ci
+      - name: Install Playwright Chromium + system deps
+        run: npx playwright install --with-deps chromium
+      - name: Run accessibility scan
+        run: npm run test:a11y
+      - name: Upload Playwright report
+        if: failure()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: playwright-a11y-report
+          path: invofi/apps/frontend/playwright-report
+          retention-days: 14
+
   frontend-build:
     name: Frontend / Build
     runs-on: ubuntu-latest
@@ -88,4 +114,4 @@ jobs:
       - uses: wagoid/commitlint-github-action@b948419dd99f3fd78a6548d48f94e3df7f6bf3ed # v6
 
   # Smart contract tests and WASM builds moved to Stellar-VaultLink/invofi-contracts
-  # (Rust-only CI) as part of the two-repo topology migration.
+  # (Rust-only CI) as part of the two-repo topology migration.
\ No newline at end of file
diff --git a/invofi/apps/frontend/e2e/a11y.spec.ts b/invofi/apps/frontend/e2e/a11y.spec.ts
new file mode 100644
index 000000000..46bedd8fb
--- /dev/null
+++ b/invofi/apps/frontend/e2e/a11y.spec.ts
@@ -0,0 +1,175 @@
+/**
+ * Automated accessibility scan (axe-core) for the InvoFi frontend.
+ *
+ * Scans every page listed in issue #175 using @axe-core/playwright and fails CI
+ * on serious/critical violations. Known, unavoidable violations are documented
+ * in a waiver list (see waivers below).
+ *
+ * The scan runs alongside the Playwright smoke suite as a separate CI job
+ * (see .github/workflows/ci.yml) so it does not block the fast-feedback unit
+ * test / lint pass.
+ */
+import { test, expect } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+import {
+  authenticate,
+  SMOKE_INVOICE,
+  SMOKE_INVOICES,
+  SMOKE_LISTINGS,
+  mockPositionListings,
+} from './fixtures';
+
+/**
+ * Known-violation waiver list.
+ *
+ * Every entry documents a specific rule + CSS selector that we accept as a
+ * known limitation. Add entries here only when:
+ *   1. The violation is a false positive (axe-core heuristic limitations).
+ *   2. The element is from a third-party library we cannot patch.
+ *   3. The fix would require a cross-cutting refactor tracked in a separate issue.
+ *
+ * Format: { ruleId: string, selector: string, reason: string }
+ */
+const WAIVERS = [
+  // The Stellar Wallet Kit dialog injects a <style> block with no text
+  // contrast requirements — it's a third-party overlay, not our code.
+  // Same for the SEP-10 wallet popup buttons.
+  {
+    ruleId: 'color-contrast',
+    selector: '.wallet-kit-dialog, [data-walletkit]',
+    reason: 'Third-party wallet kit dialog — upstream fix tracked in #176',
+  },
+  // The wallet sign-in buttons are rendered by the Stellar Wallets Kit
+  // library and use its own styling.
+  {
+    ruleId: 'button-name',
+    selector: '[data-walletkit] button',
+    reason: 'Third-party wallet kit buttons — labelled by the library, not our DOM',
+  },
+  // The Freighter auth redirect may produce a page with duplicate IDs
+  // from the extension's injected content script.
+  {
+    ruleId: 'duplicate-id',
+    selector: '#freighter-*',
+    reason: 'Freighter extension injects its own elements — not our DOM',
+  },
+];
+
+/**
+ * Runs axe-core on the current page and checks for violations, excluding
+ * known waivers.
+ */
+async function assertNoAccessibilityViolations(page: any) {
+  const builder = new AxeBuilder({ page })
+    .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'])
+    // Exclude known waivers
+    .options({
+      runOnly: {
+        type: 'tag',
+        values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'],
+      },
+    });
+
+  // Apply each waiver
+  for (const waiver of WAIVERS) {
+    builder.exclude(waiver.selector);
+  }
+
+  const results = await builder.analyze();
+
+  // Filter to only serious/critical violations
+  const seriousOrCritical = results.violations.filter(
+    (v) => v.impact === 'serious' || v.impact === 'critical',
+  );
+
+  // Log all violations for debugging
+  if (seriousOrCritical.length > 0) {
+    console.log(`\n⚠️  ${seriousOrCritical.length} serious/critical a11y violations found:`);
+    for (const v of seriousOrCritical) {
+      console.log(`  • ${v.id} (${v.impact}) — ${v.help}`);
+      console.log(`    ${v.helpUrl}`);
+      for (const node of v.nodes.slice(0, 3)) {
+        console.log(`    Target: ${node.target}`);
+      }
+    }
+  }
+
+  expect(seriousOrCritical).toHaveLength(0);
+}
+
+// ── Public pages ────────────────────────────────────────────────────────────
+
+test.describe('public page accessibility', () => {
+  test('landing page has no serious/critical violations', async ({ page }) => {
+    await page.goto('/');
+    await assertNoAccessibilityViolations(page);
+  });
+
+  test('login page has no serious/critical violations', async ({ page }) => {
+    await page.goto('/auth/login');
+    await assertNoAccessibilityViolations(page);
+  });
+
+  test('register page has no serious/critical violations', async ({ page }) => {
+    await page.goto('/auth/register');
+    await assertNoAccessibilityViolations(page);
+  });
+
+  test('register (lender role) page has no serious/critical violations', async ({ page }) => {
+    await page.goto('/auth/register?role=lender');
+    await assertNoAccessibilityViolations(page);
+  });
+});
+
+// ── Authenticated pages ─────────────────────────────────────────────────────
+
+test.describe('authenticated page accessibility', () => {
+  test('dashboard page has no serious/critical violations', async ({ page }) => {
+    await authenticate(page, { invoices: SMOKE_INVOICES });
+    await page.goto('/dashboard');
+    await assertNoAccessibilityViolations(page);
+  });
+
+  test('marketplace page has no serious/critical violations', async ({ page }) => {
+    await authenticate(page, { invoices: SMOKE_INVOICES });
+    await page.goto('/marketplace');
+    await assertNoAccessibilityViolations(page);
+  });
+
+  test('marketplace positions page has no serious/critical violations', async ({ page }) => {
+    await authenticate(page);
+    await mockPositionListings(page, SMOKE_LISTINGS);
+    await page.goto('/marketplace/positions');
+    await assertNoAccessibilityViolations(page);
+  });
+
+  test('invoice detail page has no serious/critical violations', async ({ page }) => {
+    await authenticate(page, { invoice: SMOKE_INVOICE });
+    await page.goto(`/invoices/${SMOKE_INVOICE.id}`);
+    await assertNoAccessibilityViolations(page);
+  });
+
+  test('portfolio page has no serious/critical violations', async ({ page }) => {
+    await authenticate(page, { invoices: SMOKE_INVOICES });
+    await page.goto('/portfolio');
+    await assertNoAccessibilityViolations(page);
+  });
+
+  test('settings page has no serious/critical violations', async ({ page }) => {
+    await authenticate(page, { invoices: SMOKE_INVOICES });
+    await page.goto('/settings');
+    await assertNoAccessibilityViolations(page);
+  });
+
+  test('transactions page has no serious/critical violations', async ({ page }) => {
+    await authenticate(page, { invoices: SMOKE_INVOICES });
+    await page.goto('/transactions');
+    await assertNoAccessibilityViolations(page);
+  });
+
+  test('profile page has no serious/critical violations', async ({ page }) => {
+    await authenticate(page, { invoices: SMOKE_INVOICES });
+    await page.goto('/profile');
+    await assertNoAccessibilityViolations(page);
+  });
+});
\ No newline at end of file
diff --git a/invofi/apps/frontend/package-lock.json b/invofi/apps/frontend/package-lock.json
index 5aa9b0cde..0187d34c5 100644
--- a/invofi/apps/frontend/package-lock.json
+++ b/invofi/apps/frontend/package-lock.json
@@ -54,7 +54,8 @@
         "tailwindcss": "^3.4.10",
         "tailwindcss-animate": "^1.0.7",
         "typescript": "^5.5.4",
-        "vitest": "^2.1.9"
+        "vitest": "^2.1.9",
+        "@axe-core/playwright": "^4.13.0"
       }
     },
     "node_modules/@adobe/css-tools": {
@@ -20304,6 +20305,19 @@
           "optional": true
         }
       }
+    },
+    "node_modules/@axe-core/playwright": {
+      "version": "4.13.0",
+      "resolved": "https://registry.npmjs.org/@axe-core/playwright/-/playwright-4.13.0.tgz",
+      "integrity": "sha512-6YLx+kxXu5GJceG4ozFg+33a2EMTdjYwWGloJ3sb9Kta5pp+ZNS53uxGVog5JetIY8s++P5UrtX+cri+u0VAVg==",
+      "dev": true,
+      "license": "MPL-2.0",
+      "dependencies": {
+        "axe-core": "~4.13.0"
+      },
+      "peerDependencies": {
+        "playwright-core": ">= 1.0.0"
+      }
     }
   }
 }
diff --git a/invofi/apps/frontend/package.json b/invofi/apps/frontend/package.json
index a8a72c1c7..0ceac447d 100644
--- a/invofi/apps/frontend/package.json
+++ b/invofi/apps/frontend/package.json
@@ -11,7 +11,8 @@
     "type-check": "tsc --noEmit",
     "test": "vitest run --coverage",
     "test:watch": "vitest",
-    "test:e2e": "playwright test"
+    "test:e2e": "playwright test",
+    "test:a11y": "playwright test e2e/a11y.spec.ts"
   },
   "dependencies": {
     "@sentry/nextjs": "^8.0.0",
@@ -61,6 +62,7 @@
     "@testing-library/react": "^16.3.2",
     "@vitest/coverage-v8": "^2.1.9",
     "jsdom": "^26.1.0",
-    "vitest": "^2.1.9"
+    "vitest": "^2.1.9",
+    "@axe-core/playwright": "^4.13.0"
   }
-}
\ No newline at end of file
+}