TestRailとPostmanを連携して、APIテストを自動化しよう！

# はじめに〜TestRailとは？〜
TestRailはテスト管理ツールで、テストケース、テスト結果、エビデンス、レポートなどのテストに関する成果を全て一元管理できます。
TestRailでは以下のようにテストで辟易するような方向けのサービスです。

* 従来のExcelによる辟易するような属人性の高いフォーマット
* バラバラの場所で管理され、探すのに苦労するテスト結果エビデンス
* 最終結果が出てくるまで不透明なテスト進捗状況
* ファイル上書きなどによるテスト結果の意図しない(?)改竄

このようにTestRailは、Excelと比較してチームコラボレーション、リアルタイムの進捗状況追跡、テスト自動化、レポート自動生成、バージョン管理など、多くの利点があります。


## TestRailの使い方をざっくりと解説
まずはTestRailについて、使い方をざっくり解説します。

:::note warn
なお、説明で用いる画像はオンプレ版v7.0.2と少し古めのTestRailとなります。
最新のver.8では、グラフやレポート機能が強化されているだけでなく、承認者機能なども追加されています。
詳細は以下をご確認ください。
https://www.techmatrix.co.jp/nc/news/testrail_20231018_newsrelease.html
:::

まずTestRailにログインすると最初の画面で、プロジェクトのダッシュボードが閲覧できます。
![testrail1a.jpg](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3706974/8d162d16-bbd5-8e23-e812-aebb7cfb99b8.jpeg)

以下は既にプロジェクトとテストケースがある前提です。
ダッシュボードから対象プロジェクトの**テストケース**を選択します。
すると、こんな感じでテストケース一覧が見えます。
![testrail3.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3706974/f6d05f60-1739-588c-37ae-a1fa50696a5b.png)

テストケースの詳細を開くとこのように、**テストの事前条件、手順（ステップ）、期待される結果**などが書いてあります。
これらの項目はプロジェクト内で項目を揃えることができるため、テスト仕様書の属人性を排除できます。
![testrail2a.jpg](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3706974/c7c41dfc-b6df-d4e0-87c9-ea7fbed56153.jpeg)

次に**テストランと結果**を開きます。
テストランでは、プロジェクトにおける各テストの進捗状況を一目で確認できます。
また、各テストに入るとより詳細なテスト状況やテスト結果などを確認することができます。
![testrail4.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3706974/f2aa8656-c6e5-f0b5-9a6e-ce90fa2d4c71.png)


# 本題〜TestRailでAPIテストを記録する〜
前置きが長くなりましたが、以下本題です。

現代のモバイルアプリを含むWebサービスでは、API(Application Programming Interface)によりフロントエンド（ブラウザやWebサイト）とバックエンド（サーバー、エンジンなど）を分離するケースが多いかと思います。

そのため、APIテストはフロントエンドとバックエンドをつなぐ重要な役割を果たしており、ローンチ時だけでなくアップデート時にも網羅的にテストしていくことが重要です。


## TestRailでの作業
### APIを有効化する
最初に管理->サイト設定から、**APIの有効化**をチェックして、設定を保存します。
![testrail5.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3706974/26e2add7-5e13-ebb7-5165-845735ecf935.png)


### ①APIキーを発行する
次に、一番上にある自分のアカウント名をクリックし、個人設定を選択します。
APIキーのタブを開き、キーの追加からAPIキーを追加します。
![testrail6a.jpg](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3706974/e7971c6f-3983-7115-35a6-92facf7ee685.jpeg)

追加したキーは大切に保管しておきましょう。


### ②プロジェクトとテストケースを登録する
プロジェクトを作成し、テストケースを登録します。
この時登録した**プロジェクトID**と**テストケースID**を利用しますので、控えておきます。

:::note
プロジェクトIDは、**P**をプレフィックスとして1からインクリメントされます。
テストケースIDは、**C**をプレフィックスとして1からインクリメントされます。
:::


### ③テストランを追加する
テストケースを作成したら、テストランを追加します。
テストランと結果のタブから**テストランの追加**を選択します。
追加したらテストランIDを控えておきます。

:::note
テストランIDは、**R**をプレフィックスとして1からインクリメントされます。
:::

## Postmanでの作業
次にPostmanでのAPIテストの設計を行います。

### ⓪APIテストツール"Postman"とは？
Postmanは、APIを設計、構築、テストなどのAPIに関わるあらゆる開発工程を支援するツールです。
APIテストツールに限定されているわけではありませんが、個人的にテストツールとして利用しています。

:::note info
Postmanでは、モックサーバーを簡単に構築できたり、Postmanで作成したAPIコレクションをOpenAPIの仕様書としてエクスポートすることもできます。
最近では**Flows**という機能により、APIをノーコードでグラフィカルに接続していくだけで簡単なアプリのようなものまで作ることができます！

と言っても、テストツールとしての機能が強力すぎて、多くのユーザーがテストツールとして活用されていると思います。
:::

