Azure Pipelines との統合

Azure Pipelines は、Microsoft Azure DevOps ツールセット内の CI/CD オーケストレーションプラットフォームであり、任意のプラットフォームおよびクラウドへの継続的なビルド、テスト、デプロイを可能にします。Microsoft のクラウドホスト型エージェントを使用するか、独自のホスト型エージェントを設定することで、ハードウェアと VM を管理できます。また、あらゆる主要なプラットフォームやツールの CI/CD パイプラインをフルサポートし、Azure Repos Git、GitHub、Bitbucket などとの統合が可能です。

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

※TestRail CLI は、テスト自動化フレームワークによって、互換性のある JUnit レポートが生成されることを必要とします。このサンプルでは、Playwright とともに Azure Pipelines を使用します。

前提条件

※このセクションでは、Azure セルフホスト型カスタムエージェントのセットアップ方法について説明します。クラウドホスト型のエージェントを使用している場合は、このセクションを省略して次のセクションに進むことができます。

セルフホスト型エージェントを使用する場合 (独自にエグゼキューターを管理したい場合、または単にクラウドホスト型エグゼキューターをサブスクライブしていない場合)、TestRailの自動化統合サンプルリポジトリから、TestRail CLI を実行するために Python 3.10.12 がプリインストールされた docker エージェントをビルドして実行するスクリプトを入手できます。

