TestRail CLI では、複数の入力メソッドを使用した柔軟な設定が可能です。これにより、QA チームはローカルなセットアップにも自動化された CI/CD パイプラインにもシームレスに CLI を統合できます。
この設定が重要な理由
TestRail のホスト、プロジェクト、認証情報などのパラメータ―を渡したいケースがあるでしょう。ワークフローに応じて、コマンド ラインで直接設定することも、設定ファイルを通じて設定することも、環境変数を通じて設定することもできます。
優先順位を理解することは、競合や予期しない動作を避けるのに役立ちます。
パラメーターの階層 (優先度最高位から最下位)
| 階層 | ソース | 使用するべきケース |
|---|---|---|
| 1 | CLI パラメーター | その場でオーバーライドしたい場合。スクリプトや単発の実行に最適。 |
| 2 | カスタム設定ファイル | 特定のプロジェクトやチーム レベルの設定用。 |
| 3 | 環境変数 | CI/CD やセキュアなランタイム設定 (シークレットなど) に適している。 |
| 4 | デフォルトの設定ファイル | フォールバックまたはベースライン設定用。 |
| 5 | デフォルト値 (ビルトイン) | 他に何も設定されていないときにのみ使用される。 |
カスタム設定ファイルの使用
設定ファイルは、YAML フォーマットでパラメーターおよび設定をするするための構造化された方法を提供します。次のいずれかを使用できます。
-
- デフォルトの設定ファイル: CLI と同じ場所に置くと自動的にロードされます。
- カスタム設定ファイル:
-cまたは--configを使用して手動で指定します。
config.ymlでサポートされているフィールド
認証フィールド
これらのフィールドは、TestRail インスタンスに安全に接続するために必要です。
| フィールド名 | Type | 説明 |
|---|---|---|
host |
string |
TestRail インスタンスの完全なURL (例: https://example.testrail.io) |
username |
string |
TestRail のログイン電子メール (ベーシック認証に使用されます)。キーを使用しない場合は必須です。 |
password |
string |
TestRail のパスワードです。API キーを使用する場合は任意です。 |
key |
string |
認証のための API キーです (username/password)。 |
💡 ヒント: 共有設定ファイルにはパスワードやキーを含めないようにします。機密性の高い値には環境変数を優先して使用します。
プロジェクトおよびランのターゲット フィールド
これらは、TestRail のどこに結果をアップロードするかを指定します。
| フィールド名 | Type | 説明 |
|---|---|---|
project |
string |
結果をアップロードするプロジェクト名。 |
project_id |
number |
プロジェクトID。プロジェクト名が重複している場合に、正しいターゲットに送信するために使用します。オプション |
suite_id |
number |
特定のテスト スイートを対象とします。マルチ スイート プロジェクトの場合は必須です。オプション |
run_id |
number |
指定されている場合、新しいランを作成するのではなく、既存のランを更新します。 |
milestone_id |
number |
特定のマイルストーンにテスト ランを追加します。 |
入力およびファイルフィールド
これらのフィールドは、テスト結果の入力と設定ファイルの参照を定義します。
| フィールド名 | タイプ | 説明 |
|---|---|---|
file |
string |
テスト結果ファイルへのパス (例: .xml)。必須. |
config |
string |
--config が指定されている場合、セカンダリ (カスタム) 設定ファイルへのパス。 |
メタデータ フィールド
これらのフィールドは、TestRail のランの説明に役立ちます。
| フィールド名 | タイプ | 説明 |
|---|---|---|
title |
string |
作成されるテスト ランのタイトル (例: Regression Build 12.1)。 |
run_description |
string |
テスト ランに説明 (CI ジョブの URL やコンテキストなど) を追加します。オプション |
出力およびログ記録フィールド
CLI が出力またはログに記録する内容を制御します。
| フィールド名 | Type | 説明 |
|---|---|---|
verbose |
boolean |
true の場合、処理の詳細なログを出力します。デフォルト値: false。 |
silent |
boolean |
true の場合、結果以外のすべての出力を抑制します (クワイエット モード)。デフォルト値: false。 |
💡 ヒント: デバッグには
verbose を使用し、CI でのログのクリーンアップには silent を使用します。ネットワークおよびセキュリティ フィールド
CLI が TestRail とのネットワーク通信をどのように処理するかを制御します。
| フィールド名 | Type | 説明 |
|---|---|---|
verify |
boolean |
true の場合、HTTPS リクエストで SSL 証明書をチェックします。デフォルト値: true。 |
insecure |
boolean |
true の場合、SSL 検証なしのリクエストを許可します。テスト環境で便利です。 |
💡 ヒント:
insecure: true はテストにのみ使用します – 本番環境では推奨されません。動作制御フィールド
CLI 実行時の動作を制御します。
| フィールド名 | Type | 説明 |
|---|---|---|
auto_creation_response |
boolean |
true の場合、不足している TestRail エンティティを作成するためのプロンプトを自動で確定します。 |
close_run |
boolean |
trueの場合、結果をアップロードした後にテスト ランをクローズします。デフォルト値: false。 |
パフォーマンス チューニング フィールド
結果の処理および送信方法をコントロールするのに役立ちます。
| フィールド名 | Type | 説明 |
|---|---|---|
batch_size |
number |
各バッチで送信する結果の数です。デフォルト値はシステムによって異なります。 |
timeout |
number |
終了する前に追加の結果を待機する秒数 (float 値を使用できます)。 |
💡 ヒント:
batch_size と timeout をチューニングすることで、大規模なテスト スイートのパフォーマンスを向上させることができます。高度なデータ マッピング フィールド
アップロード プロセスをカスタマイズしたり、拡張したりするのに便利です。
| フィールド名 | Type | 説明 |
|---|---|---|
case_fields |
dict |
テストケースの作成 時に適用されるカスタム フィールドの値です。フォーマット: key: value。 |
result_fields |
dict |
テストケースのアップロード 時に適用されるカスタム フィールドの値です。フォーマット: key: value。 |
case_results_statuses |
dict |
フレームワークの結果ラベル (passed、failedなど) を TestRail のステータス ID にマップします。 |
💡 ヒント: これらのフィールドは、自動テスト ツールと TestRail のカスタム ワークフローを連携する場合に重要です。
設定ファイルの例
host: https://fakename.testrail.io/
project: My TestRail Project
username: myuser@name.com
password: StrongP@ssword
file: PATH/result_file.xml
title: Automated Tests
config: PATH/alternate_config.yml
batch_size: 20
timeout: 5.5
auto_creation_response: true
case_fields:
type_id: 1,
priority_id: 3
custom_field_id: [2, 4]
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
環境変数によるパラメーターの設定
環境変数は、CLI を設定するための安全で CI に適した方法です。CLI の各オプションを環境変数に変換できます:
命名規則
-
TR_CLI_の後に大文字のパラメータ名を付加します。- ダッシュ (
-) はアンダースコア (_) に置き換えます。
例：
-
--hostまたは -h →TR_CLI_HOST--project-id→TR_CLI_PROJECT_ID- –username → TR_CLI_USERNAME
--auto-creation-response→TR_CLI_AUTO_CREATION_RESPONSE
💡 ヒント: 環境変数名に変換する場合、パラメータ名に含まれるダッシュ (
-) をアンダースコア (_) に置き換えます。環境変数の設定方法
Windows cmd
set TR_CLI_PROJECT="project name"
Windows powershell
$env:TR_CLI_PROJECT="project name"
Linux
export TR_CLI_PROJECT="project name" for Linux-like systems
💡 ヒント: これらはセッション中の一時的な設定です。永続的な設定には、シェル プロファイル (
CLI vs 設定ファイル vs 環境変数
| ソース タイプ | 使用するべきケース | 最適な用途 | 利点 | 欠点 |
|---|---|---|---|---|
| CLI パラメーター | 単発の実行やスクリプトで設定を上書きする必要がある場合 | ローカルテスト、クイック オーバーライド | – 即時制御 – 最優先 |
– 再利用不可 – パイプラインでの保守が困難 |
| カスタム設定ファイル | チームまたはプロジェクト固有の設定をリポジトリでバージョン管理したい場合 | 共有プロジェクト、開発チーム | – 再利用可能 -文書化が容易 -複雑なセットアップにも対応 |
– CLI より優先順位が低い – --config経由で渡す必要がある |
| 環境変数 | ファイル外でシークレットを管理したい、あるいは CI/CD を動的に構成したい場合 | CI/CD、安全なシークレット | – セキュア (認証に有効) – ファイル不要 |
– 可視性が低い/デバッグしにくい – セッションベース (永続的ではない) |
| デフォルトの設定ファイル | 何も渡さずにフォールバック値が欲しい場合 | シンプルなローカル ワークフロー | – 自動的に読み込まれる – 推奨されるデフォルトの動作 |
– ファイル ベースの優先度は最低 – 存在を忘れやすい |
| デフォルト値 | 何も設定していない場合 (CLI が安全なフォールバックを決定する) | シンプル、学習 | – シンプルな実行でセットアップがいらない | – 設定が不完全な場合に動作の予測が不可能 |
実践的な推奨事項
| シナリオ | 推奨されるソース | 理由 |
|---|---|---|
| ローカルな手動テスト | デフォルトの設定ファイル + 状況に合わせて CLI でのオーバーライド | 設定が簡単で、必要なときにオーバーライドできる |
| チーム共有テスト環境 | カスタム設定ファイル | バージョン管理された、読みやすい設定を全員に提供 |
| CI/CD パイプライン | 環境変数 + フォールバック用設定ファイル | 安全、スクリプト可能、再現可能 |
| 単発クイック テスト | CLI パラメーター | セットアップ不要、実行するだけ |
| 認証情報の安全な更新 | 環境変数 | 設定や CLI の履歴の外でシークレットを保持する |
| 動的またはマルチプロジェクト パイプライン | キーとなるプロジェクト ID には CLI を使用し、認証には 環境変数 を使用する。 | ランタイム データとシークレットの分離 |