この記事は NewsPicks Advent Calendar 2024 の10日目の記事です。

こんにちは。ソーシャル経済メディア「NewsPicks」の QA/SET チームの海老澤です。今回はAPIテストを OpenAPI Generator を使って書いた話を紹介させていただきます。

APIテスト

APIテストはソフトウェアテストにおいて重要な役割を果たし、テストピラミッドの中間層（統合テスト）に位置します。

NewsPicks ではE2Eテストと比較して、APIテストは基盤がほぼなかったため今回テスト基盤から作成することにしました。そこでAPIテスト基盤は記述がしやすく、かつメンテナンスもなるべく簡易になるように工夫することにしました。

OpenAPI Generator とは

OpenAPI Generator は OpenAPI Specification を基にしてさまざまなプログラミング言語やフレームワーク向けのコードを自動生成するツールですこのツールを使用することで、sdk が自動で作成され、更に以下の利点があります

一貫性の確保: API スペックが直接コードに反映されるため、仕様変更に強い。
手動ミスの削減: 自動生成されるコードにはエンドポイントや型定義が含まれ、手書きの必要がない。
多言語対応: TypeScript、Python、Java など多くの言語向けの SDK を生成可能。

Newspicks では OpenAPI の仕様書自体はあったのでこれを使って sdk を作成、APIテストで使うことでなるべく記述しやすく、メンテナンスも少ない基盤を作成できると考えました

github.com

sdkの作成

sdkの作成方法はインストールしてコマンドを打つだけで実行できます。

例

npx openapi-generator-cli generate \
  -i {openapi3.jsonを指定} \
  -g {生成するコードの種類を指定 例: typescript-axios}  \
  -o {出力する場所を指定} \
  -t {テンプレートを指定※1}

詳細はOpenAPI Generator のドキュメントを確認ください

※1 生成されるsdkをカスタマイズするためのテンプレートです。デフォルトのテンプレートはこちらにあり、これをカスタマイズすることができます。例えばコードのdocにendpointを追加したいときは上記テンプレートの一部を下記のように修正します

    {{#operation}}
    /**
     * ⇩これを追加
     * endpoint {{{path}}} 
     * {{&notes}}
     {{#summary}}
     * ~~~
     */

詳細は下記を参照ください openapi-generator.tech

テスト記載方法

後は作成したsdkを使って, テストコードを書くだけです。テストは jest と TypeScript で記載しています。

// 上記で作成した sdk
import { Configuration, TestControllerApi } from "src/api-client";

describe("テスト", () => {
    it("テスト", async () => {
        const conf = new Configuration({
            basePath: "https://example.com",
            baseOptions: {
                auth: "user",//必要に応じて認証を追加
            },
        });
        const apiClient = new TestControllerApi();

        const response = await apiClient.getUsingGET();

        expect(response.status).toBe(200);
    });
});