テスト手順

スキャンが判定するのは、ルールが判定できるものです。評価の残りは人が行います。スキャンが未決のまま残す問い（cantTell）と、どのルールもまったくテストしない達成基準の部分です。@surea11y/core 1.15.0以降、コアはその部分のやり方も示します。ルールが評価するWCAGの各達成基準と、ベストプラクティスのすべてのファセットについてのテスト手順で、手順、必要なツール、何が合格で何が不合格かを、英語、フランス語、ドイツ語、スペイン語、日本語で示します。検出結果の「確認方法」もこれと同じ文章から作られているので、チームの手動のチェックとスキャンは同じ内容を読みます。

スキャンをまったく使わない手動の監査に、スキャンが人に任せるものについてはスキャンと並べて、あるいはルールが何も見つけなかったものの全体はカバーしていない達成基準を説明するために使えます。検出結果の手順と同じく、テスト手順は助言であって検出結果の同一性の一部ではなく、文言はどのリリースでも改善されることがあります。

実際に見る

次の2つのページは、WCAG 2.2のレベルAとAAについてのコア自身の出力で、このサイトが追従するリリースごとに再生成しています。ディスクから開け、ほかの場所からは何も読み込みません。

• リファレンス：WCAGの原則とガイドラインのもとで、すべての達成基準をファセットごとにどう評価するか。
• ワークシート：各チェックを1回ずつ、記録する結果（未確認、合格、不合格、該当なし）とメモの欄とともに示します。記録はブラウザーに保存され、JSONまたはCSVでダウンロードできます。

どちらのページも、jsdomとChromiumで、ライトモードとダークモードで、WCAG 2.2 AAのプロファイルにおいて、コア自身のルールを満たしています。スキップリンク、1レベルずつの見出し、ラベル付きの領域、本物のリストとフィールドセット、見えるフォーカス、色だけに頼らない表示、強制カラーのテーマへの追従、スマートフォンの幅、印刷できるレイアウトです。

テスト手順とは

達成基準にはファセットがあります。人がその達成基準を評価するために確認するテストの目的です。ルールが判定するファセットはfull、ルールが一部を判定するファセットはpartial、人だけが判断できるファセットはmanualです。ファセットには一般的な手順があります。人がページ全体に対して、ブラウザーとその開発者ツール、キーボード、必要な場合はスクリーンリーダーを使って行う手順、合格の場合と不合格の場合にそれぞれ何が見えるか（不合格となる達成基準の名前とともに）、そしてブラウザー以外に必要なツールです。

• 技術ファセットは、ルールが1種類の要素に対して行う1つのテストです（<img>がalt属性を持つ）。それ自身の手順は持たず、coveredByが、その手順でそれを評価するより広いファセットを示します。そのため、チェックリストには人が行うことが1回ずつ挙がります。
• バリアントは、1つのルールが1つの要素について問う、より狭い問いです。その未判定の検出結果がhowToCheckとして示す手順です。検出結果は常にそのバリアントを示し、一般的な文章は示しません。両者が矛盾することはありません。コアのルールがcantTellとして報告しうるすべての理由コードは、ちょうど1つのファセットに属します。
• どの達成基準も求めていないものはbest-practiceのもとに分けてあるので、達成基準のテスト手順が助言を不合格として示すことはありません。

テスト手順がある達成基準

コアのルールが、完全に、一部だけ、またはcantTellとして評価するすべての達成基準は、どのルールもチェックしないファセットも含めて、すべてのファセットに手順を持ちます。スキャンが始めたことを人が終えるにはそれらが必要だからです。レベルA、AA、AAAのWCAG 2.2の87の達成基準と4.1.1（2.2で削除）のうち36で、ファセットは170、独自の手順が56、そのいずれかでカバーされる技術ファセットが114です。そうした達成基準はcompleteです。どのルールも評価しない残りの51の達成基準（たとえば1.2.3「音声解説、又はメディアに対する代替（収録済）」）は、ファセットとともに手順なしで挙げられます。それらを手作業でどう評価するかは、コアの範囲外です。ベストプラクティスは、13のファセットそれぞれに手順を持ちます。ランドマーク、ランドマーク内のコンテンツ、見出し、表のマークアップ、ARIAのロール、フォーカス順序、アクセスキー、スキップリンク、名前とラベル、ズーム、繰り返される名前、新しいウィンドウとダウンロード、動きの抑制です。

読み取る

Nodeでは、辞書をディスクから読む@surea11y/coreから使います。ブラウザーで動くコードは、同じものを@surea11y/core/proceduresからFromの接尾辞付きで（proceduresFrom、listProceduresFrom、procedureChecklistFrom、renderProceduresFrom、procedureLanguagesFrom）インポートし、@surea11y/core/procedures/<locale>としてインポートした辞書を渡します。ファイルシステムを必要とせず、ルールにも一切触れません。

const { proceduresFor } = require('@surea11y/core');
 
proceduresFor('1.4.12', { locale: 'fr' });
// { standard: 'wcag', id: '1.4.12', title: 'Espacement du texte', level: 'AA', complete: true,
//   rules: ['avoid-inline-spacing', 'text-spacing-content-loss'], facets: [ … ] }

