Azure Boards インテグレーション

Azure Boards インテグレーションを使用すると、失敗した mabl のテスト実行から新しい作業項目を作成したり、テストを既存の作業項目にリンクしたり、既存の作業項目を使って新しい mabl テストを作成したりできます。この記事では、mabl を Azure Boards に接続する方法、mabl が作成する作業項目を設定する方法、そしてインテグレーションを日々の作業で使う方法を説明します。

• インテグレーションを設定する
• 作業項目を作成・リンクする
• 作業項目からテストを作成する
• 接続が機能しなくなったとき

インテグレーションを設定する

はじめる前に

Azure Boards を接続するには、次のものが必要です。

• https://dev.azure.com/{organization} でホストされ、Microsoft Entra ID に接続された Azure DevOps 組織。ユーザーは職場アカウントでサインインします。オンプレミス製品の Azure DevOps Server はサポートされていません。また、個人用 Microsoft アカウントのみを使用する組織では動作しないと想定しています。
• 使用する Azure DevOps プロジェクトに通常のアクセス権を持つ Microsoft アカウント。作業項目の作成には、Basic アクセスと Contributor ロールがあれば十分です。mabl はこのアカウントの代理として動作するため、mabl が作成する作業項目の作成者にはこのアカウントが表示されます。
• 組織の Microsoft Entra 設定によっては、誰かが接続する前に管理者が mabl を承認する必要があります。詳しくは、管理者に mabl の承認を依頼するをご覧ください。

Azure DevOps を接続する

1. mabl アプリで、設定 > インテグレーション に移動します。
2. mablとインテグレーション セクションで Azure Boards を見つけ、Connect（接続）をクリックします。
3. Microsoft アカウントでサインインし、mabl が要求する権限を確認します。mabl が要求するのは、作業項目の読み取りと書き込み、テスト管理の読み取りと書き込み（今後の Azure Test Plans への結果同期で使用）、プロジェクトとチームの読み取り、ビルドの読み取りです。組織へのフルアクセスは要求しません。アクセスは維持されるため、再度サインインする必要はありません。
4. 承諾 をクリックします。Microsoft から mabl に戻り、新しいインテグレーションの設定フォームが表示されます。

Microsoft がサインインを拒否した場合、mabl は Microsoft からの理由を表示します。最も多い理由は、組織が管理者の承認を必要としていることです。

管理者に mabl の承認を依頼する

mabl は検証済みの発行元であり、要求する権限は一般ユーザーが承認できるものです。自分で承認できるかどうかは、組織の Microsoft Entra ポリシーによって決まります。ユーザーによるアプリケーションの承認を許可している組織では、初めて接続するときに mabl を承認すれば、そのまま設定フォームに進めます。

多くの組織では、ユーザーによるアプリケーションの承認を許可していません。接続時に「管理者の承認が必要」というページが表示された場合、mabl は Ask your administrator to approve mabl（管理者に mabl の承認を依頼する）というページに、そのまま送れる承認リンクを表示します。

1. Copy approval link（承認リンクをコピー）をクリックし、組織の Microsoft Entra 管理者にリンクを送ります。
2. 管理者がリンクを開いてサインインし、mabl を承認します。管理者に mabl のアカウントは必要ありません。承認が完了すると、mabl が承認されたことを示す確認画面が表示されます。
3. 設定 > インテグレーション に戻り、再度 Connect をクリックします。今回はサインインが完了し、設定フォームが表示されます。

承認は組織全体に適用されるため、Azure Boards を接続するすべての mabl ワークスペースに対して 1 回の承認で十分です。

インテグレーションを設定する

サインイン後、mabl アプリの設定フォームで、インテグレーションが使用するプロジェクトを指定します。

1. インテグレーションに名前を付けます。デフォルトの名前は「Azure Boards」です。
2. Organization URL（組織 URL）に https://dev.azure.com/{organization} の形式で入力します。プロジェクトやボードの URL を貼り付けた場合、mabl は組織の URL に変換します。
3. Project（プロジェクト）を選択します。一覧には、Microsoft アカウントから参照できるプロジェクトが表示されます。1 つのインテグレーションは 1 つのプロジェクトに接続します。別のプロジェクトや別の組織に作業項目を登録する場合は、インテグレーションを追加してください。
4. Default work item type（デフォルトの作業項目の種類）を選択します。mabl は、プロセスでの名称にかかわらず、プロジェクトのバグの種類を提案します。Basic プロセスのプロジェクトには Bug がないため、mabl は Issue を提案します。新しい作業項目はこの種類で開きますが、作成のたびに別の種類を選ぶこともできます。
5. Work item fields（作業項目のフィールド）で、作業項目の種類ごとに新規イシューフォームに表示するフィールドを確認します。詳しくは、フィールドとデフォルト値を選択するをご覧ください。
6. 保存 をクリックします。

