無障礙測試:axe、Lighthouse 與螢幕閱讀器
INFO
自動化工具能大規模捕捉人工審查容易遺漏的結構性無障礙違規:缺少標籤、錯誤的 ARIA 屬性,以及對比度不足。但自動化工具對意義是盲目的。它無法判斷標籤是否表意清晰、錯誤訊息是否有幫助,或自訂下拉選單是否在按下 Escape 後正確關閉。完整的無障礙測試策略需要結合靜態分析、CI 自動化測試,以及使用真實輔助技術的人工驗證。
情境
自動化工具的覆蓋率上限
axe-core 是大多數無障礙測試工具背後的引擎,由 Deque Systems 維護。截至 4.12 版,它預設啟用約 90 條規則(約 60 條對應 WCAG A/AA 成功準則,另外約 27 條為最佳實務檢查),且每條規則檢查的都是可透過 DOM 檢測的違規。
自動化測試實際能捕捉到多少真實世界的問題,取決於覆蓋率的衡量方式。以 WCAG 成功準則計數的研究(衡量自動化能驗證約 50 條 WCAG A/AA 成功準則中的多少條)持續落在 20% 到 40% 之間。Deque 自己在 2021 年對超過 13,000 個頁面稽核的分析,採用了不同的衡量方式:以問題數量而非準則數量計算,也就是 axe 實際標記出的所有已記錄缺陷比例。該分析得出 57% 的結果,原因是少數高頻違規(缺少 alt 文字、對比度不足、缺少表單標籤)在實際稽核中佔絕大多數,而這正是 axe 最擅長捕捉的問題類型。這兩個數字並不衝突,它們回答的是不同的問題:一個關於可測試的規則,另一個關於典型頁面實際包含的缺陷。無論哪種衡量方式,多數 WCAG 成功準則仍然需要人工驗證。
這個落差並非 axe 特有的限制。它是問題本質的一部分:許多 WCAG 成功準則涉及對意義、情境與使用者體驗的判斷,這些是任何標記檢查都無法回答的。
- WCAG 2.4.6(標題與標籤):axe 可驗證每個輸入都有標籤,但無法判斷標籤是否具有足夠描述性,讓使用者理解應輸入什麼。
- WCAG 3.3.3(錯誤建議):axe 可偵測到錯誤訊息的存在,但無法判斷訊息是否說明了如何修正問題。
- WCAG 2.1.1(鍵盤):axe 可確認互動元素可獲得焦點,但無法模擬開啟自訂下拉選單後驗證其是否在按下 Escape 時關閉的使用者互動。
- WCAG 1.3.2(有意義的順序):axe 可偵測明顯的 DOM 順序違規,但無法評估閱讀順序在情境上是否有語意意義。
零違規的 axe 報告只能證明通過了可透過 DOM 檢查的基線。它不能證明頁面能與輔助技術搭配使用,那需要下方描述的人工測試層級。
左移式無障礙測試模型
開發後期才發現的無障礙問題成本高昂:上線前一週由螢幕閱讀器測試員發現缺少標籤,需要設計審查、開發工作和新的測試週期。而在撰寫程式碼當下就被 ESLint 規則標記的同樣問題,只需按一個快速鍵即可解決。
左移模型將無障礙檢查從最早(撰寫時)到最晚(人工測試)分層,每一層捕捉前一層無法發現的問題。以下範例以 React/JSX 為主;Vue、Angular 和 Svelte 專案可在靜態分析與單元測試層替換為對應框架的等效工具(見下方「生態系中的工具」),而 axe-core、Lighthouse 與人工測試層則不受影響,可直接套用。
- 靜態分析(React/JSX 使用 eslint-plugin-jsx-a11y):在撰寫時、元件渲染前捕捉結構性違規,零執行時成本,反饋迴路最快。
- 使用 axe-core 的單元測試(React Testing Library(RTL)/ Vitest 中的 axe):對已渲染的元件 DOM 執行完整的 axe 規則集,捕捉靜態分析看不到的動態狀態問題,例如已渲染的條件式和 JavaScript 設定的 ARIA 屬性。
- 使用 axe-core 的整合測試(Playwright 中的 axe):對含有路由、非同步資料和真實瀏覽器排版的完整頁面渲染執行 axe,捕捉只在完整組合下才會出現的問題。
- 人工鍵盤測試:演練自動化工具無法模擬的互動流程,包括 modal 中的焦點捕捉、下拉選單的 Escape 行為,以及跳過導航功能。
- 螢幕閱讀器測試:驗證實際播報的體驗。axe 可確認 ARIA 標籤存在,但只有螢幕閱讀器才能告訴你對真實使用者聽起來是什麼感覺。
生態系中的工具
axe-core 是由 Deque Systems 維護的開源無障礙測試引擎。它以 JavaScript 函式庫的形式實作 WCAG 2.0、2.1 和 2.2 規則。無障礙領域中的大多數瀏覽器擴充功能、測試整合和 CI 工具,要麼以 axe-core 為基礎,要麼以其作為參考。
@axe-core/playwright 是由 Deque 維護的官方 Playwright 整合套件。它將 axe-core 注入瀏覽器頁面,並回傳可在測試中斷言的結構化違規報告。另有一個名為 axe-playwright 的獨立社群套件,採用不同的 API;本文全篇使用的都是 Deque 官方套件。
@axe-core/react 透過檢測 React 的虛擬 DOM 輸出,在開發模式下將 axe-core 違規記錄到瀏覽器主控台。它不支援 React 18 以上版本,Deque 現在也建議現代 React 使用者改用其他方案;它的前身 react-axe 已標示為 npm 棄用套件。若要在目前的 React 版本上取得開發模式的主控台回報,請改用下方的 Storybook 無障礙外掛,或範例章節中展示的 Vitest/RTL 整合。
Storybook 的無障礙外掛(@storybook/addon-a11y)會針對每個獨立的 story 執行 axe-core,並在建置過程中於 Storybook UI 中顯示違規。它同樣適用於 React、Vue、Angular 和 Svelte 元件,是已經使用 Storybook 的團隊在開發過程中捕捉 axe 違規的常見方式。
Lighthouse 是 Google 的開源網路品質稽核工具。其無障礙稽核執行 axe 規則的子集,加上額外的檢查項目,例如 Tab 順序分析和地標區域的使用。Lighthouse 產生 0 到 100 的分數,可在 Chrome DevTools、CLI,以及透過 lighthouse-ci 在 CI 工具中使用。
eslint-plugin-jsx-a11y 是一個 ESLint 靜態分析外掛,會在 JSX(React)原始碼渲染前檢查其中的無障礙問題,使其成為整個流程中反饋最快的環節。其他框架也有以相同方式建置的對應工具:Vue 樣板適用 eslint-plugin-vuejs-accessibility,Angular 可使用 @angular-eslint/eslint-plugin-template 中的無障礙規則,Svelte 則由其編譯器本身在建置時發出 a11y 警告,不需要額外的外掛。
cypress-axe 和 pa11y-ci 補上本文以 Playwright 為主的範例留下的兩個缺口。cypress-axe 在 Cypress 中執行相同的 axe-core 引擎,適合已經採用 Cypress 的團隊。pa11y-ci 則是獨立於 axe-core 開發的工具,適合在沒有應用程式測試套件可掛斷言的情況下,掃描大量網址,例如行銷網站或文件入口網站。
瀏覽器 DevTools 無障礙面板
Chrome DevTools,Accessibility 面板:在 DevTools 中選取任意元素,開啟 Accessibility 面板(位於 Elements 底下)。它會顯示該元素的無障礙樹節點:計算出的無障礙名稱、角色、狀態(已獲焦點、必填等)和 ARIA 屬性。面板中還有一個「Show accessibility tree」切換開關,可將整個 Elements 面板從 DOM 樹切換為完整頁面的無障礙樹,方便在同一個畫面中驗證標題結構和地標區域。
Firefox 無障礙檢測器:Firefox 的無障礙檢測器(DevTools → Accessibility 標籤頁)顯示完整的無障礙樹以及 Tab 順序視覺化。「Check for issues」功能執行涵蓋對比度、鍵盤和文字標籤的內建稽核。Firefox 的實作在驗證焦點順序和偵測阻礙鍵盤導航的元素方面特別有用。
視覺
無障礙測試層次,從最早的反饋到最深入的覆蓋:
範例
1. @axe-core/playwright:在 Playwright 測試中執行 axe,違規時讓 CI 失敗
# 安裝
npm install --save-dev @axe-core/playwright// tests/a11y/home.spec.ts
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';
test.describe('首頁無障礙', () => {
test('應無法自動偵測到 WCAG 違規', async ({ page }) => {
await page.goto('/');
const accessibilityScanResults = await new AxeBuilder({ page })
.withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'])
.analyze();
// 此斷言在 axe 發現違規時使測試(以及 CI)失敗。
// 錯誤訊息包含違規規則、元素和修復提示。
expect(accessibilityScanResults.violations).toEqual([]);
});
test('登入表單應無違規', async ({ page }) => {
await page.goto('/login');
// 將 axe 範圍限定在特定區域,以減少其他已知問題的雜訊
const results = await new AxeBuilder({ page })
.include('#login-form')
.withTags(['wcag2aa', 'wcag21aa'])
.analyze();
expect(results.violations).toEqual([]);
});
test('為除錯列印可讀的違規報告', async ({ page }) => {
await page.goto('/dashboard');
const results = await new AxeBuilder({ page }).analyze();
if (results.violations.length > 0) {
// 為 CI 日誌記錄人工可讀的摘要
const summary = results.violations.map((v) => ({
id: v.id,
impact: v.impact,
description: v.description,
nodes: v.nodes.map((n) => n.target),
}));
console.log('Accessibility violations:', JSON.stringify(summary, null, 2));
}
expect(results.violations).toEqual([]);
});
});2. Vitest + React Testing Library(RTL)中的 axe-core:元件層級測試
# 安裝
npm install --save-dev axe-core jest-axe
# 或用於 Vitest:
npm install --save-dev axe-core vitest-axe// src/components/LoginForm.test.tsx
import { render } from '@testing-library/react';
import { axe, toHaveNoViolations } from 'vitest-axe';
import { expect, test } from 'vitest';
import { LoginForm } from './LoginForm';
// 用無障礙匹配器擴充 Vitest 的 expect
expect.extend(toHaveNoViolations);
test('LoginForm 在預設狀態下無 axe 違規', async () => {
const { container } = render(<LoginForm />);
// axe() 對已渲染的 DOM 執行完整的 axe-core 規則集
const results = await axe(container);
expect(results).toHaveNoViolations();
});
test('LoginForm 在顯示錯誤狀態時無 axe 違規', async () => {
const { container } = render(
<LoginForm initialError="電子郵件或密碼無效。" />
);
// 特別測試錯誤狀態 — 動態 ARIA(aria-invalid、aria-describedby)
// 只存在於已渲染的 DOM 中,而非 JSX 來源中
const results = await axe(container);
expect(results).toHaveNoViolations();
});
test('Modal 開啟時無違規', async () => {
const { container } = render(<ConfirmModal isOpen={true} />);
// axe 可檢查:role="dialog"、aria-modal、aria-labelledby 指向有效標題
const results = await axe(container);
expect(results).toHaveNoViolations();
});3. eslint-plugin-jsx-a11y 設定
# 安裝
npm install --save-dev eslint-plugin-jsx-a11y// eslint.config.js(flat config,ESLint 9+)
import jsxA11y from 'eslint-plugin-jsx-a11y';
export default [
// 以建議的規則集為基礎
jsxA11y.flatConfigs.recommended,
{
files: ['**/*.{jsx,tsx}'],
plugins: {
'jsx-a11y': jsxA11y,
},
rules: {
// 建議的規則(錯誤)— 這些對 WCAG 至關重要
'jsx-a11y/alt-text': 'error', // img 必須有 alt
'jsx-a11y/anchor-is-valid': 'error', // 錨點必須是有效連結
'jsx-a11y/aria-props': 'error', // 只允許有效的 ARIA 屬性
'jsx-a11y/aria-proptypes': 'error', // ARIA 的正確值類型
'jsx-a11y/aria-role': 'error', // 只允許有效的 ARIA 角色
'jsx-a11y/aria-unsupported-elements': 'error', // 不在不支援的元素上使用 ARIA
'jsx-a11y/heading-has-content': 'error', // 標題必須有文字內容
'jsx-a11y/img-redundant-alt': 'error', // alt 文字中不含「image」或「photo」
'jsx-a11y/interactive-supports-focus': 'error', // 互動角色必須可獲得焦點
'jsx-a11y/label-has-associated-control': 'error', // label 必須程式化連結
'jsx-a11y/no-access-key': 'warn', // accesskey 會造成螢幕閱讀器衝突
'jsx-a11y/no-autofocus': 'warn', // autofocus 會干擾螢幕閱讀器流程
'jsx-a11y/no-distracting-elements': 'error', // 不使用 marquee 或 blink
'jsx-a11y/role-has-required-aria-props': 'error', // 每個角色的必要 ARIA 屬性
'jsx-a11y/tabindex-no-positive': 'error', // 正數 tabindex 會破壞自然順序
},
},
];// 仍使用 .eslintrc 的專案(ESLint 8)
{
"plugins": ["jsx-a11y"],
"extends": ["plugin:jsx-a11y/recommended"],
"rules": {
"jsx-a11y/label-has-associated-control": ["error", {
"assert": "either"
}]
}
}4. 人工鍵盤測試檢查清單
在交付任何互動元件或流程之前,請僅用鍵盤(不用滑鼠)完成以下檢查清單:
鍵盤測試檢查清單
================
[ ] 所有互動元素按照合理的視覺順序獲得焦點(由上到下、由左到右)
[ ] 每個已獲焦點的元素都有可見的焦點指示器(沒有無替代樣式的 outline:none)
[ ] Tab 向前移過互動元素;Shift+Tab 向後移動
[ ] 連結開啟其目標或觸發預期的導航
[ ] 按鈕在 Enter 和 Space 上啟動
[ ] 原生表單控制元件使用預期的鍵盤操作:
[ ] Checkbox 使用 Space 切換
[ ] Radio button 在群組內使用方向鍵切換
[ ] Select 下拉選單使用 Space/Enter 開啟並使用方向鍵導航
[ ] 自訂下拉選單 / combobox:
[ ] 在觸發按鈕上按 Enter 或 Space 開啟
[ ] 方向鍵在已開啟的下拉選單中導航選項
[ ] Enter 或 Space 選取已獲焦點的選項
[ ] Escape 關閉下拉選單並將焦點返回到觸發器
[ ] Tab 關閉下拉選單並移動到下一個可獲焦點的元素
[ ] Modal 對話框:
[ ] 開啟時焦點移動到對話框內部
[ ] 焦點被捕捉在內部(Tab 只在 modal 內循環)
[ ] Escape 關閉 modal 並將焦點返回到觸發它的元素
[ ] Modal 可以用鍵盤可及的關閉按鈕關閉
[ ] 跳過導航連結在從頁面頂端第一次按 Tab 時出現
[ ] 沒有鍵盤陷阱:焦點可以用 Tab 或 Escape 離開每個元件
[ ] 手風琴 / 展示:Space 或 Enter 切換;方向鍵導航面板(如適用)
[ ] 日期選擇器:日/月/年選擇的鍵盤導航有效
[ ] Toast / 通知:可以用鍵盤關閉(或在不需要互動的情況下消失)5. Chrome DevTools Accessibility 面板:要檢查什麼
開啟 Chrome DevTools(F12),在 Elements 面板中點選任意元素,然後開啟 Accessibility 面板(底部窗格頂端的標籤頁,在 Styles 和 Computed 旁邊)。
主要檢查事項:
無障礙樹節點:顯示瀏覽器無障礙引擎計算出的角色、名稱和狀態。將此與您預期螢幕閱讀器播報的內容進行比較。如果按鈕的「Name」欄位為空,代表該按鈕沒有無障礙名稱。axe 也會捕捉到這一點,但面板能讓您看出原因。
全頁無障礙樹:點選 Accessibility 面板中的「Show accessibility tree」切換開關。在目前版本的 Chrome 中,這是內建功能,不再是實驗性旗標;Elements 面板會切換為顯示無障礙樹而非 DOM 樹。可用於:
- 驗證標題層次結構(h1 → h2 → h3,無跳躍層級)
- 檢查地標區域(header、main、nav、footer)是否存在且正確
- 識別出現在 DOM 中但被排除在無障礙樹之外的互動元素(
aria-hidden="true"或display:none)
ARIA 屬性:面板列出元素上的每一個 ARIA 屬性,以及它們是否有效。指向不存在 ID 的 aria-labelledby 在這裡會顯示為損壞。axe 也會將其標記為違規,但面板能讓您立即看出原因。
6. Lighthouse CI:強制執行無障礙分數門檻
# 安裝 lighthouse-ci
npm install --save-dev @lhci/cli// lighthouserc.json
{
"ci": {
"collect": {
"url": ["http://localhost:4173/", "http://localhost:4173/login"],
"startServerCommand": "pnpm preview",
"numberOfRuns": 3
},
"assert": {
"assertions": {
"categories:accessibility": ["error", { "minScore": 0.9 }],
"categories:performance": ["warn", { "minScore": 0.8 }]
}
},
"upload": {
"target": "temporary-public-storage"
}
}
}# .github/workflows/lighthouse.yml
name: Lighthouse CI
on:
pull_request:
branches: [main]
jobs:
lhci:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npm run build
- run: npx lhci autorun
env:
LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}注意:Lighthouse 無障礙評分按影響力加權。0.9 分代表加權平均,因此單一高影響力違規(例如頁面上許多輸入欄位缺少表單標籤)可能比多個低影響力違規加總起來更大幅拉低分數。請將 Lighthouse 分數作為趨勢指標,搭配 @axe-core/playwright 的零違規要求一起使用。
最佳實踐
應該(SHOULD)在 CI 的每個 Pull Request 中執行 axe-core,並將違規視為測試失敗而非警告。 透過 @axe-core/playwright 或 vitest-axe 將 axe-core 整合到測試套件中,代表沒有程式化標籤的表單輸入欄位會在合併前就讓 CI 失敗,缺少的 ARIA 屬性或對比度不足的問題也是如此。請將零違規的 axe 報告視為發布的前提條件,而非無障礙合規證書:即使以問題數量衡量,它仍會漏掉相當一部分真實世界的 WCAG 缺陷(見「情境」一節)。
應該(SHOULD)在發布任何互動元件前進行純鍵盤測試。 不動滑鼠,開啟、導覽、關閉並退出每個互動元件。用 Tab 遍歷表單、用 Enter 或 Space 啟動下拉選單、用 Escape 關閉 modal,並必須(MUST)確認焦點會返回到觸發元素。一個常見的例子是:下拉選單在按下 Escape 後從未將焦點返回觸發器,它能通過每一項自動化檢查,卻只在真人用鍵盤操作時才會失敗。
應該(SHOULD)在上線新使用者流程前,至少用一個真實螢幕閱讀器進行測試。 Windows 上的 NVDA + Chrome 是免費的,涵蓋最大的免費螢幕閱讀器使用者群;VoiceOver + Safari 內建於 macOS 和 iOS,對行動裝置測試而言是不可或缺的。螢幕閱讀器測試回答了一個自動化工具都無法回答的問題:當螢幕閱讀器唸出「名稱、角色、狀態」的播報序列時,聽起來是否自然?這包括即時區域(live region,也就是螢幕閱讀器會在焦點不移動的情況下播報的動態內容),以及瀏覽模式(螢幕閱讀器將頁面當作文件朗讀)與表單模式(按鍵直接傳遞給已獲焦點的控制項)之間的差異。
設計思維
axe-core 能看到什麼、不能看到什麼
axe-core 擅長它能看到的東西:DOM 結構、屬性是否存在、對比度的計算 CSS 值,以及 ARIA 屬性組合的邏輯一致性。在 CI 中執行 axe-core 能提供有保障的基線。缺少表單標籤、含有無效 ARIA 角色組合,或對比度低於 WCAG 門檻的元件,會在合併前就讓建置失敗。
但 axe-core 無法提出需要閱讀理解力的問題:
- 「Username」根據 axe 是有效的標籤。「輸入您的 6–20 個字元使用者名稱(僅限字母和數字)」是更好的標籤。axe 無法區分兩者。
- axe 確認錯誤訊息透過
aria-describedby與輸入欄位關聯。它無法判斷「無效輸入」是否幫助使用者理解哪裡出錯了。 - axe 驗證 modal 具有
role="dialog"和aria-modal="true"。它無法驗證在鍵盤互動過程中焦點是否真的被捕捉在其中。
零違規的 axe 執行結果保證了可透過 DOM 檢查的基線:有效的標籤、有效的 ARIA、足夠的對比度。但它完全沒有說明標籤是否易於理解,或 modal 是否真的捕捉住了焦點。這些都需要人工測試才能確認。
為什麼 eslint-plugin-jsx-a11y 是最快的反饋迴路
無障礙問題被發現的時間越晚,修復成本越高。ESLint 規則會在編輯器中、檔案儲存前觸發:早於元件在瀏覽器中渲染、早於測試執行,也早於程式碼審查。開發者能在撰寫程式碼的當下就看到問題,擁有完整的情境,並在幾秒鐘內修復它。
eslint-plugin-jsx-a11y 捕捉以下模式:img 元素缺少 alt 文字、沒有無障礙名稱的按鈕、沒有內容的錨點標籤、沒有關聯標籤的表單輸入。這些是高頻違規,佔現實世界 WCAG 失敗的很大一部分。靜態捕捉它們可以消除整個類別永遠不會到達瀏覽器的問題。
靜態分析的限制在於它只能評估 JSX 來源,而不是已渲染的 DOM。條件渲染的 ARIA 屬性、動態標籤文字和執行時 DOM 結構對 ESLint 不可見。這就是測試中 axe-core 接手的地方。
為什麼鍵盤測試捕捉到 axe 遺漏的問題
鍵盤測試是兩個覆蓋率缺口的交集:自動化工具無法執行的互動流程,以及需要真實互動才能驗證的 WCAG 要求。
考慮一個自訂下拉選單元件。axe-core 可以驗證:
- 觸發按鈕有無障礙名稱。
- listbox 具有
role="listbox"。 - 每個選項具有
role="option"。
axe-core 無法驗證:
- 按下 Escape 是否關閉下拉選單並將焦點返回到觸發器?
- 下拉選單開啟時按 Tab 是否關閉它並將焦點移到下一個元素?
- 按 Arrow Down 是否將焦點移到第一個選項?
- 按 Home/End 是否移到第一個/最後一個選項?
- 提前輸入(按「C」跳到以 C 開頭的選項)是否有效?
這些都是 WCAG 2.1.1 的要求。任何一項失敗的自訂下拉選單都是鍵盤無障礙違規,但 axe 看到的是一個結構有效的 combobox,並回報沒有違規。
鍵盤測試需要人工開啟下拉選單、用方向鍵導航、按 Escape,並驗證焦點返回到觸發器。每個互動元件只需兩分鐘,就能捕捉到每個自動化工具都無法看到的違規。
為什麼螢幕閱讀器測試是不可替代的
無障礙樹和播報的體驗並非總是相同的。螢幕閱讀器會在無障礙樹之上加入自己的詮釋:每一款都採用平台特有的啟發式方法與慣例,而 NVDA、JAWS 和 VoiceOver 對同樣的標記該唸成什麼樣子,看法並不總是一致。
螢幕閱讀器測試回答了沒有任何工具能回答的問題:
- 播報的名稱、角色與狀態順序,在自然語言中是否合理?
- 即時區域更新是否在正確的時刻中斷?
- 螢幕閱讀器的虛擬游標閱讀順序是否與視覺閱讀順序匹配?
- 元件在瀏覽模式與表單模式 / 應用程式模式下是否正常工作?
NVDA + Chrome 和 VoiceOver + Safari 代表兩種使用最多的螢幕閱讀器和瀏覽器組合(分別是 Windows 和 macOS)。用兩者測試涵蓋了大多數螢幕閱讀器使用者,並捕捉到瀏覽器特定的 ARIA 處理差異。
常見錯誤
1. 將零違規的 axe 報告視為無障礙合規證書
axe-core 報告零違規。團隊將無障礙標記為完成。使用螢幕閱讀器的使用者,仍然會遇到 axe 完全無法偵測到的未標記自訂控制元件、不合理的閱讀順序,以及焦點陷阱。
零 axe 違規只代表頁面通過了 axe-core 預設檢查的約 90 條規則。這不代表頁面具有無障礙性:即使以 Deque 自己按問題數量計算的衡量方式,axe 仍會漏掉相當一部分真實世界的缺陷(見「情境」一節)。請在團隊的完成定義中明確加入這項區別,並要求在無障礙工作正式完成前,通過一次人工鍵盤測試和螢幕閱讀器測試。
2. 只對順利路徑(happy path)的頁面狀態執行 axe
只在初始頁面加載時執行的 axe 測試,錯過了大多數無障礙違規所在的狀態:含有 aria-invalid 和 aria-describedby 的錯誤狀態、使用者互動後開啟的 modal 對話框、條件渲染的分頁面板、處於開啟狀態的下拉選單。
// 錯誤:只測試預設的關閉狀態
test('應無違規', async ({ page }) => {
await page.goto('/');
const results = await new AxeBuilder({ page }).analyze();
expect(results.violations).toEqual([]);
});
// 正確:測試 modal 開啟狀態
test('modal 開啟時應無違規', async ({ page }) => {
await page.goto('/');
await page.click('button[data-testid="open-modal"]');
// 等待 modal 進入 DOM
await page.waitForSelector('[role="dialog"]');
const results = await new AxeBuilder({ page }).analyze();
expect(results.violations).toEqual([]);
});3. 將 axe 加入測試但用 exclude 抑制違規
// 錯誤:排除有問題的元件而不是修復它
const results = await new AxeBuilder({ page })
.exclude('#problematic-dropdown')
.analyze();
expect(results.violations).toEqual([]);此模式適用於您無法控制的已知第三方元件問題,但它常常被用來讓 axe 對您自己擁有的元件保持沉默。每個排除都應該有對應的 issue 票單和移除排除的計劃。
4. 安裝了 eslint-plugin-jsx-a11y 但未強制執行
將插件放在 devDependencies 中什麼都不做。規則必須在 ESLint 設定中啟用,且 lint 步驟必須在 CI 中執行。驗證方式:
# 啟用 a11y 規則執行 lint
npx eslint src/ --rule 'jsx-a11y/alt-text: error'
# 在 CI 中,lint 失敗應阻止建置
# package.json
# "scripts": { "lint": "eslint src/", "ci:lint": "eslint src/ --max-warnings 0" }延伸閱讀
- FEE-1000: 無障礙概覽
- FEE-1001: ARIA 角色與屬性
- FEE-1002: 鍵盤導航
- FEE-1004: 螢幕閱讀器與輔助技術
- FEE-1005: 無障礙表單與輸入元素 — axe-core 測試驗證的表單標籤與錯誤關聯需求
- FEE-1101: Vitest — 單元測試
- FEE-1102: React Testing Library
- FEE-1103: Playwright — E2E 測試
- FEE-1107: 左移測試哲學
參考資料
Deque Systems — axe-core 規則說明文件https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md 目前 axe-core 規則數量、WCAG 對應關係,以及哪些規則預設啟用、哪些屬於實驗性或已棄用的權威來源。規則數量會隨版本變動,任何規則數量的主張都應對應到所使用的 axe-core 版本。
Deque — 自動化測試能識別 57% 的數位無障礙問題https://www.deque.com/blog/automated-testing-study-identifies-57-percent-of-digital-accessibility-issues/ Deque 對其 2021 年針對超過 13,000 個頁面進行的稽核研究的說明,該研究以問題數量而非 WCAG 成功準則數量衡量自動化覆蓋率,得出的結果(57%)明顯高於以準則為基礎的估計(20% 至 40%)。兩種衡量方式的差異,請見「情境」一節中覆蓋率上限的討論。
@axe-core/playwright — 官方 Playwright 整合https://github.com/dequelabs/axe-core-npm/tree/develop/packages/playwright 在 Playwright 測試中執行 axe 的安裝指南、API 參考和設定選項。
eslint-plugin-jsx-a11y — 規則參考https://github.com/jsx-eslint/eslint-plugin-jsx-a11y 完整的可用規則列表、建議設定,以及將每條規則對應到其強制執行的 WCAG 準則的規則層級文件。
Google Lighthouse — 無障礙稽核文件https://developer.chrome.com/docs/lighthouse/accessibility/scoring 說明 Lighthouse 的評分方法、它執行的檢查,以及加權評分如何與 WCAG 合規性相關聯。
WebAIM — 螢幕閱讀器使用者調查https://webaim.org/projects/screenreadersurvey/ NVDA、JAWS 和 VoiceOver 與瀏覽器配對的使用統計 — 這是決定在人工測試中優先考慮哪些螢幕閱讀器和瀏覽器組合的實證基礎。
Accessibility Insights — 人工測試指南https://accessibilityinsights.io/ 微軟基於 axe-core 的無障礙測試工具,具有結構化的人工測試標籤,引導完成自動化工具無法評估的 WCAG 準則。
Storybook — 無障礙測試https://storybook.js.org/docs/writing-tests/accessibility-testing 記錄了
@storybook/addon-a11y,它會針對獨立的 story 執行 axe-core。在此引用作為框架無關、持續維護的替代方案,用以取代不支援 React 18 以上版本的@axe-core/react開發模式整合。