From 9754b95e66a7c29d667d9b8577f5475bb81d0f31 Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Tue, 10 Nov 2026 18:55:16 +0700 Subject: [PATCH] test(a11y): run axe-core over every screen, and fix the grid it failed No accessibility tooling stood behind any of this: roles were asserted one at a time, wherever a test happened to reach for getByRole. axe-core now runs over every screen inside the shell and over the components with structure of their own. It is called directly: eslint-plugin-jsx-a11y peers ESLint 9 at most and this repository is on 10, and the matcher packages are wrappers pinned to a runner's major. color-contrast stays off under jsdom and stays tokens.test.ts's job. Its first run failed on the package grid, which is fixed here: - the row checkbox was a direct child of role="row"; it is in a gridcell - the header had five column headers over six cells; the checkbox and action columns are named, visually hidden - the grid says rows are multi-selectable, which aria-selected needs And one axe cannot see: a pin chip's meaning lived in a title attribute on a span that cannot take focus. It is text now, visually hidden. Co-Authored-By: Claude Fable 5.2 --- package-lock.json | 11 + package.json | 3 +- ui/src/a11y.test.tsx | 240 ++++++++++++++++++++++ ui/src/components/PdBadge.tsx | 15 +- ui/src/components/PdPackageRow.tsx | 34 +-- ui/src/components/PdPackageTable.test.tsx | 48 +++++ ui/src/components/PdPackageTable.tsx | 15 +- ui/src/locales/en/common.json | 19 +- ui/src/locales/vi/common.json | 15 +- ui/src/test/axe.ts | 44 ++++ ui/src/test/setup.ts | 9 + 11 files changed, 420 insertions(+), 33 deletions(-) create mode 100644 ui/src/a11y.test.tsx create mode 100644 ui/src/test/axe.ts diff --git a/package-lock.json b/package-lock.json index 2c72a60..359d66c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -31,6 +31,7 @@ "@types/react-dom": "^19.3.0", "@vitejs/plugin-react": "^6.2.1", "@vitest/coverage-v8": "^5.1.0", + "axe-core": "^4.14.0", "eslint": "^10.14.0", "eslint-plugin-react-hooks": "^7.1.1", "eslint-plugin-react-refresh": "^0.5.7", @@ -2389,6 +2390,16 @@ "dev": true, "license": "MIT" }, + "node_modules/axe-core": { + "version": "4.14.0", + "resolved": "https://registry.npmjs.org/axe-core/-/axe-core-4.14.0.tgz", + "integrity": "sha512-9WTZxEjsZ7b13TH8JPmbV2z8CHbl80/2hm3XPEG4JgNdQLK81IBRXmSxHfMAOkSqQeRxT/0dwNDz2GOm3zzpcQ==", + "dev": true, + "license": "MPL-2.0", + "engines": { + "node": ">=4" + } + }, "node_modules/balanced-match": { "version": "4.0.4", "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz", diff --git a/package.json b/package.json index 3544a14..4676efc 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "pipdock", "version": "1.4.0", "private": true, - "description": "A friendly dock for your Python environments \u2014 bulk inspect, install, update and clean up Python packages.", + "description": "A friendly dock for your Python environments — bulk inspect, install, update and clean up Python packages.", "license": "GPL-3.0-only", "type": "module", "repository": { @@ -49,6 +49,7 @@ "@types/react-dom": "^19.3.0", "@vitejs/plugin-react": "^6.2.1", "@vitest/coverage-v8": "^5.1.0", + "axe-core": "^4.14.0", "eslint": "^10.14.0", "eslint-plugin-react-hooks": "^7.1.1", "eslint-plugin-react-refresh": "^0.5.7", diff --git a/ui/src/a11y.test.tsx b/ui/src/a11y.test.tsx new file mode 100644 index 0000000..0da4f91 --- /dev/null +++ b/ui/src/a11y.test.tsx @@ -0,0 +1,240 @@ +/** + * Every screen and the components with structure of their own, through axe — TESTING §2. + * + * The suite before this asserted roles one at a time, wherever a test happened to reach for + * `getByRole`. That holds what someone thought to check. This holds the rest: a `role="row"` whose + * child is not a cell, a tab without a panel, an `aria-selected` on something that cannot be + * selected. Each of those shipped, and each passed every test there was. + * + * Rendered through `` where a screen is reachable that way, because the landmarks, the + * heading order and the one-`

