Playwrightとaxe-coreでアクセシビリティを検査する方法

​​Playwright​axe-core,E2Eテスト,TypeScript,アクセシビリティ

Playwright のテストに @axe-core/playwright を入れると、ページを開いて new AxeBuilder({ page }).analyze() を呼ぶだけで、アクセシビリティの問題を一覧にできます。画像の alt の付け忘れ、アイコンだけで名前のないボタン、背景に対して薄すぎる文字色のような問題を、ふだんの E2E テストの中で見つけられます。

私は検証環境で、わざと問題を入れた会員登録ページを作り、何が見つかって何が見つからないか、検査の範囲やルールを絞るとどう変わるかを確かめました。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4、@playwright/test 1.63.0、@axe-core/playwright 4.14.0(axe-core 4.14.1)、TypeScript 7.0.2 です。ブラウザは Playwright 用の Chromium だけで、ページは Node.js の http モジュールで書いた小さなサーバーから配信しました。Firefox・WebKit、スクリーンリーダーでの読み上げ、HTML レポーターの画面は試していません。

入れるパッケージ

Playwright のテストの環境に、@axe-core/playwright を足します。検証では、版を固定して次のように入れました。

bash
npm i -D -E @playwright/test@1.63.0 @axe-core/playwright@4.14.0 typescript@7.0.2 @types/node@22.20.5

@axe-core/playwright の README によると、このパッケージのバージョンのうちメジャーとマイナー(4.14)は、中で使う axe-core のバージョンに合わせてあります。実際に入ったのは axe-core 4.14.1 でした。Playwright を最新より古い版に固定している場合は、TypeScript の型チェックでエラーが出ることがあります。直し方は最後の節に書きます。

問題を入れた会員登録ページ

検査したページには、次の問題を入れました。

html
<header><img src="/logo.png" width="120" height="32"></header>
<main>
  <h1>会員登録</h1>
  <p class="note">パスワードは8文字以上にしてください</p>
  <form>
    <input type="email" placeholder="メールアドレス">
    <button type="button" class="icon"><svg width="16" height="16"><circle cx="8" cy="8" r="6"/></svg></button>
    <button type="submit">登録する</button>
  </form>
  <button type="button" id="open">利用規約を読む</button>
  <dialog id="terms">
    <h2>利用規約</h2>
    <p>本文です。</p>
    <button type="button" class="icon" id="close">×</button>
    <img src="/stamp.png" width="40" height="40">
  </dialog>
</main>
<div id="ad"><a href="https://example.com/"><img src="/ad.png" width="200" height="50"></a></div>

ロゴと広告の画像には alt がありません。説明の文字は、白い背景に #b0b0b0 の薄い灰色です。メールアドレスの欄にはラベルがなく、placeholder だけです。広告の枠は <main> の外に置きました。ロゴなどの画像には、中身のない仮の PNG を使いました。

まずはページ全体を検査する

Playwright の公式ドキュメントのアクセシビリティテストの説明にある、いちばん基本の形で検査しました。違反の中身が分かるように、ルールの ID、深刻度、当てはまった要素を出しています。

ts
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('会員登録ページの違反を一覧にする', async ({ page }) => {
  await page.goto('/');
  const t0 = Date.now();
  const results = await new AxeBuilder({ page }).analyze();
  console.log('analyze', Date.now() - t0, 'ms');
  for (const v of results.violations) {
    console.log(v.id, v.impact, v.nodes.length, v.nodes.map((n) => n.target.join(' ')).join(', '));
  }
  console.log('passes', results.passes.length, 'incomplete', results.incomplete.length, 'inapplicable', results.inapplicable.length);
  expect(results.violations).toEqual([]);
});
text
analyze 535 ms
button-name critical 1 form > .icon[type="button"]
color-contrast serious 1 .note
image-alt critical 2 img[src$="logo.png"], img[src$="ad.png"]
link-name serious 1 a
region moderate 1 #ad
passes 24 incomplete 0 inapplicable 64

5つのルールで違反が見つかりました。名前のないアイコンのボタン(button-name)、薄い文字(color-contrast)、alt のない画像2つ(image-alt)、画像だけで名前のないリンク(link-name)、<main> などのランドマークの外にある広告の枠(region)です。見つかった要素を、ピンクの枠で囲むと次のようになります。

