GitHub Actions との統合

GitHub Actions は、あらゆるソフトウェア開発ワークフローを容易に自動化することを可能にします。GitHub Actions を使用すると、GitHub から直接コードをビルド、テスト、デプロイできます。プッシュ、課題の作成、新規リリース、さらには手動でのワークフローの開始でもワークフローを起動できます。

GitHub Actions の一般的な使用方法は、コードの変更がサブミットされるたびに自動的にアプリケーションのビルドとテストを行うというものです。自動テストの可視性を高め、手動のものも自動化されたものも含めてすべてのテストケースおよびテスト結果をより容易に管理するため、GitHub から直接 TestRail に自動テストの結果を送信できます。このセクションでは、GitHub Actions と TestRail CLI を利用して簡単にこのタスクを達成する方法を説明します。

TestRail CLI は、テスト自動化フレームワークによって、互換性のある JUnit レポートが生成されることを必要とします。

このサンプルでは、Cypress とともに GitHub Actions を使用します。

GitHub ワークフローファイルでの TestRail CLI の使用

Github では、ワークフロー設定ファイルを使用して自動化されたプロセスを設定できます。ワークフロー設定ファイルは YAML ファイルであり、構造化された方法でプロセスを指定し、各ステップで GitHub Actions を活用することで、実行環境の設定や必要なアクションの実行が容易になります。

TestRail と GitHub Actions を統合する最も簡単な方法は、TestRail CLI を使用して自動テストの結果を TestRail に送信するようワークフローファイルを設定することです。次のサンプルは、ワークフローファイルで TestRail CLI を使用してテスト結果を TestRail に送信する方法を示しています。

name: send-results-to-testrail
on: [workflow_dispatch]
jobs:
  send-test-results-to-testrail:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Execute automated tests
        uses: ...
      - name: Python setup
        if: always()
        uses: actions/setup-python@v3
        with:
          python-version: '3.x'
      - name: TestRail CLI upload results
        if: always()
        run: |
          pip install trcli
          trcli -y \
            -h https://TESTRAIL_INSTANCE.testrail.io/ \
            --project "PROJECT NAME" \
            -u USER_EMAIL \
            -p PASSWORD \
            parse_junit \
            --title "Automated Tests from GitHub workflow" \
            --run-description ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} \
            -f "junit-report.xml"

ファイルを細かく見ていくと、いくつか興味深い点があります。

- トリガーイベント on: [workflow_dispatch] は、このワークフローが手動で開始された場合にだけ実行されることを意味します。コードのプッシュ、プルリクエストの作成など、ワークフローをトリガーできるイベントはほかにもあります。
- jobs には execute-tests というアイテムだけがありますが、これは、このワークフローには 1 つのジョブしかないことを意味します。
- execute-tests ジョブは、runs-on: ubuntu-latest でエージェントを定義し、steps の下にステップがあります。ステップについては、次のセクションで詳しく説明します。
  1. Checkout
  2. Execute automated tests
  3. Python setup
  4. TestRail CLI upload results

ワークフロー機能の詳細については公式の GitHub ワークフロードキュメントを参照してください。

ステップ 1: チェックアウト

Checkout ステップは、エージェント上でリポジトリのコードをチェックアウトする actions/checkout@v3 GitHub Action を使用しています。

- name: Checkout
  uses: actions/checkout@v3

ステップ 2: 自動テストの実行

Execute automated tests ステップはプレースホルダーです。この時点で、コードリポジトリにある自動テストが実行され、結果を TestRail に送信するために必要な JUnit レポートが生成されます。これは、GitHub Action を使用して、またはカスタム実行スクリプトを挿入することで実現できます。

name: Execute Automated tests
  uses: ...

ステップ 3: エージェントへの Python のインストール

Python setup は、エージェントに Python を設定する actions/setup-python@v3 GitHub Action を使用しています。TestRail CLI は Python で開発されたツールであり、TestRail CLI をインストールして実行するには、環境に Python をインストールする必要があります。

また、if: always() 条件に注目してください。この条件により、自動テストの実行が成功したかどうかにかかわらず、ステップが実行されます。これは、デフォルトでは、多くのテスト実行フレームワークは、1 つでもテストが失敗すると、エラーコードで終了するためです。

- name: Python setup
  if: always()
  uses: actions/setup-python@v3
  with:
    python-version: '3.x'

ステップ 4: TestRail CLI のインストールとテスト結果のアップロード

TestRail CLI upload results ステップは、カスタムシェルスクリプトを実行して TestRail CLI のインストールと呼び出しを行い、テスト自動化フレームワークによって生成された JUnit レポートを解析して結果を TestRail に送信します。