### ①コレクションを作成する
APIテストをPostmanのコレクションで作成します。
左ペインにてコレクションを新規作成し、コレクション内にAPIを追加していきます。

![testrail7a.jpg](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3706974/a6d49883-117c-a894-3676-0ecaf3302ace.jpeg)

:::note
APIがない場合は、Postman Echo(postman-echo.com/get)のようなサンプルで構いません。
:::


### ②テストコードを書く
作成したAPIの**Scripts（以前はTests）タブ**を開き、以下のようなテストコードを記載します。

```javascript
pm.test("C1 Status code is 200", function () {
    pm.response.to.have.status(200);
});
```
:::note warn
Postmanのテストコードでは、```pm.test()```メソッドの先頭にTestRailで登録した**テストケースID**を記載してください。
テストケースIDは**C**を含めるようにしてください。
:::

:::note
複数のPostmanテストが同じテストケースに属している場合は、それぞれにテストケースIDを追加してください。
また、複数のTestRailテストケースを1つのPostmanテストに追加することもできます。
:::

### ③コレクションをエクスポートする
コレクション内にAPIテストの作成が完了したら、コレクションをエクスポートして保存します。
エクスポートしたコレクションは、PostmanのCLI版である**Newman**で利用します。


## 実行環境
Postmanの試験結果をTestRailで登録する方法を確認します。
今回はAWS Cloud9を使って実行しますが、ローカルやLinuxサーバーなどお手持ちの環境でも構いません。

### ①環境設定
以下のコマンドを実行し、NewmanとTestRail用レポーターをインストールします。

```sh
npm install -g newman
npm install -g newman-reporter-testrail
```

また、エクスポートしたPostmanコレクション(collection.json)をディレクトリに追加しておきます。


### ②環境変数を登録する
TestRailに必要な環境変数を登録します。

```sh
export TESTRAIL_DOMAIN=example.testrail.io
export TESTRAIL_USERNAME=test.user@example.com
export TESTRAIL_APIKEY=yourkey
export TESTRAIL_PROJECTID=1
export TESTRAIL_RUNID=10
```

|項目|内容|
|--|--|
|TESTRAIL_DOMAIN|TestRailが稼働しているホスト名|
|TESTRAIL_USERNAME|APIキーを発行したユーザー名|
|TESTRAIL_APIKEY|発行したAPIキー|
|TESTRAIL_PROJECTID|テストケースを登録したプロジェクトID|
|TESTRAIL_RUNID|追加したテストランID|


### ③NewmanでAPI試験を実行し、TestRailに登録する
以下スクリプトでNewmanでAPI試験を実行し、TestRailに登録します。

```sh
newman run collection.json --reporters cli,testrail
```


## 実行結果
以下NewmanでAPI試験が実行され、TestRailに結果が記録されます。

```sh
newman

TestRail Sample

→ C1 sample1
  GET postman-echo.com/get [200 OK, 823B, 436ms]
  ✓  C1 Status code is 200

→ C2 sample2
  GET postman-echo.com/get [200 OK, 931B, 176ms]
  ✓  C2 Status code is 200

┌─────────────────────────┬─────────────────────┬────────────────────┐
│                         │            executed │             failed │
├─────────────────────────┼─────────────────────┼────────────────────┤
│              iterations │                   1 │                  0 │
├─────────────────────────┼─────────────────────┼────────────────────┤
│                requests │                   2 │                  0 │
├─────────────────────────┼─────────────────────┼────────────────────┤
│            test-scripts │                   2 │                  0 │
├─────────────────────────┼─────────────────────┼────────────────────┤
│      prerequest-scripts │                   0 │                  0 │
├─────────────────────────┼─────────────────────┼────────────────────┤
│              assertions │                   2 │                  0 │
├─────────────────────────┴─────────────────────┴────────────────────┤
│ total run duration: 697ms                                          │
├────────────────────────────────────────────────────────────────────┤
│ total data received: 1.08kB (approx)                               │
├────────────────────────────────────────────────────────────────────┤
│ average response time: 306ms [min: 176ms, max: 436ms, s.d.: 130ms] │
└────────────────────────────────────────────────────────────────────┘
```

![testrail8a.jpg](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3706974/da841849-c034-4bbb-2fd1-8e8fa67d56b6.jpeg)


## おまけ：CI/CDアーキテクチャ
上記処理をCodePipelineにより自動CI/CDを組むことができます。
以下アーキテクチャではAWS上のサーバーレスアーキテクチャに対して、PosmantのAPIテストコードをCodeCommitで管理し、CodeBuildでNewmanを実行しています。

![testrail_arch.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3706974/af19e78b-23ad-6deb-91b5-6ee914e86e80.png)

:::note
なお、TestRailはコンテナ上で稼働していますが、オンライン版TestRailでも問題ありません。
:::

# まとめ
今回はTestRailとPostmanの連携によるAPIテストの自動化についてまとめました。