利用サービスとAPIの始め方

この記事では、利用サービスのイベントを収集してコンソールに表示するシンプルなサーバー（エコーサーバー）を設定する方法を説明します。また、エコーサーバーにイベントを送信するサンプルAPIプロジェクトを構築する方法も学べます。さらに、環境変数を使用して利用サービスに送信するイベントをどのように変更するかも紹介します。

必要条件

この例を使用するには、Node.js をインストールする必要があります。Node.js インストーラーについては Node.js を参照してください。

エコーサーバーのセットアップ

以下に示すコードを含むファイルを作成してください。

const express = require('express')
const bodyParser = require('body-parser')

const app = express()

// Parse JSON bodies.
app.use(bodyParser.json())
// Accept events.
app.post('/:version/event', (req, res) => {
  const event = req.body
  console.log(event)

  // Respond so the client is happy.
  res.status(200)
  res.send('Event accepted!')
})

// Listen for requests.
app.listen(3000)

ファイルを echo-server.js と呼びます。新しいディレクトリに保存し、そのディレクトリに移動してください。

サーバーはポート3000でリクエストを待ち受け、受信したリクエストの本文をコンソールに書き込みます。つまり、APIクライアントまたはCLIのテストが実行されるたびに（利用ログが有効になっている場合）、エコーサーバーは受信した利用イベントを書き込みます。

上記のコードを実行するのに必要な 2 つの依存関係、express と body-parser をインストールしてください：

npm i express body-parser

エコーサーバーを開始します。

node echo-server.js

テストの作成

例カタログを使用してサンプルテストコードを取得できます。このテストコードを実行すると、前のセクションで作成したエコーサーバーに利用メトリクスデータが送信されます。

次のステップのために新しいターミナルまたはコンソールウィンドウを開いてください。

GitHubでDeque例カタログリポジトリをクローンし、そのディレクトリに移動します：

git clone git@github.com:dequelabs/axe-devtools-html-api-examples.git
cd axe-devtools-html-api-examples

この例では、Node.js Playwrightのコードサンプルを使用しました。そのディレクトリに移動して、必要なNode.jsパッケージをインストールしてください：

cd Node/playwright
npm i

また、Playwrightの依存関係をインストールする必要があるかもしれません：

npx playwright install

必要な環境変数を設定してメトリクス報告を有効にし、サーバーを先に作成したローカルエコーサーバーに設定します：

• export AXE_TRACK_USAGE=true
• export AXE_METRICS_URL=http//localhost:3000

LinuxやmacOSのコマンドラインから環境変数を設定してテストを実行することができます（npm test）：

AXE_TRACK_USAGE=true AXE_METRICS_URL=http://localhost:3000 npm test

set AXE_TRACK_USAGE=true
set AXE_METRICS_URL=http://localhost:3000

setx AXE_TRACK_USAGE true
setx AXE_METRICS_URL http://localhost:3000

稼働中のエコーサーバーを含むターミナルウィンドウには、次のような結果が表示されます：

{
  dateTime: '2023-01-20T17:26:54.371Z',
  productComponent: 'api-node-playwright',
  productName: 'axe-devtools-html',
  version: 'v2',
  event: 'analyze',
  distinctId: '1b8a5e67-eb1f-4637-9668-be3a332d2c41',
  applicationProperties: {
    target: 'https://broken-workshop.dequelabs.com/',
    target_medium: 'text/html',
    engineVersion: '4.5.2',
    failedRuleCount: 2,
    failedRuleNames: 'color-contrast,label',
    failedItemCount: 5,
    inapplicableRuleCount: 39,
    incompleteRuleCount: 2,
    passedRuleCount: 21,
    testResults: {}
  }
}

このオブジェクトのプロパティの詳細は、イベントオブジェクトをご覧ください。

環境変数を用いたイベントの変更

環境変数を使用して、APIやCLIが利用サービスに送信するイベントを変更できます。この例では、イベントの変更方法を示します。

まず、変更したい値の環境変数を設定します。例えば：

export AXE_DEPARTMENT="test department"

これにより、以下の例に示すようにイベントオブジェクトのdepartmentプロパティが変更されます（LinuxやmacOS上で）：

AXE_DEPARTMENT="test department" AXE_TRACK_USAGE=true AXE_METRICS_URL=http://localhost:3000  npm test

エコーサーバーを稼働させているターミナルウィンドウから、次のように強調表示された行でdepartment情報を含むイベントが表示されるはずです：

{
  dateTime: '2023-01-20T17:31:48.422Z',
  productComponent: 'api-node-playwright',
  productName: 'axe-devtools-html',
  version: 'v2',
  event: 'analyze',
  distinctId: '18cd1262-b5b7-4681-9f7a-a7d4c97745c8',
  applicationProperties: {
    target: 'https://broken-workshop.dequelabs.com/',
    target_medium: 'text/html',
    engineVersion: '4.5.2',
    failedRuleCount: 2,
    failedRuleNames: 'color-contrast,label',
    failedItemCount: 5,
    inapplicableRuleCount: 39,
    incompleteRuleCount: 2,
    passedRuleCount: 21,
    testResults: {}
  },
  department: 'test department'}

利用イベントを変更するために使用できる環境変数についての詳細は、環境変数による利用サービスの制御をご覧ください。

次のステップ

CLI用にこのチュートリアルのバージョンを確認するには、利用サービスとCLIの始め方をご覧ください。

利用サービスに関する概要情報は、利用サービスをご覧ください。

イベントオブジェクトのリファレンスについては、利用サービスイベントリファレンスをご覧ください。