JestとOpenAPIでAPIテストを自動化する方法｜OpenAI APIとの違いも整理

「openai api vs jest」で検索すると、比較記事ではなくAPIテストの解説が出てくることがあります。これはOpenAPI（Swagger）とOpenAI APIの名前が似ているためで、この2つはまったく別の技術です。本記事では、まずこの混同を解消したうえで、JestとOpenAPI仕様を使ってAPIレスポンスを自動検証する具体的な手順を、ライブラリjest-openapiとCI向けのStepCIの実例で解説します。バージョンはjest-openapi 0.14.2時点の仕様に沿っています。

まとめ：JestとOpenAPIによるAPIテスト自動化の要点

• OpenAPIとOpenAI APIは無関係。OpenAPIはAPIの仕様記述形式（旧Swagger）、OpenAI APIはOpenAI社のLLM呼び出しサービス。「Jestとどちらを使うか」という比較対象ではない。
• JestでAPIレスポンスをOpenAPI仕様に照合するには jest-openapi の toSatisfyApiSpec() マッチャを使う。1行で「実装が仕様どおりか」を検証でき、仕様と実装のズレを自動検出できる。
• リクエストの連鎖やCIでのワークフロー検証には、宣言的YAMLで書く StepCI が向く。個別のレスポンス契約検証はjest-openapi、シナリオ全体はStepCI、と役割で使い分ける。
• 仕様駆動テストは「仕様が最新であること」が前提。仕様を更新せずコードだけ直すと、テストが誤って落ちる／通ることがある。

OpenAPIとOpenAI APIの違い｜「vs jest」で迷ったときの整理

検索クエリ「openai api vs jest」「jest vs openai api」は、多くの場合OpenAPIをOpenAI APIと打ち間違えたものか、両者を同じ土俵の技術だと誤解したものです。まずここを切り分けないと、必要なドキュメントにたどり着けません。

OpenAPI（Swagger）＝APIの設計図となる仕様形式

OpenAPIは、RESTful APIのエンドポイント・HTTPメソッド・パラメータ・レスポンス構造・認証方式をYAMLまたはJSONで記述する標準仕様です。2011年にTony Tam氏が「Swagger」として公開し、後にLinux Foundation傘下のOpenAPI Initiativeへ寄贈されて改称されました。現行はJSON Schemaと整合した3.1系（2021年公開）です。APIの「契約書」にあたり、これ自体はコードを実行しません。仕様そのものの基礎はOpenAPI（Swagger）とは何かを解説した記事で詳しく扱っています。

OpenAI API＝OpenAI社のLLMを呼び出すサービス

一方のOpenAI APIは、OpenAI社がGPT系モデルなどをHTTP経由で提供する商用サービスです。テキスト生成や埋め込みを得るためにリクエストを送るもので、API仕様の記述形式であるOpenAPIとは目的も提供元もまったく異なります。綴りは「P」が入るか入らないかの違いにすぎませんが、技術領域はまったく無関係です。

Jestは「仕様」の競合ではなく検証ツール

Jestはコードの動作を検証するJavaScript/TypeScript向けテストフレームワークです。OpenAPIは検証される「基準（仕様）」、Jestはその基準に照らして「実装が合っているか判定する側」であり、両者は競合ではなく組み合わせて使う関係です。したがって「JestかOpenAPIか」という二択は成立しません。同様に「jest vs pytorch」といった比較クエリも、JavaScriptのテスト用途と機械学習フレームワークを取り違えたもので、比較の意味を持ちません。

jest-openapiでレスポンスを仕様に自動照合する

Jestに「レスポンスがOpenAPI仕様を満たすか」を判定させる最短ルートが、専用マッチャを追加する jest-openapi です。モノレポ openapi-library/OpenAPIValidators で開発されているパッケージで、Chai向けの姉妹パッケージchai-openapi-response-validatorもあります。

toSatisfyApiSpecの仕組みと対応クライアント

expect(res).toSatisfyApiSpec() は、レスポンスのリクエストパスとステータスコードから該当する仕様定義を探し、ボディの型・必須プロパティ・列挙値などが仕様と一致するかを検証します。OpenAPI 2および3、YAML/JSONの両形式に対応し、axios・supertest・superagent・request-promise・chai-httpのレスポンスをそのまま渡せます。個別のオブジェクトを名前付きスキーマと突き合わせたいときは toSatisfySchemaInApiSpec('User') を使います。

インストールと最小構成（supertestの例）

導入は npm install --save-dev jest-openapi で、テスト冒頭に jestOpenAPI() で仕様ファイルを読み込むだけです。以下はExpressアプリをsupertestで叩き、レスポンスが仕様を満たすか確認する例です（TypeScriptやESMで書く場合は、ts-jestなど既存のJestトランスパイル設定が前提になります）。

import jestOpenAPI from 'jest-openapi';
import path from 'path';
import request from 'supertest';
import app from '../app';

// OpenAPI仕様を読み込む（ファイルパスまたはオブジェクト）
jestOpenAPI(path.join(__dirname, '../openapi.yaml'));

describe('GET /users/{id}', () => {
  it('レスポンスがOpenAPI仕様を満たす', async () => {
    const res = await request(app).get('/users/1');
    expect(res.status).toEqual(200);
    expect(res).toSatisfyApiSpec();
  });
});

検証に必要なのは実質2行（仕様読み込みとマッチャ呼び出し）です。個々のフィールドを手書きで expect する必要がなく、仕様書がそのままテストの正解データになります。

