Maestroを使った開始手順

Axe DevTools Mobile for Maestroは、Axe DevTools for Mobile SDKに基づいて、Maestroに組み込みのアクセシビリティスキャン機能を提供します。これを使用してUIテストフローを実行すると、axeStartScanSessionとaxeScanの2つのコマンドで、YAML内で直接自動アクセシビリティチェックを簡単に呼び出すことができます。

必要条件

• macOSまたはLinux — インストーラーにはUnixシェルが必要です。
  • macOS：AndroidエミュレーターとiOSシミュレーターの両方をサポート
  • Linux：Androidエミュレーターのみサポート（iOSシミュレーターはmacOS専用）
• Java 17+ — java -versionで確認してください
• curlとunzip — macOSおよびほとんどのLinuxディストリビューションに事前にインストールされています
• AndroidエミュレーターまたはiOSシミュレーターにアプリをインストール
• Axe DevTools Mobile APIキー
• Axe Developer HubプロジェクトID

(注：Windowsのサポートは近日中に提供予定です。)

インストール

1. 以前にHomebrewを使用して公開Maestroをインストールした場合、PATHの競合を避けるためにまずアンインストールしてください:

   brew uninstall maestro

2. DequeのプライベートArtifactoryからのアイデンティティトークンが必要です。持っていない場合は、DequeのプライベートArtifactoryを使った開始手順の手順に従ってください。

   DQ_AGORA_IDENTITY_TOKENが環境で設定されていることを確認し、次のコマンドをmacOSまたはLinuxで実行してください:

   curl -fsSL -H "Authorization: Bearer $DQ_AGORA_IDENTITY_TOKEN" \
   "https://agora.dequecloud.com/artifactory/axe-devtools-mobile-maestro/install.sh" | bash

   特定のバージョンをインストールするには、以下をbashコマンドに含めてください:

   curl -fsSL -H "Authorization: Bearer $DQ_AGORA_IDENTITY_TOKEN" \
   "https://agora.dequecloud.com/artifactory/axe-devtools-mobile-maestro/install.sh" | MAESTRO_VERSION=1.1.0 bash

3. 新しい端末を開き、maestro --versionがAxe DevToolsのバージョンを表示することを確認してください。

   maestro --version

クイックスタート

1. フローファイルを作成します。

   accessibility-check.yamlという名前のファイルを作成し、以下のコードスニペットを追加してください:

   appId: com.example.myapp
   ---
   - launchApp
   - axeStartScanSession:
       apiKey: "YOUR_API_KEY"
       projectId: "YOUR_PROJECT_ID"
   - axeScan

   com.example.myappをアプリのパッケージ名（Android）またはバンドルID（iOS）に置き換え、Axe DevTools Mobile APIキーとAxe Developer HubからのプロジェクトIDを入力してください。

2. フローを実行します。

   iOSの場合：

   maestro test --device <DEVICE_ID> accessibility-check.yaml

   Androidの場合：

   maestro test --device <DEVICE_ID> accessibility-check.yaml

   作成したフローファイルを参照して、Maestroがアプリを起動し、Axe DevToolsスキャンセッションを初期化し、現在の画面でアクセシビリティスキャンを実行します。結果は自動的にAxe Developer Hubにアップロードされます。

   note

   「DEVICE_ID」は、テストを実行するマシン用のMaestroが使用するユニークな識別子です。デバイスIDの探し方については、Maestroのドキュメントをご確認ください。

環境変数を使って認証情報を管理

YAMLファイルにAPIキーをハードコーディングすることは推奨されません。代わりに環境変数を使ってMaestroの変数補完を利用してください。

注意： Maestroは、MAESTRO_で始まるシェル環境変数のみを自動的に注入します。YAMLフローで使用したい変数にはMAESTRO_プレフィックスを使用してください。

次をシェルプロファイルに追加します（例：~/.zshrcまたは~/.bashrc）：

export MAESTRO_AXE_API_KEY="YOUR_API_KEY"
export MAESTRO_AXE_PROJECT_ID="YOUR_PROJECT_ID"

その後、これらをYAMLで参照してください：

appId: com.example.myapp
---
- launchApp
- axeStartScanSession:
    apiKey: ${MAESTRO_AXE_API_KEY}
    projectId: ${MAESTRO_AXE_PROJECT_ID}
