CLI コマンド リファレンス

全般

TRCLI は、テスト ランの作成、結果のアップロード、外部レポートからのケースの生成などの TestRail のアクションを自動化するコマンドライン ツールです。

用途の例

• • ローカル スクリプトまたは CI/CD パイプラインから QA ワークフローを自動化する
  • TestRail の UI を使用せずに、より速く、繰り返しアクションを実行する

利用可能なオプションやコマンドのヘルプ情報を表示する最も基本的なコマンド:

trcli --help

以下のようなリストを取得します。

TestRail CLI v1.1X.X
Copyright 2025 Gurock Software GmbH - www.gurock.com
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 used for authenticating with TestRail. This must
                     be used in conjunction with --username. If provided,
                     --password is not required.
  -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
  --proxy            Proxy address and port (e.g.,
                     http://proxy.example.com:8080).
  --proxy-user       Proxy username and password in the format
                     'username:password'.
  --noproxy          Comma-separated list of hostnames to bypass the proxy
                     (e.g., localhost,127.0.0.1).
  --help             Show this message and exit.

Commands:
  add_run        Add a new test run in TestRail
  parse_junit    Parse JUnit report and upload results to TestRail
  parse_openapi  Parse OpenAPI spec and create cases in TestRail
  parse_robot    Parse Robot Framework report and upload results to TestRail

グローバル オプション

これらのオプションはどの TRCLI コマンドでも使用できます。

オプション	説明
-c, --config	設定ファイルへのパス (例: testrail-credentials.json)。コマンド ラインに表示されないようにログイン情報を保存するのに便利です。
-h, --host	TestRail インスタンスの URL です。(例: https://yourcompany.testrail.io) 必須。
--project	TestRail のプロジェクト名。特定のプロジェクトのランを作成または取得するのに使用します。
--project-id	プロジェクトの ID。複数のプロジェクトが同じ名前を持つ場合にのみ使用されます。
-u, --username	TestRail のログイン ユーザー名 (通常は電子メール)。設定ファイルを使用しない場合は必須です。
-p, --password	TestRail のパスワード。API キーを使用する場合はオプションです。
-k, --key	セキュアな認証に使用する API キーです。--usernameと共に使用します。
-v, --verbose	API の呼び出しおよび応答を含む詳細なログを表示します。デバッグに便利です。
--verify	データ (アップロードされたテスト結果など) が正しく追加されたことを検証します。
--insecure	セキュアではない HTTPS リクエスト を許可します (SSL検証をスキップする)。使用には注意が必要です。
-b, --batch-size	各 API バッチで処理するアイテムの数です。デフォルト値: 50。大量のデータをアップロードする場合には値を増やします。
-t, --timeout	API バッチ間の待ち時間 (秒)。デフォルト値: 30。API レート制限に合わせて調整します。
-y, --yes	プロンプトに対して自動的に ‘yes’ と答えます (たとえばテスト ケースを自動作成する場合など)。CI/CD で便利です。
-n, --no	プロンプトに対して自動的に ‘no’ と答えます。テスト ケースが存在しない場合の自動作成を防ぎます。
-s, --silent	すべての 標準出力 (stdout) を抑制します。
--proxy	プロキシ サーバー を使用します (例: http://proxy.company.com:8080)。
--proxy-user	username:password という形式のプロキシ認証情報。
--noproxy	プロキシをバイパスするホストのカンマ区切りリスト (例: localhost,127.0.0.1)。
--help	コマンドのヘルプを表示します。

コマンドの概要

コマンド	処理
add_run	TestRail に新規テスト ランを作成します。
parse_junit	JUnit XML レポートを解析し、結果を TestRail にアップロードします。
parse_openapi	OpenAPI 仕様を解析し、テスト ケースを作成します。
parse_robot	Robot Framework テスト レポートを解析し、結果をアップロードします。

TestRailでの新規テスト ランの作成

TestRail でテスト ランを作成するには、 trcli add_run コマンドを使用します。ランを手動で実行する場合にも、自動実行された結果をアップロードする前にも使用できます。また、スケジュールを定義したり、テスターを割り当てたり、参照や要件をランにリンクしたりする場合にも使用できます。

次のような場合に役立ちます:

• • QA マネージャーやテスターが事前に作業計画を立てる
  • 結果をアップロードする前に自動化エンジニアがラン ID を必要とする場合
  • 要件、マイルストーン、またはスプリントの日付にテスト ランを合わせる場合

例

trcli add_run \
  --title "Release 2.3 Regression" \
  --suite-id 7 \
  --milestone-id 14 \
  --run-start-date "08/01/2025" \
  --run-end-date "08/05/2025" \
  --run-include-all \
  --run-refs REQ-101,REQ-202 \
  --run-assigned-to-id 3

このコマンドは、予定された日付範囲とすべてのテスト ケースを含む、マイルストーンにリンクされたスイ ート ID 7 のタイトル付きテスト ランを作成します。ランは特定のテスターに割り当てられ、2 つの要件を参照します。

利用可能なオプション

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

  Add a new test run in TestRail

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-start-date       The expected or scheduled start date of this test run
                         in MM/DD/YYYY format
  --run-end-date         The expected or scheduled end date of this test run
                         in MM/DD/YYYY format
  --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.
  --run-case-ids         Comma separated list of test case IDs to include in
                         the test run (i.e.: 1,2,3,4).
  --run-refs             A comma-separated list of references/requirements
  -f, --file             Write run data to file.
  --help                 Show this message and exit.

オプション	説明
--title	TestRail UIに表示されるテスト ランの名前 (例: “Sprint 34 Regression”)。
--suite-id	ランを関連付ける テスト スイート ID。プロジェクトで複数のスイートを使用している場合は必須です。
--run-description	ランの概要またはメモ。スコープや目標を明確にするのに便利です。
--milestone-id	このランを特定の マイルストーン ID (リリースやスプリントなど) にリンクします。
--run-start-date	MM/DD/YYYY フォーマットの開始予想または予定日。
--run-end-date	ランの終了予想または予定日。
--run-assigned-to-id	このランを特定の ユーザー ID (ランを担当する主要なテスター) に割り当てます。
--run-include-all	すべてのテスト ケース をこのランに含めます。--run-case-idsと同時には使用できません。
--run-case-ids	含めるテスト ケース ID のカンマ区切りリスト (例: 101,102,103)。
--run-refs	外部参照または要件 ID のカンマ区切りリスト (例: REQ-101,REQ-202)。
-f, --file	生成されたラン データを登録する代わりにローカルのファイル に書き込みます。プレビューや監査に便利です。
--help	このコマンドのヘルプ情報を表示します。

ヒント

• • ランを特定のケースに限定したい場合は、--run-case-idsを使用します。
  • スケジュールされた作業に対して、QA管理者は開始日/終了日を定義して可視化できます。
  • テストのアップロードを自動化する場合、先にランを作成し、後で --run-id を指定して parse_junit を使用できます。

JUnit の結果をアップロードする

JUnit XML レポート (自動テストでは一般的) を解析し、結果を TestRail にアップロードします。

parse_junit を使用して JUnit XML レポートを解析し、テスト結果を TestRail にアップロードします。これは CI/CD パイプラインや自動テストの実行後によく利用されます。

利用に適したケース:

• • 自動テストの実行後 (JUnit、TestNG、Seleniumなど)
  • 結果を直接 TestRail にアップロードしたい場合
  • ケースが存在しない場合に自動作成したり、既存のテスト実行を更新したりしたい場合

例

trcli parse_junit \
  -f build/test-results/test/TEST-results.xml \
  --project "Mobile App" \
  --title "Regression Test - Aug 1" \
  --suite-id 10 \
  --milestone-id 22 \
  --case-matcher title \
  --close-run

このコマンドは、JUnit XML ファイルから結果をアップロードし、指定されたスイートの下にテスト ランを作成し、マイルストーンと関連付け、タイトルでテストケースを照合し、終了後にランを閉じます。

利用可能なオプション

TestRail CLI v1.1X.X
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli parse_junit [OPTIONS]

  Parse JUnit report and upload results to TestRail

Options:
  -f, --file          Filename and path.
  --close-run         Close the newly created run
  --title             Title of Test Run to be created or updated in TestRail.
  --case-matcher      Mechanism to match cases between the report and
                      TestRail.
  --suite-id          Suite ID to submit results to.  [x>=1]
  --suite-name        Suite name to submit results to.
  --run-id            Run ID for the results they are reporting (otherwise the
                      tool will attempt to create a new run).  [x>=1]
  --plan-id           Plan ID with which the Test Run will be associated.
                      [x>=1]
  --config-ids        Comma-separated configuration IDs to use along with Test
                      Plans (i.e.: 34,52).
  --milestone-id      Milestone ID to which the Test Run should be associated
                      to.  [x>=1]
  --section-id        Section ID to create new sections with test cases under
                      (optional).  [x>=1]
  --run-description   Summary text to be added to the test run.
  --case-fields       List of case fields and values for new test cases
                      creation. Usage: --case-fields type_id:1 --case-fields
                      priority_id:3
  --result-fields     List of result fields and values for test results
                      creation. Usage: --result-fields custom_field_a:value1
                      --result-fields custom_field_b:3
  --allow-ms          Allows using milliseconds for elapsed times.
  --special-parser    Optional special parser option for specialized JUnit
                      reports.
  --help              Show this message and exit.

オプション	説明
-f, --file	JUnit XML レポート ファイルへのパス。必須
--close-run	結果をアップロードした後、自動的にテスト ランを終了します。
--title	作成または更新されるテスト ランのタイトル。TestRail UI に表示されます。
--case-matcher	JUnit レポートと TestRail の間でテスト ケースをマッチさせる方法 (タイトル、ID、カスタム属性など)。
--suite-id	結果を登録するスイートの ID。マルチ スイート プロジェクトの場合は必須です。
--suite-name	--suite-idの代替です。ランに関連付けるスイートの名前です。
--run-id	新しいランを作成する代わりに更新する既存のテスト ランの ID。
--plan-id	テスト ランを テスト計画 にアタッチします (より広範な計画の下でランを整理している場合)。
--config-ids	ランに関連付ける設定 ID のカンマ区切りのリスト (例: OS、ブラウザー)。
--milestone-id	ランを関連付けるマイルストーンの ID (例: “Sprint 14 “、”Release 2.1”)。
--section-id	新しいテスト ケースを作成するセクション (該当する場合)。
--run-description	テストランに説明やメモを追加します。コンテキストを理解するのに役立ちます。
--case-fields	新しく作成されたテスト ケースのカスタム フィールド値 (タイプ、優先度など) を設定します。使用方法: --case-fields priority_id:3
--result-fields	各テスト結果のカスタム フィールド値を設定します (テスト環境、注意など)使用方法: --result-fields custom_status:passed
--allow-ms	レポートで経過時間にミリ秒 を使用することを許可します。
--special-parser	非標準の JUnit フォーマットに対してカスタム解析ロジックを使用します。
--help	コマンドの使用方法を表示して終了します。

ヒント

• • すでに add_runを使用してテスト ランを作成済みの場合は、--run-id を使用します。
  • テスト ケースの重複を避け、既存のテスト ケースに結果をリンクするには --case-matcher を使用します。
  • テスト マトリックス (プラットフォームとブラウザーの組み合わせなど) を管理している場合は、--plan-id と --config-ids を組み合わせます。
  • --result-fields は、ビルド バージョンや欠陥リンクのようなメタデータを取り込むことができます。

OpenAPI 仕様からテスト ケースを生成する

このコマンドを使用すると、OpenAPI (旧 Swagger) の仕様に基づいて、TestRail にテスト ケースを自動作成します。これは、REST API のテスト カバレッジをすばやく達成するのに理想的です。

利用に適したケース:

• • 新しい API をリリースする際に、テストケースの作成を自動で行いたい。
  • 仕様ファイルに基づいて、エンドポイント (GET/POST/その他) のテスト ケースを構造化したい。
  • API 設計に合わせてテスト カバレッジを達成したい。

例

trcli parse_openapi \
  -f specs/user-api.yaml \
  --suite-id 5 \
  --case-fields type_id:1 \
  --case-fields priority_id:3

このコマンドは、user-api.yaml を読み込み、スイート ID 5にテスト ケースを生成し、各新規ケースにタイプと優先度の値を設定します。

利用可能なオプション

TestRail CLI v1.1X.X
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli parse_openapi [OPTIONS]

  Parse OpenAPI spec and create cases in TestRail

Options:
  -f, --file      Filename and path.
  --suite-id      Suite ID to create the tests in (if project is multi-suite).
                  [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.

オプション	説明
-f, --file	OpenAPI の YAML または JSON ファイル へのパス (例: api-spec.yaml)。必須
--suite-id	テスト ケースを作成するスイート ID。マルチ スイート プロジェクトの場合は必須です。
--case-fields	各テストケースに適用する 1 つ以上のカスタム フィールド値。次のフォーマットを使用します: field_id:value。オプションを繰り返して複数のフィールドを設定できます。
--help	コマンドの使用方法を表示して終了します。

ヒント

• • ケースにテスト タイプ、自動化ステータス、または優先度のタグを付けるには、--case-fields を使用します。
  • プロジェクトが単一のスイートしか使用しない場合は、--suite-id を省略できます。
  • 生成されたケースは、TestRail のカスタム フィールドとケース テンプレートの設定に従います。

Robot Framework の結果をアップロードする

Robot Framework のテスト実行結果 (通常は output.xml ファイル) を TestRail にアップロードするには、このコマンドを使用します。

使用するべきケース

• • テスト自動化に Robot Framework を使用している
  • 結果を自動的に TestRail に反映させたい場合
  • テスト ケースを自動作成したい、または結果を既存のラン/計画にリンクしたい

例

trcli parse_robot \
  -f output.xml \
  --project "Hardware QA" \
  --suite-name "Peripheral Tests" \
  --title "Regression - Aug 1" \
  --milestone-id 12 \
  --close-run \
  --case-matcher title

このコマンドは output.xml からテスト結果をアップロードし、「Peripheral Tests」スイートにテスト ランを作成し、テスト ランをマイルストーンにリンクし、タイトルでケースをマッチさせ、その後ランを閉じます。

利用可能なオプション

TestRail CLI v1.1X.X
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli parse_robot [OPTIONS]

  Parse Robot Framework report and upload results to TestRail

Options:
  -f, --file          Filename and path.
  --close-run         Close the newly created run
  --title             Title of Test Run to be created or updated in TestRail.
  --case-matcher      Mechanism to match cases between the report and
                      TestRail.
  --suite-id          Suite ID to submit results to.  [x>=1]
  --suite-name        Suite name to submit results to.
  --run-id            Run ID for the results they are reporting (otherwise the
                      tool will attempt to create a new run).  [x>=1]
  --plan-id           Plan ID with which the Test Run will be associated.
                      [x>=1]
  --config-ids        Comma-separated configuration IDs to use along with Test
                      Plans (i.e.: 34,52).
  --milestone-id      Milestone ID to which the Test Run should be associated
                      to.  [x>=1]
  --section-id        Section ID to create new sections with test cases under
                      (optional).  [x>=1]
  --run-description   Summary text to be added to the test run.
  --case-fields       List of case fields and values for new test cases
                      creation. Usage: --case-fields type_id:1 --case-fields
                      priority_id:3
  --result-fields     List of result fields and values for test results
                      creation. Usage: --result-fields custom_field_a:value1
                      --result-fields custom_field_b:3
  --allow-ms          Allows using milliseconds for elapsed times.
  --help              Show this message and exit.

オプション	説明
-f, --file	Robot Framework の XML 結果ファイル へのパス (通常は output.xml)。必須
--close-run	結果をアップロードした後にテスト ランをクローズします。
--title	テスト ランのタイトル (TestRail に表示されます)。
--case-matcher	TestRailでテストケースをマッチさせる方法 (タイトル、ID など) を定義します。
--suite-id	結果を登録するスイートの ID。マルチ スイート プロジェクトの場合は必須です。
--suite-name	スイート名。--suite-idの代替です。
--run-id	更新する 既存のテスト ラン のID。省略された場合は、新しいランが作成されます。
--plan-id	ランをテスト計画にリンクします (オプション)。
--config-ids	カンマで区切られた設定 ID (例: Chrome/Linux のような環境)。
--milestone-id	ランをマイルストーン ID (スプリントやリリースなど) にリンクします。
--section-id	指定されたセクション ID の下に新しいテスト ケースを作成します (構造化に役立ちます)。
--run-description	テスト ランに概要またはメモを追加します。
--case-fields	タイプや優先度などの新規テスト ケースのフィールド値を設定します (例: type_id:1)。
--result-fields	カスタム ステータス、期間、メモなどのテスト結果のフィールド値を設定します。
--allow-ms	継続時間をミリ秒単位で報告できるようにします (正確な時間調整に役立ちます)。
--help	コマンドのヘルプを表示して終了します。

ヒント

• • 重複するケースが作成されるのを防ぐには、--case-matcher を使用します。
  • テスト計画および構成と統合する場合、 --plan-id と --config-ids を組み合わせます。
  • add_runで事前に作成したランを更新するには --run-id を使用します。

GitHub Actions でテスト結果をアップロードする

このパイプラインは、JUnit テストを実行し、TRCLI を使用して結果を TestRail にアップロードします。

name: Run and Upload Tests

on: [push, pull_request]

jobs:
  test-and-upload:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Java
        uses: actions/setup-java@v3
        with:
          java-version: '17'

      - name: Run JUnit tests
        run: |
          ./gradlew test

      - name: Install TRCLI
        run: |
          curl -L https://testrail.com/downloads/trcli/latest -o trcli.zip
          unzip trcli.zip -d trcli
          chmod +x trcli/trcli
          sudo mv trcli/trcli /usr/local/bin/trcli

      - name: Upload results to TestRail
        run: |
          trcli parse_junit \
            -f build/test-results/test/TEST-results.xml \
            --project "WebApp" \
            --title "CI Smoke - ${{ github.sha }}" \
            --milestone-id 12 \
            --close-run \
            --case-matcher title \
            --key ${{ secrets.TESTRAIL_API_KEY }} \
            --username ${{ secrets.TESTRAIL_USER }} \
            --host ${{ secrets.TESTRAIL_HOST }}

注意：

• • ファイル パスを実際のテスト レポートの場所に置き換えてください。
  • セキュリティを確保するため、GitHub Secrets に認証情報を保存します。
  • テスト ケースを自動作成したい場合は --yes を追加します。

参考情報

• • TRCLI 公式ドキュメント
  • GitHub: testrail-cli
  • TestRail システム全体のマニュアル