仕様と実装のズレを検出するワークフロー

このマッチャの価値は「テストが落ちたとき」に出ます。仕様ではidがnumberなのに実装が文字列を返した、必須フィールドが欠けた、といった不一致を toSatisfyApiSpec が具体的なパスを添えて指摘します。仕様を先に直してからコードを実装する契約駆動開発では、この照合をCIに組み込むことで「ドキュメントと実装が乖離したまま気づかない」という典型的な事故を防げます。逆に言えば、仕様を更新せずコードだけ変えるとテストが誤検知するため、仕様ファイルを常に最新に保つ運用が前提になります。

StepCIでAPIワークフロー全体をCIで検証する

jest-openapiは「1つのレスポンスが仕様を満たすか」に強い一方、ログイン→トークン取得→データ操作といった複数リクエストの連鎖や、CIでの定期実行はStepCIが得意です。StepCIはMPL-2.0のオープンソース（TypeScript製）で、REST・GraphQL・gRPC・tRPC・SOAPを1つのワークフローで扱えます。

宣言的YAMLでシナリオを書く

StepCIはテストコードを書く代わりに、ステップと検証条件をYAMLで宣言します。実行は npx stepci run workflow.yml だけで、Node.jsのテスト基盤を別途組む必要がありません。

version: "1.1"
name: User API Test
env:
  host: http://localhost:3000
tests:
  users:
    steps:
      - name: ユーザー取得
        http:
          url: ${{env.host}}/users/1
          method: GET
          check:
            status: 200
            schema:
              type: object
              required: [id, name]
              properties:
                id: { type: number }
                name: { type: string }

各ステップの check にステータスや期待スキーマを書き、前ステップのレスポンス（トークン等）を後続ステップに引き回せます。OpenAPI仕様を読み込んでワークフローの雛形を生成する機能もあり、仕様起点でシナリオテストを作れます。

GitHub Actionsへの組み込み

StepCIはCLIが終了コードで成否を返すため、npx stepci run workflow.yml をCIのステップに置くだけで、プルリクエストごとにAPIの疎通と契約を自動検証できます。単体テストはjest-openapi、E2Eに近いシナリオ検証はStepCIをGitHub ActionsやGitLab CIで回す、という二段構えが実務では扱いやすい構成です。

仕様駆動テストの使い分けと採用を避けるべき場面

ツールが複数あると「全部入れる」判断になりがちですが、役割が重なると保守コストだけ増えます。目的別に絞るのが正解です。

jest-openapi・StepCI・OpenAPI Generatorの役割分担

仕様からクライアントコードを自動生成する用途なら、テストではなくOpenAPI Generatorによるコード自動生成が担当領域です。Spring Bootでコントローラーから仕様書を逆生成したい場合はspringdoc-openapiでの仕様書自動生成、TypeScriptでZodのスキーマからOpenAPIを起こしたい場合はZodとOpenAPIの連携が適しています。

仕様駆動テストを避けるべき失敗パターン

次のような状況では、jest-openapiやStepCIの導入をいったん見送るべきです。第一に、OpenAPI仕様書を運用する体制がなく、仕様が更新されない現場。この場合、テストは「古い仕様」を正解とみなして誤って失敗し、開発者はtoSatisfyApiSpecを無効化して終わります。第二に、内部ロジックのバグを見つけたい場合。仕様適合テストはあくまで「入出力の形」を見るもので、計算結果の正しさは通常のユニットテスト（必要に応じてJestのモック（mockImplementation）で依存を差し替える）で担保します。契約検証とロジック検証を混同すると、どちらも中途半端になります。

よくある質問

「openai api vs jest」で調べると比較記事が出ないのはなぜですか？

OpenAPI（API仕様形式）とOpenAI API（LLMサービス）が別物のため、両者を比較する記事が存在しないからです。多くはOpenAPIの打ち間違いか、JestとOpenAPIを比較対象と誤解した検索です。実際に必要なのはjest-openapiによるAPIテスト自動化の情報であることがほとんどです。

jest-openapiは何をするライブラリですか？

Jestに toSatisfyApiSpec() などのマッチャを追加し、HTTPレスポンスがOpenAPI仕様どおりかを1行で検証できるようにするライブラリです。OpenAPI 2/3とYAML/JSONに対応し、supertestやaxiosのレスポンスを渡せます。最新は0.14.2系です。

jest-openapiとStepCIはどちらを使うべきですか？

目的で選びます。既存のJestテストに「仕様適合」を足すならjest-openapi、ログインを挟む複数リクエストの流れやCIでの定期疎通を検証するならStepCIです。両方を役割分担で併用しても構いません。

StepCIは無料で使えますか？

StepCIのフレームワーク本体はMPL-2.0のオープンソースで、npx stepci run で無料で実行できます。REST・GraphQL・gRPCなど複数プロトコルに対応します。

OpenAPIとSwaggerは違うものですか？

実質同じ仕様です。2011年に「Swagger」として始まり、OpenAPI Initiativeへの寄贈時に仕様名が「OpenAPI」へ改称されました。現在「Swagger」はSwagger UIなどのツール群を指す名称として残っています。

関連記事

• OpenAPI（Swagger）とは何か｜仕様の基本と歴史
• Jestのモック（mockImplementation）の使い方
• OpenAPI GeneratorでJavaコードを自動生成する
• springdoc-openapiでAPI仕様書を自動生成する
• ZodとOpenAPIを連携させる方法