Zephyr インテグレーション

mabl の Zephyr インテグレーションを使用すると、mabl のテスト結果の最新の記録を Zephyr に残せるため、リリースレポートやコンプライアンス監査に必要な証跡をそろえられます。主な機能は次のとおりです。

• mabl のプラン実行の結果を Zephyr のテストケースに同期する
• Zephyr のテストケースの要件に基づいて新しい mabl のテストを作成する

この記事では、Zephyr インテグレーションの設定方法、mabl の結果を Zephyr のテストケースに同期する方法、Zephyr のテストケースから mabl のテストを作成する方法を説明します。

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

Zephyr の情報を準備する

mabl でインテグレーションを追加する前に、Zephyr と Jira で次の情報を確認してください。

1. Zephyr が動作している Jira サイトの URL（https://your-site.atlassian.net など）。
2. Zephyr サイトがホストされているリージョン（United States、Europe、Australia、Germany のいずれか）。
3. Zephyr の API トークン（作成手順は後述）。
4. リンクする Zephyr のテストケースが含まれる Jira プロジェクトのキー。たとえば、テストケースが PROJ-T123 の形式であれば、プロジェクトキーは PROJ です。

API トークンを作成するには、次の手順を実行します。

1. Jira で個人設定を開きます。上部のナビゲーションバーにある設定（歯車）アイコンをクリックし、General settings を選択します。
2. 左側のナビゲーションパネルで Zephyr API Access Tokens を選択します。
3. Create access token をクリックし、表示されたキーをすぐにコピーします。トークンは、そのトークンのホスティングリージョンでのみ機能します。

mabl でインテグレーションを追加する

1. mabl アプリで、インテグレーションページ（ワークスペース > インテグレーション）に移動します。
2. mablとインテグレーション セクションで、Zephyr の + セットアップ ボタンをクリックします。
3. インテグレーションに名前を付けます。デフォルトの名前は「Zephyr」です。
4. セットアップ で、Integration enabled をオンのままにします。完了したすべてのプラン実行を mabl が自動的に Zephyr に記録するようにしたい場合は、Automatically sync plan run results をチェックします。この設定は後からオンにすることもできます。詳しくは、自動同期をご覧ください。
5. Jira site URL を入力し、Zephyr region を選択して、API token を入力します。
6. Zephyr project keys に、リンクするテストケースが含まれるプロジェクトのキー（PROJ など）を入力します。複数のキーはカンマで区切ります。mabl は、これらのプロジェクトにのみ結果を記録します。
7. Test connection をクリックします。mabl が Zephyr でトークン、プロジェクト、リージョンを確認し、成功すると、各プロジェクトに共通するステータスを読み込みます。
8. Test cycles で、各プラン実行の結果を mabl が記録する場所を選択します。
   • Create a test cycle for each plan run：同期されるプラン実行ごとに、mabl が新しいテストサイクルを作成します。必要に応じて、各プロジェクトのテストサイクルを作成するフォルダーの ID を入力します。空欄のままにすると、テストサイクルは最上位に作成されます。
   • Add results to an existing test cycle：プロジェクトごとに既存のテストサイクルのキーを入力します。同期されるプラン実行はすべて、そのサイクルにテスト実行を追加します。
9. Execution statuses で、成功（Passed）、失敗（Failed）、スキップ（Skipped）した mabl のテストに対して記録する Zephyr のステータスを選択します。スキップされたテストを記録しない場合は、Don't record skipped tests を選択します。
10. Result details で、各テスト実行に含める内容を選択します。
    • Attach a screenshot to failed executions：失敗したテスト実行の最終的なアプリケーションの状態のスクリーンショットを mabl が添付します。
    • Record the mabl environment：mabl の環境と同じ名前の環境が Zephyr プロジェクトにある場合、mabl はその環境をテスト実行に記録します。
11. 保存 をクリックします。

保存すると、インテグレーションはプロジェクトとリージョンとともに アクティブなインテグレーション セクションに表示されます。

インテグレーションを編集、無効化、削除する

インテグレーションを編集するには、アクティブなインテグレーション セクションで該当するインテグレーションを見つけ、鉛筆アイコンをクリックします。保存済みの API トークンは mabl に再表示されず、フィールドには「API token (saved)」と表示されます。

• その他の設定を変更する場合は、API token フィールドを空欄のままにします。mabl は保存済みのトークンを引き続き使用します。
• トークンを置き換える場合は、新しいトークンを入力して 保存 をクリックします。

インテグレーションを削除せずに一時停止するには、Integration enabled をオフにして 保存 をクリックします。インテグレーションが無効になっている間、mabl は結果を Zephyr に同期しません。

