@mitsue/axeel

v0.2.0

Published

a month ago

axeel is a tool for code-based checking by axe-core.

0High
0Medium
0Low

mitsue

axeel

axeelはソースコードベースでaxe-coreによるチェックを行うためのツールです。読み方は「アクセル」です。

静的なHTMLをJSDOM / happy-domで解析した結果を検証します。ブラウザで描画したあとのDOMや、拡張機能のaxe結果と同一にならない可能性があります。

最小限の使い方

インストール
```
npm i --save-dev @mitsue/axeel
```
プロジェクト内に設定ファイルを作成する（任意。未指定時はカレント以下の **/*.+(htm|html|shtml) を走査）
```
html:
    include:
        - 'docs/**/*.html'
```
実行する
```
npx axeel --config .axeelrc.yml
```

package.json の例:

{
  "scripts": {
    "a11y": "axeel --config .axeelrc.yml"
  }
}

詳細な使い方

コマンドライン引数

npx axeel --help で一覧表示されます。いずれの引数も任意です。

| 引数 | 省略 | 用途 | デフォルト | | --- | --- | --- | --- | | --config | -c | HTML の include / ignore などの YAML | 未指定時は内蔵の glob | | --out | -o | 結果ファイル（--format に応じて要約・詳細・JSON） | なし | | --format | -f | 出力内容を summary（要約）| full（詳細）| json で切り替えます。 | summary | | --verbose | -v | ファイルごとの進捗を標準エラーに出す | オフ | | --domType | -d | DOM 実装 jsdom | happy-dom | jsdom | | --parallel | -p | 並列実行数 | CPU コア数 | | --axe-linter | | axe-linter.yml のパス | AXEEL_AXE_LINTER 環境変数、または ./axe-linter.yml | | --ignore-file | | .axeelignore.yml のパス | AXEEL_IGNORE 環境変数、または ./.axeelignore.yml（存在すれば読む） | | --rebaseline | | 走査した結果から、.axeelignore.ymlを書き出す | オフ | | --rebaseline-out | | --rebaseline の出力パス | .axeelignore.yml |

チェック結果の出力

要約（既定）: 全体のエラー件数、ファイル別、ルールID別のエラー件数を表示
詳細: ファイルごとに検知されたエラーをすべて表示
JSON: --format json で全件を機械可読形式に表示

※ --out を付けた場合はファイルに書き、標準出力は短いメッセージに留まります。

axeelの設定

設定ファイルにはチェック対象とするファイルと、除外対象とするファイルを指定できます。

html: 
    include:
        - 'docs/**/*.html'
    ignore:
        - '**/node_modules/**'

--config にパスを指定したのにファイルが読めないときはエラー終了します（未指定なら既定 glob のみ）。

--rebaseline（無視リストの生成）

--rebaseline を付けると、通常のチェック結果はコンソールに出力せず、検出した違反を、ファイルごとのルール ID 一覧を .axeelignore.yml として出力し、終了コード 0 で終了します。

これはエラーを無視して先に進むための機能ではなく、既知の違反を記録に残し、改善するための出発点として使うことを想定しています。必ず内容を確認してから採用してください。

既知違反の無視（axeelignore）

プロジェクトルートに .axeelignore.yml を置くと、ファイル（グロブ）とaxeルールIDの組み合わせで違反を除外します。ルールIDはaxe-coreのGitHubを参照してください。

以下はサンプルです。

'**/*.html':
  - image-alt
'subdir/page.html':
  - label

ignore: キーの下にネストしても構いません。「とりあえず無視」の積み上がりは負債になりやすいので、チケットや期限をチームで決める運用を推奨します。

axe-coreの設定

VSCodeにはaxe Accessibility Linterという拡張機能があります。

この拡張機能はaxe-linter.ymlという設定ファイルでルールの有効無効を切り替えることができます。

axeelは axe-linter.yml（または --axe-linter / 環境変数 AXEEL_AXE_LINTER）があればその設定を適用します。無い場合は color-contrast など一部ルールを既定でオフにします。

axe-linter.ymlに設定できるルールはAvailable Rulesを参照してください。

※ 設定の役割の違い: axe-linter.yml はルール全体の on/off。.axeelignore.yml は既知の違反だけをパス単位で素通りする設定、です。

axeelにチェックできないこと

axeelは、大量のファイルを速くチェックすることを第一目的としているため、HTMLコードベースのチェックのみを実施しています。

そのため、カラーコントラストのチェックやJavaScript実行後のHTMLのチェックなど、ブラウザでのレンダリング処理を前提とするチェックは実施できません。

もし包括的なチェックを実施したい場合は以下のようなツールを使ってみてください。

またhidden属性が付与されている要素はチェック対象となりません。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme