TestRail CLI

TestRail CLI は、任意の JUnit 形式の XML ファイルから簡単に自動テストの結果を TestRail アップロードできるコマンド ライン インターフェイス ツールです。

概要

TestRail CLI を使用すると、ほぼどのようなテスト自動化ツールまたはフレームワークの自動テストの結果でも解析できます (ツールが JUnit 形式の XML ファイルでテスト結果をエクスポートできる場合)。TestRail CLI で使用可能なレポートを簡単に生成できる一般的な自動化フレームワークの例として以下が挙げられます。

• • JUnit
  • TestNG
  • Cypress.io
  • Playwright
  • Robot Framework
  • Pytest
  • NUnit

コマンド ラインから直接 JUnit 形式のテスト結果を解析して TestRail にアップロードするか、自動化されたビルド パイプラインの一部として CLI を実行することで、API の呼び出しやテスト結果のアップロードに関するその他の技術的詳細にわずらわされることなく、テスト コードの作成に集中できます。

TestRail CLI は GitHub にホストされたオープン ソースのプロジェクトであり、誰でも課題を作成したり、さらに新機能や改善を実装するコードを開発したりといった貢献を行うことができます。詳細な手順についてはREADMEを参照してください。

TestRail CLI のインストール

TestRail CLI は、テスト結果のアップロードに関してはプログラミング言語を意識する必要はありませんが、ツール自体は Python で開発されており、パブリックな Python Package Index (PyPI) からインストールできます。マシンに TestRail CLI をインストールしたり、エージェントをビルドしたりする場合、OS に合った Python 3.10.4 インストーラーをダウンロードしてインストール ウィザードの指示に従い、pip もインストールすることを推奨します。正常にインストールされたことを確認するには、コマンド ラインから  pythone -version および pip –version  コマンドを実行します。すると、バージョンが出力されます。

Python のインストールが完了したら、TestRail CLI のインストールは、システムのコマンド ラインで次の 1 行を実行するだけです。

$ pip install trcli

TestRail インスタンスの設定

TestRail CLI を使用する前に、次のように TestRail インスタンスを設定する必要があります。

1. 1. TestRail API を有効化します。[管理] > [サイト設定] にアクセスして [API] タブをクリックし、[API の有効化] オプションをオンにします。詳細については API 入門ページを参照してください。
   2. カスタム テスト ケース フィールドを作成し、自動テスト ケースのコードと TestRail のケースをマッピングします。そうすると、テスト ケースを複製したり、テスト自動化コード内に TestRail のケース ID を記述したりせずに、TestRail にテスト結果をアップロードできます。 新規カスタム フィールドを作成するには、[管理] > [カスタマイズ] にアクセスして [フィールドの追加] をクリックします。フィールド作成画面に移動したら、下の図に示すように、下記の 2 つの要件に従ってフィールドを作成します。詳細についてはカスタム フィールドの設定ページを参照してください。
      • システム名は automation_id 
      • タイプは String

      

TestRail CLI を使用した自動テスト結果のアップロード

TestRail CLI は簡素で効率的であるよう設計されています。TestRail CLI をインストールし、TestRail インスタンスを設定したら、コマンド ラインから JUnit 形式の結果ファイルを渡してすばやくランを作成し、テスト結果を追加し、さらに、まだ TestRail に自動テスト用のテスト ケースが存在しない場合は、自動的にケースを生成することもできます。

下記の JUnit 形式 XML レポートのサンプルを使用して次のような簡単なコマンドを実行し、テスト結果を TestRail に送信できます。コマンドの -y オプションに注目してください。このオプションは、プロンプトをスキップして自動的に新規テストを作成します。これは、CI ツールから TestRail CLI を実行する場合に便利です。

<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_1" time="159">
      <skipped type="pytest.skip" message="Please skip">
        skipped by user
      </skipped>
    </testcase>
    <testcase classname="tests.LoginTests" name="test_case_2" time="650">
    </testcase>
    <testcase classname="tests.LoginTests" name="test_case_3" time="159">
      <failure type="pytest.failure" message="Fail due to...">
        failed due to…
      </failure>
    </testcase>
  </testsuite>
</testsuites>

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

Checking project. Done.
Adding missing sections to the suite.
Found test cases not matching any TestRail case (count: 3)
Adding missing test cases to the suite.
Adding test cases: 3/3, Done.
Creating test run. Done.
Adding results: 3/3, Done.
Submitted 3 test results in 6.5 secs.