インテグレーションを削除するには、該当する行のごみ箱アイコンをクリックして確認します。結果の同期は停止し、リンクされていたケースキーは テストケースID フィールドにプレーンテキストとしてテストに残ります。インテグレーションを再度追加すると、キーは再びリンクされたケースとして表示され、結果の同期も再開されます。

インテグレーションを再接続する

アクティブなインテグレーション セクションでインテグレーションに Reconnect required ステータスが表示されている場合、保存済みの API トークンが期限切れになったか取り消されたため、Zephyr がそのトークンを拒否しています。この状態では、mabl はそのインテグレーションの結果の同期を停止します。再接続するには、インテグレーションを開き、新しい API token を入力して 保存 をクリックします。

Zephyr のテストケースを mabl のテストにリンクする

mabl のテストと Zephyr のテストケースは、テスト情報ダイアログの Test cases セクションでリンクします。Zephyr のテストケースキーはプロジェクトキーで始まります。たとえば、プロジェクト PROJ のテストケースキーは PROJ-T123 のようになります。プラン実行では、リンクされたケースに対して結果が記録されます。

1. テストの詳細ページで、鉛筆アイコンをクリックしてテスト情報を更新します。
2. Test cases セクションの Add test cases で、Add from から Zephyr プロジェクトを選択します。このセクションは、テストがすでにリンクしているシステムが選択された状態で開きます。
3. プロジェクトのテストケースを名前またはキーで検索し、1 つ選択します。PROJ-T123 のように完全なキーを入力して Enter キーを押すこともできます。
4. 保存 をクリックします。

リンクされた各ケースは、Zephyr のロゴとケース名が付いたチップとして表示されます。名前をクリックすると、Zephyr でケースが開きます。1 つのテストにリンクできるケースは最大 20 件です。上限に近づくと、見出しに Linked (18 of 20) のように使用中の件数が表示されます。

Zephyr に存在しないキーがある場合、mabl はリストの下にその旨を表示し、キーを修正または削除するまで、プラン実行ではそのキーがスキップされます。また、ケースのプロジェクトはインテグレーションの Zephyr project keys に含まれている必要があります。含まれていない場合、プラン実行ではそのリンクが「project not in the integration」（インテグレーションに含まれていないプロジェクト）としてスキップされます。

ケースのリンクを削除するには、テスト情報ダイアログを開き、ケースのチップにある × をクリックして、保存 をクリックします。

テストの詳細ページでは、リンクされた Zephyr のキーが、テストのその他の詳細の横に Zephyr のロゴ付きで表示されます。キーをクリックすると、Zephyr でケースが開きます。

プラン実行の結果を Zephyr に同期する

mabl のプラン実行が同期されると、手動か自動かにかかわらず、mabl はプラン内のテストにリンクされた Zephyr のテストケースごとに、Zephyr にテスト実行を追加します。プラン内のすべてのテストがリンクされている必要はありません。Zephyr のテストケースがリンクされていない mabl のテストは、mabl では通常どおり実行されますが、Zephyr には記録されず、スキップとしても表示されません。

プラン実行のヘッダーにある Zephyr ボタンには、実行の結果が Zephyr に記録されているかどうかが表示されます。同期ステータスを確認したり、結果を同期したりするには、このボタンをクリックします。期待したとおりに同期で記録されなかった場合は、同期が不完全な場合や失敗した場合をご覧ください。

プラン実行を手動で同期する

1. プラン実行の出力ページを開き、Zephyr ボタンをクリックします。
2. Sync to Zephyr をクリックします。
3. 同期中はボタンに「Syncing to Zephyr」と表示され、完了すると結果が表示されます。ポップオーバーの Results went to セクションには、Jira サイト上のテストサイクルへのリンクが表示されます。

自動同期

自動同期をオンにすると、誰かが Sync to Zephyr をクリックしなくても、失敗したプラン実行も含め、完了したすべてのプラン実行が mabl によって Zephyr に記録されます。

1. ワークスペース > インテグレーション に移動し、Zephyr インテグレーションの鉛筆アイコンをクリックします。
2. セットアップ で、Automatically sync plan run results をチェックします。
3. 保存 をクリックします。

以降は、プラン実行が完了すると、mabl が結果を Zephyr に同期します。

• 自動同期をオンにする前に完了したプラン実行は対象外です。これらの実行を記録するには、各実行の結果ページを開いて手動で同期してください。
• 自動同期をオフにするには、インテグレーション設定で Automatically sync plan run results のチェックを外し、保存 をクリックします。すでに同期された実行は Zephyr に残ります。新しい実行には、誰かが手動で同期するまで「not synced」ステータスが表示されます。

mabl が Zephyr に記録する内容

プラン内のテストにリンクされた Zephyr の各テストケースについて、mabl はプラン実行のテストサイクルに 1 件のテスト実行を追加します。

