Axe DevTools for WebのPuppeteer APIリファレンス

コンストラクタ

Axe DevTools Puppeteerには2つのコンストラクタがあります。これは標準のコンストラクタです。

AxeDevToolsPuppeteer(page: Frame | Page, options?: IOptions)

最初の引数にはPuppeteerのインスタンスを渡す必要があります。 Frame または Pageです。これはスキャンのターゲットです。2番目の引数はオプションのオブジェクトで、次の2つのプロパティのいずれかを含めることができます。

1. axeSource （オプション）：axe-coreのソースコードの文字列
2. rulesetID （オプション）：ストックルールセットのID

標準で含まれているもの以外の特定のバージョンのaxe-coreを使用する場合は、axe-coreのソースファイルを引数として渡すことができます。まず、ファイルシステムからaxe-coreファイルを読み込んでaxeソースオブジェクトを作成します。次に、Axe DevToolsインスタンスをaxeソースオブジェクトに渡します。

const axeSource = fs.readFileSync('./axe-3.0.js', 'utf8');
const builder = new AxeDevToolsPuppeteer(page, { axeSource });

標準以外の事前定義されたルールセットを使用したい場合は、rulesetIDをAxe DevToolsインスタンスに渡すことができます。

const builder = new AxeDevToolsPuppeteer(page, { rulesetID: 'wcag2' });

別のコンストラクタはページを開いてCSP迂回を行います。事前にロードされたページを渡す代わりに、 Browser オブジェクトとURLを渡します。 analyze が呼び出された後、自動的にページを閉じます。さらに、CSP迂回を自動的に実行します。これがそのコンストラクタです。

loadPage(browser: Browser, url: string, options?: IOptions)

このコンストラクタには、代替のaxe-coreソースやルールセットのための同じオプションが含まれており、これらの引数は上記と同じ方法で渡されます。以下は、代替コンストラクタを使用してスキャン結果をコンソールに記録するサンプルファイルです。

const puppeteer = require('puppeteer');
const { AxeDevToolsPuppeteer } = require('@axe-devtools/puppeteer');

(async () => {
    //launch puppeteer web driver
    const browser = await puppeteer.launch();
    const page = await browser.newPage();

    //launch page for testing
    await page.goto('https://broken-workshop.dequelabs.com');

    //analyze page
    const results = await new AxeDevToolsPuppeteer(page).analyze();
    //log results to console
    console.log(results);

    //close browser
    browser.close();
})();

analyze

.analyze([callback: (Error | null[, Object]) => void])

このメソッドは分析を実行し、発生したエラーや結果オブジェクトを指定されたコールバックまたはプロミス関数に渡します。非同期操作であるため、チェーンはできませんので注意してください。

以下の例では、返されたプロミスを使用し、結果オブジェクトをコンソールに記録します。

new AxeDevToolsPuppeteer(page)
  .analyze()
  .then(function(results) {
    console.log(results);
  })
  .catch(err => {
    // Handle error somehow
  });

この例は、 analyse() メソッドをコールバック関数とともに使用した様子を示しています。

new AxeDevToolsPuppeteer(page).analyze(function(err, results) {
  if (err) {
    // Handle error somehow
  }
  console.log(results);
});

analyzeUniversal

.analyzeUniversal(): Promise<UniversalExport>

分析を実行し、結果を Axe Universal Formatで返します。既存の analyze() メソッドは変更されていません。

new AxeDevToolsPuppeteer(page)
  .analyzeUniversal()
  .then(function(results) {
    console.log(results);
  })
  .catch(err => {
    // Handle error somehow
  });

スコープ設定

Axe DevToolsのスキャンのスコープを設定するには、次の2つのオプションがあります： include と excludeです。これらは指定されたCSSセレクタをスコープとしてスキャンします。チェーン可能で、単一のCSSセレクタまたはCSSセレクタの配列を使用できるため、スキャンを完全にカスタマイズできます。

include

.include(selector: string | string[])

include チェーンメソッドを使用すると、CSSセレクタまたはCSSセレクタの配列で選択された要素のみをスキャンします。これは、コンポーネント化されたページの単一インスタンスを確認したり、現在の開発に結果を限定したりするのに便利です。

以下の例では、スコープがクラス内の要素に限定されていることを示しています。 results-panel クラス：

new AxeDevToolsPuppeteer(page).include('.results-panel');

exclude

.exclude(selector: string | string[])

exclude チェーンメソッドを使用すると、CSSセレクタまたはCSSセレクタの配列で選択された要素をスキャン対象から除外します。 include メソッドと同様に、単一セレクタやセレクタの配列を渡すことができます。このメソッドも include メソッドとチェーン可能です。

