Jenkins との統合 (freestyle)

Jenkins は主要なオープン ソースの自動化サーバーであり、プロジェクトのビルド、デプロイ、自動化をサポートする多数のプラグインを提供しています。Jenkins は単に CI サーバーとして使用することも、継続的デリバリーのハブとすることもでき、Web インターフェイスを使用したセットアップと設定が容易です。

Jenkins のよくある使用方法は、コードの変更がサブミットされるたびにアプリケーションのビルドとテストを行うというものです。TestRail の利点を最大限に活用し、手動のものも自動化されたものも含めてすべてのテスト ケースおよびテスト結果を管理するため、Jenkins から直接 TestRail に自動テストの結果を送信できます。このマセクションでは、Jenkins freestyle プロジェクト と TestRail CLI を利用して簡単にこのタスクを達成する方法を説明します。

前提条件

1. 1. 次の内容を Dockerfile という名前のファイルに保存します。

      FROM jenkins/jenkins:lts
      
      USER root
      RUN apt-get update
      RUN apt-get install -y \
              build-essential \
              zlib1g-dev \
              libncurses5-dev \
              libgdbm-dev \
              libnss3-dev \
              libssl-dev \
              libreadline-dev \
              libffi-dev \
              libsqlite3-dev \
              wget \
              libbz2-dev
      RUN wget https://www.python.org/ftp/python/3.10.0/Python-3.10.0.tgz && \
              tar -xvf Python-3.10.0.tgz && \
              cd Python-3.10.0 && \
              ./configure --enable-optimizations && \
              make -j 2 && \
              make altinstall && \
              python3.10 --version
      USER jenkins

   2. ファイルを保存したディレクトリでコマンド ラインを開きます。
   3. 次のコマンドを実行します。

      docker build -t jenkins:local .
      docker run -p 8080:8080 -p 50000:50000 jenkins:local

   4. コンソールのキーをコピーし、ブラウザーで http://localhost:8080 を開きます。
   5. インストール ウィザードに従います。

新規 Jenkins ジョブの作成

1. 1. Jenkins インスタンスで [New Item] をクリックします。
   2. [New Item name] に入力し、[Freestyle project] を選択して [OK] をクリックします。

Git リポジトリのセットアップ

このサンプルでは、Git リポジトリを使用して自動テスト プロジェクトを取得します。ここでは、TestRail の GitHub プロジェクトのサンプル automation-frameworks-integration を使用します。

1. 1. [Source Code Management] セクションで [Git] を選択します。
   2. [Repository URL] に URL を指定します (今回のサンプルでは https://github.com/gurock/automation-frameworks-integration.git)。
   3. [Branch Specifier] にブランチを指定します (今回のサンプルでは */main)。

ビルド ステップの設定

1. 1. [Build] セクションの [Add build step] ドロップダウンを使用して [Execute shell] ステップを追加します。
   2. [Execute shell ] ステップの [Command] に以下を行うためのコマンドを含むスクリプトを挿入します。
      • 環境のセットアップ
      • テスト プロジェクトの実行
      • TestRail CLI を使用したテスト結果のアップロード

      

シェル スクリプトの詳細

次のコードは、上のステップで使用されたスクリプトのコピーと、各セクションの簡単な説明です。

# Go to test project folder
cd samples/python/pytest

# Setup virtual environment
python3.10 -m venv ./venv
. ./venv/bin/activate

# Install and run test project
pip install -r requirements.txt
pytest --junitxml "reports/junit-report.xml" "./tests" || pytest_exit_code=$?

# Install TestRail CLI and upload test results
pip install trcli
trcli -y \
  -h "https://INSTANCE.testrail.io" \
  -u "USER_EMAIL" \
  -p "API_TOKEN" \
  --project "PROJECT NAME" \
  parse_junit \
  --title "Automated Test Run" \
  --run-description "CI Build: ${BUILD_URL}" \
  -f "reports/junit-report.xml"
    
# Exit with Pytest exit code
exit $pytest_exit_code

スクリプトは、まず、実行する自動テスト プロジェクトを含む Pytest サンプル プロジェクトのベース フォルダーに移動します。

# Go to test project folder

次に、プロジェクト専用の Python 仮想環境を作成します。仮想環境を作成するのは、確実に一貫性のあるベースラインから始められる良いプラクティスです。仮想環境を作成したらアクティベートする必要があります。つまり、グローバルな Python の代わりにこの環境を使用します。

# Setup virtual environment

仮想環境をアクティベートしたら、Pytest テスト プロジェクトを直接インストールして実行できます。--junitxml "reports/junit-report.xml" オプションに注目してください。これは、TestRail CLI で使用可能な JUnit 形式のレポートを生成するよう Pytest に指示します。詳細な説明は Pytest との統合マニュアルにあります。このスクリプトで注目すべきもう 1 つの詳細は pytest コマンドの後の || pytest_exit_code=$? です。これは、テストが失敗し、Pytest がエラー終了コードを返してジョブ実行全体を中断するような場合でも続行するようシェルに指示します。後で pytest_exit_code でスクリプトを終了し、テスト結果に従ってビルドを成功または失敗させます。この動作を実現する方法や利用できるプラグインは多数ありますが、これがサンプルの目的を達成する最も簡単な方法です。

# Install and run test project

テストの実行が正常に完了した場合 (失敗したテストの有無にかかわらず)、JUnit 形式のレポートが生成され、TestRail に結果をアップロードできます。結果をアップロードするには、 pip を使用して TestRail CLI をインストールし、TestRail インスタンスの情報を指定して実行するだけです。-h、-u、-p および --project のプレースホルダーを置き換える必要があります。もう 1 つ、このスクリプトでの trcli の呼び出しで、ささいですが役に立つ情報は、--run-description "CI Build: ${BUILD_URL}" オプションです。このオプションは、現在の Jenkins ビルド URL を TestRail のテスト ランに追加し、簡単にビルドに戻れるようにします。最後に推奨事項として、パスワードや API トークンをスクリプトで直接使用せず、Jenkins credentials manager を使用します。

# Exit with Pytest exit code

上でも述べたように、元の Pytest の終了コードでスクリプトを終了しているため、Jenkins に実際の自動テスト実行の結果が伝えられます。

ジョブの実行

1. 1. 上で設定したジョブを保存したら、ジョブを実行します。それには、左パネルの [Build Now] アクションをクリックします。
   2. ジョブが完了したら、ビルドの [Console Output] ページのログをざっと見て、スクリプトが期待どおり実行されたことを確認できます。テスト実行が問題なく完了し、TestRail CLI が適切に設定されており、指定された場所でテスト結果の JUnit レポートを発見できた場合、TestRail CLI がテスト結果を TestRail インスタンスにサブミットしたことがログで確認できるはずです。
   3. 最後に、TestRail を開いて [テスト ランと結果] ページに移動すると、 Automated Test Run という名前で新しく実行されたランがあり、テスト結果とともに、このテスト ランを生成した Jenkins ジョブ ビルドへのリンクが表示されています。

次のステップ

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

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