保存すると、インテグレーションが アクティブなインテグレーション セクションに表示されます。複数の Azure DevOps プロジェクトに接続する場合は、作業項目を登録するプロジェクトごとにインテグレーションを追加してください。

フィールドとデフォルト値を選択する

Azure の作業項目の種類には数十のフィールドがあり、そのほとんどはバグを登録する人が気にする必要のないものです。設定フォームの Work item fields では、作業項目の種類ごとに、新規イシューフォームに表示するフィールドと、その初期値を決めます。State、Reason、監査用のタイムスタンプなど、Azure DevOps が自動的に管理するフィールドは、mabl があらかじめ除外しています。

1. Work item type（作業項目の種類）を選択します。テーブルには、その種類で mabl が設定できるすべてのフィールドが表示されます。必須フィールドには Required（必須）バッジが付きます。
2. 新規イシューフォームからフィールドを除くには、Shown（表示）トグルをオフにします。必須フィールドは、デフォルト値がある場合にのみ非表示にできます。デフォルト値がないと、Azure DevOps が作業項目を受け付けないためです。
3. フィールドをあらかじめ入力しておくには、Default value（デフォルト値）を入力します。Priority のように値が固定されているフィールドでは、一覧から選択します。Area Path と Iteration Path では、入力を始めるとプロジェクトのパスから選択できます。デフォルト値のあるフィールドはフォーム上で必須ではなくなり、デフォルト値があって選択肢が 1 つしかないフィールドは、選ぶものがないため非表示になります。
4. すべてのカスタムフィールドを一度に除くには、Hide all custom fields（すべてのカスタムフィールドを非表示）をクリックします。デフォルト値のない必須カスタムフィールドは表示されたままです。
5. チームが mabl から登録する作業項目の種類ごとに繰り返し、保存 をクリックします。

新しいインテグレーションでは、デフォルトの作業項目の種類の Tags に mabl というデフォルト値が設定されているため、mabl から登録した作業項目を Azure Boards で見つけやすくなります。このタグが不要な場合は、保存する前にデフォルト値を削除してください。

mabl はフォームを開くたびに、これらの設定を Azure DevOps のプロセスと照合します。そのため、Azure DevOps 側の変更によってフォームが気づかないうちに壊れることはありません。

• 非表示にしたフィールドが Azure DevOps で必須になり、デフォルト値がない場合、フォームにそのフィールドが再び表示されます。
• 選択リストから削除された値など、デフォルト値が無効になった場合、mabl はデフォルト値を削除してフィールドを表示します。
• Azure DevOps に存在しなくなった種類、フィールド、値の設定は、保存時に削除されるものとして設定フォームに一覧表示されます。

インテグレーションを編集・再接続・削除する

インテグレーションを編集するには、アクティブなインテグレーション セクションでインテグレーションを見つけ、鉛筆アイコンをクリックします。プロジェクトを変更すると、フィールドの設定はクリアされます。設定は以前のプロジェクトのプロセスに属するものだからです。Microsoft に再度サインインするには、Reconnect（再接続）をクリックします。詳しくは、接続が機能しなくなったときをご覧ください。

インテグレーションを削除するには、その行のゴミ箱アイコンをクリックして確認します。テストにリンクされたイシューはそのまま残りますが、mabl から作業項目を登録・リンクしたり、作業項目からテストを作成したりすることはできなくなります。Azure Boards 側は何も変わりません。

作業項目を作成・リンクする

mabl アプリの次の場所から、作業項目を作成・リンクできます。

• 失敗したテスト実行から: テスト出力ページで、失敗分析の下、または失敗したステップの イシューを作成 をクリックします。
• テストから: テストの詳細ページで Issue タブを開き、+ 新規イシュー をクリックします。
• イシューページから: 左側のナビゲーションで テスト をクリックし、Issue タブを開いて + 新規イシュー をクリックします。

失敗した実行から作業項目を作成する

新規イシュー フォームで、次の情報を入力します。

1. イシュー管理 ドロップダウンで、Azure Boards インテグレーションを選択します。
2. 「新規作成」を選択します。
3. プロジェクト と Work item type（作業項目の種類）を選択します。一覧にはプロジェクトのプロセスにあるすべての種類が含まれるため、長くなることがあります。インテグレーションのデフォルトの種類が先頭に表示されます。
4. 次 をクリックします。その種類で表示するように設定したフィールドが、デフォルト値が入力された状態で表示されます。失敗した実行から作成する作業項目では、mabl がタイトルに失敗分析のタイトルを、説明に失敗分析の残りの内容をあらかじめ入力します。どちらも編集できます。
5. その他のフィールドを入力し、送信 をクリックします。

画面の下部に成功メッセージが表示されます。リンクをクリックすると、Azure Boards の作業項目が新しいタブで開きます。

失敗したテストに対して使用する種類は、ほとんどの場合 Bug か、Bug のない Basic プロセスでは Issue です。mabl はプロジェクトのバグの種類をあらかじめ選択しており、管理者はインテグレーションでデフォルトを変更できます。修正を Task として登録するチームもあります。種類の一覧を絞り込むことはできませんが、管理者はフィールドの設定で種類ごとのフォームを調整できます。

