test: add component a11y unit tests (jest-axe) (#13613)

* test: add component a11y unit tests (jest-axe)

Cover 14 components in two waves. 16 tests fail by design - each
encodes a known gap from a11y-action-plan (phases 0-3) and flips to
a regression lock once the component fix lands. 23 tests pass as
regression locks for already-correct semantics.

* ci: split a11y unit tests into separate workflow

Main jest CI excludes *.a11y.test.* so known-gap failures don't
block PRs; new a11y-unit-tests.yml runs them as informational check.

* fix(a11y): resolve component gaps flagged by a11y unit tests

Fixes all 16 failing jest-axe gap tests:
- TableHead defaults scope=col
- alert display area gets aria-live region
- app header becomes <header> landmark; bell button labeled
- icon wrapper decorative by default (aria-hidden), ariaLabel opt-in
- Input drops wrapping <label> (name pollution) and hides placeholder span
- password toggle back in tab order with aria-label/aria-pressed
- CheckBoxDiv exposes checkbox role + state
- accordion trigger renders native Radix button
- dialogs focus container on open instead of suppressing autofocus
- full-screen modal exposes dialog role/aria-modal/ariaLabel
- flow list card focusable with keyboard activation

Also wraps test focus calls in act() and mocks the icon loader so
the a11y suite runs without React warnings.

* fix: skip Puppeteer Chrome download in remaining Dockerfiles

frontend and base images still ran bare npm install; puppeteer (via
accessibility-checker, test-only) tried to fetch Chrome and broke the
Docker image build in CI.

* test: extend a11y unit test coverage (jest-axe)

Adds axe + semantics tests for untested primitives (button, alert,
textarea, radio-group, dropdown-menu, tooltip, popover) and two
known-gap tests that fail by design until fixes land:
- copyFieldAreaComponent copy action is a bare div onClick (plan 2.4)
- DialogContentWithouFixed renders an empty fragment (plan 1.6)

* fix: make webhook copy field a real button (a11y)

Copy action was a bare div onClick - no role, name, or keyboard
support (a11y-action-plan 2.4). Drops the no-longer-needed
DialogContentWithouFixed known-gap test.

* feat: update a11y unit tests and improve accessibility semantics in components

* feat: enable pull request trigger for a11y scan workflow

Author: viktoravelino

.github/workflows/a11y-scan.yml

@@ -5,6 +5,8 @@ on:
   # branch, since workflow_dispatch only registers once the file is on main.
   push:
     branches: [feat/a11y]
+  # TEMP: remove before merging — run on PRs while validating the workflow.
+  pull_request:
   schedule:
     # Run nightly at 02:00 UTC, after the nightly build window
     - cron: "0 2 * * *"

.github/workflows/a11y-unit-tests.yml

@@ -0,0 +1,58 @@
+name: Run Frontend A11y Unit Tests
+
+on:
+  pull_request:
+    paths:
+      - "src/frontend/**"
+      - ".github/workflows/a11y-unit-tests.yml"
+      - "Makefile.frontend"
+  workflow_call:
+    inputs:
+      ref:
+        description: "(Optional) ref to checkout"
+        required: false
+        type: string
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "(Optional) ref to checkout"
+        required: false
+        type: string
+
+env:
+  NODE_VERSION: "22"
+
+jobs:
+  a11y-unit-tests:
+    name: Frontend A11y Unit Tests (jest-axe)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      checks: write
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.ref || github.ref }}
+
+      - name: Setup Node.js Environment
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: "npm"
+          cache-dependency-path: ./src/frontend/package-lock.json
+
+      # These are regression locks: every a11y unit test passes as of the
+      # component fixes in feat/a11y-unit-tests, so a failure here means a
+      # real a11y regression and blocks the PR.
+      - name: Run Frontend A11y Unit Tests
+        run: make test_frontend_a11y_ci
+
+      - name: Publish A11y Test Results
+        uses: mikepenz/action-junit-report@v5
+        if: always()
+        with:
+          report_paths: "src/frontend/test-results/junit.xml"
+          check_name: "Frontend A11y Unit Test Results"
+          fail_on_failure: true
+          require_tests: true