- axeScan

または、これらの環境変数を実行時にインラインで渡すこともできます：

iOSの場合：

MAESTRO_AXE_API_KEY=your-key MAESTRO_AXE_PROJECT_ID=your-project maestro test --device <DEVICE_ID> accessibility-check.yaml

Androidの場合：

MAESTRO_AXE_API_KEY=your-key MAESTRO_AXE_PROJECT_ID=your-project maestro test --device <DEVICE_ID> accessibility-check.yaml

コマンドリファレンス

axeStartScanSession

必要な認証情報を提供してaxeStartScanSessionのAxe DevToolsスキャンセッションを初期化します。フロー内の最初のaxeScanの前に一度呼び出してください。

- axeStartScanSession:
    apiKey: ${MAESTRO_AXE_API_KEY}
    projectId: ${MAESTRO_AXE_PROJECT_ID}
    axeAccountUrl: "https://..."

axeScan

axeScanを使用して、現在の画面にアクセシビリティスキャンを実行します。フロー内で以前にaxeStartScanSessionが呼び出された場合、結果はAxe Developer Hubにアップロードされます。

# Simple form (all defaults):
- axeScan

例

単一画面をスキャンする

appId: com.example.myapp
---
- launchApp
- axeStartScanSession:
    apiKey: ${MAESTRO_AXE_API_KEY}
    projectId: ${MAESTRO_AXE_PROJECT_ID}
- axeScan

一つのフローで複数の画面をスキャンする

appId: com.example.myapp
---
- launchApp
- axeStartScanSession:
    apiKey: ${MAESTRO_AXE_API_KEY}
    projectId: ${MAESTRO_AXE_PROJECT_ID}

# Scan the home screen
- axeScan

# Navigate and scan the settings screen
- tapOn: "Settings"
- axeScan

# Navigate and scan the profile screen
- tapOn: "Profile"
- axeScan

カスタムAxeアカウントURLでスキャンする

オンプレミスまたはプライベートクラウドのAxe DevToolsの導入には、axeAccountURLが必要です：

appId: com.example.myapp
---
- launchApp
- axeStartScanSession:
    apiKey: ${MAESTRO_AXE_API_KEY}
    projectId: ${MAESTRO_AXE_PROJECT_ID}
    axeAccountUrl: "https://axe.YOUR_COMPANY.com"
- axeScan

非ブロッキングアクセシビリティスキャン

optional: trueとaxeScanを組み合わせてスキャンを実行し、エラーが発生しても全体のフローを失敗させないようにします：

appId: com.example.myapp
---
- launchApp
- axeStartScanSession:
    apiKey: ${MAESTRO_AXE_API_KEY}
    projectId: ${MAESTRO_AXE_PROJECT_ID}
    optional: true
- axeScan:
    optional: true

# The flow continues regardless of scan results
- tapOn: "Continue"

アクセシビリティスキャンとUIテストを組み合わせる

appId: com.example.myapp
---
- launchApp
- axeStartScanSession:
    apiKey: ${MAESTRO_AXE_API_KEY}
    projectId: ${MAESTRO_AXE_PROJECT_ID}

# Test login flow and scan each screen
- assertVisible: "Welcome"
- axeScan:
    label: "Login screen"

- tapOn: "Email"
- inputText: "user@example.com"
- tapOn: "Password"
- inputText: "password123"
- tapOn: "Sign In"

- assertVisible: "Dashboard"
- axeScan:
    label: "Dashboard after login"

結果の閲覧

スキャンが完了した後、結果はAxe Developer Hubで利用可能です。ここは、アプリ内で発見されたアクセシビリティ問題をチーム全体で閲覧し管理できる中央の場所です。Developer Hubの問題は、深刻度やWCAGガイドライン別に分類されており、チームが修正の優先順位を付けることができます。

トラブルシューティング

問題が発生した場合は、次の方法を試してください。

• 「コマンドが見つかりません：maestro」

  インストール後に新しいターミナルを開くか、以下を実行してください：

  export PATH="$HOME/.maestro/bin:$PATH"

• Javaバージョンエラー

  Axe DevTools Mobile MaestroにはJava 17以上が必要です。Javaのバージョンを確認してください：

  java -version

  バージョンが17未満の場合は、新しいJDKをインストールしてください（例：Adoptiumを使用）。