Hello, community!

 

IrisApiTester アプリを作成した後、それにもっと可能性があることに気付き、いくつか調整することで強力なコラボレーションツールになるのではないかと考えました。

 

そこで、以下の事について検討してみました。

• API コレクションをチーム全体で共有できるか？
• ユニットテストの実行に使用できるか？
• 統合テストにはメリットがあるか？
• CI/CD 継続的インテグレーションレイヤーを追加するとどうなるか？

 

可能な答えを考えた末、試してみることにしました。 作業を終えると、すべての回答が（ある程度）肯定であることがわかりました。 最終的には、この記事を書いて、この経験を皆さんと共有することに決めました。 知識の交換に役立ち、できればアプリケーションを一緒に改善していければと思います。

 

この記事は役に立つと思います。 新しいアプリケーションを検討するきっかけになるかもしれませんし、アジャイルな方法で実行できることを知らなかったテストを、このヒントでやっと実行できるようになることに気付くでしょう。

 

簡潔にするために、この記事を複数のセクションに分けています。 そのため、直接必要な箇所を読むことも、全文を読むこともできるように構成されています。

 

手順にしたがってテストを実行する場合は、すでに IrisApiTester Docker イメージをダウンロード済みで、インスタンスを実行していることが前提です。 そうでない場合は、必要なデータは以前に書いた記事に含まれています:

https://community.intersystems.com/post/iris-api-tester

 

ポイント 1 - チーム間で Postman コレクションを共有する:

 

最初に考えたのは、自分の Postman コレクションをテストと共に同僚全員と共有できるのか、ということです。その解決策は思った以上にかなり単純なものでした。

 

1 つまたは複数の API コレクションを含むリポジトリに Postman を接続できることがわかったのです。 同時に、Postman には、ターミナルなどに切り替えずに Postman からコレクションの更新、コミット、およびその他の操作の実行を行える Git クライアントも含まれていました。 みんなは知っていたことかもしれませんが、私は知りませんでした (^^;)

 

さぁ、準備はいいですか？！ これから、API コレクションを含むリポジトリに Postman を接続する方法を説明します。

 

例として、GitHub にリポジトリを作成しました。 また、Bitbucket にも作成したので、 そちらのサービスの方が好みの場合は、それを使うこともできます。 私のリポジトリへのリンクです:

https://github.com/daniel-aguilar-garcia/postman-collection-test

 

必要であれば、フォークできます。 コレクションには、IrisApiTester のローカルインスタンス（localhost）にある Docker コンテナーを指す単純なテストがいくつか含まれています。

 

まず、リポジトリに Postman を接続します。

 

Postman を開き、「APIs」をクリックして API を作成します。

 

次に、コレクションの名前を選択して、GitHub アイコン（または Bitbucket）をクリックします。

 

認証を求められる場合があります。 求められたら、自分の GitHub ユーザーに接続することを許可してください。

 

許可したら、GitHub ユーザー、API を保存するリポジトリ、およびリポジトリのブランチを選択します。

 

（新規リポジトリでない場合は）接続が完了すると、リポジトリに含まれる API コレクションが表示されます。

 

API 内のすべてのコレクションはメニューにも表示されます。

 

コレクションを変更すると、Git セクションがすぐに更新されるため、 コミット、プル、プッシュなどの操作を実行できます。

 

Postman の有料ライセンスを使用している場合は、共有ワークスペースを作成するだけで開発チーム全員と接続することができますが、 無料のアカウントを使用している場合は、開発チームのすべてのコンピューターで上記のすべての手順を繰り返す必要があります。

 

上記の手順によって、チームメンバーとコレクションを共有し、最新状態に維持するという最初のポイントを完了しました。 唯一の欠点は、無料アカウントを使用している場合に生成できる API が 3 つまでということです。 その場合は、同じリポジトリにすべてのコレクションを配置すると、問題を介できます。

 

ポイント 2 - ユニットテスト:

 

次に解決する課題は、API テストだけでなく、ユニットテストの実行にもツールを使用する方法に関係しています。 この時点で、新しいエンドポイントをテストごとに作成せずに、一番速くテストを生成する方法は何かについて考えてみました。その答えが以下です。

 

ウェブアプリを /run パスに作成しました。

 

また、API のクラスも作成しました。 次のルートを作りました（リポジトリでは、Example パッケージの TestRoutes.cls クラスです）。

 

このウェブアプリとルートを使用すると、すべてのクラスにいわゆる「自動公開」メソッドを確立できます。 API にクラストとメソッド名を渡すだけでこれを達成できます。 以下の例を見てください。

localhost:52773/run/IrisNewman.Example.TestMethods/TestOK

 

この場合、以下のように指定しました。

/run -> ウェブアプリのパス

/IrisNewman.Example.TestMethods -> 実行するメソッドが配置されるクラス

/TestOK -> 実行するメソッド

 

TestOK メソッドでは、ユニットテストの単純なチェック操作が実行されます。

ClassMethod TestOK() As %Status
{
    Set testNumber = 1
    Set a = 1
    Set b = 2
    Set res = ..SumNumbers(a,b)

    Do ..assert(res,3,$G(%methodname),testNumber)

    Quit $$$OK
}

 

このクラスでは、独自の assert メソッドを定義しているのが特徴です。 このメソッドによって、パラメーター 1 と 2 に渡される値が同等であることを確実にしています。 パラメーター 3 はメソッドの実際の名前で、4 はメソッド内のアサーションの数です。 これらの最後の 2 つのパラメーターは、アサーションでエラーが発生した場合に詳細なメッセージを返すために使用されます。 比較されたときに値が一致しない場合、一般のスローで例外をスローし、リクエストのヘッダーに 500 のレスポンスコードを送信します。 すると、Newman のレポートでそのテストがエラーにマークされます。

 

