Introduction
SchemathesisとはREST APIのtest toolのひとつでopenapi.jsonが与えられた場合それをもとにtest caseを自動生成してリクエストを投げてテストを行ってくれる. 現在のプロジェクトではfastapiを使ってREST APIを開発しているのでopenapi.jsonも自動生成してくれる. APIをクラウドにdeployしたあとリクエストを投げてテストを行いたいがtestコードを書くのが面倒だったのでOpenAPI toolsからいくつか試して一番良かったのがこれである.
解説
OpenAPI Specification (OAS)とはREST APIのための機械で読み取り可能なインターフェース定義可能な言語のこと. 言い換えるとAPIの仕様書の規格. 以前はSwagger Specificationという名前で知られていた. Swaggerは2010年から開発が始まり, 2016年にプロジェクトが分かれOpenAPI Initiativeで管理されるようになった. 一方swaggerはAPI開発のためのOSSツール群でOASを通じてAPI開発をサポートしてくれる. OASはjsonやymlで書くことがきる. OASの作法に乗っ取って仕様を書いておけば, 例えばswagger UIから利用可能なendpoints, parameters, authentificationなどのドキュメントを生成することができる.
参考
fastAPI
チームで利用しているfastAPIにはopenAPIを利用した機能がいくつかあり, 例えばlocalでAPIを起動するとhttp://127.0.0.1:8000/docs にアクセスすることでswagger UIによってinteractiveなドキュメントを参照することができる.
- http://127.0.0.1:8000/docs でinteractiveなドキュメントを参照することができる.
- http://127.0.0.1:8000/redocs でinteractiveなドキュメントを参照することができる.
- http://localhost:8000/openapi.json でopenapi.jsonが得られる.
現在fastAPIが利用しているOSAはversion 3.0.2である. またAPI経由でopenapi.josnが得られるのでこれを利用してAPIのテストを作成したい. ここではCI/CD用にAPIを起動すれば勝手にそのendpointからリクエスト例を取ってきてリクエストを投げるようにしたい. OpenAPI toolsからいくつか試してみた.
step ci
APIをtestするOSSのtool. OSAからtest用のworkflowを自動生成してtestを実行できる. step ciにはfastapiのintegration機能ある(が別にintegrationしていないと思う):
stepci generate http://127.0.0.1:8000/openapi.json
ただしこうしてできるworkflow.ymlは文字列がラテン語で生成される箇所がある. これはopenapi.jsonの作りが悪いせいである.
stepci runの実行:
stepci run workflow.yml
ⓘ Anonymous usage data collected. Learn more on https://step.ci/privacy
PASS Default
Tests: 0 failed, 1 passed, 1 total
Steps: 0 failed, 0 skipped, 1 passed, 1 total
Time: 7.16s, estimated 7s
Workflow passed after 7.16s
Give us your feedback on https://step.ci/feedback
generateのオプションでexampleを使う様に指定できるが機能しなかった.
Schemathesis
使い方は公式のドキュメントを読んで欲しいが
schemathesis run http://localhost/openapi.json --hypothesis-phases=explicit -H 'hoge:foo'
でexampleのリクエストを使ってtestを行ってくれる. また仕事ではalbの関係でheaderも付ける必要があったがそれも問題なかった. dockerのimageも提供されているのでci/cdに組み込んだりdocker-composeでtestを行うのも簡単だった.