TestRail CLI は Python Package Index (PyPI) にホストされた Python パッケージであるため、pip install trcli コマンドを実行するだけでインストールできます。

TestRail CLI をインストールした後は、TestRail インスタンスのアドレスおよび認証情報、レポートするプロジェクト、テストランのタイトル、JUnit レポートへのパスなどの必須引数を指定します。実行の説明引数は必須ではありませんが、これを利用して TestRail から GitHub ワークフロー実行へのリンクを追加することを推奨します。このリンクは、下のスニペットのように、GitHub の埋め込み変数を使用して URL を構成することで取得できます。

引数の詳細については、TestRail CLI のドキュメントを参照してください。

- name: TestRail CLI upload results
  if: always()
  run: |
    pip install trcli
    trcli -y \
      -h https://TESTRAIL_INSTANCE.testrail.io/ \
      --project "PROJECT NAME" \
      -u USER_EMAIL \
      -p PASSWORD \
      parse_junit \
      --title "Automated Tests from GitHub workflow" \
      --run-description ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} \
      -f "junit-report.xml"

Cypress を使用した動作するサンプル

次の GitHub ワークフローファイルのサンプルは、Cypress のテストを実行して結果を TestRail に送信します。

name: cypress-tests
on: [workflow_dispatch]
jobs:
  execute-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Cypress run
        id: cypress
        uses: cypress-io/github-action@v4
        with:
          command: npx cypress run --reporter junit --reporter-options mochaFile=reports/TEST-[hash].xml
      - name: Python setup
        if: always()
        uses: actions/setup-python@v3
        with:
          python-version: '3.x'
      - name: TestRail CLI upload results
        if: always()
        run: |
          pip install trcli
          junitparser merge --glob "reports/TEST-*" "reports/junit-report.xml"
          trcli -y \
            -h https://TESTRAIL_INSTANCE.testrail.io/ \
            --project "PROJECT NAME" \
            -u USER_EMAIL \
            -p PASSWORD \
            parse_junit \
            --title "Automated Tests from GitHub workflow" \
            --run-description ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} \
            -f "reports/junit-report.xml"

ファイルを細かく見たとき、上で説明した汎用的な GitHub ワークフローとの違いで注目するべき点は 2 つだけです。

1. 2 番目のステップが cypress-io/github-actions@v4 GitHub Action を使用する Cypress run に置き換えられています。このアクションは、Cypress プロジェクトの依存関係をインストールし、with パラメーターでコマンドを実行して自動テスト実行をトリガーします。
2. TestRail CLI upload results には、Cypress によって生成されたレポートをマージするコマンドが追加されています。TestRail CLI はレポートを 1 つだけ要求するいっぽう、Cypress は複数のレポートを生成するため、このコマンドが必要です。詳細については、Cypress との統合を参照してください。

固有のリポジトリの作成

ここでは、Cypress サンプルプロジェクトを使用して上記の GitHub ワークフローをセットアップします。プロジェクトの詳細については、Cypress との統合を参照してください。

下の手順に従うだけで、テスト実行と TestRail への結果のレポートを行う GitHub ワークフローを簡単に作成できます。

1. GitHub での新規リポジトリの作成
2. Cypress サンプルプロジェクトのファイルをダウンロードします。
3. パス .github/workflows の下にファイル cypress-tests.yml を追加し、上のサンプルの内容をコピーします。
4. ファイルの TESTRAIL_INSTANCE、PROJECT NAME、USER_EMAIL および PASSWORD をユーザー固有の情報に置き換えます (パスワードは直接置き換えず、GitHub シークレットを使用することを推奨します)。
5. GitHub リポジトリにプロジェクトをアップロードします。

ワークフローの実行

1. リポジトリの Actions ページに移動します。リストにワークフローが表示されているはずです。
2. これは手動で開始するワークフローであるため、実行するには、左のワークフロー名をクリックしてから [Run workflow] ボタンをクリックします。
3. ワークフローの詳細に移動して、何が問題だったかを確認できます。実行ログはステップごとに分割されています。下の画像では、Cypress run の実行が失敗していることがわかります。
4. Cypress run のログの詳細を見ると、実行は成功していますが、1 つのテストが失敗していることがわかります。テストは失敗していますが、その場合でも TestRail に結果が送信されるよう、if: always() 条件が使用されているため、 Python setup および TestRail CLI upload results ステップは実行されています。
5. TestRail に移動し、テストランの結果を参照します。GitHub ワークフローへのリンクが張られ、テスト結果を詳しくデバッグできることがわかります

次のステップ

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

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