その手の平は尻もつかめるさ

ギジュツ的な事をメーンで書く予定です

Test::JsonAPI::Autodocをリリースしました

Test::JsonAPI::Autodocをリリースしました.
https://metacpan.org/pod/Test::JsonAPI::Autodoc
https://github.com/moznion/Test-JsonAPI-Autodoc

これは何

Ruby (RSpec) にはautodocという,@r7kamuraさんが書かれたクールなモジュールがあって,
これが何かと言うと,JSON APIのテストを記述するとそのリクエストとレスポンスに応じて
自動的にそのAPIのドキュメントを生成してくれるという大層便利なモジュールです.
「テストを書くとドキュメントが出来る」という発想は最早発明と言っても過言では無いでしょう.

autodocにまつわる情報は以下を参照頂いた方が詳しくて良いでしょう.

で,これにインスパイアされて……というかこのアイデアをパクって出来たのが
このTest::JsonAPI::Autodocです.

使い方

大体ドキュメントに書いてある通りです.

こんな感じで,Test::JsonAPI::Autodocを使ったテストを書いてやって……

gist7279141

$ TEST_JSONAPI_AUTODOC=1 prove t/test_jsonapi_autodoc.t

という感じでテストを走らせてやると,
(ちなみに,TEST_JSONAPI_AUTODOCという環境変数に真値を入れない場合はドキュメントが生成されません)

gist7279162

このようなMarkdown形式のドキュメントが生成されます.便利っぽい!

ちょっと詳しく

describeというメソッドはsubtestと同じような使い方が可能なメソッドで *1
このdescribeメソッドの内部でhttp_okメソッドを呼び出してやると,
http_okメソッドがAPIのテストを行って (APIのテストと言ってもステータスコードを見るだけですが),
その後にリクエストとレスポンスに応じてMarkdown形式のドキュメントを自動的に生成します.

なお,describeメソッドの第一引数の文字列はドキュメントの見出しに,
http_okメソッドの第三引数の文字列はドキュメントの説明 (見出しの下のノート) になります.

http_okメソッドは単体で利用する事も可能ですが (つまり,describeメソッドの外部で呼び出す),
その場合はステータスコードのチェックを行うだけで,ドキュメントの生成は行いません.

Markdownドキュメントは,デフォルトではプロジェクトルート直下のdocs/test_name.mdというパスに出力されます.
ドキュメントの出力先はset_documents_pathというメソッドで設定してやることが出来ます.
なお,ここでいう「プロジェクトルート」とはテストスクリプトからルートディレクトリに遡る途中で発見した
cpanfileが置いてあるディレクトリの事を指します.つまりcpanfileをどこか *2 に配置してやる必要があります

また,生成されるMarkdownのテンプレートも,set_templateというメソッドで自由にカスタムすることが出来ます.
これに関してはドキュメントを参照して下さい.
https://metacpan.org/pod/Test::JsonAPI::Autodoc#CUSTOM-TEMPLATE

こんな感じです!!!

なんか便利そうなので是非ご利用下さいませ.

多分,まだ色々至らない部分があると思うので,皆様のフィードバックをお待ちしております.

追記

先頃リリースしましたバージョン0.10で,Plack::Testに対応しました.
以下のように利用する事が可能です.

gist7291445

こうしたテストスクリプトを実行すると,以下のようなドキュメントが返ってきます.

gist7291453

よろしくお願いします.

追記2

Test::JsonAPI::AutodocはJSON-RPCに対応しています
以下のようなコードを書いてやると動きます.

gist7303022

このテストを実行すると以下のようなマークダウンが得られます.

gist7303033

追記3

describe()subtest()のように,describe()の中にTest::Moreのメソッドを記述する事が出来ます.
つまり、describeの中にsubtestを書いたりしても大丈夫です.describeの中にdescribeを書くのだけは駄目です.

*1:とは言え,describeはネスト不可能ですが

*2:たいていは素直にプロジェクトルートでしょう