このアプローチでは、以下の操作のみが残っています。

• Postman コレクションへの呼び出しをメソッドに含める。
• 変更をコミットする。 

 

そうすれば、全員のリポジトリでコレクションを更新させることができるようになります。

 

ポイント 3 - 統合テスト:

 

前の手順と同じように、統合テストに使用されているウェブアプリを再利用することができます。 テストの例として、データベースにユーザーを追加しましょう。

localhost:52773/run/IrisNewman.Example.TestMethods/InsertPerson

 

ここでは、以下の項目について指定されています。

/run -> ウェブアプリのパス

/IrisNewman.Example.TestMethods -> 実行するメソッドが配置されるクラス

/InsertPerson -> 実行するメソッド

 

InsertPerson メソッドでは、すべての操作をトランザクション内で実行し、求める値が格納されたことをアサーションで確認しています。 最後に、変更を元に戻すロールバックが含まれています。

ClassMethod InsertPerson()
{

    Set testNumber = 1
    Set method=$G(%methodname)

    TSTART
    Set person=##class(IrisNewman.Example.Entity.Person).%New()
    Set person.IDCard="11111111H"
    Set person.Name="Incognito Guy"
    Set person.Address="False Street, 123"
    Set person.City="Springfield"
    Set res = person.%Save()

    Do ..assert(res,1)

    Set personReaded = ##class(IrisNewman.Example.Entity.Person).%OpenId(person.IDCard)

    Do ..assert(personReaded.Name,"Incognito Guy",method,testNumber)

    TROLLBACK
    Quit $$$OK
}

 

更新や削除などの操作も同じようにテストできるため、必要な統合テストの実行が可能となります。

 

ポイント 4 - CI/CD の追加:

 

「これはこれでいいけれど、もっと自動化させたい。 同僚のテストを自動的に起動するにはどうすればいいのか」と思ってていませんか？

 

このために、アプリに新しいエンドポイントを作成しました（Postman ではなくブラウザで起動する必要があります）。

http://localhost:52773/pull_and_run_tests

 

このエンドポイントは、Git または Bitbucket リポジトリから最新バージョンのコレクションをダウンロードします。 また、それに対してテストを実行し、画面上にテスト結果のレポート（Newman）も表示するようになっています。

 

pull_and_run_test エンドポイントを実行するには、repository.cfg ファイルに、テストのコレクションを保存するリポジトリへのアクセスデータを構成する必要があります。

 

このとき、コミットするたびに自動的にすべてのテストを実行するワークフローをリポジトリに追加すればよくなるのではないかという考えがありました。

 

このための新しいエンドポイントを作ることがアイデアとして浮かびました。

http://localhost:52773/pull_run_and_send_google

 

これは、ApiTesting Docker イメージをダウンロードしてからリポジトリからコレクションをダウンロードし、テストを実行して Google Chat に結果の HTML ファイルの URL と共にメッセージを送信します。

 

これが機能するには、repository.cfg ファイルで、メッセージの受信先である Google Chat チャンネルのウェブフックの URL を構成する必要があります。

 

次の図に、リポジトリにコミット完了ごとのワークフロー実行の例を示します。

 

以下は、例として使用した GitHub ワークフローのコードです。

name: Launch Tests
on:
  push:
    branches:
      - main
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout source code
      uses: actions/checkout@v2
    - name: Clone the irisapitester repository
      run: git clone https://github.com/daniel-aguilar-garcia/irisapitester.git
    - name: Raise Docker Compose
      run: docker-compose up -d
      working-directory: ./irisapitester
    - name: Wait for Docker
      run: sleep 30
    - name: Send report to Google Chat
      id: send_report_google
      run: |

        $(curl -s http://localhost:52773/pull_run_and_send_google)

 

では、受信するメッセージの例を見てみましょう。

（この例では URL のみを送信していますが、 失敗したときにのみ送信するか、「executed Ok / KO」と URL をレポートに送信するようにプログラムすることもできます。）

 

注意: メッセージ送信の機能を使用する場合は、テスト結果の HTML を保存するネットワークストレージにマッピングすることをお勧めします。 Docker インスタンスはワークフロー中に生成されて破棄されるため、そこに保存しても消えてしまいます。 この問題を解決するには、Docker ファイルへのパスでネットワークボリュームを追加し、IrisNewman/Api.cls クラスの executionsTestPath パラメーターのテストストレージパスを変更します。

 

 

上記を行うと、自動化しようとしているすべてのテストの大部分が対応されたことになります。 このワークフローは手順の例として使用しているため、テストリポジトリに追加しましたが、 ソフトウェアのリポジトリに保存することもできます。 もう 1 つのオプションは、ソフトウェアのコードと実行されるコレクションを直接同じリポジトリに配置することです。 この場合は、コミットごとに、更新した Postman コレクションのテストが実行され、操作の結果が自動的に通知（この場合は Google Chat）されます。

 

この記事に興味を持っていただき、このアプリケーションまたは作業方法を日常業務で使っていただけたら幸いです。少なくとも、このアイデアがどこかで役立てられればと思います。

 

ご質問や不明な点は、コメントセクションにぜひ投稿してください。 ご質問を歓迎しています。

 

お読みいただきありがとうございました！！