GitLab CI/CD との統合

GitLab CI/CD を使用すると、コードのビルド、テスト、デプロイに必要なすべての手順を自動化できます。通常、チームは、ソースコードを格納するために GitLab を使用するほか、CI/CD 機能を使用して GitLab 内部でコードをビルドおよびテストします。パイプラインを作成し、コードがデプロイされる前に効率的にビルドおよびテストを行います。

パイプラインの一環として、自動化されたテストが実行されるのが普通です。自動テストの可視性を高め、手動のものも自動化されたものも含めてすべてのテストケースおよびテスト結果を管理するため、GitLab から直接 TestRail に自動テストの結果を送信できます。このセクションでは、GitLab CI/CD と TestRail CLI を利用して簡単にこのタスクを達成する方法を説明します。

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

このサンプルでは、Playwright とともに GitLab CI/CD を使用します。

GitLab パイプラインでの TestRail CLI の使用

GitLab リポジトリのルートに .gitlab-ci.yml ファイルを追加することで GitLab パイプラインを作成できます。このファイルによって、YML 構文を使用した構造化された方法でプロセスを指定できます。順次または並行して実行されるジョブを使用して、パイプラインの複数のステージを定義できます。

TestRail と GitLab CI/CD を統合する最も簡単な方法は、.gitlab-ci.yml ファイルのいずれかのステージで TestRail に自動テストの結果を送信するよう TestRail CLI を設定することです。次のサンプルは、テスト自動化フレームワークとして Playwright を使用し、TestRail CLI を使用してテスト結果を TestRail に送信する GitLab パイプラインを示しています。

stages:
  - playwright_tests
  - trcli_results_upload

playwright_tests:
  stage: playwright_tests
  image: node:latest
  artifacts:
    when: always
    paths:
      - test-results/
  allow_failure: true
  script:
    - npm install
    - npx playwright install-deps
    - npx playwright install
    - npx playwright test

trcli_results_upload:
  stage: trcli_results_upload
  image: python:latest
  dependencies:
    - playwright_tests
  script: |
    pip install trcli
    trcli -y \
      -h https://TESTRAIL_INSTANCE.testrail.io/ \
      --project "PROJECT NAME" \
      -u USER_EMAIL \
      -p PASSWORD \
      parse_junit \
      -f "test-results/junit-report.xml" \
      --run-description "URL: $CI_PIPELINE_URL" \
      --title "Automated Tests from GitLab CI/CD"

ファイルを細かく見ていくと、注目するべき点がいくつかあります。

- このパイプラインファイルには 2 つのジョブが定義されています。
  1.playwright_tests では、サンプル自動テストプロジェクトが実行されます。
  2.trcli_results_upload では、生成された結果を TestRail にアップロードします。
- デフォルトでは、ジョブは並行して実行されます。この例では、自動テスト実行が完了した後に結果を送信したいので、stages セクションを使用してジョブを実行する順序を指定します。
- 生成された成果物 (この場合は JUnit の結果ファイル) を共有するため、trcli_results_upload ジョブの dependencies で設定された playwright_tests ジョブで artifacts パスを宣言しています。

このサンプルでは、テスト実行と結果のアップロードは、2 つの個別のジョブとして実行されます。なぜなら、この 2 つは別のテクノロジーを使用するため、実行に適切なコンテナー image を必要とするからです。2 つを同じジョブで実行するには、Node.js および Python の両方を含むコンテナーを作成する必要があります。

パイプライン機能の詳細については公式の GitLab CI/CD ドキュメントを参照してください。

ステップ 1: Playwright 自動テストの実行

playwright_tests ジョブは、Node.js コンテナーで実行されます。コンテナーには、Playwright を実行できる主要なテクノロジーが含まれています。

上で説明したとおり、次のジョブでは、TestRail CLI が解析対象の JUnit レポートを使用できるよう、artifacts パラメーターが必要です。when: always パラメーターに注目してください。これは、自動テストが失敗したためにジョブが失敗した場合でも成果物を保存するために必要です。 paths パラメーターは、利用したいパス (この場合は test-results/ フォルダー) のリストで構成されます。Playwright プロジェクトは、このフォルダーに JUnit レポートを出力するよう設定されています。

allow_failure パラメーターは、テストが失敗した場合でも次のステップを実行し、テスト結果を TestRail にアップロードするために使用されます。