エージェントをビルドするには、 <AZURE_URL> プレースホルダーをインスタンスへの URL (例: https://dev.azure.com/yourorganization) に置き換え、 <TOKEN> プレースホルダーを Azure Personal Access Token に置き換え、スクリプトと同じフォルダーで開始したターミナルで次のコマンドを実行するだけです。

docker build -t azureagent:latest .
docker run -e AZP_URL="<AZURE_URL>" -e AZP_TOKEN="<TOKEN>" -e AZP_AGENT_NAME="SelfHostedLinux" azureagent:latest

Azure Pipelines での TestRail CLI の使用

互換性のある任意のリポジトリのルートに azure-pipelines.yml ファイルを追加することでパイプラインを作成できます。このファイルによって、YML 構文を使用した構造化された方法でプロセスを指定できます。パイプラインを構成する際、環境のセットアップなどの目的を達成するタスクのほか、任意の目的に対応するシェルコマンドを記述できるスクリプトなど、タイプの異なるステップを定義できます。

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

trigger:
- main

pool:
  vmImage: ubuntu-latest

steps:
- task: NodeTool@0
  inputs:
    versionSpec: '16.x'
  displayName: 'Install Node.js'
- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.10.12'
  displayName: 'Setup Python'

- script: |
    npm install
    npx playwright install-deps
    npx playwright install
    npx playwright test
  displayName: 'Run Playwright tests'
  continueOnError: true
- script: |
    pip install trcli
    trcli -y \
      -h "https://INSTANCE-NAME.testrail.io" \
      --project "PROJECT-NAME" \
      -u "USERNAME" \
      -p "PASSWORD" \
      parse_junit \
      -f "test-results/junit-report.xml" \
      --title "Playwright automated tests" \
      --run-description "$(System.TeamFoundationCollectionUri)$(System.TeamProject)/_build/results?buildId=$(Build.BuildId)"
  displayName: 'Upload results with TestRail CLI'

セルフホスト型エージェントの使用

trigger:
- main

pool: Default

steps:
- task: NodeTool@0
  inputs:
    versionSpec: '16.x'
  displayName: 'Install Node.js'
- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.10.12'
    disableDownloadFromRegistry: true
  displayName: 'Setup Python'

- script: |
    npm install
    npx playwright install-deps
    npx playwright install
    npx playwright test
  displayName: 'Run Playwright tests'
  continueOnError: true
- script: |
    pip install trcli
    trcli -y \
      -h "https://INSTANCE-NAME.testrail.io" \
      --project "PROJECT-NAME" \
      -u "USERNAME" \
      -p "PASSWORD" \
      parse_junit \
      -f "test-results/junit-report.xml" \
      --title "Playwright automated tests" \
      --run-description "$(System.TeamFoundationCollectionUri)$(System.TeamProject)/_build/results?buildId=$(Build.BuildId)"
  displayName: 'Upload results with TestRail CLI'

ファイルを詳細に確認すると、以下が記述されています。

- CI アプローチで、 main にプッシュがあるたびにジョブを開始するよう設定された trigger
- ステップが実行されるエージェントを定義する pool。これは、クラウドホスト型エージェントを使用するか、セルフホスト型エージェントを使用するかによって異なります。
- steps には、環境をセットアップする 2 つのタスクと、テストを実行して結果をアップロードする 2 つのスクリプトがあります。
  1. task: NodeTool@0
  2. task: UsePythonVersion@0
  3. script (Run Playwright tests)
  4. script (Upload results with TestRail CLI)

パイプラインの設定方法については、公式の Azure Pipelines ドキュメントを参照してください。

ステップ 1: Node.js をインストールする

NodeTool@0 タスクを使用すると、Playwright テストの実行に必要な node を簡単にエージェントにインストールできます。

- task: NodeTool@0
  inputs:
    versionSpec: '16.x'
  displayName: 'Install Node.js'

ステップ 2: Python をセットアップする

UsePythonVersion@0 タスクは、TestRail CLI のインストールと実行に必要な Python をセットアップします。このタスクは、クラウドホスト型エージェントでジョブを実行するか、セルフホスト型エージェントでジョブを実行するかによって、設定を変える必要があります。

クラウドホスト型エージェントでは、 versionSpec を追加するだけで、必要なバージョンのダウンロードとエージェントへのインストールをタスクが行います。

セルフホスト型エージェントの場合、タスクは Python をダウンロードしてインストールすることができないため、エージェント内ですでに設定されている必要があり、 disableDownloadFromRegistry: true 入力コンフィギュレーションを追加する必要があります。このチュートリアルのコードを使用してセルフホスト型エージェントをセットアップすると、エージェントにはすでに Python 3.10.12 がプリインストールされているため、ユーザー自身がインストールする必要はないことに注意してください。

- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.10.12'
  displayName: 'Setup Python'

ステップ 3: Playwright テストを実行する

Run Playwright tests ステップには、必要なシステム依存関係とともに Playwright プロジェクトをインストールし、テストプロジェクトを実行するシェルスクリプトが含まれています。プロジェクトは test-results/ フォルダにJUnit レポートを生成するように設定されていることに注目してください。

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

- script: |
    npm install
    npx playwright install-deps
    npx playwright install
    npx playwright test
  displayName: 'Run Playwright tests'
  continueOnError: true

ステップ 4: TestRail CLI で結果をアップロードする

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

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

TestRail CLI をインストールした後は、TestRail インスタンスのアドレスおよび認証情報、レポートするプロジェクト、テストランのタイトル、JUnit レポートへのパスなどの必須引数を指定します。--run-description 引数は必須ではありませんが、これを利用して TestRail から Azure Pipelines 実行へのリンクを追加することを推奨します。サンプルコードには、ジョブ実行へのリンクを出力する一連の定義済みパイプライン変数が含まれています。

- script: |
    pip install trcli
    trcli -y \
      -h "https://INSTANCE-NAME.testrail.io" \
      --project "PROJECT_NAME" \
      -u "USERNAME" \
      -p "PASSWORD" \
      parse_junit \
      -f "test-results/junit-report.xml" \
      --title "Playwright automated tests" \
      --run-description "$(System.TeamFoundationCollectionUri)$(System.TeamProject)/_build/results?buildId=$(Build.BuildId)"
  displayName: 'Upload results with TestRail CLI'

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

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

Azure Pipelines を使用するには、 Azure DevOps にアクティブなアカウントが必要です。コードは、Azure DevOps インスタンス内の Azure Repos にホストすることも、GitHub や Bitbucket などの外部ソース管理ツールを使用することもできます。この例では Azure Repos を使用します。

固有のリポジトリの作成

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

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

1. Azure DevOps での新規プロジェクトの作成
2. [Repos] セクションに移動し、 Playwright サンプルプロジェクトのファイルを含む新しいリポジトリを作成します。
3. [Pipelines] セクションに移動し、 [Create Pipeline] をクリックします。
4. 使用するリポジトリタイプを選択します。この場合は Azure Repos Git を選択します。
5. 作成したリポジトリを選択します。
6. 開始点として任意のパイプラインテンプレートを選択します。
7. テンプレートを上記の YML ファイルに置き換えます (必ずプレースホルダー INSTANCE-NAME、 PROJECT-NAME、 USERNAME および PASSWORD を置き換えます。パスワードは直接記述せず、Azure シークレット変数を使用することを推奨します)。
8. [Save and run] をクリックし、リポジトリに azure-pipelines.yml ファイルを作成するコミットを実行します。
9. パイプラインのトリガーはマスターブランチへのプッシュであるため、すぐにジョブが実行キューに追加されます。
10. ジョブをクリックすると実行ログが表示され、末尾にTestRail CLI のログがあります。TestRail CLI は Playwright のテスト結果がレポートされたテスト実行へのリンクを生成します。
11. リンクをクリックすると、TestRail にリダイレクトされ、テスト結果とデバッグ情報が表示されます。トレーサビリティを提供し、移動を容易にするため、ジョブ実行へのリンクが張られています。

次のステップ

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

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

前提条件

Azure Pipelines での TestRail CLI の使用

クラウドホスト型エージェントの使用

セルフホスト型エージェントの使用

ステップ 1: Node.js をインストールする

ステップ 2: Python をセットアップする

ステップ 3: Playwright テストを実行する

ステップ 4: TestRail CLI で結果をアップロードする

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

固有のリポジトリの作成

次のステップ

目次