CI/CD パイプラインでの TRCLI

TRCLI が容易に CI/CD パイプラインに適合する理由

TRCLI は TestRail のコマンドラインクライアントであり、API を介して TestRail インスタンスへのテスト結果のアップロードを自動化します。以下の理由により、TRCLI は容易に CI/CDワークフローに適合します。

- JUnit 形式の XML (Playwright、Selenium など) から TestRail への自動化されたレポートを合理化します。
- 設定ベースの自動化とオーバーライドをサポートし、複数の環境にわたって予測と反復が可能なアップロードを可能にします。
- オープンソースで軽量であり、CI 段階でのスクリプト作成に最適です。
- 失敗を許容できるため、テストが失敗した場合でも、常に結果のアップロードが実行されます。
- ジョブ間で成果物が共有されます。
- 認証情報とメタデータにパイプライン環境変数を使用します。

前提条件

- API アクセスが有効化された TestRail インスタンス
- 自動化フレームワークが JUnit 形式の XML を出力するように設定されていること
- CI 環境に (pip install trcli 経由で) TRCLI がインストールされていること
- 認証情報が安全に保存されること (環境変数または CI のシークレット)

主要パラメーター

stages:
  - test
  - upload-results

test-job:
  image: node:latest
  script:
    - npm install
    - npx playwright test --reporter junit
  artifacts:
    when: always
    paths: [test-results/]
  allow_failure: true

upload-results:
  image: python:latest
  dependencies: [test-job]
  script:
    - pip install trcli
    - trcli -y \
        -h https://your.testrail.io/ \
        --project "My Project" \
        --username $TR_USERNAME \
        --password $TR_API_TOKEN \
        parse_junit \
        -f test-results/junit-report.xml \
        --title "CI Test Run - $CI_PIPELINE_ID" \
        --run-description "GitLab pipeline $CI_PIPELINE_URL" \
        --close-run

フラグ	目的	CI/CD のヒント
`--host`, `--project`	アップロード先 TestRail プロジェクトの詳細	環境変数または設定ファイルを使用してステージングと運用に対応します
`-u`、 `-p` (または API キー)	認証	安全な変数として保存します
`parse_junit`	JUnit XML レポートの取り込み	他のフォーマットに対応するその他のパーサーがあります
`-f`	CI ワークスペース内の JUnit ファイルパス	成果物の場所に合わせます
`--run-description`	コンテキストリンク（CI 実行 URL など)	トレーサビリティを強化します
`--close-run`	アップロード後にテストを自動でクローズ	複数の CI ステップにわたって一貫性を確保します
`--case_result_statuses:`	ステータス名をカスタム TestRail ID にマッピング	チームごとのカスタムワークフローを実現します
`--run-id`	新しいランを作成する代わりに既存のランに追加	失敗したテストの再実行に便利です

ベストプラクティス

- 設定ファイル (config.yml) を使用して、設定 (プロジェクト、スイート、タイムアウト、バッチサイズ) を一元化します。
- 認証情報に環境変数を使用する – バージョン管理システムの外でシークレットを保管します。TRCLI は CLI フラグ、設定ファイル、環境変数の順に優先します。
- TRCLI に組み込まれたリトライ/スロットリング動作を有効にして、TestRail API のレート制限に対処します。
- バッチサイズの調整: デフォルトはリクエストあたり 50 レコードですが、batch_size を使って大規模用に調整できます。
- バージョンの固定: 特に GitHub の gurock/trcli-action と組み合わせる場合は、変更を壊さないようにパイプライン間で一貫した TRCLI バージョンを使用します。

トラブルシューティングのヒント

- 終了コードを確認する: 0 は成功を意味し、0 以外はアップロードや認証のエラーを示します。
- 詳細なログ記録のために --verbose または --verify を有効にします。
- テストケースが存在しないために失敗する場合は、 --auto_create_cases_yes をオンにするか、テストケースのマッピングが適切に設定されていることを確認します (例: auto、name、property)。
- API スロットリングを監視する – ログには自動的に再試行が反映されます。

CI/CD 統合のためのスターターチェックリスト

✅ 自動化フレームワークが JUnit XML 出力をエクスポートすることを確認します。

✅ CI ジョブに TRCLI のインストールステップ (例: pip install trcli) を追加します。

✅ CI 環境変数/シークレットを仕様して認証情報を保護します。

✅ parse_junit コマンドを適切なフラグおよび環境変数とともに使用します。

✅ CI 実行にリンクする --run-description を追加します。

✅ --close-run を使用し、オプションで --run-id を使用します。

✅ 必要に応じて batch_size、タイムアウト、スレッドを調整します。

✅ オプション: --case_result_statusesを介してカスタムステータスをマップします。

