テストの追加

テストをワークフローに関連付けることにより、そのワークフローに関連付けられているレビューが作成/更新/サブミットされた場合に、関連付けられているテストが実行されます。テストをグローバルワークフローに関連付けると、Swarmでレビューの作成/更新/サブミットを行うたびに、関連付けられているテストが実行されます。これにより、テストがプロジェクトに含まれていない場合であっても、すべての変更に対してこれらのグローバルなテストが実行されます。

テストを追加するには、以下の手順を実行します。

1. Swarmの[テスト]ページで、[+テスト定義を追加]ボタンをクリックします。

   [テスト定義を追加]ページが表示されます。

   
2. テスト名を入力します。一意のテスト名を1～32文字の範囲で入力する必要があります。
3. 任意: テストの説明を入力します。

4. 自分がワークフローの所有者として自動的に追加されます。

   任意: 必要に応じて、自分以外の所有者を追加します。このフィールドに文字を入力すると、Helixサーバ内でその文字に一致するグループやユーザが自動的に表示されます(グループとユーザの組み合わせで最大20件)。

   重要

   • テストには、1人以上の所有者が必要です。
   • 所有者である自分自身をテストから削除すると、super ユーザ権限を持っていない限り、このテストの設定を編集できなくなります。

5. 任意: 自分が所有しているテストを他のSwarmユーザも使用できるようにするには、[他のユーザと共有済み]チェックボックスを選択します。

   ヒント

   テストが正しく機能することが確認できない場合は、このチェックボックスを選択しないでください。このチェックボックスを選択するまで、自分が所有するテストを他のSwarmユーザが使用することはできません。テストに問題がないことを確認してからこのチェックボックスを選択して、他のユーザとテストを共有してください。

6. テストを要求するURLを入力します。このURLを[URL]テキストボックスに入力すると、テストスイートが実行されます。

   Swarmからテストスイートに詳細情報を渡すための特殊な引数を指定することもできます。詳しくは、「特殊な引数をテストスイートに渡す」を参照してください。

   注意

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

7. 任意: [タイムアウト(秒)]の値を整数で指定します。このタイムアウト値は、Swarmがテストスイートに接続する際に使用されます。タイムアウト値を設定しなかった場合は、http_client_optionsのtimeout設定の値が使用されます。デフォルト値は10秒です。
8. 任意: テストスイートで必要なパラメータをテスト要求の[本文]で指定し、以下のラジオボタンを使用してエンコード方法を選択します。
   • [URLエンコード]を選択すると、POSTパラメータが「名前=値」のペアとして解析されます。これがデフォルトの設定です。
   • [JSONエンコード]を選択すると、指定したパラメータがそのままの状態でPOST本文に渡されます。
   • [XMLエンコード]を選択すると、パラメータがXML形式でPOST本文に渡されます。

Swarmからテストスイートに詳細情報を渡すための特殊な引数を指定することもできます。詳しくは、「特殊な引数をテストスイートに渡す」を参照してください。

9. [影響を受けるプロジェクトとブランチの反復テスト]チェックボックス

[任意]を選択定すると、レビューが関連付けられているブランチとプロジェクトごとに個別のテスト実行が作成されます。{projects}引数、{branch}引数、{branch}引数によってURLまたは本文内に生成される詳細情報は、レビューページのテストステータスドロップダウンに表示されるテスト名で使用されます。

例: テストのURLまたは本文内で、以下のように{projects}引数と{branches}引数を指定した場合

'{projects}' => 'foo,bar',

'{branches}' => 'foo:dev,foo:main,bar:dev,bar:candidate',

この場合、Swarmによってこれらの引数が繰り返し処理され、以下に示すプロジェクトブランチごとにテスト実行が作成されます。

• 「foo dev」プロジェクトブランチ

• 「foo main」プロジェクトブランチ

• 「bar dev」プロジェクトブランチ

• 「bar candidate」プロジェクトブランチ

[影響を受けるプロジェクトとブランチの反復テスト]を選択しなかった場合、複数のブランチとプロジェクトがレビューに関連付けられていても、レビューに対して実行されるテストは1つだけになります。

注意

プライベートプロジェクト: テストに対して[影響を受けるプロジェクトとブランチの反復テスト]が選択されているためにプライベートプロジェクトのテストがレビューに追加される場合、Swarmでは、そのプライベートプロジェクトの権限が優先され、表示権限のないユーザに対して、そのプロジェクトがプライベートプロジェクトとしてレビューのテスト一覧に表示されます。

• レビューのテスト一覧の詳細については、「テストステータス」を参照してください。

• プライベートプロジェクトの詳細については、「プライベートプロジェクト」を参照してください。

10. [ヘッダ]の情報を指定します。

任意: テストスイートに渡す「名前=値」のペアを指定します。

ヒント

[保存]ボタンをクリックした場合にのみ、ヘッダがテストに保存されます。

ヘッダの「名前=値」のペアを追加する場合: 

1. ヘッダ領域で[]をクリックします。
2. 空の[ヘッダ]ボックスと[値]ボックスに「名前=値」のペアを入力します。
3. テストページで[保存]をクリックします。これにより、新しいヘッダがテストに保存されます。

