使用例

自動テスト結果のアップロードを管理する方法や、より多くのデータで結果を補強する方法に関して、TestRail CLI は幅広いニーズをサポートするさまざまな機能があります。

CLI を使用したテスト結果の補強

テスト結果をサブミットする際、TestRail はさまざまなフィールドにさまざまなタイプのデータを追加できます。たとえば、画面ショットを添付ファイルとしてアップロードしたり、結果にテキストコメントを追加したり、カスタム結果フィールドを使用してより構造的にデータを格納したりすることができます。TestRail CLI を使用すると、これをすべて、複数の方法で行うことができます。CLI を使って呼び出せるオプションは以下のとおりです。

- 結果フィールド
  - 名前: --result-fields またはこれを接頭辞とします。
  - 値: field_name:field_value というパターンを使用します。

次の例のように、すべての結果のフィールドに同じ値を追加する場合、--result-fields を 1 回または複数回使用して、コマンドラインで直接値を渡すことができます。

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --result-fields "version:1.2" \
>    --result-fields "custom_environment:qa02" \
>    -f "results.xml"

自動化プロジェクトにおけるテスト結果の補強

結果ごとに異なる値を追加する必要がある場合も、JUnit レポートの各テストケースにプロパティを追加することで実現できます。このテクニックを使用すると、フィールドデータで結果を補強するだけでなく、コメントや添付ファイルを追加することもできます。

JavaおよびJUnit 5 を使用して TestRail JUnit Extensions Project を実装し、テスト結果を TestRail に統合するときにテスト結果のコメントとカスタマイズ可能な属性をプログラムで追加するサンプルプロジェクトを参照してください。

- 添付ファイル
  - 名前: testrail_attachment またはこれを接頭辞とします。
  - 値: アップロードするファイルへのパスを指定します。

@ExtendWith(TestRailTestReporterParameterResolver.class)
class SumTests {
    @Test
    @DisplayName("Add Two Numbers With Decimals")
    void AddTwoNumbersWithIntegers(TestRailTestReporter customReporter) {
        // Sets the "testrail_attachment" property on the report with a path to a file to be uploaded with the test result
        customReporter.setProperty("test", "sample_reports/testrail.jpg");
        assertEquals(3, 2+1, "2+1 should equal 3");
    }
}

- コメント
  - 名前: testrail_result_comment またはこれを接頭辞とします。
  - 値: コメントフィールドに追加するテキストを指定します。

@ExtendWith(TestRailTestReporterParameterResolver.class)
class SumTests {
    @Test
    @DisplayName("Add Two Integers")
    void AddTwoNumbersWithIntegers(TestRailTestReporter customReporter) {
        // Sets the "testrail_attachment" property on the report with a path to a file to be uploaded with the test result
        customReporter.setProperty("testrail_result_comment", "positive case integer addition scenario");
        
assertEquals(3, 2+1, "2+1 should equal 3");
    }
}

注意：結果ステップを正常に送信するには、対象のテストケースのテンプレートで、step_results フィールドがアクティブでなければなりません。デフォルトでは、この結果フィールドは「テストケース (ステップ)」テンプレートだけにありますが、他のテンプレートをカスタマイズして「テストケース (ステップ)」を含めることもできます。テストケースのテンプレートに関する詳細は、こちらを参照してください。

<testsuites name="test suites root">
  <testsuite failures="0" errors="0" skipped="1" tests="1" time="0.05" name="tests.LoginTests">
    <properties><property name="setting1" value="True"/></properties>
    <testcase classname="tests.LoginTests" name="test_case_2" time="650">
     <properties>
         <property name="testrail_attachment" value="path_to/logs.log"/>
         <property name="testrail_attachment" value="path_to/screenshot.jpg"/>
         <property name="testrail_result_field" value="version:1.2"/>
         <property name="testrail_result_field" value="custom_environment:qa02"/>
         <property name="testrail_result_comment" value="Finding 1"/>
         <property name="testrail_result_comment" value="Finding 2"/>
         <property name="testrail_result_step" value="passed: Insert login credentials"/>
         <property name="testrail_result_step" value="failed: Click submit"/>
         <property name="testrail_result_step" value="untested: User should be logged in"/>
     </properties>
    </testcase>
  </testsuite>
</testsuites>

テストケース作成の補強