インポート処理が完了した後、TestRail プロジェクトのテスト ケース ページに移動すると、テスト結果レポートに含まれていたテストに対応するテスト ケースが TestRail によって自動的に作成されていることがわかるでしょう。JUnit レポートのテストごとに classname.name というパターンを使用し、classname および name 属性を組み合わせて一意の Automation ID を追加していることに注目してください。この Automation ID を使用して自動化コードのテストと TestRail のテスト ケースをマッピングします。つまり、TestRail CLI を実行するたびに、TestRail の既存のテスト ケースと比較し、該当する Automation ID を持つテスト ケースがない場合にだけ新しいテスト ケースを作成します。

例：

<testcase
  classname=”tests.LoginTests”  name=”test_case_1″  time=”159″>
</testcase>

テスト ランおよびテスト結果ページに移動すると、TRCLI Test プロジェクトに Automated Tests Run という名前の新しいランが表示されます。

テスト ランを開くと、各テスト ケースの結果が表示されます。失敗したテスト ケースをドリル ダウンし、JUnit レポートから直接インポートされたエラー メッセージを確認できます。これはテスト中に起きた問題の概要をすばやく把握するのに便利です。

その他の便利な機能

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

別のインスタンスやプロジェクトにすばやく簡単に結果をサブミットしたり、コマンドで別の認証情報やあらかじめ設定した別のパラメーターのセットを使用したりするには、設定ファイルを使用します。設定ファイルは 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

Checking project. Done.
Creating test run. Done.
Adding results: 3/3, Done.
Closing test run. Done.
Submitted 3 test results in 3.2 secs.

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

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

Checking project. Done.
Adding results: 3/3, Done.
Closing test run. Done.
Submitted 2 test results in 2.5 secs.

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

テスト ランのクローズ

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

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

Checking project. Done.
Creating test run. Done.
Adding results: 3/3, Done.
Closing test run. Done.
Submitted 3 test results in 3.2 secs.

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

CLI リファレンス

全般

$ trcli --help
Usage: trcli [OPTIONS] COMMAND [ARGS]...

  TestRail CLI

Options:
  -c, --config       Optional path definition for testrail-credentials file or
                     CF file.
 -h, --host          Hostname of instance.
 --project           Name of project the Test Run should be created under.
 --project-id        Project id. Will be only used in case project name will
                     be duplicated in TestRail [x>=1]
 -u, --username      Username.
 -p, --password      Password.
 -k, --key           API key.
 -v, --verbose       Output all API calls and their results.
 --verify            Verify the data was added correctly.
 --insecure          Allow insecure requests.
 -b, --batch-size    Configurable batch size. [default: (50); x>=2]
 -t, --timeout       Batch timeout duration. [default: (30); x>=0]
 -y, --yes           answer 'yes' to all prompts around auto-creation
 -n, --no            answer 'no' to all prompts around auto-creation
 -s, --silent        Silence stdout
 --help              Show this message and exit.

JUnit 形式の結果のアップロード

$ trcli parse_junit --help
Usage: trcli parse_junit [OPTIONS]

  Parse report files and upload results to TestRail

Options:
  -f, --file            Filename and path.
  --close-run           Whether to close the newly created run
  --title               Title of Test Run to be created in TestRail.
  --suite-id            Suite ID for the results they are reporting. [x>=1]
  --run-id              Run ID for the results they are reporting (otherwise
                        the tool will attempt to create a new run). [x>=1]
  --case-fields         List of case fields and values for new test cases
                        creation. Usage: --case-fields type_id:1
                        --case-fields priority_id:3
  --help                Show this message and exit.

次のステップ

テスト結果が TestRail に集約されたので、失敗したテストのエラー メッセージも含めて自動テスト実行の結果を確認できるだけでなく、手動テストと自動テストをレポート上で集約し、アプリケーションに関する完全なテスト カバレッジを表示したり、テスト自動化プロセスを追跡したりすることも可能です。また、手動テストの結果だけでなく、自動テストの結果から任意の課題トラッカーに直接バグをレポートすることもできます。

TestRail のレポート機能を活用する方法については、TestRail のレポートおよびテスト メトリクスの動画 (英語) を参照してください。