会員登録ページのスクリーンショット。ロゴの場所の仮の画像(中身のない灰色の四角)、薄い灰色の説明文、丸いアイコンのボタン、下の広告の枠(同じく仮の画像)がピンクの線で囲まれ、それぞれに image-alt、color-contrast、button-name、image-alt・link-name・region のラベルが付いている
axe が違反として返した要素を、テストの中でピンクの枠とルールの ID で囲んだ画面

analyze() にかかった時間は535msでした。別のテストで、同じページを開いたまま5回続けて測ると、599、361、373、345、369ms で、2回目からは短くなりました。

toEqual([]) の失敗メッセージを短くする

公式ドキュメントの例のとおり expect(results.violations).toEqual([]) で落とすと、失敗メッセージの差分は、受け取った値の側だけで395行になりました。各違反の説明文やチェックの中身まで、全部が出るためです。

ルールの ID と要素のセレクターだけに絞ってから比べると、どこを直せばよいかが一目で分かります。

ts
const found = results.violations.map((v) => ({
  rule: v.id,
  targets: v.nodes.map((n) => n.target.join(' ')),
}));
expect(found).toEqual([]);
text
    - Expected  -  1
    + Received  + 33
    - Array []
    + Array [
    +   Object {
    +     "rule": "button-name",
    +     "targets": Array [
    +       "form > .icon[type=\"button\"]",
    +     ],
    +   },
    +   Object {
    +     "rule": "color-contrast",
    +     "targets": Array [
    +       ".note",
    +     ],
    +   },

(33行のうち、先頭の部分です)

色のコントラストは、ブラウザで描いた色で測る

Playwright では本物のブラウザでページを描くので、color-contrast のルールも動きます。違反の要素の any[0].data に、測った数値が入っていました。

text
data {
  fgColor: '#b0b0b0',
  bgColor: '#ffffff',
  contrastRatio: 2.16,
  fontSize: '12.0pt (16px)',
  fontWeight: 'normal',
  messageKey: null,
  expectedContrastRatio: '4.5:1'
}

#b0b0b0 の文字は白い背景に対して 2.16:1 で、求められる 4.5:1 に足りません。

一方、背景画像の上に白い文字を置いたページでは、違反は0件でした。代わりに、incomplete(自動では判定できず、人が確かめる必要があるもの)に入りました。

text
violations []
incomplete color-contrast [ 'p' ] [
  "Element's background color could not be determined due to a background image"
]

violations だけを見ていると、この文字は通ったように見えます。

placeholder だけの入力欄は違反にならなかった

ラベルのないメールアドレスの欄は、違反に入りませんでした。label のルールの結果を見ると、non-empty-placeholder のチェックで合格になっていました。

text
label passes [ [ 'input', [ 'non-empty-placeholder' ] ] ]
label violations 0

axe-core 4.14 は、空でない placeholder があれば、その入力欄には名前があるとみなしました。違反が0件でも、入力欄に見えるラベルがあるかどうかまでは分かりません。公式ドキュメントでも、自動のテストで見つかるのは一部の問題で、手で確かめることとの組み合わせを勧めています。

ダイアログは開いてから検査する

analyze() は、呼んだ時点のページを調べます。閉じたダイアログの中にある alt のない画像は、ページ全体の検査に出てきませんでした。include('#terms') でダイアログだけに絞っても、0件です。

ボタンを押してダイアログを開き、表示を待ってから検査すると、見つかりました。

ts
await page.getByRole('button', { name: '利用規約を読む' }).click();
await expect(page.getByRole('dialog')).toBeVisible();
const after = await new AxeBuilder({ page }).include('#terms').analyze();
text
開く前 []
開いた後 [ 'image-alt (critical) img[src$="stamp.png"]' ]
開いた後のページ全体 [ 'image-alt (critical) img[src$="stamp.png"]' ]

ダイアログを開いたあとにページ全体を検査すると、ダイアログの外の5つの違反は出ませんでした。このダイアログは showModal() で開いています。MDN の showModal() の説明によると、モーダルのダイアログを開くと、ダイアログの外の要素は inert(操作も読み上げもできない状態)になります。そのため、ページ全体の検査は、ダイアログを開く前に別に行う必要があります。

検査するルールや範囲を絞る

AxeBuilder には、検査を絞るメソッドがあります。同じページで、それぞれの結果を比べました。

書き方 残った違反
何も絞らない button-name、color-contrast、image-alt(2件)、link-name、region
.withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa']) region が消えた
.exclude('#ad') 広告の image-alt、link-name、region が消えた
.disableRules(['color-contrast']) color-contrast が消えた

withTags() で region が消えたのは、このルールのタグが best-practice で、WCAG のタグを持たないからです。

text
region のタグ [ 'cat.keyboard', 'best-practice', 'RGAAv4', 'RGAA-9.2.1' ]

exclude('#ad') では、広告の枠の中は、どのルールでも調べなくなりました。公式ドキュメントでも、exclude() は指定した要素とその子孫のすべてのルールを止めると説明しています。

disableRules() は、指定したルールだけを、ページ全体で止めます。止めたルールは、広告の枠以外でも調べなくなります。要素ごとに既知の違反だけを許したいときは、次の節のスナップショットの方法が使えます。

いまある違反を固定して、増えたときだけ落とす

すぐには直せない違反があるときは、公式ドキュメントで紹介されている、ルールの ID とセレクターだけのスナップショットを取る方法が使えます。

ts
const fingerprints = results.violations.map((v) => ({
  rule: v.id,
  targets: v.nodes.map((n) => n.target),
}));
expect(JSON.stringify(fingerprints, null, 2)).toMatchSnapshot('violations.json');

1回目はスナップショットのファイルがないので、ファイルを書き出して、テストは落ちました。2回目からは通りました。そのあと、ラベルのないチェックボックスをフォームに1つ足して実行すると、増えた違反だけが差分に出て落ちました。

text
    Error: expect(string).toMatchSnapshot(expected) failed
      @@ -25,10 +25,18 @@
      ...
      +    "rule": "label",
      +    "targets": [
      +      [
      +        "input[type=\"checkbox\"]"
      +      ]
      +    ]

(差分の前後を省いています)

結果の全体をテストの添付ファイルにする

失敗メッセージを短くした分、詳しい情報は testInfo.attach() で残します。

ts
test('違反を読みやすく出して落とす', async ({ page }, testInfo) => {
  await page.goto('/');
  const results = await new AxeBuilder({ page }).analyze();
  await testInfo.attach('accessibility-scan-results', {
    body: JSON.stringify(results, null, 2),
    contentType: 'application/json',
  });
  // ここで違反を比べる
});

JSON レポーターの出力を確かめると、accessibility-scan-results という名前で、86,294バイトの JSON が添付されていました。公式ドキュメントによると、結果には違反のほかに、合格したルールや、判定できなかった要素(incomplete)も入っています。

TypeScript で「Page 型が合わない」と言われたとき

@playwright/test@1.63.0 に固定して入れたところ、npx tsc で AxeBuilder({ page }) の行がすべてエラーになりました(17か所)。

text
tests/basic.spec.ts(7,42): error TS2739: Type 'import("/path/to/app/node_modules/playwright/node_modules/playwright-core/types/types").Page' is missing the following properties from type 'import("/path/to/app/node_modules/playwright-core/types/types").Page': getByRef, webmcp

(パスは /path/to/app に置き換えています)

@axe-core/playwright は、playwright-core を peerDependencies に >= 1.0.0 で持っています。npm はこれに合わせて、その時点の最新の playwright-core 1.65.1 を入れました。テストの page は Playwright 1.63.0 側の型で、AxeBuilder が受け取る型は 1.65.1 側の型なので、合わなくなります。

text
+-- @axe-core/playwright@4.14.0
| +-- axe-core@4.14.1
| `-- playwright-core@1.65.1
`-- @playwright/test@1.63.0
  `-- playwright@1.63.0
    `-- playwright-core@1.63.0

テストの実行そのものは、この状態でも動きました。型チェックを通すには、playwright-core を Playwright と同じ版で入れて、1つにそろえます。

bash
npm i -D -E playwright-core@1.63.0
text
+-- @axe-core/playwright@4.14.0
| `-- playwright-core@1.63.0 deduped
+-- @playwright/test@1.63.0
| `-- playwright@1.63.0
|   `-- playwright-core@1.63.0 deduped
`-- playwright-core@1.63.0

これで npx tsc のエラーは0件になりました。同じ構成で @playwright/test を最新の 1.65.1 にした場合は、playwright-core は1つにまとまり、型エラーは出ませんでした。

​Posted by 86