CI/CD パイプライン用設定ファイルのセットアップ

TRCLIで config.yml ファイルを使用すると、静的コンフィギュレーションをコマンド呼び出しの外に出すことで、CI/CD パイプラインを簡素化できます。これにより、パイプラインがより明確かつ安全に保たれ、メンテナンスも容易になります。

- コマンドをより簡潔にする: --host、--project などのように繰り返される引数を削除します。
- シークレット管理の改善: 設定にシークレットをハードコーディングする代わりに、環境変数を参照します。
- 移植性: ローカルスクリプトと GitHub Actions、GitLab、Jenkins、その他の CI ツールで同じ設定ファイルを使用します。
- 環境固有のコントロール: 環境ごとに異なる設定ファイルを読み込みます (例: config.staging.yml、config.prod.yml)。

例：

- name: Upload test results to TestRail
  uses: gurock/trcli-action@v1
  with:
    args: >
      -y
      --config .testrail/config.yml
      parse_junit
      -f test-results/junit.xml

絶対に避けるべき事項:

- config.ymlに実際の認証情報を直接ハードコードすること
- シークレットを含む config.yml を公開リポジトリにコミットすること

TRCLI 経由でテスト結果をTestRail にアップロードするGitHub アクションの例

このワークフローは以下を自動化します。

依存関係のインストールとテストの実行
TRCLI で JUnit 形式の結果を TestRail にアップロード

name: Playwright Tests + Upload to TestRail

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test-and-upload:
    runs-on: ubuntu-latest
    env:
      TESTRAIL_USERNAME: ${{ secrets.TESTRAIL_USERNAME }}
      TESTRAIL_API_KEY: ${{ secrets.TESTRAIL_API_KEY }}
      TESTRAIL_HOST: https://yourcompany.testrail.io
      TESTRAIL_PROJECT: "My Project Name"

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

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 18

      - name: Install dependencies
        run: npm ci

      - name: Run Playwright tests and generate JUnit report
        run: |
          npx playwright install
          npx playwright test --reporter=junit
        continue-on-error: true  # Always upload results, even if tests fail

      - name: Upload results to TestRail
        uses: gurock/trcli-action@v1
        with:
          args: >
            -y
            --host ${{ env.TESTRAIL_HOST }}
            --project "${{ env.TESTRAIL_PROJECT }}"
            --username "${{ env.TESTRAIL_USERNAME }}"
            --password "${{ env.TESTRAIL_API_KEY }}"
            parse_junit
            -f test-results/junit.xml
            --title "GitHub Run #${{ github.run_number }}"
            --run-description "GitHub Actions run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
            --close-run

環境変数の設定

リポジトリでシークレットが公開されるのを防ぐには、次の操作を行います。

1. [GitHub] > リポジトリ > [Settings] > [Secrets and variables] > [Action] に移動します。
2. 以下を追加します。
  - TESTRAIL_USERNAME: TestRail ログイン用電子メールアドレスです
  - TESTRAIL_API_KEY: TestRail API トークン ([個人設定] > [API キー] で参照できます)

- --close-run は、アップロード後すぐにランをクローズします。
- --run-description には、TestRail 内でクリック可能な GitHub Actions へのリンクが含まれています。
- フレームワークの出力に合わせて test-results/junit.xml を調整します。
- continue-on-error: true は、テストが失敗しても結果がアップロードされるようにします。

並列ジョブおよび単一ラン用 GitHub Action の例

このセットアップにより、複数のテストジョブが結果を共通の TestRail ランにプッシュでき、複数のプラットフォームでテストスイート全体の実行が可能になります。

name: Parallel Playwright Tests + TestRail Upload