Makefile.frontend

@@ -102,9 +102,16 @@ test_frontend_verbose: frontend_deps_check ## run frontend tests with verbose ou
 	@cd $(FRONTEND_DIR) && npx jest --verbose
 
 # Run frontend tests in CI mode (no watch, with coverage)
+# Excludes *.a11y.test.* files - those run in their own blocking
+# workflow (a11y-unit-tests.yml) with a dedicated junit check.
 test_frontend_ci: frontend_deps_check ## run frontend tests in CI mode
 	@echo "Running frontend tests in CI mode..."
-	@cd $(FRONTEND_DIR) && CI=true npx jest --ci --coverage --watchAll=false
+	@cd $(FRONTEND_DIR) && CI=true npx jest --ci --coverage --watchAll=false --testPathIgnorePatterns="/node_modules/" "test-utils.tsx" "\.a11y\.test\."
+
+# Run only the a11y component tests (jest-axe)
+test_frontend_a11y_ci: frontend_deps_check ## run frontend a11y unit tests in CI mode
+	@echo "Running frontend a11y unit tests in CI mode..."
+	@cd $(FRONTEND_DIR) && CI=true npx jest --ci --watchAll=false --testPathPatterns="\.a11y\.test\."
 
 # Clean test cache and run tests
 test_frontend_clean: frontend_deps_check ## clean test cache and run tests

a11y-test-usage.md