自動テストケースの作成を伴うコードファーストアプローチを採用する場合、任意のフィールドにデータを設定してテストケースを補強できます。テスト結果をサブミットする際、TestRail はさまざまなフィールドにさまざまなタイプのデータを追加できます。たとえば、画面ショットを添付ファイルとしてアップロードしたり、結果にテキストコメントを追加したり、カスタム結果フィールドを使用してより構造的にデータを格納したりすることができます。TestRail CLI を使用すると、これをすべて、複数の方法で行うことができます。

すべてのテストケースのフィールドに同じ値を追加する場合、--case-fields を 1 回または複数回使用して、コマンドラインで直接値を渡すことができます。

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --result-fields "version:1.2" \
>    --result-fields "custom_environment:qa02" \
>    -f "results.xml"

テストケースごとに異なる値を追加したい場合も、次の形式で JUnit レポートの各テストケースにプロパティを追加することで実現できます:

- ケースフィールド
  - 名前: testrail_case_field またはこれを接頭辞とします。
  - 値: field_name:field_value というパターンを使用します。

<testsuites name="test suites root">
  <testsuite failures="0" errors="0" skipped="1" tests="1" time="0.05" name="tests.LoginTests">
    <properties><property name="setting1" value="True"/></properties>
    <testcase classname="tests.LoginTests" name="test_case_2" time="650">
     <properties>
         <property name="testrail_case_field" value="refs:STORY-1"/>
         <property name="testrail_case_field" value="custom_preconds:My preconditions"/>
     </properties>
    </testcase>
  </testsuite>
</testsuites>

新しいテストケースを 1 つのセクションに保持する

自動テストケース作成でコードファーストのアプローチを使用している場合、これらをテストケースリポジトリ内の他のテストケースから分離することが必要な場合があります。すべての新しいテストケースを 1 つのセクションにまとめるのに --section-id 引数を使用できます。これにより、すべての自動スイートとテストケースが指定されたセクションの下に作成されます。

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --section-id "213" \
>    -f "results.xml"

マイルストーンへのテストランの追加

マイルストーンは、テスト作業を整理するのに非常に役立ちます。マイルストーンを使用すると、共通の目的を持つテストランまたはテスト計画を集約できます。マイルストーンの下に自動テスト用のテストランを作成したい場合、--milestone-id 引数を渡すと、TestRail CLI は指定されたマイルストーンの下にテストランを作成します。

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --milestone-id "57" \
>    -f "results.xml"

指定されたマイルストーンに新しいテストランが表示されます。これは、1 箇所で自動テストの結果を追跡し続ける方法の 1 つです。

テスト計画へのテストランの追加

また、テスト計画は、共通の目的を持つテスト計画を集約し、さらに、特定の実行構成を指定できるようにします。たとえば、同じテストセットを異なるブラウザーで実行し、その情報をテスト計画に表示することができます。テスト計画の下に自動テスト用のテストランを作成したい場合、--plan-id 引数を渡すと、TestRail CLI は指定されたテスト計画の下にテストランを作成します。それに加えて、オプションとして、テストランを特定の構成と関連付けたい場合は、 --config-ids 引数にカンマ区切りの設定 ID を渡すこともできます。

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --plan-id "57" \
>    --config-ids "25,34" \
>    -f "results.xml"

指定されたテスト計画に新しいテストランが表示されます。これは、1 箇所で自動テストの結果を追跡し続けるもう 1 つの方法です。

既存のテストランのテスト結果を更新する

TestRail CLI を実行し、自動テストの結果が TestRail に入力されているが、一部のテストが失敗しているので該当テストを再実行し、既存のテストランを新しい結果で更新したい場合を想定します。これを実現するには、--run-id 引数を渡します。すると、TestRail CLI は指定された ID のテストランを更新します。

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --run-id "32" \
>    -f "results.xml"

テスト詳細パネルに新しいテスト結果が表示されます。これは、1 つのテストランで自動テストの結果を追跡し続ける方法の 1 つです。

カスタムテスト結果に基づくテスト結果の更新

config.yaml を変更するだけで、TestRail のデフォルトのテスト結果ステータス (Passed、Failed、Skipped など) をカスタムステータス ID にマッピングし、ステータスをオーバーライドできるようになりました。

この機能が重要な理由:

- 柔軟なワークフローをサポート: テスト結果をチーム独自のステータス分類法に合わせます (例: 「オートメーション合格」、「実行中のエラー」)。
- 手作業を軽減: アップロード後に手動でステータスを更新する必要がなくなります。
- より簡単な自動化統合：構成駆動型のアプローチにより、CI/CD パイプラインや自動化ツールとの統合が容易になります。
- 後方互換性: デフォルトステータスを使用する既存のワークフローとシームレスに連携します。

