OpenAPIまたはGraphQLスキーマをお持ちの場合、Schemathesisはアサーションを1行も書くことなく、それを何千ものテストケースに変換できます。仕様を読み込み、ワイルドで有効な入力を生成し、APIに送信して、応答が契約に違反している箇所を報告します。このガイドでは、Schemathesisとは何か、インストールと実行方法、プロパティベースのテストが実際に何を意味するのか、そしてそれが機能テストや契約テストワークフローとApidogでどのように連携するかを説明します。
Schemathesisとは？
Schemathesisは、スキーマからAPIテストを自動的に生成するオープンソースのPythonツールです。OpenAPIまたはGraphQL定義を指示すると、すでに宣言されている型、フォーマット、制約からテストケースを構築します。これはPython用のプロパティベーステストライブラリであるHypothesisの上に構築されており、MITライセンスの下で配布されています。
その核となるアイデアはシンプルです。あなたの仕様は、有効なリクエストとレスポンスがどのようなものであるかをすでに記述しています。Schemathesisはその記述を信頼できる情報源として扱い、実行中のAPIが実際にそれを尊重しているかどうかをチェックします。APIが500を返したり、宣言されたスキーマに違反する応答を送信したり、拒否すべき入力を受け入れたりした場合、Schemathesisはそれをフラグ付けします。
コマンドラインからschemathesis run（または短縮エイリアスst run）で実行します。CLIではなくpytestから駆動したい場合は、Python統合も利用できます。ほとんどのチームはセットアップがほとんど不要なため、CLIから始めます。
プロパティベースのテストとは
ほとんどのAPIテストは例ベースです。リクエストを書き、特定の応答をアサートし、その1つのケースでテストがパスまたは失敗します。これは有用ですが、テストを書こうと思ったバグしか捕捉できません。
プロパティベースのテストは、このアプローチを逆転させます。固定された1つの例ではなく、常に成り立つべきプロパティを記述し、ツールがそれを破ろうと何百もの入力を生成させます。Schemathesisにとってのプロパティは概ね、「有効なリクエストがサーバーをクラッシュさせたり、スキーマに違反する応答を生成したりしてはならない」というものです。
Schemathesisは、仕様の制約から入力を生成します。フィールドが最小値1の整数である場合、1、大きな数値、境界値、そして素朴な検証を妨げるような種類の入力を試します。テストが失敗すると、Hypothesisはバグを再現する最小のケースまで入力を縮小するため、4KBのランダムなペイロードではなく、最小限で読みやすい再現コードが得られます。
これは、インターフェースにランダムな入力を投げつけて何が壊れるかを見るモンキーテストとは異なります。プロパティベースのテストは構造化されています。スキーマを使用して、もっともらしくターゲットを絞った入力を生成し、仕様によって正しい結果がどのようなものかを認識しています。
Schemathesisのインストールと実行
SchemathesisはPythonパッケージなので、Python 3とpipが必要です。通常通りインストールしてください。
pip install schemathesis
uvがセットアップされている場合、uvx schemathesisを使用して永続的にインストールすることなく実行することもできます。インストール後、基本的なコマンドはスキーマとベースURLを指します。
st run http://127.0.0.1:8000/openapi.json
スキーマがURLの背後ではなくディスク上にある場合、ファイルパスを渡し、SchemathesisにライブAPIの場所を伝えます。
st run ./openapi.yaml --url http://127.0.0.1:8000
認証が必要なAPIの場合、ヘッダーを追加します。
st run http://127.0.0.1:8000/openapi.json \
--header 'Authorization: Bearer your-token'
Schemathesisは仕様内のすべての操作を検出し、それぞれに対してケースを生成し、どのチェックが合格し、どのチェックが失敗したかの要約を出力します。失敗した場合は、送信された正確なリクエストが付属するため、curlまたは任意のAPIクライアントでそれをリプレイできます。主要なバージョン間でフラグ名とデフォルトは変更される可能性があるため、この記事のようなブログのスニペットを信頼するのではなく、インストールされているバージョンに対してst run --helpを確認してください。
Schemathesisが検出するもの
デフォルトのチェックは、仕様が約束することとサーバーが実行することとの間のギャップを対象としています。以下に示すような問題が表面化する傾向があります。
| 問題 | どのような状態か |
|---|---|
| サーバーエラー | リクエストが、処理された4xxまたは有効な応答ではなく500をトリガーする |
| スキーマ違反 | 応答ボディが、そのステータスコードに対して宣言したスキーマと一致しない |
| ステータスコードの不一致 | APIが、仕様に記載されていないステータスコードを返す |
| Content-typeのずれ | 応答のContent-typeが、仕様が宣伝するものと一致しない |
| ステートフルなバグ | 操作は単独では機能するが、現実的な複数ステップのワークフロー内では失敗する |
最後の点については詳しく見てみる価値があります。Schemathesisはステートフルテストを実行でき、仕様内のリンクに基づいて操作を連結します。例えば、リソースを作成し、それを取得し、削除するといった具合です。更新後に誤った状態を報告するリソースのように、シーケンスでしか現れないバグは、単一リクエストのテストでは見つけにくいものです。ステートフルフェーズは、それらのシーケンスをステートマシンとして駆動します。
フックを使用してデフォルトの動作を拡張できます。フックは、データの生成をカスタマイズしたり、独自のチェックを追加したり、テスト対象となる操作をフィルタリングしたりできるPython関数です。これにより、チームは認証フローや仕様では表現できない自明でない制約を持つAPIにSchemathesisを適合させることができます。
Schemathesisを使用するタイミング
Schemathesisは、適切に正確なOpenAPIまたはGraphQL仕様があり、エッジケースの広範で安価なカバレッジを望む場合にその価値を発揮します。手動テストでは決して書かないであろう障害、つまり未処理の入力、文書化されていないエラー形式、仕様と実装間の契約のずれを見つけるのに強力です。
次のような場合に適しています。
- OpenAPI仕様を管理しており、それを実際のサーバーに対して強制したい場合。
- 未処理の500エラーを懸念しており、CIでファジングレイヤーを導入したい場合。
- APIに順序が重要なステートフルなワークフローがある場合。
- チームがすでにPythonで作業しており、
pipとpytestに慣れている場合。
スキーマが記述する内容しかテストできないため、仕様が薄い場合や古くなっている場合は適していません。入力がゴミであれば、出力もゴミです。また、例ベースの機能テストに取って代わるものでもありません。エンドポイントが決してクラッシュしないことを知っていることと、既知の入力に対して正しい値を返すことを知っていることとは異なります。両方が必要です。
SchemathesisとApidog：それぞれの役割
ApidogとSchemathesisは異なる問題を解決し、うまく連携します。Apidogは、APIの設計、デバッグ、テスト、モック、ドキュメント作成のためのオールインワンプラットフォームです。Schemathesisは、プロパティベースのファザーに特化しています。ここでの境界線を正直に理解することが重要です。
Apidogはプロパティベースのファジングを行いません。それに最も近い機能はモンキーテストで、ランダムな入力を送信してクラッシュを表面化させます。これは有用ですが、スキーマ駆動のプロパティベースのテストとは異なります。Schemathesisは仕様の制約から入力を生成し、スキーマに対して応答をチェックします。したがって、プロパティベースのファジングが必要な場合は、ApidogではなくSchemathesisを使用してください。
Apidogが適合するのは、そのファジングフェーズを取り巻くライフサイクルの残りの部分です。
| ワークフロー段階 | Schemathesis | Apidog |
|---|---|---|
| 仕様からのプロパティベースファジング | はい、コア機能 | いいえ |
| ビジュアルAPI設計と仕様編集 | いいえ | はい |
| 例ベースの機能テスト | 限定的 | はい、ビジュアルテストビルダー |
| 仕様に対する契約テスト | 部分的、スキーマチェック経由 | はい、専用ワークフロー |
| スキーマからのモックサーバー | いいえ | はい、スマートモック |
| CIテストランナー | はい、st run |
はい、apidog run |
| 自動生成ドキュメント | いいえ | はい |
実用的な組み合わせは次のようになります。Apidogで仕様を設計および保守し、そこから機能テストケースとモックサーバーを生成し、apidog runを使用してCIでそれらを実行します。その後、Schemathesisパスを追加して、同じ仕様に対してエッジケースのクラッシュや契約違反をファジングします。この2つの層は異なる種類のバグを検出します。Apidogは既知のケースに対してAPIが正しく動作することを確認し、Schemathesisはそれを破壊する未知のケースを探します。
目標がファジング実行ではなく、仕様を実行可能な機能スイートに変えることである場合、ApidogはOpenAPI仕様からAPIテストコレクションを直接生成でき、Apidogをダウンロードしてそのフローを試すことができます。
よくある質問
Schemathesisは無料ですか？
はい。SchemathesisはMITライセンスの下でオープンソースであり、CLIはpip install schemathesisを通じて無料でインストールおよび実行できます。管理されたエクスペリエンスを望むチーム向けのホスト型商用サービスもありますが、ローカルやCIで実行するコアツールは無料です。
schemathesis runとst runの違いは何ですか？
これらは同じコマンドです。stはschemathesisの短いエイリアスなので、st runとschemathesis runはまったく同じことを行います。お好みのものを使用してください。どちらもスキーマパスまたはURLに加えて、--urlや--headerなどのオプションを受け取ります。
Schemathesisは私の機能APIテストに取って代われますか？
いいえ、そのような目的ではありません。Schemathesisは、APIがクラッシュしないことと、応答がスキーマと一致することをチェックします。割引計算が正しいかどうかのようなビジネスロジックは検証しません。そのためには、Apidogで構築して実行できる例ベースの機能テストや契約テストが必要です。Schemathesisは代替ではなく、追加のファジングレイヤーとして扱ってください。
SchemathesisはGraphQLで動作しますか？
はい。SchemathesisはOpenAPIとGraphQLの両方のスキーマをサポートしています。GraphQLの場合、スキーマの型定義からクエリを生成し、OpenAPIで定義されたREST APIと同じ方法で応答をチェックします。
結論
Schemathesisは、1つのタスクに特化した鋭いツールです。OpenAPIまたはGraphQL仕様を取得し、プロパティベースの生成を用いてライブAPIに対してストレステストを行います。例ベースのテストでは見逃されがちなクラッシュや契約違反を見つけ出し、CIに追加する費用はほとんどかかりません。しかし、設計、モック、ドキュメント作成、ビジネスロジックの検証は行いません。
ここでApidogがそれを補完します。仕様を設計し、機能テストとモックを生成し、apidog runでCIでそれらを実行し、結果をすべて一箇所でドキュメント化し、その上にファジングのためにSchemathesisを重ねます。そのワークフローの設計および機能面を構築するにはApidogをダウンロードし、エッジケースの探索はSchemathesisに任せてください。