` rule are properties of the shell and its screen together — the + * seam a component test cannot see. `ui/src/test/axe.ts` says what axe itself cannot see. + */ + +import { fireEvent, render, screen, waitFor } from '@testing-library/react' +import { beforeEach, describe, expect, it, vi } from 'vitest' + +import { App } from '@/App' +import { NAV_KEYS } from '@/components/nav' +import { PdAuditReport } from '@/components/PdAuditReport' +import { PdConflictRow } from '@/components/PdConflictRow' +import { PdHealthReport } from '@/components/PdHealthReport' +import { PdLegalGate } from '@/components/PdLegalGate' +import { PdPackageTable } from '@/components/PdPackageTable' +import { PdSummarySheet } from '@/components/PdSummarySheet' +import { PdUninstallDialog } from '@/components/PdUninstallDialog' +import type { + AuditReport, + Dist, + EnvRow, + ExecutionOutcome, + ExecutionSummary, + FlowStep, + GuardReport, + HealthReport, + Pin, + SnapshotMeta, +} from '@/ipc' +import { PdPlanPanel } from '@/screens/PdPlanPanel' +import { joinRows } from '@/screens/rows' +import { useEnvStore, useLegalStore, usePlanStore, useUiStore } from '@/stores' +import { groupRuff, HEALTH_TABS } from '@/stores/health' +import { violations } from '@/test/axe' +import auditFixture from '@/test/fixtures/audit_report.json' +import summaryFixture from '@/test/fixtures/execution_summary.json' +import flowStep from '@/test/fixtures/flow_step.json' +import flowStepForced from '@/test/fixtures/flow_step_forced.json' +import guardFixture from '@/test/fixtures/guard_report.json' +import healthFixture from '@/test/fixtures/health_report.json' +import pinFixture from '@/test/fixtures/pin_list.json' +import listFixture from '@/test/fixtures/pkg_list.json' +import outdatedFixture from '@/test/fixtures/pkg_outdated.json' +import snapshotFixture from '@/test/fixtures/snapshot_list.json' +import { resetStore } from '@/test/stores' + +const { legalConsentGet } = vi.hoisted(() => ({ legalConsentGet: vi.fn() })) + +vi.mock('@/ipc', async () => { + const actual = await vi.importActual('@/ipc') + const { ipcMock } = await import('@/test/ipc') + // The real module for its types and helpers, the spies over every command a screen calls on + // mount, and the consent check the shell fails closed on (see App.test.tsx). + return { + ...actual, + ...ipcMock(), + legalConsentGet, + // Environments subscribes on mount; the real one reaches for a Tauri host jsdom does not have. + onScanProgress: vi.fn().mockResolvedValue(() => undefined), + } +}) +vi.mock('@tauri-apps/plugin-opener', () => ({ openUrl: vi.fn().mockResolvedValue(undefined) })) +vi.mock('@tauri-apps/plugin-clipboard-manager', () => ({ + writeText: vi.fn().mockResolvedValue(undefined), +})) + +const DISTS = listFixture as Dist[] +const INTERPRETER = String.raw`C:\proj\.venv\Scripts\python.exe` +const ROW: EnvRow = { + interpreter: INTERPRETER, + source: 'venv-scan', + envHash: 'abc123', + env: { + interpreter: INTERPRETER, + prefix: String.raw`C:\proj\.venv`, + pythonVersion: '3.12.10', + externallyManaged: false, + hiddenUserSite: null, + source: 'venv-scan', + }, +} +const JOINED = joinRows(DISTS, outdatedFixture, pinFixture as Pin[]) +const HEALTH = healthFixture as HealthReport +const SUMMARY = summaryFixture as ExecutionSummary +const OUTCOME: ExecutionOutcome = { + summary: SUMMARY, + snapshot: (snapshotFixture as SnapshotMeta[])[0]!, +} + +beforeEach(() => { + vi.clearAllMocks() + resetStore(usePlanStore) + legalConsentGet.mockResolvedValue({ current: true, docsHash: 'a1b2c3d4e5f60718' }) + useLegalStore.setState({ accepted: true, review: false }) + useEnvStore.setState({ + rows: [ROW], + selected: INTERPRETER, + dists: DISTS, + packages: JOINED.rows, + listing: 'ready', + outdatedStatus: 'ready', + selection: new Set(), + }) +}) + +describe('every screen, inside the shell', () => { + it.each(NAV_KEYS)('%s', async (key) => { + useUiStore.setState({ nav: key }) + render() + await screen.findByRole('heading', { level: 1 }) + + expect(await violations(document.body, { page: true })).toEqual([]) + }) + + it('the command palette, open', async () => { + useUiStore.setState({ nav: 'installed' }) + render() + fireEvent.keyDown(window, { key: 'k', code: 'KeyK', ctrlKey: true }) + await screen.findByRole('combobox') + + expect(await violations(document.body, { page: true })).toEqual([]) + }) + + it('the legal gate, which replaces the shell', async () => { + render() + await waitFor(() => { + expect(screen.getByRole('dialog')).toBeInTheDocument() + }) + + expect(await violations()).toEqual([]) + }) +}) + +describe('components with structure of their own', () => { + it('the package grid, with pinned and outdated rows', async () => { + render( + , + ) + + expect(await violations()).toEqual([]) + }) + + it.each(HEALTH_TABS)('the health report on its %s tab', async (tab) => { + render( + , + ) + + expect(await violations()).toEqual([]) + }) + + it('the audit report', async () => { + render() + + expect(await violations()).toEqual([]) + }) + + it('a conflict row and its three choices', async () => { + const step = flowStep as FlowStep + if (!('report' in step)) throw new Error('the fixture must be a step carrying a report') + render( +
    + +
, + ) + + expect(await violations()).toEqual([]) + }) + + it('the uninstall guard', async () => { + render( + , + ) + + expect(await violations()).toEqual([]) + }) + + it('the plan panel, previewing a forced plan', async () => { + usePlanStore.setState({ + phase: 'preview', + kind: 'update', + step: flowStepForced as FlowStep, + env: ROW.env ?? null, + }) + render() + + expect(await violations()).toEqual([]) + }) + + it('the plan panel, on its summary', async () => { + usePlanStore.setState({ phase: 'summary', outcome: OUTCOME, kind: 'update' }) + render() + + expect(await violations()).toEqual([]) + }) + + it('the summary sheet alone', async () => { + render() + + expect(await violations()).toEqual([]) + }) +}) diff --git a/ui/src/components/PdBadge.tsx b/ui/src/components/PdBadge.tsx index 61a2c7f..169ff01 100644 --- a/ui/src/components/PdBadge.tsx +++ b/ui/src/components/PdBadge.tsx @@ -22,18 +22,29 @@ interface PdBadgeProps { * as a colour emoji from Segoe UI Emoji, which sits badly next to monospace data. */ glyph?: string - /** Overrides the accessible name when the visible label is a bare glyph or a version. */ + /** + * What the chip means, when the visible label is a bare glyph or a version. + * + * **Rendered as text, not only as a tooltip.** This was a `title` attribute and nothing else, + * and the comment here called it "the accessible name" — which a `title` on a `` that + * cannot take focus is not: a pointer could hover it, and a keyboard or a screen reader could + * not reach it at all. So a held pin read as a bare version number. The sentence is in the + * document now, visually hidden, and the visible label is hidden from assistive technology in + * its favour — the sentence already contains the version, and both would say it twice. + */ title?: string } export function PdBadge({ tone, label, glyph, title }: PdBadgeProps) { + const explained = title !== undefined && title !== label return ( {glyph === undefined ? null : } - {label} + {label} + {explained ? {title} : null} ) } diff --git a/ui/src/components/PdPackageRow.tsx b/ui/src/components/PdPackageRow.tsx index a1630f8..21d7484 100644 --- a/ui/src/components/PdPackageRow.tsx +++ b/ui/src/components/PdPackageRow.tsx @@ -113,20 +113,25 @@ function Row({ state === 'current' ? 'text-text-dim' : 'text-text' } ${selected ? 'bg-surface-2' : 'bg-surface'}`} > - { - onToggle(row.name) - }} - aria-label={row.name} - // Not a tab stop: the row is (see onKeyDown above). Still clickable and still announced. - tabIndex={-1} - className={`${COLUMNS.checkbox} accent-accent disabled:opacity-40`} - /> + {/* In a cell of its own: a `role="row"` may own cells and nothing else, and the checkbox was + a direct child of the row. `flex`, so the cell is exactly the checkbox's box and the + column stays the width the header reserves for it. */} + + { + onToggle(row.name) + }} + aria-label={row.name} + // Not a tab stop: the row is (see onKeyDown above). Still clickable and still announced. + tabIndex={-1} + className="w-full accent-accent disabled:opacity-40" + /> + {row.name} @@ -193,6 +198,7 @@ function Row({ onUninstall(row.name) }} data-action="uninstall" + data-destructive aria-label={t('packages.actions.uninstall')} title={t('packages.actions.uninstall')} className="shrink-0 rounded-pd border border-border px-2 py-0.5 text-data text-text-dim" diff --git a/ui/src/components/PdPackageTable.test.tsx b/ui/src/components/PdPackageTable.test.tsx index f6fc9b7..16173ce 100644 --- a/ui/src/components/PdPackageTable.test.tsx +++ b/ui/src/components/PdPackageTable.test.tsx @@ -180,3 +180,51 @@ describe('keyboard', () => { expect(onSelectAll).toHaveBeenCalledOnce() }) }) + +describe('grid structure', () => { + it('puts every control in a cell, and gives every cell a header', () => { + // A `role="row"` may own cells and nothing else. The checkbox was a direct child of the row, + // and the header had five column headers over six cells — so a screen reader moving by + // column read "Status" above the action buttons. + setup() + const [header, ...rows] = screen.getAllByRole('row') + if (header === undefined) throw new Error('no header row') + const headers = within(header).getAllByRole('columnheader') + + for (const row of rows) { + expect([...row.children].map((c) => c.getAttribute('role'))).toEqual( + headers.map(() => 'gridcell'), + ) + } + expect([...header.children].every((c) => c.getAttribute('role') === 'columnheader')).toBe(true) + // The two that have no visible heading are named for whoever cannot see the column. + expect(headers.map((h) => h.textContent)).toEqual([ + 'Select', + 'Package', + 'Version', + 'Latest', + 'Size', + 'Status', + 'Actions', + ]) + }) + + it('says more than one row can be selected', () => { + // `aria-selected` on a row means nothing to a reader unless the grid says selection exists. + setup() + expect(screen.getByRole('grid')).toHaveAttribute('aria-multiselectable', 'true') + }) + + it('says what a pin chip means in text, not only in a tooltip', () => { + // The meaning lived in `title` on a span that cannot take focus, so it was reachable with a + // mouse and with nothing else. + setup() + const pinned = screen + .getAllByRole('row') + .find((row) => row.getAttribute('data-pinned') === 'true') + if (pinned === undefined) throw new Error('the fixture has no pinned row') + expect(within(pinned).getByText(/kept at this version|left out of every update/)).toHaveClass( + 'sr-only', + ) + }) +}) diff --git a/ui/src/components/PdPackageTable.tsx b/ui/src/components/PdPackageTable.tsx index 74c16e0..9641061 100644 --- a/ui/src/components/PdPackageTable.tsx +++ b/ui/src/components/PdPackageTable.tsx @@ -78,6 +78,9 @@ export function PdPackageTable({ role="grid" aria-label={t('packages.tableLabel')} aria-rowcount={rows.length + 1} + // `aria-selected` on a row means nothing unless the grid says rows can be selected, and that + // more than one can. + aria-multiselectable="true" // Focusable but not a tab stop: the rows are (Sonar S6852, the ARIA grid pattern). tabIndex={-1} // `@container`: the columns size against the table's width, not the window's (U22). @@ -102,8 +105,12 @@ export function PdPackageTable({ aria-rowindex={1} className={`${COLUMNS.row} shrink-0 overflow-hidden border-b border-border py-1 text-data text-text-dim [scrollbar-gutter:stable]`} > - {/* Aligns with the row checkbox, which has no header of its own. */} -