マッピングの例:

- Passed → “Automation Passed” (ID: 7)
- Failed → “Automation Failed” (ID: 8)
- Skipped → “Step Skipped” (ID: 3)
- Error → “Error in Execution” (ID: 4)

このアップデートにより、TestRail で複雑なテスト環境や自動化されたテスト環境を管理するチームの管理と一貫性が強化されます。

実装方法:

まず、TestRail インスタンスでカスタムのテスト結果ステータスを作成し、各ステータスの ID を実行から返される結果にマッピングする必要があります。

TestRail で定義を設定したら、--case_result_statuses 引数と結果タイプの ID を渡すだけで、解析時に情報がマッピングされます。

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --case_result_statuses:
                  passed: 7     # e.g., Automation Passed
                  failure: 8    # e.g., Automation Failed
                  error: 4      # Optional: for exceptions
                  skipped: 3    # Optional: for skipped tests\
>    -f "results.xml"

テストランのクローズ

新しく作成したテストランをただちにクローズするには、--close-run 引数を渡します。すると、TestRail CLI はすべてのテスト結果を追加してからクローズアクションを実行します。これは、ランを完了した後に結果を変更したくない場合に便利です。

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --close-run \
>    -f "results.xml"

テストランは完了済みテストランのセクションに表示されます。

ミリ秒単位での結果の経過時間

TestRail バージョン 5.5 以上では、テスト結果の経過時間をミリ秒 (つまり 0.001 秒)単位でサブミットできます。デフォルトでは、TestRail CLI はすべてのバージョンの TestRail に適用できるよう、時間を秒単位に丸めます。ミリ秒をサポートするバージョンを使用しており、結果の経過時間をミリ秒単位で表示したい場合、--allow-ms 引数を渡します。

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --allow-ms \
>    -f "results.xml"

テスト結果で、経過時間フィールドにミリ秒が使用されているのがわかります。

代替設定を設定ファイルに保存する

別のインスタンスやプロジェクトにすばやく簡単に結果をサブミットしたり、コマンドで別の認証情報やあらかじめ設定した別のパラメーターのセットを使用したりするには、代替設定ファイルを使用します。設定ファイルは YAML フォーマットで記述され、デフォルトでは config.yml という名前で TRCLI 実行モジュールと同じディレクトリに保存されます。環境変数を使用することもできます。コマンドで設定ファイルを参照すると、設定ファイルのすべてのパラメーターで環境変数が上書きされます。コマンドで指定されたパラメーターも設定ファイルで上書きされます。

次のサンプルは、ユーザーの認証情報を保存した代替設定ファイルの使用例です。

host: https://INSERT-INSTANCE-NAME.testrail.io 
project: TRCLI Test
username: username@domain.com 
password: passwordORapikey
title: Automated Tests Run
$ trcli -y \
>    --config alternate_config.yaml \
>    parse_junit \
>    -f "results.xml"

新規テストランの作成

解析コマンドを実行する前にテストランを作成しなければならない場合、add_run コマンドを使用します。たとえば、テストが独立したテストノードで並行して実行される場合、すべてのノードが同じテストランに結果を報告する必要があります。まず、add_run コマンドを使用して新しいランを作成します。次に、ランのタイトルと ID を各テストノードに渡し、それを使用してすべての結果を同じテストランにアップロードします。

$ trcli add_run --help
TestRail CLI v1.9.12
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli add_run [OPTIONS]

Options:
  -title               Title of Test Run to be created or updated in
                       TestRail.
  --suite-id           Suite ID to submit results to. [x>=1]
  --run-description    Summary text to be added to the test run.
  ---milestone-id      Milestone ID to which the Test Run should be
                       associated to. [x>=1]
  --run-assigned-to-id The ID of the user the test run should be assigned
                       to. [x>=1]
  --run-include-all    Use this option to include all test cases in this test run.
  --case-ids           Comma separated list of test case IDs to include in
                       the test run.
  --run-refs           A comma-separated list of references/requirements
  -f, --file           Write run title and id to file.
  --help               Show this message and exit.

CLI を使用したテスト結果の補強

自動化プロジェクトにおけるテスト結果の補強

テスト ケース作成の補強

新しいテスト ケースを 1 つのセクションに保持する

マイルストーンへのテスト ランの追加

テスト計画へのテスト ランの追加

既存のテスト ランのテスト結果を更新する

カスタム テスト結果に基づくテスト結果の更新

テスト ランのクローズ