ヘッダの「名前=値」のペアを編集する場合:

1. [ヘッダ]ボックスと[値]ボックスで「名前=値」のペアを編集します。
2. テストページで[保存]をクリックします。これにより、ヘッダの編集内容が保存されます。

ヘッダの「名前=値」のペアを削除する場合:

テストから削除するヘッダの横に表示されている[削除]ボタン()をクリックします。

ヘッダはすぐに削除されます。確認画面は表示されません。ヘッダの削除を完了するには、テストを保存する必要があります。

11. [保存]をクリックします。

    注意

    いずれかの必須フィールドに値が入力されていない場合は、[保存]ボタンが無効になります。

特殊な引数をテストスイートに渡す

テスト要求のURLと本文で特殊な引数を指定し、テストスイートに対してテストの実行をトリガした変更に関する情報をSwarmに渡すことができます。Swarmはテストを呼び出す際に、これらの引数を、関連するSwarm情報に置き換えます。

• {change}: 変更番号を指定します。
• {status}: 保留状態の変更のステータスを指定します(shelvedまたはcommitted)。
• {review}: レビューIDを指定します。
• {version}: レビューのバージョンを指定します。
• {reviewStatus}: レビューのSwarmステータスを指定します(needsReview、needsRevision、archived、rejected、approved、approved:commit)。
• {description}: この更新の生成時に使用された変更の説明を指定します。{description}をURL内で使用することはできません。これを使用できるのは、リクエストの本文内だけです。
• {test}: テスト名を指定します。
• {testRunId}: テスト実行IDを指定します。
• {projects}: レビューに関係するプロジェクトのIDを指定します。レビューに関係するプロジェクトが存在しない場合はNULLになります。複数のプロジェクトがレビューに関係している場合は、各プロジェクトがカンマで区切られます。
• {branches}: レビューに関係するブランチのIDを指定します。プロジェクトに関係するブランチの場合、ブランチIDの先頭にプロジェクトIDが付加されます(デフォルト設定の場合、プロジェクトIDとブランチIDの間にコロン(:)が挿入されます)。ブランチに関係するプロジェクトが存在しない場合はNULLになります。複数のプロジェクトがブランチに関係している場合は、各プロジェクトがカンマで区切られます。
ヒント

一部のCIシステムでは(Jenkinsなど)、テスト要求が失敗する原因となるデフォルトのコロン文字(:)をエスケープする必要があります。CIシステムで別の区切り文字を使用する必要がある場合は、Swarmでその区切り文字を使用するようにSwarmのadmin ユーザに依頼してください。

一部の文字については、テストを呼び出す際にエラーが発生する可能性があるため、区切り文字を指定する場合は注意が必要です。例えば、URLの呼び出しで「#」という文字を使用すると、ブランチがアンカーとして処理され、JSON本文のエンコーディングで使用されている「%」という文字がエスケープされます。どちらの場合も、テスト要求が失敗します。

区切り文字の設定方法については、「project_and_branch_separator」を参照してください。

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

これは、プロジェクトテストで使用するための引数です。後方互換性を確保する目的で、ワークフローテストでサポートされています。ただし、ワークフローテストで{branches}引数を使用することをお勧めします。

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

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

注意

{update}を使用する場合の注意事項:

• ビルドスクリプトからテスト実行に関するメッセージにアクセスできる場合は、{update}でURLを指定して、そのメッセージをSwarmに渡してください。Swarmにより、そのメッセージがテストの実行結果に追加されます。
• ビルドスクリプトからテストの実行結果にアクセスできる場合は、{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}: テストにパスした場合のコールバックURLを指定します。バージョン2019.3以降のSwarmでは、{update}オプションを使用することをお勧めします。詳細については、以下の「注」を参照してください。
• {fail}: テストにパスしなかった場合のコールバックURLを指定します。バージョン2019.3以降のSwarmでは、{update}オプションを使用することをお勧めします。詳細については、以下の「注」を参照してください。
注意
• {update}、{pass}、{fail}は、Swarmによって自動的に設定され、Swarmの専用レビュー認証トークンが挿入されます。
• {pass}と{fail}を使用する場合の注意事項: ビルドスクリプトからテストの実行結果にアクセスできる場合は、テストにパスした場合のURLまたはテストにパスしなかった場合のURLを呼び出す際に、GETパラメータまたはPOSTパラメータでurlを指定する必要があります。SwarmはこのURLを使用して、レビューをテストの結果に関連付けます。
ヒント

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

• {projectNames}: レビューに関係するプロジェクトの名前を指定します。レビューに関係するプロジェクトが存在しない場合はNULLになります。複数のプロジェクトがレビューに関係している場合は、各プロジェクトがカンマで区切られます。
注意

テストに対して[影響を受けるプロジェクトとブランチの反復テスト]チェックボックスを選択しても、反復テストは実行されません。反復テストを実行する場合は、{projects}引数を使用してください。

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

テストに対して[影響を受けるプロジェクトとブランチの反復テスト]チェックボックスを選択しても、反復テストは実行されません。反復テストを実行する場合は、{branches}引数を使用してください。