on:
  workflow_dispatch:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  create-run:
    runs-on: ubuntu-latest
    outputs:
      run-id: ${{ steps.create-run.outputs.run-id }}
    env:
      TESTRAIL_USERNAME: ${{ secrets.TESTRAIL_USERNAME }}
      TESTRAIL_API_KEY: ${{ secrets.TESTRAIL_API_KEY }}
      TESTRAIL_HOST: https://yourcompany.testrail.io
      TESTRAIL_PROJECT: "My Project Name"
    steps:
      - name: Create TestRail run
        id: create-run
        run: |
          pip install trcli
          RUN_ID=$(trcli -y \
            --host "$TESTRAIL_HOST" \
            --project "$TESTRAIL_PROJECT" \
            --username "$TESTRAIL_USERNAME" \
            --password "$TESTRAIL_API_KEY" \
            create_run \
            --title "CI Run #${{ github.run_number }}" \
            --run-description "Triggered by GitHub Actions" \
            --suite-id 1 \
            --json | jq -r '.id')
          echo "run-id=$RUN_ID" >> "$GITHUB_OUTPUT"

  test-linux:
    needs: create-run
    runs-on: ubuntu-latest
    env:
      TESTRAIL_RUN_ID: ${{ needs.create-run.outputs.run-id }}
      TESTRAIL_USERNAME: ${{ secrets.TESTRAIL_USERNAME }}
      TESTRAIL_API_KEY: ${{ secrets.TESTRAIL_API_KEY }}
      TESTRAIL_HOST: https://yourcompany.testrail.io
      TESTRAIL_PROJECT: "My Project Name"
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 18

      - name: Install dependencies
        run: npm ci

      - name: Run Playwright tests (Linux)
        run: |
          npx playwright install
          npx playwright test --reporter=junit
        continue-on-error: true

      - name: Upload results (Linux)
        uses: gurock/trcli-action@v1
        with:
          args: >
            -y
            --host ${{ env.TESTRAIL_HOST }}
            --project "${{ env.TESTRAIL_PROJECT }}"
            --username "${{ env.TESTRAIL_USERNAME }}"
            --password "${{ env.TESTRAIL_API_KEY }}"
            parse_junit
            -f test-results/junit.xml
            --run-id ${{ env.TESTRAIL_RUN_ID }}

  test-windows:
    needs: create-run
    runs-on: windows-latest
    env:
      TESTRAIL_RUN_ID: ${{ needs.create-run.outputs.run-id }}
      TESTRAIL_USERNAME: ${{ secrets.TESTRAIL_USERNAME }}
      TESTRAIL_API_KEY: ${{ secrets.TESTRAIL_API_KEY }}
      TESTRAIL_HOST: https://yourcompany.testrail.io
      TESTRAIL_PROJECT: "My Project Name"
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 18

      - name: Install dependencies
        run: npm ci

      - name: Run Playwright tests (Windows)
        run: |
          npx playwright install
          npx playwright test --reporter=junit
        continue-on-error: true

      - name: Upload results (Windows)
        uses: gurock/trcli-action@v1
        with:
          args: >
            -y
            --host ${{ env.TESTRAIL_HOST }}
            --project "${{ env.TESTRAIL_PROJECT }}"
            --username "${{ env.TESTRAIL_USERNAME }}"
            --password "${{ env.TESTRAIL_API_KEY }}"
            parse_junit
            -f test-results/junit.xml
            --run-id ${{ env.TESTRAIL_RUN_ID }}

  close-run:
    needs: [test-linux, test-windows]
    runs-on: ubuntu-latest
    env:
      TESTRAIL_RUN_ID: ${{ needs.create-run.outputs.run-id }}
      TESTRAIL_USERNAME: ${{ secrets.TESTRAIL_USERNAME }}
      TESTRAIL_API_KEY: ${{ secrets.TESTRAIL_API_KEY }}
      TESTRAIL_HOST: https://yourcompany.testrail.io
      TESTRAIL_PROJECT: "My Project Name"
    steps:
      - name: Close the TestRail run
        run: |
          pip install trcli
          trcli -y \
            --host "$TESTRAIL_HOST" \
            --project "$TESTRAIL_PROJECT" \
            --username "$TESTRAIL_USERNAME" \
            --password "$TESTRAIL_API_KEY" \
            close_run \
            --run-id $TESTRAIL_RUN_ID

この構造の理由

- create-run は、すべてのテストジョブで使用される TestRail のラン ID を設定します。
- 各テストジョブは、 --run-idを使用して個別にアップロードします。
- close-run はすべての結果がアップロードされた後にだけランをクローズします。
- より多くのプラットフォームやマトリクスビルドに対応するよう簡単に拡張できます。

TRCLI が容易に CI/CD パイプラインに適合する理由

前提条件

主要パラメーター

ベストプラクティス

トラブルシューティングのヒント

CI/CD 統合のためのスターターチェックリスト

CI/CD パイプライン用設定ファイルのセットアップ

例：

絶対に避けるべき事項:

TRCLI 経由でテスト結果をTestRail にアップロードするGitHub アクションの例

環境変数の設定

並列ジョブおよび単一ラン用 GitHub Action の例

この構造の理由

参考情報

目次

CI/CD パイプラインでの TRCLI

TRCLI が容易に CI/CD パイプラインに適合する理由

前提条件

主要パラメーター

ベスト プラクティス

トラブルシューティングのヒント

CI/CD 統合のためのスターター チェックリスト

CI/CD パイプライン用設定ファイルのセットアップ

例：

絶対に避けるべき事項:

TRCLI 経由でテスト結果をTestRail にアップロードするGitHub アクションの例

環境変数の設定

注意

並列ジョブおよび単一ラン用 GitHub Action の例

この構造の理由

参考情報

目次

ベストプラクティス

CI/CD 統合のためのスターターチェックリスト