はじめに
インストール
インストールのコマンドは1つではありません。surea11yはコアエンジンと、個別に公開されているバインディング群で構成されているため、どのパッケージをインストールするかは、テストやスクリプトを現在どう実行しているかによって決まります。使っている環境に合わせて選んでください。
実際のWebアプリケーションをスキャンするならPlaywright、ターミナルやCIパイプラインから静的なHTMLをチェックするならCLIを使ってください。
| 目的 | おすすめ | 理由 |
|---|---|---|
| 実際のWebアプリケーションを分析する | Playwright | 実際のブラウザーを操作し、最近のテストスイートがすでに使っている連携方法なので、結果に実際のレイアウトとレンダリングが反映されます。 |
| 静的なHTMLを分析する | CLI | 連携のコードを書く必要がありません。ファイル、URL、サイトマップ、CIのステップに対してコマンドを1つ実行するだけです。--browserを付ければ、JavaScriptでレンダリングされるページもスキャンします。 |
| Cypress、Selenium、Puppeteer、WebdriverIOをすでに使っている | 対応するバインディング | すでにあるテスト環境にそのまま組み込めます。 |
| ユニットテスト、コンポーネントテスト | test-matchers | jsdomを対象にJest/Vitestと直接連携します。 |
| 独自の連携、またはエンジンへの直接アクセス | @surea11y/core | 実行と結果を最大限に制御できます。 |
5分でわかる例
実際の結果を見るいちばん速い方法はCLIです。ブラウザーの準備もテストフレームワークも要りません。最小限のページをスキャンしてみます。
<html lang="en"><body><main><h1>Welcome</h1><p style="color: #999999; background-color: #ffffff;">This text has low contrast.</p><a href="/details">Click here</a></main></body></html>
$ npm install -g @surea11y/cli$ surea11y scan ./index.html
surea11y scan: file:///path/to/index.htmlengine: @surea11y/core 1.14.1pass: 14 fail: 3 cantTell: 2 notApplicable: 126occurrences by tier: fail: 3 cantTell: 2needs review: likely fail: 0 likely pass: 0 needs a person: 2FAIL (3 rule(s)):contrast-enhanced (serious, 1 fail occurrence(s))- html > body > main > pElement has insufficient color contrast (AAA) of 2.85:1 (foreground:#999999, background: #ffffff, font size: 16px, font weight: normal).Expected contrast ratio of 7:1 (normal text).hint: Change the text color, the background color, or both, so thecontrast ratio reaches at least 7:1.contrast-minimum (serious, 1 fail occurrence(s))- html > body > main > pElement has insufficient color contrast of 2.85:1 (foreground:#999999, background: #ffffff, font size: 16px, font weight: normal).Expected contrast ratio of 4.5:1 (normal text).hint: Change the text color, the background color, or both, so thecontrast ratio reaches at least 4.5:1.page-title-present (serious, 1 fail occurrence(s))- head > titleThis page has no <title> element.hint: Add a <title> that says what the page is about or what it is for.cantTell — needs human review (2 rule(s)): link-name-quality,manual-reviewcriteria (WCAG 2.2):fail 1.4.3 Contrast: minimum; 1.4.6 Contrast: enhanced; 2.4.2 PagetitledcantTell 1.1.1 Non-text content: text alternatives; 1.2.1 Audio-onlyand video-only (prerecorded): transcript; 1.2.2 Captions(Prerecorded); 1.3.1 Info and Relationships; 1.3.4Orientation; 1.3.5 Identify Input Purpose; 1.4.1 Use ofColor; 1.4.2 Audio Control; 1.4.4 Resize Text; 1.4.5 Imagesof Text; 1.4.12 Text Spacing; 2.1.1 Keyboard; 2.1.3 Keyboard(No Exception); 2.2.1 Timing Adjustable; 2.2.2 Pause, Stop,Hide; 2.2.4 Interruptions; 2.4.1 Bypass Blocks; 2.4.3 Focusorder; 2.4.4 Link Purpose (In Context); 2.4.6 Headings andLabels; 2.4.7 Focus visible; 2.4.9 Link Purpose (Link Only);2.5.8 Target size: minimum; 3.1.1 Language of page; 3.1.2Language of Parts; 3.2.5 Change on Request; 3.3.1 ErrorIdentification; 3.3.2 Labels or Instructions; 3.3.8Accessible Authentication (Minimum); 4.1.2 Name, role, value:accessible name; 4.1.2 Name, role, value: ARIA validity;4.1.3 Status MessagesnotApplicable: 2A criterion that passes here means the checks that ran found nothing init, not that the page conforms.
エンジンが確信を持っている問題が2つあり、failになっています。AAとAAAの両方の比率で不合格になった低コントラストのテキストと、欠けている<title>です。次に、人がレビューするためのcantTellの一覧(「Click here」はリンク名として適切か、手動で確認すべきものがないか)があります。needs reviewの行は、どちらの問いもどちらにも傾いておらず、どちらも人の確認が必要なことを示しています。126件のnotApplicableの中にはtarget-size-minimumがあります。このルールは実際のCSSレイアウトがないと実行できず、静的なHTMLのスキャンにはそれがないためです(--browserを付ければレイアウトがあります)。
最後のブロックは、同じ結果をWCAG 2.2の達成基準ごとに示しています。1.4.3、1.4.6、2.4.2はfail、スキャンがチェックするほかの達成基準はすべて人が判断するcantTellで、判断する対象のなかった2つの達成基準は件数だけが示されます。passとして示される達成基準はありません。@surea11y/core1.14から、達成基準が合格になるのは、そのルールが基準の求めることをすべてチェックする場合だけで、まだそうした基準はないため、ルールがすべて合格しても残りは人が確認します。完全な結果の各フィールドの意味は結果とレポートを参照してください。
- 実際のブラウザーまたはヘッドレスブラウザーを操作するE2Eテスト:Cypress、Playwright、Puppeteer、Selenium、WebdriverIO。
- jsdomを対象にしたユニットテスト、コンポーネントテスト:Jest/Vitest向けのtest-matchers。
- ターミナルやCIパイプラインから、静的なHTMLとして、またはブラウザーでページをチェックする:CLI。
- テストフレームワークもビルド手順もない場合:スタンドアロン。
@surea11y/coreを直接インストールするか、ブラウザー用バンドルを読み込みます。
使い方
jsdom、実際のブラウザー、どのバインディング、CLIと、スキャンをどう実行しても、返ってくるのは同じネイティブの結果の形です。checksResults(ルールごとに1件のエントリー。pass/notApplicableもすべて含み、「違反だけ」のリストではありません)とrulesResults(WCAG達成基準の集約)です。これはほかの広く使われているアクセシビリティテストツールのviolations/passes/incomplete/inapplicableという形とは異なります。各バインディングのメソッド名は、移行しやすいようにこの分野でよく使われる慣例にならっていますが、より情報量の多い結果のスキーマはそのまま保っています。スキーマの全体は結果とレポートを参照してください。