StopLight.ioを使って233のエンドポイントを数秒でテストする方法

この記事は How We Use StopLight.io to Test 233 API Endpoints in Seconds の抄訳です。

SendGridでは7つのプログラミング言語向けに公式ライブラリを提供しており、それぞれ233のエンドポイントをサポートしています。こういった状況で、各テストフレームワーク向けにモックコードを書くことなく、Web API v3全てのエンドポイントを素早くサポートしつつ、基本的な挙動確認のテストをする方法が必要でした。

StopLight.ioが提供するPrismモックサーバ（Swagger/OAIドリブンなSendGrid APIサーバのモック版が構築可能）がこの課題を劇的に解決してくれました。本記事では、全エンドポイントを数秒（数分ではありませんよ）でテストするワークフローについてご紹介します。

まずはじめに登場するのがStopLight.ioのドキュメント化ツールです。ドキュメント化は今回のチャレンジの中で最も退屈な部分でした。この作業が必要なエンドポイントは233にものぼりますが、StopLight.ioのディスカバリーツールを利用することで劇的にスピードアップできました。このツールはStopLight.ioを経由してSendGrid.comをブラウズするだけで、StopLight.ioは自動的に各エンドポイントのドキュメント化を行います。最後にStopLight.ioのAPIデザインツール（下図）を使って定義を調整しました。

最終調整を行いドキュメント化が完了したら、上記のインターフェイスでボタンをクリックするだけでAPIのSwagger/OAI定義をエクスポートできます。

例えば、`/user/webhooks/parse/settings` をGETするエンドポイントのSwagger/OAIの定義は次の通りです（こういったものを多数記述、管理しなければならないことをイメージしてください！）：

"/user/webhooks/parse/settings": {
            "get": {
                "consumes": [
                    "application/json"
                ],
                "description": "**This endpoint allows you to retrieve all of your current inbound parse settings.**\n\nThe inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).",
                "operationId": "GET_user-webhooks-parse-settings",
                "produces": [
                    "application/json"
                ],
                "responses": {
                    "200": {
                        "description": "",
                        "examples": {
                            "application/json": {
                                "result": [
                                    {
                                        "hostname": "mail.mydomain.com",
                                        "send_raw": true,
                                        "spam_check": true,
                                        "url": "http://mydomain.com/parse"
                                    }
                                ]
                            }
                        },
                        "schema": {
                            "properties": {
                                "result": {
                                    "description": "The list of your current inbound parse settings.",
                                    "items": {
                                        "$ref": "#/definitions/parse-setting"
                                    },
                                    "type": "array"
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "summary": "Retrieve all parse settings",
                "tags": [
                    "Settings - Inbound Parse"
                ]
            }

次に、StopLight.ioが生成したSwagger/OAIの定義を使って、全エンドポイントのドキュメント、サンプルコード、API呼び出しのテストコードを7言語分自動的に生成するツールを作成しました（これについては別途ご紹介します）。テストコードはシンプルにAPIをコールしレスポンスが正しいことをチェックします。Prismがなかったら、これら全てのモックを自前で作成する必要があったでしょう。

以下はJava実装の基本的なモックサーバのコードですが、実際にはエンドポイントおよびそのパラメータに応じて適切なレスポンスを全て定義する必要があります。

package com.sendgrid;

import java.io.IOException;
import java.util.HashMap;

public class MockSendGrid extends SendGrid {
  Request request;

  public MockSendGrid(String apiKey) {
    super(apiKey);
  }

  public Response makeCall(Request request) throws IOException {
    this.request = request;
    Response response = new Response();
    response.statusCode = 200;
    response.body = "{\"message\":\"success\"}";
    response.headers = new HashMap<String, String>();
    response.headers.put("Test", "Header");
    return response;
  }

  public Request getRequest() {
    return this.request;
  }
}

PrismをインストールしてSwagger/OAIファイルのパスを設定すると、ローカルのモックサーバとStopLight.ioサービス上にホストされたサーバに対してローカルテストを実行できます。

これで、特別なモック関数を作ること無く、以下のようなテストコードで全エンドポイントとライブラリのチェックを高速かつ非常に簡単に行えるようになりました。

  @Test
  public void test_alerts_get() throws IOException {
    SendGrid sg = new SendGrid("SENDGRID_API_KEY", true);
    sg.setHost("localhost:4010");
    sg.addRequestHeader("X-Mock", "200");

    Request request = new Request();
    request.method = Method.GET;
    request.endpoint = "alerts";
    Response response = sg.api(request);
    Assert.assertEquals(200, response.statusCode);
  }

こうした中で1点問題にぶつかりました。当初233以上のテストをTravis CIからStopLight.ioのサービスを使って実行していましたが、テスト数が多すぎて、予想以上に時間がかかり、StopLight.ioのサーバに不必要な負荷がかかりました。

そこで、StopLight.ioのエンジニアTomは、Travis CIに自動的にPrismをインストールし、モックサーバを起動し、テスト完了後にサーバをシャットダウンするスクリプトを書くという素晴らしい顧客サービスを提供してくれました。このスクリプトはローカル環境でも動作し、OS毎に最適なバージョンのPrismを自動的にインストールしてくれます。これで開発用のテスト環境の起動とテストの実行が1度のクリックもなしに可能になりました。

こうして、SendGridサーバのモックを簡単に構築する方法を手に入れることができました。この方法は、SendGridと連携する際のモック環境を構築したり、SendGridのクレジットを利用する前にテストとプロトタイピングするといった、他のユースケースでも利用可能です。

SendGridのAPIモックサーバが他にどのような用途で利用されるか興味があります。是非、Twitter、LinkedIn、Facebookなどでシェアしてください！