以下の例では、スコープから h2 クラスを持つ要素を除外している様子を示しています。 results-panel クラス：

new AxeDevToolsPuppeteer(page).include('.results-panel h2');

ルールの設定

withRules

.withRules(rules: string | string[])

このメソッドは、指定されたルールIDまたはルールIDに分析を制限します。ルールの詳細と説明については、 axe-coreルールドキュメンテーションをご覧ください。

以下の例では、 html-lang と image-alt ルールのみがテストされます。

new AxeDevToolsPuppeteer(page).withRules(['html-lang', 'image-alt']);

withTags

.withTags(tags: string | string[])

この withTags メソッドは指定されたタグに関連付けられたルールにスキャンを限定します。ルールセットタグの完全なリストは axe-core ドキュメントで見つけることができます。

次の例は、WCAG 2.0 レベル A のルールのみをテストします。

new AxeDevToolsPuppeteer(page).withTags('wcag2a');

disableRules

.disableRules(rules: string | string[])

このメソッドは、現在使用されているルールのリストから特定のルールまたはルールの配列を削除します。ルールはそのルールIDによって指定されます。このメソッドの後続の呼び出しは、以前の呼び出しを上書きします。ルールIDとその説明の完全なリストは axe-core ルールドキュメントに記載されています。

次の例は、カラ―コントラストの検証を無効にします。

new AxeDevToolsPuppeteer(page).disableRules('color-contrast');

さらに、この disableRules メソッドは他のルール構成メソッドと連鎖して、ユーザー構成のルールセットを変更できます。

次の例では、ルールセットをWCAG 2.0 AおよびAAのルールのみに変更し、その後カラ―コントラストの検証ルールを削除します。

new AxeDevToolsPuppeteer(page)
  .withTags(['wcag2a', 'wcag2aa'])
  .disableRules('color-contrast');

axe-core のオプション

オプション

.options(options: Axe.RunOptions)

この options メソッドは、axe.run に使用されるオプションを指定します。これは、 withRules への呼び出しを含む他の構成されたオプションを上書きします。 withTags詳細については axe-core API ドキュメント を参照してください。

new AxeDevToolsPuppeteer(page).options({
  checks: { 'valid-lang': ['orcish'] }
});

configure

.configure(config: Axe.Spec)

この configure メソッドは、分析前にルールセットを変更するためにaxeの構成オブジェクトを注入します。このメソッドの後続の呼び出しは、 axe.configure() を呼び出して構成オブジェクトを置き換えることによって以前のものを無効にします。 axe-core API ドキュメント をオブジェクトの構造について参照してください。

次の例では、新しいaxe-core構成を作成し、Axe DevToolsに渡してスキャンに使用します。

const config = {
  checks: [Object],
  rules: [Object]
};
const results = await new AxeDevToolsPuppeteer(page).configure(config).analyze();

使用サービス

デフォルトでは、使用サービスは無効化されており、デフォルトのURLは https://usage.deque.comです。

環境変数

これらの環境変数により、使用サービスを構成し、報告されるイベントのプロパティを変更することができます。

enableTracking

この enableTracking() メソッドは、ユーザーが使用サービスにデータを送信するオプトインを可能にします。

.enableTracking(state: boolean)

この例では、 enableTracking メソッドと analyze メソッドを組み合わせて results オブジェクトをコンソールにログ記録します。

new AxeDevToolsPuppeteer(page)
  .enableTracking(true)
  .analyze()
  .then(function(results) {
    console.log(results)
  })

setTrackingUrl

この setTrackingUrl() メソッドは、使用メトリクスデータが送信される場所を変更することをユーザーに許可します。

.setTrackingUrl(url: string)

この例では、 setTrackingUrl() メソッドと analyze() メソッドを使用し、 results オブジェクトをコンソールにログ記録します。

new AxeDevToolsPuppeteer(page)
  .enableTracking(true)
  .setTrackingUrl('https://foobar.biz')
  .analyze()
  .then(function(results) {
    console.log(results)
  })

setDistinctId

このメソッドは、格納または使用される一意のIDを変更することができます。

.setDistinctId(distinctId: string)

この例では、 setDistinctId メソッドと analyse メソッドを組み合わせて結果のオブジェクトをコンソールにログ出力します。

new AxeDevToolsPuppeteer(page)
  .enableTracking(true)
  .setDistinctId('foobar')
  .analyze()
  .then(function(results) {
    console.log(results)
  })