script は、Playwright プロジェクトおよび依存関係のインストールから自動テストの実行までの一連のシェルコマンドで構成されます。

playwright_tests:
  stage: playwright_tests
  image: node:latest
  artifacts:
    when: always
    paths:
      - test-results/
  allow_failure: true
  script:
    - npm install
    - npx playwright install-deps
    - npx playwright install
    - npx playwright test

ステップ 2: TestRail への結果のアップロード

trcli_upload_results ジョブは、 Python コンテナーでシェルスクリプトを実行して TestRail CLI のインストールと呼び出しを行い、Playwright によって生成された JUnit レポートを解析して結果を TestRail に送信します。

dependencies パラメーターは、ジョブが結果のアップロードに必要な playwright_tests JUnit 結果ファイルにアクセスするために必要です。

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

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

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

trcli_results_upload:
  stage: trcli_results_upload
  image: python:latest
  dependencies:
    - playwright_tests
  script: |
    pip install trcli
    trcli -y \
      -h https://TESTRAIL_INSTANCE.testrail.io/ \
      --project "PROJECT NAME" \
      -u USER_EMAIL \
      -p PASSWORD \
      parse_junit \
      -f "test-results/junit-report.xml" \
      --run-description "URL: $CI_PIPELINE_URL" \
      --title "Automated Tests from GitLab CI/CD"

動作するサンプルの設定

GitLab CI/CD パイプラインを使用するには、 GitLab にアクティブなアカウントがあり、そこにコードがホストされている必要があります。

固有のリポジトリの作成

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

次の手順に従うと、自動テストプロジェクトを実行し、結果を TestRail に送信する GitLab パイプラインの動作するサンプルをすばやくセットアップできます。

1. GitLab での新規プロジェクトの作成
2. ローカルマシンに新しく作成したプロジェクトをクローンします。
3. Playwright サンプルプロジェクトのファイルをダウンロードし、ローカルプロジェクトにファイルを追加します。
4. プロジェクトのルートに .gitlab-ci.yml ファイルを作成し、このページのパイプラインスニペットのサンプルを追加します。
5. ファイルの TESTRAIL_INSTANCE、PROJECT NAME、USER_EMAIL および PASSWORD をユーザー固有の情報に置き換えます (パスワードは直接置き換えずGitLab 変数を使用することを推奨します)。
6. GitLab でファイルをプロジェクトリポジトリにプッシュします。

パイプラインの実行

1. パイプラインは CI/CD 用に設計されています。つまり、新規コミットのたびにパイプラインが実行されます。初めて GitLab にコードをプッシュすると、ただちにパイプラインが実行され、自動テストプロジェクトを実行して結果を TestRail に送信します。パイプラインを参照するには、左側のパネルで [CI/CD] > [Pipelines] に移動します。最初のパイプラインの実行の詳細が表示されています。すべてが期待どおり実行されている場合、パイプラインが成功し、警告がレポートされているはずです。
2. パイプラインの status をクリックすると、より詳細な実行の情報を含む新しいページが表示され、パイプラインの概要を確認できます。次の画像のように、パイプラインは失敗した playwright_tests ジョブと成功した trcli_results_upload ジョブで構成されます。
3. playwright_tests ジョブをクリックすると、実行時間、成果物、コンソールログなどのジョブの実行の詳細が表示されます。コンソールログをざっと確認すると、1 つのテストが失敗しているために、ジョブも失敗していることがわかります。
4. trcli_results_upload ジョブをクリックすると、同じ情報が表示されます。ログを参照すると、TestRail CLI の出力から、7 つのテスト結果が TestRail に送信され、結果がサブミットされたテストランに移動できるよう URL が設定されていることがわかります。
5. ログの URL をクリックすると、TestRail に移動し、Playwright 自動テストプロジェクトのすべてのテスト結果を含む新しく作成されたテストランを参照できます。GitLab パイプラインへの URL もあることに注目してください。これは、テストランで発生した問題をデバッグする必要がある場合にトレーサビリティを維持するのに役に立ちます。
6. 上で説明したとおり、初めてテスト自動化コードをプッシュした後、コミットによって自動的にトリガーされた 1 つのパイプラインが表示されます。自動プロジェクトのコードに変更を加えずに自動テストケースを再実行したい場合、メイン画面の [Run pipeline] ボタンをクリックすると、新しいパイプラインを手動でトリガーし、実行対象のブランチを選択してランをサブミットできます。

次のステップ

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

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