レビューの自動テスト

Helix Swarmをテストスイートに統合するには、プロジェクトの設定で[自動テスト]を有効にし、トリガのURLを指定する必要があります。 トリガのURLが要求されると、Swarmではテストスイートが実行されます。 テストが完了すると、Swarmは、updateパラメータで指定されたコールバックURL、passパラメータで指定されたコールバックURL、またはfailパラメータで指定されたコールバックURL がテストスイートによって要求されるのを待機します。

1. [プロジェクト]ページに移動します。
2. プロジェクトの[設定]タブをクリックして、[プロジェクトの設定]ページを表示します。
3. プロジェクトに構成された指定の各ブランチは、その他の指定ブランチのパスと重複しないようにしてください。

4. [自動テスト]チェックボックスで[有効]を選択して、設定フィールドを表示します。

   

5. テストスイートの実行をトリガするURLを指定します。

   以下に示す特殊な引数を使用して、Swarmのさまざまな情報をテストスイートに渡すことができます。 Swarmはテストを呼び出す際に、これらの引数を、関連するSwarm情報で置き換えます。

   注意

   Jenkins向けHelixプラグイン 1.10.11以降の場合: POST要求として、ビルド用のパラメータをSwarmからJenkinsに送信する必要があります。 これを行うには、[POST本文]でパラメータを入力して[URLエンコード]を選択します。

   {test}

   テスト名を指定します。

   {testRunId}

   テスト実行のIDを指定します。

   {change}

   変更番号を指定します。

   {status}

   変更のステータスとして、shelvedまたはsubmitted を指定します。

   {review}

   レビュー担当者のIDを指定します。

   {version}

   レビューのバージョンを指定します。

   {description}

   テストがトリガされた原因となった変更の説明を指定します。 {description}をURLに含めることはできません。{description}を使用できるのは、[POST本文]内だけです。

   {project}

   プロジェクトのIDを指定します。

   {projectName}

   プロジェクトの名前を指定します。

   {branch}

   レビューの影響を受けるブランチのIDを指定します。複数のIDを指定する場合は、各IDをコンマで区切ります。

   {branchName}

   レビューの影響を受けるブランチの名前を指定します。複数のブランチ名を指定する場合は、各ブランチ名をコンマで区切ります。

   {update}

   更新処理用のコールバックURLを指定します。 更新処理用のコールバックURLを呼び出してテスト実行を更新する際に、テストステータス、メッセージ、URLのいずれかを(またはこれらすべてを)、該当するCIシステムにリンクするPOSTリクエストの本文内に含めることができます。 これらのメッセージは、POSTリクエストの本文内でJSON形式になっている必要があります。 テストステータスの有効な値は、running、pass、failです。 最大10件のメッセージを渡すことができます。10件を超えるメッセージを指定した場合は、最初に指定した10件のメッセージだけが保存されます。 各メッセージには、最大80文字を含めることができます。80文字を超えるメッセージは自動的に切り捨てられます。 {update}は、Swarm 2019.3の推奨オプションです。 詳細については、以下の「注」を参照してください。

   {pass}

   テストに合格したコールバックURLです。 Swarm 2019.3以降では、{update}を使用することをお勧めします。 詳細については、以下の「注」を参照してください。

   {fail}

   テストに失敗したコールバックURLです。 Swarm 2019.3以降では、{update}を使用することをお勧めします。 詳細については、以下の「注」を参照してください。

   注意

   • Swarm 2019.3以降の場合も、{pass}と{fail}は引き続きサポートされていますが、{update}を使用することをお勧めします。{update}を使用すると、テストステータスにメッセージを含めることができます。
   • {update}、{pass}、{fail}は、Swarmによって自動的に設定されます。 これらのパラメータには、Swarmの専用レビュー認証トークンが挿入されます。

6. 任意: HTTP POST経由で送信する必要がある自動テストの必須パラメータを[POST本文]フィールドで指定します。 POSTパラメータには、上記の特殊引数を含めることができます。

   POSTパラメータの形式として、[URLエンコード]または[JSONエンコード]を選択します。

   • [URLエンコード]を選択すると、POSTパラメータが「名前と値」のペアとして解析されます。
   • [JSONエンコード]を選択すると、指定したパラメータがそのままの状態でPOST本文に渡されます。

JenkinsをSwarm統合環境用に設定する

1. Jenkins用のp4プラグインをインストールします。

   p4プラグインのインストール方法については、『Jenkins向けHelixプラグインガイド』の「インストール」章を参照してください。

