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セレクタまたは配列で選択された要素のみがスキャンされます。これは、コンポーネント化されたページの単一インスタンスを確認したり、現在の開発に結果を限定したりするのに便利です。

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

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

exclude

.exclude(selector: string | string[])

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

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

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

ルールの設定

withRules

.withRules(rules: string | string[])

このメソッドは、指定されたルールIDまたはルールIDsに分析を限定します。ルールとその説明の完全なリストは 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)
  })