import { proceduresFrom } from '@surea11y/core/procedures';
import en from '@surea11y/core/procedures/en';
import fr from '@surea11y/core/procedures/fr';
 
proceduresFrom({ en, fr }, '1.4.12', { locale: 'fr' });

各ファセットは、そのlabel、automation、それを対象とするrules、そのtools、そのprocedure（{ steps, passWhen, failWhen }、または技術ファセットではcoveredByとともにnull）、そしてそのvariantsを持ちます。各バリアントは、そのコードについてのそのルールの検出結果のhowToCheckとまったく同じものです。読んだ言語とは別の言語のテキスト（2.1での4.1.1の「Parsing」のような以前のWCAG自身のタイトルや、ロケールにないテキスト）はその言語を示すので、ツールはWCAG 3.1.2が求めるとおりlangで示せます。形の全体は、GitHub上のコアのPROCEDURES.mdにあります。

一覧にする

const { listProcedures } = require('@surea11y/core');
 
listProcedures();                                         // WCAG 2.2, every level
listProcedures({ version: '2.1', levels: ['A', 'AA'] });  // WCAG 2.1 A and AA
listProcedures({ standard: 'best-practice' });
listProcedures({ levels: ['A', 'AA'], automation: ['manual', 'partial'] }); // what a scan leaves

WCAGの達成基準は、そのバージョンがそのレベルで持つものです。2.0と2.1は4.1.1を「構文解析」という名前のレベルAの達成基準として挙げ、2.2は挙げません。複数のフィルターを指定すると、ファセットはそのそれぞれに一致する必要があります。要件のcompleteは、その要件自身のもののままです。

チェックリスト

procedureChecklistは同じオプションを受け取り、規格を評価するために人が行うことを、それぞれ1回ずつ返します。一般的な手順ごとに1項目で、それがあわせて評価する技術ファセットをcoversに、その背後にあるルールをrulesに持ちます。

const { procedureChecklist } = require('@surea11y/core');
 
procedureChecklist({ levels: ['A', 'AA'] }).items[0];
// {
//   key: '1.1.1/text-alternative-mechanism',
//   label: 'Non-text content that conveys something has a text alternative',
//   automation: 'partial',
//   wcag: '1.1.1',
//   requirements: ['1.1.1'],
//   covers: ['img-alt-attr-present', 'role-img-text-alternative-present', …],
//   rules: ['img-alt-present', …],
//   tools: [{ id: 'devtools', label: "The browser's developer tools" }],
//   procedure: { steps: ['…'], passWhen: '…', failWhen: '… which fails WCAG 1.1.1.' }
// }

ページとワークシート

renderProceduresは、listProcedures、procedureChecklist、proceduresForが返すものを、人が読んだり順に進めたりする文書に変えます。サーバー、ネットワーク、ほかの場所のフォントやスクリプトなしでディスクから開ける、単体で完結した1つのHTMLページか、Markdownです。同じ入力とオプションからは、常に同じページが作られます。

const { listProcedures, procedureChecklist, renderProcedures } = require('@surea11y/core');
const fs = require('node:fs');
 
// A reference: how to assess every WCAG 2.2 A and AA criterion.
fs.writeFileSync('wcag-22-aa.html', renderProcedures(listProcedures({ levels: ['A', 'AA'] })));
 
// A worksheet: each check once, with a result and notes to record.
fs.writeFileSync('wcag-22-aa-checklist.html', renderProcedures(procedureChecklist({ levels: ['A', 'AA'] })));
 
// The same in Markdown, for a repository or a wiki.
fs.writeFileSync('wcag-22-aa.md', renderProcedures(listProcedures({ levels: ['A', 'AA'] }), { format: 'markdown' }));

一覧のページは規格のリファレンスです。タイトルと範囲、結果の意味（ベストプラクティスはどの適合性にも数えられず、レベルAAAは助言です）、「始める前に」、目次、そして各要件とそのファセットを示します。各ファセットが何をチェックするか、ルールがどこまで判定するか、ツール、手順、何が合格で何が不合格か、それをテストするルールです。

チェックリストのページはワークシートです。各項目の下に、人が結果とメモを記録します。ページは結果を数えてスクリーンリーダーが読み上げるステータスメッセージに示し、ブラウザーに保存し（localStorage。規格、バージョン、タイトルをキーにします）、各要件の結果をその項目から集約したJSON、またはアクセント記号付きの文字もそのまま表計算ソフトで開けるCSVとしてダウンロードします。要件は、項目のどれかが不合格なら不合格、まだ確認していない項目があればopen、該当する項目がなければnotApplicable、それ以外は合格になります。

{
  "title": "WCAG 2.2: manual checklist",
  "standard": "wcag",
  "version": "2.2",
  "items": [
    {
      "key": "1.1.1/text-alternative-mechanism",
      "requirements": ["1.1.1"],
      "outcome": "fail",
      "notes": "The logo has no alt."
    }
  ],
  "requirements": [{ "id": "1.1.1", "outcome": "fail" }]
}