作成された作業項目に含まれる内容

失敗した実行から作成された作業項目には、開発者が問題に着手するために必要なものがすべて含まれます。

• タイトル: 失敗分析のタイトル、またはフォームで変更した内容。
• 説明: 失敗分析の残りの内容、実行終了時のページのスクリーンショット、そして View the failed test run in mabl（mabl で失敗したテスト実行を表示）と Open the test in mabl（mabl でテストを開く）の 2 つのリンクを含むフッター。説明は markdown で記述されます。
• 添付ファイル: 失敗した実行の最終状態のスクリーンショット、DOM スナップショット、HAR ファイル、Chrome トレース。
• リンク: 作業項目の他のリンクと並んで表示される、mabl のテスト実行と mabl のテストへのハイパーリンク。

添付ファイルはベストエフォートで追加されます。25 MB を超えるファイルはスキップされ、アップロードできないファイルがあっても、作業項目はそのファイルなしで作成されます。

既存の作業項目にリンクする

mabl のテストまたはテスト実行を既存の作業項目にリンクするには、新規イシュー フォームを開いて次の手順を行います。

1. イシュー管理 ドロップダウンで、Azure Boards インテグレーションを選択します。
2. 「既存のリンク」を選択します。
3. プロジェクト を選択します。
4. 関連付けられるイシュー で、作業項目をタイトルで検索するか、ID を入力します。
5. 送信 をクリックします。

画面の下部に成功メッセージが表示され、テストの Issue タブに作業項目が表示されます。

mabl で作業項目を管理する

リンクされたすべての作業項目は、イシューページ（テスト > Issue）または特定のテストの Issue タブで確認できます。作業項目のリンクをクリックして Azure Boards で開いたり、mabl のテストを再実行して問題を再現したり修正を検証したりできます。

mabl は作業項目を「Open」または「Closed」のいずれかで表示します。mabl は約 10 分ごとに、リンクされた各作業項目を確認します。Azure Boards で作業項目をクローズ、再オープン、削除、復元すると、次回の確認時に mabl のイシューが更新されます。

テストから作業項目を削除するには、テストの詳細ページで Issue タブを開き、削除するイシューを選択して Unlink をクリックし、確認します。作業項目自体は Azure Boards に残ります。

作業項目からテストを作成する

テストしたい動作が作業項目にすでに記述されている場合は、新しいテストを作成するときや既存のテストを編集するときに、その作業項目を mabl エージェントに渡すことができます。受け入れ基準のあるユーザーストーリー、プロダクトバックログ項目、要件のほか、再現手順のあるバグや Azure Test Plans のテストケースが適しています。ワークスペースに有効な Azure Boards インテグレーションがある場合、テスト作成 ページのプロンプトの下にある + メニューに Azure Boards work item オプションが表示されます。

1. テスト作成 に移動し、新規テスト タブまたは テストを編集 タブで、プロンプトの下にある + をクリックして Azure Boards work item を選択します。
2. ワークスペースに複数の Azure Boards インテグレーションがある場合は、検索するインテグレーションを選択します。
3. タイトルで検索するか、123 や AB#123 のような作業項目 ID を入力するか、作業項目の URL を貼り付けます。選択した各作業項目はチップとして表示されます。最大 5 件まで追加できます。
4. テストデータや開始状態など、作業項目に含まれていない内容を記述して、プロンプトを送信します。

エージェントは、その種類の作業項目で動作を記述しているフィールドを読み取ります。ユーザーストーリーではタイトル、説明、受け入れ基準を、バグでは再現手順を、テストケースでは共有ステップを含むステップと期待される結果を読み取ります。コメント、履歴、添付ファイル、カスタムフィールドは読み取りません。会話の中では、エージェントは作業項目を AB#123 の形式の ID で参照します。

接続が機能しなくなったとき

インテグレーションの背後にある Microsoft との接続は、機能しなくなることがあります。約 90 日間使用されなかった場合、接続したアカウントのパスワードがリセットされた場合、または管理者が mabl のアクセスを取り消した場合、Microsoft は接続を失効させます。その状態で作業項目を作成しようとすると、インテグレーションの再接続を求めるメッセージとともに失敗します。

再接続するには:

1. 設定 > インテグレーション に移動し、Azure Boards インテグレーションの鉛筆アイコンをクリックします。
2. Reconnect をクリックし、Microsoft アカウントでサインインします。このアカウントはインテグレーションのプロジェクトを参照できる必要がありますが、最初に接続したアカウントである必要はありません。
3. フォームに戻ると、「Signed in to Azure DevOps again」というメッセージが新しい接続を確認します。保存 をクリックします。

再接続しても、インテグレーションの作業項目とフィールドの設定はそのまま維持されます。置き換わるのはサインインだけです。