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 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Fable 5.2 committed 2026-11-10 20:01:03 +07:00
1 parent 2329d55298
commit 9754b95e66
11 files changed
+420 -33

No files matched your search

+11
View File
@@ -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",
+2 -1
View File
@@ -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",
+240
View File
@@ -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 `<App />` where a screen is reachable that way, because the landmarks, the
* heading order and the one-`<h1>` 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<typeof import('@/ipc')>('@/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<string>(),
})
})
describe('every screen, inside the shell', () => {
it.each(NAV_KEYS)('%s', async (key) => {
useUiStore.setState({ nav: key })
render(<App />)
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(<App />)
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(<PdLegalGate />)
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(
<PdPackageTable
rows={JOINED.rows}
outdatedStatus="ready"
selection={new Set(['pandas'])}
onToggle={vi.fn()}
onPinToggle={vi.fn()}
onUninstall={vi.fn()}
onDetails={vi.fn()}
onSelectAll={vi.fn()}
initialRect={{ width: 1280, height: 600 }}
/>,
)
expect(await violations()).toEqual([])
})
it.each(HEALTH_TABS)('the health report on its %s tab', async (tab) => {
render(
<PdHealthReport
report={HEALTH}
ruffByFile={groupRuff(HEALTH.ruff.findings)}
tab={tab}
onTab={vi.fn()}
installed={['numpy', 'pandas']}
onUninstall={vi.fn()}
/>,
)
expect(await violations()).toEqual([])
})
it('the audit report', async () => {
render(<PdAuditReport report={auditFixture as AuditReport} />)
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(
<ul>
<PdConflictRow
pkg="numpy"
resolved="1.26.4"
latest="2.5.1"
blockers={step.report.heldBack?.[0]?.blockers ?? []}
impossible={false}
value={undefined}
onChoose={vi.fn()}
/>
</ul>,
)
expect(await violations()).toEqual([])
})
it('the uninstall guard', async () => {
render(
<PdUninstallDialog
report={guardFixture as GuardReport}
busy={false}
onCancel={vi.fn()}
onWiden={vi.fn()}
onConfirm={vi.fn()}
/>,
)
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(<PdPlanPanel onFinished={vi.fn()} />)
expect(await violations()).toEqual([])
})
it('the plan panel, on its summary', async () => {
usePlanStore.setState({ phase: 'summary', outcome: OUTCOME, kind: 'update' })
render(<PdPlanPanel onFinished={vi.fn()} />)
expect(await violations()).toEqual([])
})
it('the summary sheet alone', async () => {
render(<PdSummarySheet outcome={OUTCOME} onDone={vi.fn()} />)
expect(await violations()).toEqual([])
})
})
+13 -2
View File
@@ -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 `<span>` 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 (
<span
className={`inline-flex shrink-0 items-center gap-1 rounded-pd px-1.5 py-0.5 text-data ${TONES[tone]}`}
title={title ?? label}
>
{glyph === undefined ? null : <span aria-hidden="true">{glyph}</span>}
<span>{label}</span>
<span aria-hidden={explained ? 'true' : undefined}>{label}</span>
{explained ? <span className="sr-only">{title}</span> : null}
</span>
)
}
+20 -14
View File
@@ -113,20 +113,25 @@ function Row({
state === 'current' ? 'text-text-dim' : 'text-text'
} ${selected ? 'bg-surface-2' : 'bg-surface'}`}
>
<input
type="checkbox"
checked={selected}
// A pinned row is visible but not selectable: DATA-FLOW §9.5 keeps it out of bulk
// updates, and showing it greyed says so more honestly than hiding it.
disabled={pinned}
onChange={() => {
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. */}
<span role="gridcell" className={`${COLUMNS.checkbox} flex items-center`}>
<input
type="checkbox"
checked={selected}
// A pinned row is visible but not selectable: DATA-FLOW §9.5 keeps it out of bulk
// updates, and showing it greyed says so more honestly than hiding it.
disabled={pinned}
onChange={() => {
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"
/>
</span>
<code role="gridcell" className={`${COLUMNS.name} font-mono text-data`}>
{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"
+48
View File
@@ -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',
)
})
})
+12 -3
View File
@@ -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. */}
<span aria-hidden="true" className={COLUMNS.checkbox} />
{/* The checkbox and action columns have no visible heading, and are still columns: the
header had five headings over six cells, so moving by column read "Status" above the
action buttons. Named for whoever cannot see which column they are in. */}
<span role="columnheader" className={COLUMNS.checkbox}>
<span className="sr-only">{t('packages.column.select')}</span>
</span>
<span role="columnheader" className={COLUMNS.name}>
{t('packages.column.name')}
</span>
@@ -119,7 +126,9 @@ export function PdPackageTable({
<span role="columnheader" className={COLUMNS.status}>
{t('packages.column.status')}
</span>
<span aria-hidden="true" className={COLUMNS.actions} />
<span role="columnheader" className={COLUMNS.actions}>
<span className="sr-only">{t('packages.column.actions')}</span>
</span>
</div>
<div ref={scrollRef} className="min-h-0 flex-1 overflow-auto [scrollbar-gutter:stable]">
+11 -8
View File
@@ -77,7 +77,9 @@
"version": "Version",
"latest": "Latest",
"size": "Size",
"status": "Status"
"status": "Status",
"select": "Select",
"actions": "Actions"
},
"badge": {
"update": "UPDATE",
@@ -168,6 +170,7 @@
"confirm": "Confirm ({{count}} changes)",
"applyDecisions": "Apply choices",
"console": "Console",
"closeConsole": "Close console",
"progress": "{{done}} of {{total}} complete",
"executing": "Applying changes…",
"stop": "Stop",
@@ -307,13 +310,11 @@
"notRunYet": "not checked yet",
"notRunYetHint": "Press Run to check this folder.",
"notebooks": "Jupyter notebooks (.ipynb) are excluded from every report.",
"tabLabel": {
"deptry_one": "Dependencies, {{count}} finding",
"deptry_other": "Dependencies, {{count}} findings",
"vulture_one": "Dead code, {{count}} finding",
"vulture_other": "Dead code, {{count}} findings",
"ruff_one": "Lint, {{count}} finding",
"ruff_other": "Lint, {{count}} findings"
"tabs": "Code Health tools",
"tabTopic": {
"deptry": "Dependencies",
"vulture": "Dead code",
"ruff": "Lint"
},
"declared": {
"pyproject": "Dependencies declared in pyproject.toml",
@@ -388,6 +389,8 @@
"placeholder": "Search PyPI…",
"warming": "Preparing the package index…",
"searching": "Searching…",
"resultCount_one": "{{count}} result",
"resultCount_other": "{{count}} results",
"indexMissing": "The package index has not been downloaded yet.",
"refreshIndex": "Download the index",
"refreshing": "Downloading…",
+10 -5
View File
@@ -76,7 +76,9 @@
"version": "Phiên bản",
"latest": "Mới nhất",
"size": "Dung lượng",
"status": "Trạng thái"
"status": "Trạng thái",
"select": "Chọn",
"actions": "Thao tác"
},
"badge": {
"update": "UPDATE",
@@ -156,6 +158,7 @@
"confirm": "Xác nhận ({{count}} thay đổi)",
"applyDecisions": "Áp dụng lựa chọn",
"console": "Bảng điều khiển",
"closeConsole": "Đóng bảng điều khiển",
"progress": "Hoàn tất {{done}}/{{total}}",
"executing": "Đang áp dụng thay đổi…",
"stop": "Dừng",
@@ -280,10 +283,11 @@
"notRunYet": "chưa kiểm tra",
"notRunYetHint": "Nhấn Chạy để kiểm tra thư mục này.",
"notebooks": "Jupyter notebook (.ipynb) được loại khỏi mọi báo cáo.",
"tabLabel": {
"deptry_other": "Phụ thuộc, {{count}} phát hiện",
"vulture_other": "Mã chết, {{count}} phát hiện",
"ruff_other": "Lint, {{count}} phát hiện"
"tabs": "Công cụ Code Health",
"tabTopic": {
"deptry": "Phụ thuộc",
"vulture": "Mã chết",
"ruff": "Lint"
},
"declared": {
"pyproject": "Phụ thuộc được khai báo trong pyproject.toml",
@@ -345,6 +349,7 @@
"placeholder": "Tìm trên PyPI…",
"warming": "Đang chuẩn bị danh mục gói…",
"searching": "Đang tìm…",
"resultCount_other": "{{count}} kết quả",
"indexMissing": "Danh mục gói chưa được tải về.",
"refreshIndex": "Tải danh mục",
"refreshing": "Đang tải…",
+44
View File
@@ -0,0 +1,44 @@
/**
* axe-core against a rendered tree — TESTING §2's accessibility tier.
*
* axe is called directly rather than through a matcher package. The matcher packages are thin
* wrappers pinned to a test runner's major version, and `eslint-plugin-jsx-a11y` — the other usual
* gate — peers ESLint 9 at most while this repository is on 10. axe-core itself has no
* dependencies and no opinion about the runner.
*
* **What this cannot see, so that nobody reads a pass as more than it is:**
*
* - `color-contrast` is off. jsdom computes no layout and no real colours, so the rule would
* report "incomplete" for every node. Contrast is `tokens.test.ts`'s job, which computes it from
* the tokens themselves.
* - Nothing here knows what a screen reader *says*, what forced-colors draws, or where focus goes
* after a keypress. Those are the hand tier and the focus tests.
*
* It returns strings rather than asserting, so the failure message is the list of what is wrong
* and where — `expect(await violations()).toEqual([])` prints every rule and selector.
*/
import axe from 'axe-core'
interface Options {
/**
* `region` asks that all content sit inside a landmark. True of the whole app, and meaningless
* for a component rendered alone into a bare `<div>`.
*/
page?: boolean
}
export async function violations(
root: Element = document.body,
{ page = false }: Options = {},
): Promise<string[]> {
const results = await axe.run(root, {
rules: {
'color-contrast': { enabled: false },
region: { enabled: page },
},
})
return results.violations.flatMap((violation) =>
violation.nodes.map((node) => `${violation.id}: ${violation.help} — ${node.target.join(' ')}`),
)
}
+9
View File
@@ -97,4 +97,13 @@ if (typeof HTMLDialogElement !== 'undefined') {
}
}
/**
* jsdom has no layout, so it has no `scrollIntoView` either — the method is simply absent, and a
* component that calls it throws. A no-op unless a test replaces it to watch what was scrolled.
*/
const element = Element.prototype as unknown as Record<string, unknown>
element['scrollIntoView'] ??= function scrollIntoView() {
/* nothing to scroll */
}
export { VIEWPORT }