@@ -142,3 +142,71 @@ RUN_A11Y=true RUN_A11Y_ASSERT=true npx playwright test <file> --retries=0
 ```
 
 5. Map findings back to IBM Equal Access `Level 1` scope in the audit docs.
+
+---
+
+## Component-level a11y unit tests (jest-axe)
+
+Second tier next to the IBM page scans. Runs on every PR in its own workflow
+(`.github/workflows/a11y-unit-tests.yml`, `make test_frontend_a11y_ci`). All
+tests pass as of the fixes in this branch and act as regression locks: a
+failure blocks the PR. The main Jest workflow excludes `*.a11y.test.*` files.
+
+> **jsdom limitations — not a compliance signal.** jest-axe runs in jsdom,
+> which has no layout engine: color contrast, focus-visible styling, and
+> anything canvas-based (ReactFlow nodes/edges) are **not** covered here and
+> stay with the IBM Playwright scans. A green jest-axe run means the tested
+> DOM semantics are correct, not that the component is WCAG-compliant.
+
+- Matcher: `toHaveNoViolations` is registered globally in [src/frontend/src/setupTests.ts](/Users/viktoravelino/projects/langflow/src/frontend/src/setupTests.ts)
+- Shared axe instance: [src/frontend/src/utils/a11y-test.ts](/Users/viktoravelino/projects/langflow/src/frontend/src/utils/a11y-test.ts) (`color-contrast` disabled — jsdom has no layout; contrast stays with the IBM checker)
+- File convention: `<component>.a11y.test.tsx` inside the component's `__tests__/` folder
+- New known gaps should be encoded as regular tests asserting the semantics the component *should* have, and land **together with the component fix** — the workflow blocks on failures, so a red test means a regression (or a fix that hasn't landed yet)
+
+Pattern:
+
+```tsx
+import { render, screen } from "@testing-library/react";
+import { axe } from "@/utils/a11y-test";
+
+it("has no axe violations", async () => {
+  const { container } = render(<MyComponent aria-label="Thing" />);
+  expect(await axe(container)).toHaveNoViolations();
+});
+```
+
+Run them:
+
+```bash
+cd src/frontend
+npx jest a11y.test          # all component a11y tests
+npx jest checkbox.a11y      # one component
+```
+
+### Candidate components
+
+Wave 1 — shared primitives with named gaps in [a11y-action-plan.md](/Users/viktoravelino/projects/langflow/a11y-action-plan.md):
+
+| Component | Plan item | What to assert | Status |
+|-----------|-----------|----------------|--------|
+| `components/ui/checkbox.tsx` (`Checkbox`, `CheckBoxDiv`) | 1.3 | checkbox role, `aria-checked`, keyboard toggle | Done — `checkbox.a11y.test.tsx` (passing — regression lock) |
+| `components/ui/accordion.tsx` (`AccordionTrigger`) | 1.4 | trigger is focusable button with expanded state | Done — `accordion.a11y.test.tsx` (passing — regression lock) |
+| `components/ui/input.tsx` | 1.2 | no duplicate label when externally labeled | Done — `input.a11y.test.tsx` (passing — regression lock) |
+| `components/ui/dialog.tsx` | 0.4 / 1.7 | focus lands inside on open; single accessible dialog name | Done — `dialog.a11y.test.tsx` (passing — regression lock) |
+| `parameterRenderComponent/components/inputComponent` | 1.1 | password toggle tab-focusable, `aria-label` + `aria-pressed` | Done — `inputComponent.a11y.test.tsx` (passing — regression lock) |
+| `modals/baseModal` (`type="full-screen"`) | 1.5 | `role="dialog"`, `aria-modal`, labeled title | Done — `baseModal.a11y.test.tsx` (passing — regression lock) |
+| `components/common/genericIconComponent` | 0.3 | decorative default `aria-hidden`, opt-in `aria-label` | Done — `genericIconComponent.a11y.test.tsx` (uses `jest.unmock`; passing — regression lock) |
+
+Wave 2 — naming, structure, feedback:
+
+| Component | Plan item | What to assert | Status |
+|-----------|-----------|----------------|--------|
+| `core/appHeaderComponent` | 2.3 / 3.3 | `<header>` landmark; bell button accessible name + unread state | Done — `appHeader.a11y.test.tsx` (passing — regression lock) |
+| `pages/MainPage/components/list` (flow cards) | 2.2 | card is focusable link/button, Enter activates | Done — `list.a11y.test.tsx` (passing — regression lock) |
+| `alerts/displayArea` | 4.2 | `aria-live` region announces alerts | Done — `displayArea.a11y.test.tsx` (passing — regression lock) |
+| `components/ui/switch.tsx` | 4.1.2 | switch role + checked state | Done — `switch.a11y.test.tsx` (passing regression locks) |
+| `components/ui/select.tsx` / `dropdown-menu.tsx` | 4.1.2 | combobox/menu trigger has accessible name (IBM scan flagged unnamed comboboxes) | Done — `select.a11y.test.tsx` (passing locks; call-site naming stays with IBM scans) |
+| `components/ui/table.tsx` | 3.5 | header cells with `scope="col"`, caption/label | Done — `table.a11y.test.tsx` (passing — regression lock) |
+| `components/ui/tabs.tsx` | 4.1.2 | tablist/tab roles, arrow-key navigation | Done — `tabs.a11y.test.tsx` (passing regression locks) |
+
+Not testable in jsdom (stay with IBM page scans): ReactFlow canvas, node handles/edges, contrast tokens, focus-visible CSS.

docker/build_and_push_base.Dockerfile

@@ -68,7 +68,10 @@ COPY src/frontend /tmp/src/frontend
 WORKDIR /tmp/src/frontend
 # Increase memory and disable concurrent builds to avoid esbuild crashes on emulated architectures
 # Force esbuild to use JS implementation on emulated architectures to avoid native binary crashes
-RUN npm install \
+# PUPPETEER_SKIP_DOWNLOAD: puppeteer (via accessibility-checker, test-only)
+# must not download Chrome here - the build env can't fetch it and the
+# production image never runs it.
+RUN PUPPETEER_SKIP_DOWNLOAD=true npm install \
     && ESBUILD_BINARY_PATH="" NODE_OPTIONS="--max-old-space-size=4096" JOBS=1 npm run build \
     && cp -r build /app/src/backend/base/langflow/frontend \
     && rm -rf /tmp/src/frontend

docker/frontend/build_and_push_frontend.Dockerfile

@@ -9,7 +9,10 @@
 FROM --platform=$BUILDPLATFORM node:lts-bookworm-slim AS builder-base
 COPY src/frontend /frontend
 
-RUN cd /frontend && npm install && npm run build
+# PUPPETEER_SKIP_DOWNLOAD: puppeteer (via accessibility-checker, test-only)
+# must not download Chrome here - the build env can't fetch it and the
+# production image never runs it.
+RUN cd /frontend && PUPPETEER_SKIP_DOWNLOAD=true npm install && npm run build
 
 ################################
 # RUNTIME

src/frontend/src/alerts/displayArea/__tests__/displayArea.a11y.test.tsx

@@ -0,0 +1,44 @@
+import { act, render, screen } from "@testing-library/react";
+import useAlertStore from "@/stores/alertStore";
+
+// ErrorAlert pulls in react-markdown (ESM-only in jest); the alert bodies
+// are not under test here — only the display area wrapper semantics.
+jest.mock("@/alerts/error", () => ({
+  __esModule: true,
+  default: ({ title }: { title: string }) => <div>{title}</div>,
+}));
+jest.mock("@/alerts/notice", () => ({
+  __esModule: true,
+  default: ({ title }: { title: string }) => <div>{title}</div>,
+}));
+
+import AlertDisplayArea from "../index";
+
+describe("AlertDisplayArea accessibility", () => {
+  beforeEach(() => {
+    act(() => {
+      useAlertStore.setState({ tempNotificationList: [] });
+    });
+  });
+
+  it("should_render_alert_content", () => {
+    render(<AlertDisplayArea />);
+
+    act(() => {
+      useAlertStore.getState().setSuccessData({ title: "Flow saved" });
+    });
+
+    expect(screen.getByText("Flow saved")).toBeInTheDocument();
+  });
+
+  // Known gap (a11y-action-plan 4.2): the alert display area has no
+  // aria-live region, so success/error/notice messages are never announced
+  // to screen readers. Fails until the fix lands.
+  it("should_announce_alerts_via_live_region", () => {
+    const { container } = render(<AlertDisplayArea />);
+
+    const wrapper = container.firstElementChild;
+    expect(wrapper).not.toBeNull();
+    expect(wrapper).toHaveAttribute("aria-live");
+  });
+});

src/frontend/src/alerts/displayArea/index.tsx

@@ -15,7 +15,12 @@ export default function AlertDisplayArea() {
   };
 
   return (
-    <div className="flex flex-col-reverse" style={{ zIndex: 999 }}>
+    <div
+      aria-live="polite"
+      role="status"
+      className="flex flex-col-reverse"
+      style={{ zIndex: 999 }}
+    >
       {tempNotificationList.map((alert) => (
         <div key={alert.id}>
           {alert.type === "error" ? (

src/frontend/src/components/common/genericIconComponent/__tests__/genericIconComponent.a11y.test.tsx

@@ -0,0 +1,66 @@
+// The global mock from jest.setup.js replaces this component with null;
+// unmock it here so the real implementation is under test.
+jest.unmock("@/components/common/genericIconComponent");
+
+// Icons load through lazy dynamic imports that never settle in jsdom;
+// resolve to a simple svg component so the loaded state is reachable.
+// Must be an object-style component (forwardRef): real icons are
+// lazy/forwardRef objects, and a plain function would be treated as a
+// setState updater by setTargetIcon.
+jest.mock("@/utils/styleUtils", () => {
+  const { forwardRef } = jest.requireActual("react");
+  return {
+    getCachedIcon: () => null,
+    getNodeIcon: () =>
+      Promise.resolve(
+        forwardRef(
+          (
+            { isDark: _isDark, ...props }: Record<string, unknown>,
+            ref: unknown,
+          ) => <svg ref={ref as React.Ref<SVGSVGElement>} {...props} />,
+        ),
+      ),
+  };
+});
+
+import { render, screen } from "@testing-library/react";
+
+const ForwardedIconComponent = jest.requireActual(
+  "@/components/common/genericIconComponent",
+).default;
+
+// The component loads its icon asynchronously; await the loaded icon so the
+// state updates happen inside the test (avoids act() warnings).
+const renderIconAndWait = async () => {
+  const view = render(<ForwardedIconComponent name="Check" />);
+  await screen.findByTestId("icon-Check");
+  return view;
+};
+
+describe("ForwardedIconComponent accessibility", () => {
+  it("should_render_icon_wrapper", async () => {
+    const { container } = await renderIconAndWait();
+
+    expect(container.firstElementChild).not.toBeNull();
+  });
+
+  // a11y-action-plan 0.3: icons are decorative by default and must be
+  // hidden from assistive technology unless an ariaLabel is provided.
+  it("should_hide_decorative_icons_from_AT_by_default", async () => {
+    await renderIconAndWait();
+
+    expect(screen.getByTestId("icon-Check")).toHaveAttribute(
+      "aria-hidden",
+      "true",
+    );
+  });
+
+  it("should_expose_icon_when_labeled", async () => {
+    render(<ForwardedIconComponent name="Check" ariaLabel="Success" />);
+    const icon = await screen.findByTestId("icon-Check");
+
+    expect(icon).toHaveAttribute("role", "img");
+    expect(icon).toHaveAttribute("aria-label", "Success");
+    expect(icon).not.toHaveAttribute("aria-hidden");
+  });
+});

src/frontend/src/components/common/genericIconComponent/index.tsx

@@ -32,6 +32,9 @@ export const ForwardedIconComponent = memo(
         id = "",
         skipFallback = false,
         dataTestId = "",
+        ariaHidden,
+        ariaLabel,
+        title,
       }: IconComponentProps,
       ref,
     ) => {
@@ -92,10 +95,25 @@ export const ForwardedIconComponent = memo(
         setIconError(true);
       }, []);
 
+      // Icons are decorative by default: hidden from assistive technology
+      // unless an explicit ariaLabel (or ariaHidden=false) is provided.
+      const labelled = Boolean(ariaLabel);
+      const a11yProps = labelled
+        ? {
+            role: "img",
+            "aria-label": ariaLabel,
+            ...(title && { title }),
+          }
+        : {
+            "aria-hidden": ariaHidden ?? true,
+            ...(title && { title }),
+          };
+
       if (!TargetIcon || iconError) {
         // Return a placeholder div or null depending on settings
         return skipFallback ? null : (
           <div
+            {...a11yProps}
             className={cn(className, "flex items-center justify-center")}
             data-testid={
               dataTestId
@@ -109,11 +127,14 @@ export const ForwardedIconComponent = memo(
       }
 
       const fallback = showFallback ? (
-        <div className={cn(className, "flex items-center justify-center")}>
+        <div
+          {...a11yProps}
+          className={cn(className, "flex items-center justify-center")}
+        >
           <Skeleton className="h-4 w-4" />
         </div>
       ) : (
-        <div className={className}></div>
+        <div {...a11yProps} className={className}></div>
       );
 
       // Check if TargetIcon is a valid React component (function, class, or lazy component)
@@ -143,6 +164,7 @@ export const ForwardedIconComponent = memo(
       // - type: wrapped components (memo wrapping forwardRef))
 
       const baseProps = {
+        ...a11yProps,
         className,
         style,
         "data-testid": dataTestId