OpenAPIファイルを保持していても、実行中のサービスが徐々にそのファイルから乖離していく場合、Specmaticはそのギャップを埋めるためにまさに構築されたツールです。Specmaticは仕様を実行可能な契約として扱い、その契約に対して実際のサービスをテストし、同じ仕様をスマートなスタブとして実行します。このガイドでは、Specmaticが何をするのか、契約テストが例ベースのテストとどう異なるのか、そしてこのツールがどこに適合するのかを説明します。また、ApidogのAPI契約テストのようなより広範なプラットフォームアプローチとの比較についても触れています。すべての基盤となる仕様形式として、Specmaticが読み込む信頼できる情報源はOpenAPI Specificationです。
Specmaticとは
Specmaticは、契約駆動開発のためのオープンソースツールです。その核となる考え方はシンプルです。API仕様が契約であり、Specmaticはその契約を実行可能にします。OpenAPIファイルを指定するだけで、相補的な2つの役割を果たすことができます。
- ライブサービスに対して仕様をテストとして実行し、サービスが仕様で約束されているすべてのパス、ステータスコード、スキーマを尊重しているかを確認します。
- 仕様をスタブサーバーとして実行し、契約通りに正確に応答するモックに対してコンシューマが開発できるようにします。
どちらの役割も同じファイルを読み込みます。これが肝心な点で、「テスト定義」と「仕様」を別々に同期させる必要はありません。SpecmaticはOpenAPI以外にも対応しています。バージョン2.0ではGraphQLとgRPCが追加され、Kafkaスタイルのイベント契約にはAsyncAPIを、さらにWSDLやAvroのような形式もサポートしています。しかし、ほとんどのチームにとっての入り口は、通常のOpenAPIのYAMLまたはJSONファイルです。
コマンドラインまたはDockerイメージから実行できるため、CIに簡単に組み込めます。開発元の企業は商用のアドオンを提供していますが、契約エンジン自体は無料でオープンソースです。
契約テストと例ベースのテストの比較
これは多くの人を混乱させる区別であるため、正確に説明する価値があります。
例ベースのテストとは、ほとんどのAPIクライアントで行うことです。リクエストを作成し、返されたレスポンスをアサートし、おそらくステータスコードや1、2個のフィールドを確認します。各テストは手書きの例です。仕様に40個のエンドポイントがある場合、多くの例を作成し、維持する必要があり、見落としが発生しやすくなります。
契約テストはこのモデルを逆転させます。特定の例をアサートするのではなく、サービスが契約に合致することをアサートします。Specmaticはスキーマを読み込み、そこからテストを生成します。レスポンスが宣言された型に準拠しているか、必須フィールドが存在するか、ステータスコードが一致しているか、そしてサービスが仕様が示唆する方法で不正なリクエストを拒否するかをチェックします。アサーションを一つずつ書く必要はありません。仕様そのものがアサーションなのです。
| 側面 | 例ベースのテスト | Specmaticによる契約テスト |
|---|---|---|
| 信頼できる情報源 | 手書きのテストケース | OpenAPI仕様そのもの |
| 維持するもの | 個々のリクエストとアサーション | （いずれにせよ保持している）仕様 |
| カバレッジ | 記述したことだけ | 仕様が宣言するすべての操作 |
| 乖離の検出 | 手動 | 仕様変更時に自動 |
| 典型的な失敗 | 特定の例が壊れた | サービスが契約に合致しなくなった |
もう一つ言及すべき側面があります。契約テストには様々な種類があり、Specmaticはその特定の一つに位置づけられます。Pactスタイルのコンシューマー駆動契約テストでは、コンシューマーがブローカーに期待を公開し、プロバイダーがそれに対して検証を行います。Specmaticは代わりに契約駆動テストを行います。つまり、仕様が両者が合意する単一の契約であり、Specmaticはプロバイダーをその契約に対して検証し、コンシューマー向けにプロバイダーをスタブ化します。これはPactブローカーではなく、コンシューマーが公開する契約を管理するものではありません。より広範な情報を知りたい場合は、API契約テストおよびモックツールの概要をご覧ください。
Specmaticの実行方法
CLIを直接インストールするか、Dockerイメージをプルできます。CIではローカルランタイムの設定を避けることができるため、Dockerが一般的な選択肢です。
契約テストの実行
`test`コマンドはSpecmaticに仕様と実行中のサービスを指示します。最小限のローカル実行は次のようになります。
# ネイティブCLI
specmatic test api.yaml --testBaseURL=http://localhost:8080
# Docker
docker run -v "$(pwd):/usr/src/app" specmatic/specmatic \
test api.yaml --testBaseURL=http://host.docker.internal:8080
Specmaticは`api.yaml`を読み込み、それが記述する操作に対するリクエストを生成し、それらをベースURLに送信し、すべてのレスポンスをスキーマに対して検証します。テストが失敗するということは、サービスと契約が一致しないことを意味します。どちらかを修正します。これが一連のプロセスです。
仕様をスタブとして実行する
スタブサーバーはもう一つの側面です。これを起動すると、Specmaticは契約に一致するレスポンスを提供するため、実際のバックエンドが存在する前にフロントエンドやダウンストリームサービスがそれに対して開発を進めることができます。
specmatic stub api.yaml --port=9000
デフォルトでは、スキーマに準拠したレスポンスをその場で生成します。また、具体的な例を仕様の隣にある`_examples`ディレクトリに保存することもでき、リクエストが一致した場合にスタブがそれらを返します。これにより、実際のバックエンドを立ち上げることなく、現実的で制御可能なデータを得ることができます。複数のツールでスタブとモックのオプションを比較している場合、契約テストおよびモックサーバーのまとめがSpecmaticを理解するのに役立ちます。
Specmaticは、そもそも仕様を作成するのにも役立ちます。既存のサービスの手前にプロキシとして配置され、実際のトラフィックをキャプチャし、そこからOpenAPIドキュメントとサンプルファイルを生成できます。これは、サービスはあるがまだ仕様がない場合に便利です。
契約としての仕様とスタブモデル
1つのファイルをテストとスタブの両方として実行することがなぜ重要なのか、その理由を説明します。仕様が契約である場合、テスト側とスタブ側は決して意見の相違を生じません。なぜなら、それらは同じドキュメントを読み取るからです。
- プロバイダーチームはCIで`specmatic test`を実行します。APIを変更しても仕様を更新しない場合、契約テストは失敗します。
- コンシューマーチームはローカルで`specmatic stub`を実行します。彼らは同じ契約に確実に一致するレスポンスに対して開発を進めます。
このように、仕様は誰も信頼しない古いドキュメントではなく、生きている合意となります。これがスタブとよりリッチなモックの違いであり、ワークフローを設計する前にAPIスタビングとモッキングの比較で基本的な考え方を理解しておく価値があります。
Specmaticは後方互換性チェックも追加します。`backward-compatibility-check`コマンドは、新しいバージョンの仕様からスタブを起動し、以前のバージョンからテストを生成し、それらを新しいスタブに対して実行します。以前は動作していたものが動作しなくなった場合、リリース前にそれを発見できます。これは、独立してデプロイされるマイクロサービスにとって強力なガードレールであり、双方向契約テストで扱われるより広範な概念の一種です。
Specmaticが適合するケース
チームにとって次のことが当てはまる場合、Specmaticはその価値を発揮します。
- あなたのOpenAPI（またはAsyncAPI、GraphQL、gRPC）仕様が現実的で、ある程度完成している。
- 同期を保つ必要がある、個別のプロバイダーチームとコンシューマーチーム、またはサービスがある。
- 仕様の乖離がレビューで発見されるのではなく、ビルドを自動的に失敗させることを望む。
- CLIおよびCI優先のワークフローに抵抗がない。
仕様を保持していない場合、APIの設計や探索のためのビジュアルワークスペースを求めている場合、またはアドホックなデバッグ、ドキュメント作成、チームコラボレーションもすべて1つのツールで処理したい場合は、あまり適していません。Specmaticは契約エンジンに特化しており、その1つの仕事をうまくこなします。
この特化の仕方は、Apidogのようなプラットフォームとは異なる特徴を持つ点でもあります。Apidogも同様にスキーマ駆動であり、OpenAPI仕様を読み込み、スキーマに対してレスポンスを検証し、コードなしでOpenAPIスキーマからモックサーバーを立ち上げます。正直な違いはスコープです。SpecmaticはシャープなCLIネイティブの契約ツールです。Apidogは、デザイン、テスト、モック、ドキュメントをビジュアルエディターを備えた1つのワークスペースにまとめ、作業中に仕様、テスト、モックが共存し、同期を保ちます。ApidogもPactスタイルのコンシューマー駆動型契約ブローカーではないため、チームが特にPactブローカーを必要とする場合は、どちらのツールもその役割は果たしません。
そのようなワークスペース内で仕様から直接実行可能なテストを生成したい場合は、ApidogがOpenAPI仕様からのAPIテストコレクション生成をどのように処理するかをご覧ください。
よくある質問
Specmaticは無料ですか？
はい、そうです。コアとなる契約エンジンはオープンソースで、CLIまたはDockerから無料で利用できます。商用版の提供もありますが、OpenAPI仕様から契約テストやスタブサーバーを実行するのに費用はかかりません。有料ティアに関する最新情報は、公式サイトとGitHubでご確認ください。
SpecmaticはOpenAPIのみに対応していますか？
いいえ、そうではありません。OpenAPIが最も一般的な入り口ですが、Specmaticはイベント駆動型契約のためのAsyncAPIもサポートしており、バージョン2.0からはGraphQLとgRPCも、さらにWSDLやAvroなどのフォーマットにも対応しています。これらすべてにおいてモデルは同じです。つまり、仕様が実行可能な契約であるということです。このフォーマット自体に慣れていない場合は、このOpenAPI Specificationチュートリアルから始めてください。
SpecmaticはPactと同じですか？
少し違います。Pactはコンシューマー駆動です。コンシューマーが期待をブローカーに公開し、プロバイダーがそれに対して検証を行います。Specmaticは契約駆動です。仕様が単一の共有契約であり、Specmaticはプロバイダーをその契約に対して検証し、コンシューマー向けにプロバイダーをスタブ化します。どちらも連携時の予期せぬ問題を軽減しますが、契約の管理方法が異なります。
SpecmaticはOpenAPI仕様を生成できますか？
はい、可能です。Specmaticは既存のサービスの手前にプロキシとして実行され、実際のリクエストとレスポンストラフィックをキャプチャし、そこからOpenAPIドキュメントとサンプルファイルを生成できます。これは、動作するサービスはあるがまだテストするための正式な仕様がない場合に役立ちます。
まとめ
Specmaticは、特定の現実的な問題、すなわち、従うべきOpenAPI仕様に対して実行中のサービスが誠実であることを保証するという問題に答えます。仕様を実行可能にすることで、1つのファイルから契約テストと対応するスタブを提供し、さらに後方互換性チェックも行います。もしあなたがターミナルとCI環境で作業し、堅牢な仕様を維持しているのであれば、これはぴったりと適合します。
もし、同じOpenAPIファイルを読み込む1つのビジュアルワークスペースで、契約、テスト、モック、ドキュメントをすべて扱いたいのであれば、Apidogをお試しください。Apidogはスキーマに対してレスポンスを検証し、コードなしでエンドポイントをモック化し、仕様を実行可能なテストコレクションに変換します。Apidogをダウンロードして、あなたの仕様を指し示し、設計からテストまでの完全なループを1か所で確認してください。