POSTMAN、Playwrightで実行したテスト結果をTestRailに連携してみた！

# はじめに
TestRailは、ソフトウェアテスト管理を効率的に行うための強力なツールです。特に、複数のテストケースを一元管理することで、プロジェクトの進行状況を把握しやすくなります。エクセルやスプレッドシートのテストケースをTestRailで管理することはもちろん、APIテストや自動化されたエンドツーエンド（E2E）テストの結果も統合できれば、さらなる利便性が期待できます。

そこで今回は、APIテストツールのPOSTMANと、E2EテストフレームワークのPlaywrightを用いて、テスト結果をTestRailに反映させる方法について紹介します！

# POSTMANで実行したテストをTestRailに連携する

[参考にした記事](https://icehousecorp.com/leveraging-postman-and-testrail-for-progression-and-regression-api-testing/)

## 事前準備(インストール)

* [POSTMAN](https://www.postman.com/downloads/)

* [Node.js](https://nodejs.org/en/download/package-manager/)

  * NEWMANを利用するために必要になります。

* NEWMAN

  * Node.js をインストールした後,ターミナルから以下を実行します。
   ```npm install -g newma```


* NEWMANのプラグインをインストールします。

  * `npm install -g newman newman-reporter-htmlextra newman-reporter-testrail`
    * [newman-reporter-htmlextra](https://www.npmjs.com/package/newman-reporter-htmlextra)
    * [newman-reporter-testrail](https://www.npmjs.com/package/newman-reporter-testrail)

## TestRailの環境変数の設定

.zshrcファイルにTestRailの環境変数を設定します。
（以下の設定は必須項目のみになります。）

```.zshrc
export TESTRAIL_DOMAIN=<TESTRAIL_URL>   #https://以降から.comまでのドメイン名
export TESTRAIL_USERNAME=<TESTRAIL_USERNAME>  #　#TestRailに登録しているユーザーのメールアドレス
export TESTRAIL_APIKEY=<TESTRAIL_API_KEY>  #TestRailで生成したAPI key
export TESTRAIL_PROJECTID=<PROJECT_ID_WITHOUT_PREFIX_P>  #プロジェクトのID
```

オプションなど具体的に何を設定したら良いのかはプラグインの[ドキュメント](https://www.npmjs.com/package/newman-reporter-testrail#usage)を確認してください。


変更を加えた後は以下のコマンドを実行して反映させましょう。

`source ~/.zshrc`

↑↑
こちらを実行するのを忘れてしまうとうまく結果を連携することができません。

## POSTMANのテストスクリプトにTestRailのテストケースIDを紐付ける

1. テストスクリプトの先頭に定数を宣言して、実施したいTestRailのテストケースIDを格納します。
   1. `const tc_id = "Cxxxxxxx";`

2. テストケースのタイトルにstep1で定義したIDの変数を追加します。
   1. `` `${tc_id} test case title` ``

![スクリーンショット 2024-07-17 21.16.03.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/385025/d12263a2-9f6e-b040-de8e-6d99920e0b07.png)





## NEWMANでテストを実行する

ターミナルで以下のコマンド実行をします。
```
newman run "テスト対象のファイル or URL"  -r testrail --reporter-testrail-configFile　testrail-config.json --reporter-testrail
```


テスト実行後に連携に成功した場合、ターミナルにテスト結果のURLが表示されます。
テストランのURLにアクセスしてテスト結果を確認します。

![スクリーンショット 2024-07-17 21.18.53.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/385025/76bf0180-2113-e690-8c80-d06938084c24.png)




# Playwrightで実行したテスト結果をTestRailに連携する

[公式ドキュメント](https://docs.testrail.techmatrix.jp/testrail/docs/801/test-automation/automation-frameworks/playwright/)

## 事前準備(インストール)

1. [Playwright](https://playwright.dev/docs/intro#installing-playwright)のインストール
   1. ターミナルで以下を実行しPlaywrightをインストールします。
      1. `npm init playwright@latest`

      2. インストール後は以下のディレクトリ構成になります。

         ```
          │── node_modules
          │── tests
          │   └── example.spec.ts   
          │── tests-examples
          │   └── demo-todo-app.spec.ts
          │── .gitignore
          │── package-lock.json
          │── package.json
          └── playwright.config.ts   # Playwrightの設定を追加するファイル
         
         ```
2. [pip](https://pip.pypa.io/en/stable/installation/)のインストール(Pythonの環境構築が必要です。)
   1. `python get-pip.py`
3. TestRail CLIのインストール
   1. ターミナルで以下を実行しtrcliをインストールします。
   2. `pip install trcli`
4. 上記のコマンドで以下のエラーが発生する可能性があります。
   1. × This environment is externally managed
      ╰─> To install Python packages system-wide, try brew install
      xyz, where xyz is the package you are trying to
      install.
   2. [PEP668](https://docs.brew.sh/Homebrew-and-Python#pep-668-python312-and-virtual-environments) に準拠してパッケージのインストールを行う必要があるとのことです。
      1. 参考にした[記事](https://qiita.com/yokoto/items/6d9e7d0ee440b3d147ac)
5. [仮想環境を作成](https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-and-using-virtual-environments)する
   1. `$ python -m venv .python/venv`
6. 仮想環境のアクティベートを行う
   1. `$ source .python/venv/bin/activate`
7. 再度TestRail CLIのインストールを試してみてください。
8. 仮想環境を終了する
   1. `$ deactivate`

## PlaywrightでJUnit形式のテストレポートを準備する

1. playwright.config.tsにて、レポートの形式を[設定](https://playwright.dev/docs/test-reporters#junit-reporter)します。
   1. ```playwright.config.ts
        reporter: [
          ['junit', { outputFile: 'results/junit-results.xml' }],
        ],
      ```
2. Playwrightでテストを実行します。
   1. `npx playwright test`
3. テスト実行後に、playwright.config.tsのreporterで設定したディレクトリにテストレポートが出力されます。

## TestRail のカスタムフィールドの設定

1. 自動テスト ケースのコードと実際の TestRail のケースをマッピングするための **[カスタム フィールド](https://docs.testrail.techmatrix.jp/testrail/docs/801/user-guide/administration-and-customizations/custom-fields/)** を作成します
2. 。それには、**\[管理\] > \[カスタマイズ\]** に移動して \[**フィールドの追加**\] をクリックします。
3. フィールド作成画面に移動したら、下記の 2 つの要件に従ってフィールドを作成します。
   * **システム名**は *automation_id*
   * **タイプ**は *String*

## TestRailとPlaywrightの設定

TestRailのテストケース名とPlaywrightのテストケース名は一致させた方が良さそうです。

* TestRailのテストケース名
![スクリーンショット 2024-07-17 21.11.55.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/385025/e78f3890-f619-197f-2023-9604b2932073.png)

* Playwrightのテストケース名
![スクリーンショット 2024-07-17 21.11.02.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/385025/3178a16f-8446-662b-db46-11f39a46f817.png)


## TestRail CLIを使用してテストレポートをTestRailに連携させる

1. ターミナルで以下のコマンドを実行します。

```
trcli -y \
 -h "ドメインURL"/\  //https://xxx.com
--project "プロジェクト名"\
--username "登録したメールアドレス"\
--password "API_KEY"\
parse_junit\
--title "テストラン名"\
--suite-name "テストスイート名" \
-f "./results/junit-results.xml"\ //対象のテストレポートのパス
```

2. テストレポートファイルについて、ブラウザごとに同じテストケースを実施している場合、テストスイートのnameが重複するため、テストスイートごとにname属性を設定します。
![スクリーンショット 2024-07-17 21.12.40.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/385025/31835583-e6eb-856c-39f4-ffd29c958fdc.png)

 
3. TestRailの連携が成功した場合、ターミナルにレポートのURLが表示されます。
 
4. TestRailのテストラン画面で結果を確認します。
![スクリーンショット 2024-07-17 21.13.54.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/385025/c4a6e149-2313-737e-73a7-70ef3833bd34.png)

   

# 終わりに

TestRailを使用することで、テストケースの一元管理が容易になり、APIテストやE2Eテストの結果を効率的に管理できます。POSTMANやPlaywrightとの連携により、手動での結果登録の手間を省くことができ、テストプロセス全体の効率が向上します。今後もさらなる自動化と統合を目指して、より良いテスト環境を構築していきましょう！！