レビューの自動テスト
Swarm 2020.1以降では、Swarmの[テスト]ページでテストを定義することをお勧めします。[テスト]ページを使用すると、以下のようなメリットがあります。
- テストをワークフローに関連付けることにより、そのワークフローに関連付けられているレビューが作成/更新/サブミットされた場合に、関連付けられているテストが実行されます。
- テストをグローバルワークフローに関連付けると、Swarmでレビューの作成/更新/サブミットを行うたびに、関連付けられているテストが実行されます。これにより、テストがプロジェクトに含まれていない場合であっても、すべての変更に対してこれらのグローバルなテストが実行されます。
Helix Swarmをテストスイートに統合するには、プロジェクトの設定で[自動テスト]を有効にし、トリガのURLを指定する必要があります。トリガのURLが要求されると、Swarmではテストスイートが実行されます。テストが完了すると、Swarmは、updateパラメータで指定されたコールバックURL、passパラメータで指定されたコールバックURL、またはfailパラメータで指定されたコールバックURL がテストスイートによって要求されるのを待機します。
- [プロジェクト]ページに移動します。
- プロジェクトの[設定]タブをクリックして、[プロジェクトの設定]ページを表示します。
- プロジェクトに設定した各ブランチのパスは、他のブランチのパスと重複しないようにしてください。
-
[自動テスト]チェックボックスで[有効]を選択して、設定フィールドを表示します。
-
テストスイートの実行をトリガする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内で使用することはできません。これを使用できるのは、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を指定します。バージョン2019.3以降のSwarmでは、{update}オプションを使用することをお勧めします。詳細については、以下の「注」を参照してください。
- {fail}
- テストにパスしなかった場合のコールバックURLを指定します。バージョン2019.3以降のSwarmでは、{update}オプションを使用することをお勧めします。詳細については、以下の「注」を参照してください。
注意- バージョン2019.3以降のSwarmでも、{pass}と{fail}は引き続きサポートされていますが、{update}を使用することをお勧めします。これを使用すると、テストステータスにメッセージを含めることができます。
- {update}、
{pass}、{fail}は、Swarmによって自動的に設定されます。これらのパラメータには、Swarmの専用レビュー認証トークンが挿入されます。
-
任意: HTTP POST経由で送信する必要がある自動テストの必須パラメータを[POST本文]フィールドで指定します。POSTパラメータには、上記の特殊引数を含めることができます。
POSTパラメータの形式として、[URLエンコード]または[JSONエンコード]を選択します。
- [URLエンコード]を選択すると、POSTパラメータが「名前=値」のペアとして解析されます。
- [JSONエンコード]を選択すると、指定したパラメータがそのままの状態でPOST本文に渡されます。
JenkinsをSwarm統合環境用に設定する
JenkinsホストとSwarmホストは、双方向で通信できるようにする必要があります。Swarmホストは、Jenkinsホストと通信できるようにする必要があります。適切なDNS/host構成があり、各サーバがHTTP/HTTPS経由で他方に到達できることを確認してください。
-
Jenkins用のp4プラグインをインストールします。
p4プラグインのインストール方法については、『Jenkins向けHelixプラグインガイド』の「インストール」章を参照してください。
-
Jenkinsプロジェクトを設定します。
注意Jenkins向けHelixプラグイン 1.10.11以降の場合: POST要求として、ビルド用のパラメータをSwarm からJenkinsに送信する必要があります。これを行うには、[POST本文]でパラメータを入力して[URLエンコード]を選択します。
-
以下で定義されるように、ジョブ名がトリガURLで使用されているプロジェクトIDと一致するように指定します。
例えば、
{projectName}_{branchName}の算出された値にします。または、トリガURLを編集して、指定したJenkinsのジョブ名を使用します。
-
ビルドをパラメータ化して、これらのパラメータを受け入れます(これらの名前は、呼び出しされたスクリプトと一致するものにしてください)。
- {test}
- テスト名を指定します。
- {testRunId}
- テスト実行IDを指定します。
- {status}
- テストするチェンジリストの状態として、shelved またはsubmitted を指定します。
- {change}
- テストするチェンジリストの番号を指定します。
- {review}
- レビュー担当者のIDを指定します。
- {version}
- レビューのバージョンを指定します。
- {branchName}
- レビューの影響を受けるブランチの名前を指定します。複数のブランチ名を指定する場合は、各ブランチ名をコンマで区切ります。
- {update}
- テスト実行を更新するためのPOSTに対するURLを指定します。テストステータスをレポートする場合は、更新処理用のコールバックURLを呼び出してテスト実行を更新する際に、ステータス、メッセージ、URLのいずれかを(またはこれらすべてを)、該当するCIシステムにリンクされるPOSTリクエストの本文内に含めることができます。これらのメッセージは、POSTリクエストの本文内でJSON形式になっている必要があります。ステータスの有効な値は、running、pass、failです。最大10件のメッセージを渡すことができます。10件を超えるメッセージを指定した場合は、最初に指定した10件のメッセージだけが保存されます。各メッセージには、最大80文字を含めることができます。80文字を超えるメッセージは自動的に切り捨てられます。 {update}を使用することをお勧めします。
- ビルドスクリプトからテスト実行に関するメッセージにアクセスできる場合は、{update}でURLを指定して、そのメッセージをSwarmに渡してください。Swarmにより、そのメッセージがテストの実行結果に追加されます。
- ビルドスクリプトからテストの実行結果にアクセスできる場合は、{update}で指定したURLを呼び出す際に、urlというPOSTパラメータを指定してください。SwarmはそのURLを使用して、レビューをテストの実行結果に関連付けます。テストステータスの値は、running、pass、failです。
- {update}で指定したコールバックURLでは、JSON本文が許可されます。JSON本文で、メッセージ、URL、またはステータスを指定することができます(あるいは、これらすべてを指定することもできます)。
- {pass}
- ビルドが成功した場合のwgetのURLを指定します。バージョン2019.3以降のSwarmでは、{update}オプションを使用することをお勧めします。詳細については、以下の「注」を参照してください。
- {fail}
- ビルドが失敗した場合のwgetのURLを指定します。バージョン2019.3以降のSwarmでは、{update}オプションを使用することをお勧めします。詳細については、以下の「注」を参照してください。
重要テストシステムからSwarmに対してPOSTパラメータを渡すことができない場合は、updateパラメータを使用することはできません。代わりに、passパラメータとfailパラメータを使用する必要があります。
注意{update}を使用する場合の注意事項:
{ "messages" : ["My First Message", "My Second Message"], "url" : "http://jenkins_host:8080/link_to_run", "status": "pass" }注意{pass}と{fail}を使用する場合の注意事項: ビルドスクリプトからテストの実行結果にアクセスできる場合は、テストにパスした場合のURLまたはテストにパスしなかった場合のURLを呼び出す際に、GETパラメータまたはPOSTパラメータでurlを指定する必要があります。SwarmはこのURLを使用して、レビューをテストの結果に関連付けます。
ヒントバージョン2019.3以降のSwarmでも、{pass}と{fail}は引き続きサポートされていますが、{update}を使用することをお勧めします。{update}を使用すると、テストステータスにメッセージを含めることができます。
-
[ソースコード管理]セクションでPerforceソフトウェアを選択します。
重要[ソースコード管理]セクションにPerforceが表示される場合があります。これは、以前のコミュニティに付属していた、Swarmのサポートが含まれていないPerforceプラグインです。
-
必要に応じて、資格情報やワークスペースの動作を設定します。
資格情報とワークスペースの設定方法については、『Jenkins向けHelixプラグインガイド』の「資格情報」セクションと「ワークスペースの動作」セクションを参照してください。
重要- HelixサーバがHelix認証サービス用に構成されている場合、自動テスト用のサービスユーザの資格情報でHelix認証サービスを使用しないでください。
- Jenkinsで設定されているクライアントワークスペースには、Swarmのブランチ用に定義されたパスを持つビューが存在している必要があります。
-
-
以下のようなURLとパラメータを使用して自動テストを実行するようにSwarmプロジェクトを設定します。
重要Jenkinsでは、ジョブ名をURLのジョブIDと一致させる必要があります。上記の例では、これは
{projectName}_{branchName}の算出された値になります。Jenkinsで別の命名方法を使用する場合は、上記URLの
{projectName}_{branchName}を、実際にJenkinsで定義されたプロジェクト名で置き換えます。重要Jenkinsでセキュリティが有効な場合、トリガURLには資格情報が含まれている必要があります。以下の手順を実行します。
- SwarmのビルドをトリガするJenkinsユーザを作成します。例えば、「swarm」などのユーザを作成します。
- Jenkinsに新規ユーザとしてログインします。
- Jenkinsツールバーにあるユーザ名をクリックします。
- [APIトークン]が表示されるまで、下方向にスクロールします。
- [APIトークンを表示]をクリックします。
-
[APIトークン]の値をSwarmトリガのURLに挿入します。
例えば、ユーザ名が「swarm」でAPIトークンの値が「832a5db7e5500c1288324c1441460610」である場合、SwarmトリガのURLとパラメータは以下のようになります。