• テスト実行のステータスは、Execution statuses で対応付けたステータスになります。
• 1 つのケースが複数の mabl のテストにリンクされている場合、失敗したテストが 1 つでもあれば、テスト実行は失敗として記録されます。失敗したテストがなく、成功したテストが 1 つでもあれば、成功として記録されます。すべてのテストがスキップされた場合にのみ、スキップとして記録されます。
• テスト実行には、実行の終了日時と所要時間が記録されます。
• テスト実行のコメントは「Result reported by mabl」で始まり、対象の各 mabl のテストが、そのステータスと実行へのリンクとともに記載されます。
• スクリーンショットをオンにしている場合、失敗したテスト実行には、失敗したテスト実行の最終的なアプリケーションの状態が添付されます。
• Record the mabl environment をオンにしていて名前が一致する場合、テスト実行には Zephyr の環境が記録されます。
• 記録された各テストケースには、結果の元になった各 mabl のテストへの Web リンクが mabl test: <test name> という名前で追加されるため、Zephyr から mabl のテストを開けます。誰かがこのリンクを削除しても、次回の同期で再び追加されます。

Create a test cycle for each plan run を選択している場合、mabl はプランの名前と実行日時を付けた新しいテストサイクルを、設定したフォルダーに作成し、mabl のプラン実行へのリンクを追加します。

Sync again は、このプラン実行のテスト実行がまだないケースだけを記録するため、2 回同期してもテスト実行が重複することはありません。テストで修正したケースキーは、次のプラン実行で反映されます。

同期されないもの

• 単一テストのアドホック実行。Zephyr に記録されるのはプラン実行のみです。
• キャンセルまたは停止されたプラン実行。
• プラン内で無効になっているテスト、または Zephyr のテストケースがリンクされていないテスト。Zephyr にテスト実行は作成されず、スキップとしても表示されません。
• 他のテストケース管理システムの ID。それらは該当するシステムのために保持されます。

同期が不完全な場合や失敗した場合

Zephyr ボタンに次の 3 つのステータスのいずれかが表示されている場合、その実行には対応が必要です。

• Zephyr — N links skipped：実行は同期されましたが、一部のケースリンクを記録できませんでした。ボタンをクリックし、ポップオーバーの Skipped セクションを確認してください。詳しくは、スキップされたケースリンクをご覧ください。
• Zephyr sync failed：同期が完了する前に停止しました。ポップオーバーには、停止する前に記録されたケースの数が表示されます。Sync again をクリックしてください。同じように失敗する場合は、インテグレーションの設定を確認してください。
• Zephyr sync status unavailable：この実行が同期されたかどうかを mabl が確認できませんでした。ページを再読み込みするか、実行を同期してください。

プランの実行履歴と プラン ページにも同じ状態が Sync incomplete または Sync failed として表示されるため、実行を開かなくても対応が必要な実行を見つけられます。

スキップされたケースリンク

ケースリンクを記録できなかった場合、ポップオーバーには次のいずれかの理由とともにそのリンクが表示されます。

Sync again が役立つのは、原因が Zephyr 側にあった場合のみです。テストで修正したケースキーは、次のプラン実行で反映されます。

Zephyr のテストケースからテストを作成する

テストで何をすべきかが Zephyr のテストケースにすでに記述されている場合は、新しいテストを作成する際に、そのテストケースを mabl エージェントに渡すことができます。ワークスペースに有効な Zephyr インテグレーションがある場合、テスト作成 ページのプロンプトの下にある + メニューに Zephyr テストケース オプションが表示されます。

1. テスト作成 に移動し、新規テスト タブまたは テストを編集 タブで、プロンプトの下にある + をクリックして Zephyr テストケース を選択します。
2. インテグレーションが複数のプロジェクトを対象にしている場合は、プロジェクト を選択します。
3. テストケースの名前またはキーでリストを絞り込み、使用するケースを選択します。最大 5 件のテストケースを追加できます。
4. テストデータや開始状態など、テストケースに含まれていない内容を記述して、プロンプトを送信します。

エージェントは各テストケースの目的、前提条件、ステップを読み取り、テストのアウトラインの仕様として使用します。別のテストケースを呼び出すステップも読み取ります。テストケースを完全に読み取れなかった場合は、アウトラインにどのテストケースかが示されます。

リストには、プロジェクトの最初の 5,000 件のテストケースが表示されます。それ以外のテストケースを見つけるには、PROJ-T123 のように正確なキーを入力してください。

自動リンク

1 つの Zephyr テストケースだけから新しいテストを作成した場合、エージェントがテストを保存する際に mabl がそのテストをケースにリンクするため、以降のプラン実行ではそのケースに対して結果が記録されます。複数のテストケースを参照して新しい mabl のテストを作成した場合は、Test cases セクションで自分でリンクを追加する必要があります。