ページ自身の文言は、コアが同梱するすべての言語でそろっています。テスト手順、ファセットのラベル、WCAGの原則、ガイドライン、達成基準も同様で、名前は各言語で公開されているWCAGの翻訳に従います。ページとは別の言語のものはその言語で示されるので、スクリーンリーダーは各部分をその言語で読み上げます。fragment: trueは、独自のスタイルを持つドキュメントサイトのために、内容だけをh1から始まる見出しとともに<div class="surea11y-procedures">に入れて返します。

CLIから

@surea11y/cli 1.5.0は、コードを書かずに同じページを書き出します。スキャンなしではsurea11y procedures、スキャンと並べてスキャンが人に任せるチェックには--manual-checksを使います。

# How to assess every WCAG 2.2 A and AA criterion, or a worksheet for a manual audit
$ surea11y procedures --wcag-level AA -o wcag-22-aa.html
$ surea11y procedures --wcag-level AA --checklist --title "Audit: example.com" -o audit.html
# The checks a scan leaves to a person, as a worksheet next to its report
$ surea11y scan https://example.com/ --wcag 2.2 --html report.html --manual-checks manual-checks.html

HTMLレポートで

HTMLレポートには「人による確認が残っているもの」のセクションがあります。スキャンした規格の要件のうち、どのルールも完全には判定しないチェックを持つものすべてを、スキャンでの判定結果を横に付けて示し、その下に折りたたんだ形で、それらのチェックを手順とともに示します。ルールがすべて合格した要件も、そのチェックが合格して初めて満たされ、レポートもそう示します。renderHtmlReport(result, { manualChecks: false })にすると、このセクションを省きます。

使い方

スキャンなしの手動の監査。監査担当者は、監査の対象となる規格のワークシートを順に進め、各結果とメモを記録し、レポートのためにJSONをダウンロードします。

const checklist = procedureChecklist({ version: '2.2', levels: ['A', 'AA'] });
fs.writeFileSync('audit-worksheet.html', renderProcedures(checklist, { title: 'Accessibility audit: example.com' }));

テスト実行の添付ファイル。ページをスキャンするPlaywrightのテストは、ルールが判定しないチェックを添付できるので、それらはテストレポートの中でスキャンと並びます。

test('home page', async ({ page }, testInfo) => {
  // ... scan the page ...
  const left = procedureChecklist({ levels: ['A', 'AA'], automation: ['manual', 'partial'] });
  await testInfo.attach('manual-checks.html', {
    body: renderProcedures(left, { record: false }),
    contentType: 'text/html'
  });
});

スクリーンリーダーの利用者とのセッション。スクリーンリーダーを毎日使う人とのセッションのために、スクリーンリーダーが必要なものだけを示します。

const sr = listProcedures({ levels: ['A', 'AA'], tools: 'screen-reader' });
fs.writeFileSync('screen-reader-session.html', renderProcedures(sr, { title: 'Screen reader session' }));

ドキュメント。ドキュメントサイトやリポジトリに規格ごとに1つのMarkdownファイルを置き、コアを更新したときに再生成すれば、チームはツールが使うのと同じテスト手順を読めます。必要な場所で、1つの達成基準を。検出結果を表示するツールは、renderProcedures(proceduresFor('1.4.12', { locale: 'de' }), { fragment: true })で、その達成基準全体の評価方法を示せます。

パックの規格

パックの規格は、人がその独自の要件をどう評価するかを示すことができ、上のすべての関数は、パックを渡せばそれを読みます。その規格自身の番号とグループで、言語を宣言していればその言語で読みます。WCAGの達成基準を再掲する要件は、その達成基準のテスト手順を、その要件として読み替えて使います（「which fails EN 301 549 9.1.4.3」）。core 1.16.0以降、ファセットは、規格の対応付けがそれが評価するものに振り分けるコアのルールも列挙します（mappedRules。チェックリスト項目のmappedRulesにも）。そのため、コアのルールだけがチェックする要件やテストが、チェックされていないように見えることはありません。

const en301549 = require('@surea11y/pack-en301549');
 
proceduresFor('9.1.4.3', { packs: [en301549], standard: 'en301549', version: 'V4.1.1', locale: 'fr' });
relatedRequirements('1.4.3', { packs: [en301549] });
// [{ standard: 'EN 301 549', id: '9.1.4.3', version: 'V4.1.1', relation: 'restates', … }]
 
const options = { packs: [en301549], standard: 'en301549', version: 'V4.1.1', locale: 'fr' };
fs.writeFileSync('en-301-549.html', renderProcedures(procedureChecklist(options), { packs: [en301549] }));

EN 301 549のパック 1.2.0は、コアのルールが評価する達成基準を持つ第9章のすべての条項についてテスト手順を5つの言語で提供し、WAI-ARIAのパックは、各要件のチェックリストを、妥当なロール、状態、値をすべて列挙して提供します。テスト手順を提供しないパックは何も変えません。WCAGのテスト手順は、パックがあってもなくても同じです。