2. Jenkinsプロジェクトを設定します。

   注意

   Jenkins向けHelixプラグイン 1.10.11以降の場合: POST要求として、ビルド用のパラメータをSwarmからJenkinsに送信する必要があります。 これを行うには、[POST本文]でパラメータを入力して[URLエンコード]を選択します。

   1. 以下で定義されるように、ジョブ名がトリガURLで使用されているプロジェクトIDと一致するように指定します。

      例えば、{projectName}_{branchName}の算出された値にします。

      または、トリガURLを編集して、指定したJenkinsのジョブ名を使用します。

   2. ビルドをパラメータ化して、これらのパラメータを受け入れます(これらの名前は、呼び出しされたスクリプトと一致するものにしてください)。

      {test}

      テスト名を指定します。

      {testRunId}

      テスト実行のIDを指定します。

      {status}

      テストするチェンジリストの状態として、shelved またはsubmitted を指定します。

      {change}

      テストするチェンジリストの番号を指定します。

      {review}

      レビュー担当者のIDを指定します。

      {version}

      レビューのバージョンを指定します。

      {update}

      テスト実行を更新するためのPOSTに対するURLを指定します。 テストステータスをレポートする場合は、更新処理用のコールバックURLを呼び出してテスト実行を更新する際に、テストステータス、メッセージ、URLのいずれかを(またはこれらすべてを)、該当するCIシステムにリンクするPOSTリクエストの本文内に含めることができます。 これらのメッセージは、POSTリクエストの本文内でJSON形式になっている必要があります。 テストステータスの有効な値は、running、pass、failです。 最大10件のメッセージを渡すことができます。10件を超えるメッセージを指定した場合は、最初に指定した10件のメッセージだけが保存されます。 各メッセージには、最大80文字を含めることができます。80文字を超えるメッセージは自動的に切り捨てられます。 {update}を使用することをお勧めします。

      重要

      テストシステムからSwarmに対してPOSTパラメータを渡すことができない場合は、updateパラメータを使用することはできません。代わりに、passパラメータとfailパラメータを使用する必要があります。

      {pass}

      ビルドが成功した場合のwgetのURLを指定します。 Swarm 2019.3以降では、{update}を使用することをお勧めします。 詳細については、以下の「注」を参照してください。

      {fail}

      ビルドが失敗した場合のwgetのURLを指定します。 Swarm 2019.3以降では、{update}を使用することをお勧めします。 詳細については、以下の「注」を参照してください。

      ヒント

      Swarm 2019.3以降の場合も、{pass}と{fail}は引き続きサポートされていますが、{update}を使用することをお勧めします。{update}を使用すると、テストステータスにメッセージを含めることができます。

   3. [ソースコード管理]セクションでPerforceソフトウェアを選択します。

      重要

      [ソースコード管理]セクションにPerforceが表示される場合があります。 これは、以前のコミュニティに付属していた、Swarmのサポートが含まれていないPerforceプラグインです。

   4. 必要に応じて、資格情報やワークスペースの動作を設定します。

      資格情報とワークスペースの設定方法については、『Jenkins向けHelixプラグインガイド』の「資格情報」セクションと「ワークスペースの動作」セクションを参照してください。

      重要

      • HelixサーバがMulti-Factor Authentication (MFA)用に構成されている場合、自動テスト用のサービスユーザの資格情報でMFAを使用しないでください。
      • Jenkinsで設定されているクライアントワークスペースには、Swarmのブランチ用に定義されたパスを持つビューが存在している必要があります。

3. 以下のようなURLとパラメータを使用して自動テストを実行するようにSwarmプロジェクトを設定します。

   

   重要

   Jenkinsでは、ジョブ名をURLのジョブIDと一致させる必要があります。 上記の例では、これは{projectName}_{branchName}の算出された値になります。

   Jenkinsで別の命名方法を使用する場合は、上記URLの{projectName}_{branchName}を、実際にJenkinsで定義されたプロジェクト名で置き換えます。

   注意

   • {update}を使用する場合の注意点:
     • ビルドスクリプトからテストの実行に関するメッセージにアクセスできる場合は、{update}で指定したURLを使用して、そのメッセージをSwarmに渡すことができます。 Swarmは、渡されたメッセージをテストの結果に追加します。 最大10件のメッセージを渡すことができます。10件を超えるメッセージを指定した場合は、最初に指定した10件のメッセージだけが保存されます。 各メッセージには、最大80文字を含めることができます。80文字を超えるメッセージは自動的に切り捨てられます。
     • ビルドスクリプトからテストの実行結果にアクセスできる場合は、{update}で指定したURLを呼び出す際に、urlというPOSTパラメータを指定してください。 Swarmは、指定されたURLを使用して、レビューをテストの結果にリンクします。 テストステータスの値は、running、pass、failです。
     • {update}で指定したコールバックURLでは、JSON本文が許可されます。JSON本文で、メッセージ、URL、またはステータスを指定することができます(あるいは、これらすべてを指定することもできます)。

     { "messages" : ["My First Message", "My Second Message"], "url" : "http://jenkins_host:8080/link_to_run", "status": "pass" } 

   • {pass} と {fail} を使用する場合: ビルドスクリプトからテストの実行結果にアクセスできる場合は、{pass}または{fail}で指定したURLを呼び出す際に、urlというGETパラメータまたはPOSTパラメータを指定してください。 Swarmは、指定されたURLを使用して、レビューをテストの結果にリンクします。
   重要

   Jenkinsでセキュリティが有効な場合、トリガURLには資格情報が含まれている必要があります。 以下の手順を実行します。

   1. SwarmのビルドをトリガするJenkinsユーザを作成します。 例えば、「swarm」などのユーザを作成します。
   2. Jenkinsに新規ユーザとしてログインします。
   3. Jenkinsツールバーにあるユーザ名をクリックします。
   4. [APIトークン]が表示されるまで、下方向にスクロールします。
   5. [APIトークンを表示]をクリックします。

   6. [APIトークン]の値をSwarmトリガのURLに挿入します。

      例えば、ユーザ名が「swarm」でAPIトークンの値が「832a5db7e5500c1288324c1441460610」である場合、SwarmトリガのURLとパラメータは以下のようになります。