Test::JsonAPI::Autodoc - Test JSON API response and auto generate API documents
use HTTP::Request::Common; use Test::More; use Test::JsonAPI::Autodoc; # JSON request describe 'POST /foo' => sub { my $req = POST 'http://localhost:5000/foo'; $req->header('Content-Type' => 'application/json'); $req->content(q{ { "id": 1, "message": "blah blah" } }); my $res = http_ok($req, 200, "returns response"); # <= Check status whether 200, and generate documents. # And this test method returns the response as hash reference. }; # Can also request application/x-www-form-urlencoded describe 'POST /bar' => sub { my $req = POST 'http://localhost:3000/bar', [ id => 42, message => 'hello' ]; http_ok($req, 200, "returns response"); } # And you can use Plack::Test use Plack::Test; use Plack::Request; my $app = sub { my $env = shift; my $req = Plack::Request->new($env); if ($req->path eq '/') { return [ 200, [ 'Content-Type' => 'application/json' ], ['{ "message" : "success" }'] ]; } return [ 404, [ 'Content-Type' => 'text/plain' ], [ "Not found" ] ]; }; my $test_app = Plack::Test->create($app); describe 'POST /' => sub { my $req = POST '/'; $req->header('Content-Type' => 'application/json'); $req->content(q{ { "id": 1, "message": "blah blah" } }); plack_ok($test_app, $req, 200, "get message ok"); }; # Of course you can use `test_psgi` test_psgi $app, sub { my $cb = shift; describe 'POST /not-exist' => sub { my $req = POST '/not-exist'; $req->header('Content-Type' => 'application/json'); $req->content(q{ { "id": 1, "message": "blah blah" } }); plack_ok($cb, $req, 404, "not found"); }; };
Test::JsonAPI::Autodoc tests JSON API response (only check status code). And it generates API documents according to the response automatically. Please refer to "USAGE" for details.
A document will be generated if describe is used instead of Test::More::subtest. And call http_ok or plack_ok at inside of describe, then it tests API response and convert the response to markdown document.
describe
Test::More::subtest
http_ok
plack_ok
Run test as follows.
$ TEST_JSONAPI_AUTODOC=1 prove t/test.t
If TEST_JSONAPI_AUTODOC doesn't have true value, documents will not generate.
TEST_JSONAPI_AUTODOC
The example of test.t is as follows.
use HTTP::Request::Common; use Test::More; use Test::JsonAPI::Autodoc; # JSON request describe 'POST /foo' => sub { my $req = POST 'http://localhost:5000/foo'; $req->header('Content-Type' => 'application/json'); $req->content(q{ { "id": 1, "message": "blah blah" } }); http_ok($req, 200, "get message ok"); };
The following markdown document are outputted after execution of a test. Document will output to $project_root/docs/test.md on default setting.
generated at: 2013-11-04 22:41:10 ## POST /foo get message ok ### Target Server http://localhost:5000 ### Parameters __application/json__ - `id`: Number (e.g. 1) - `message`: String (e.g. "blah blah") ### Request POST /foo ### Response - Status: 200 - Content-Type: application/json ```json { "message" : "success" } ```
Please also refer to example (https://github.com/moznion/Test-JsonAPI-Autodoc/tree/master/eg).
describe ($description, \&coderef)
describe method can be used like Test::More::subtest. If this method is called, a document will be outputted with a test.
$description will be headline of markdown documents.
$description
*** DO NOT USE THIS METHOD AS NESTING ***
http_ok ($request, $expected_status_code, $note)
http_ok method tests API response (only status code). and convert the response to markdown document.
$note will be note of markdown documents.
$note
When this method is not called at inside of describe, documents is not generated.
And this method returns the response as hash reference.
Example of response structure;
$response = { status => <% status code %>, content_type => <% content type %>, body => <% response body %>, }
Moreover if $note is hash reference like below, you can describe each request parameters.
{ description => 'get message ok', param_description => { param1 => 'This is param1' param2 => 'This is param2', }, }
description is the same as the time of using as <$note> as scalar. param_description contains descriptions about request parameters. Now, this faculty only can describe request parameters are belonging to top level. Please refer https://github.com/moznion/Test-JsonAPI-Autodoc/tree/master/eg/http_with_req_params_description.t and https://github.com/moznion/Test-JsonAPI-Autodoc/tree/master/eg/doc/http_with_req_params_description.md.
description
param_description
plack_ok ($plack_app, $request, $expected_status_code, $note)
plack_ok method carries out almost the same operation as http_ok. This method is for Plack application. This method requires plack application as the first argument.
This method also returns the response as hash reference.
set_documents_path
Set the output place of a document. An absolute path and a relative path can be used.
set_template
Set the original template. This method require the string. Please refer to "CUSTOM TEMPLATE" for details.
Generated document will output to $project_root/docs/ on default setting. $project_root means the directory on which cpanfile discovered while going back to a root directory from a test script is put. Therefore, it is necessary to put cpanfile on a project root.
Documents are generated when true value is set to this environment variable.
You can customize template of markdown documents.
Available variables are the followings.
generated_at
results
result.note
result.path
result.server
result.method
result.query
result.request_content_type
result.request_parameters
result.is_plack_app
result.status
result.response_body
result.response_content_type
: if $generated_at { generated at: <: $generated_at :> : } ## <: $description :> : for $results -> $result { <: $result.note :> : if $result.server { ### Target Server <: $result.server :> : if $result.is_plack_app { (Plack application) : } :} ### Parameters : if $result.request_parameters { : if $result.request_content_type { __<: $result.request_content_type :>__ : } : for $result.request_parameters -> $parameter { <: $parameter :> : } : } : else { Not required : } ### Request <: $result.method:> <: $result.path :> : if $result.query { <: $result.query :> : } ### Response - Status: <: $result.status :> - Content-Type: <: $result.response_content_type :> ```json <: $result.response_body :> ``` : }
Template needs to be written by Text::Xslate::Syntax::Kolon as looking.
Yes. It can use as https://github.com/moznion/Test-JsonAPI-Autodoc/tree/master/eg/json_rpc.t.
subtest()
describe()
Yes, of course!
This module is inspired by “autodoc”, which is written by Ruby. That is very nice RSpec extension.
See also https://github.com/r7kamura/autodoc
Yuuki Tsubouchi (y-uuki)
Copyright (C) moznion.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
moznion <moznion@gmail.com>
To install Test::JsonAPI::Autodoc, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Test::JsonAPI::Autodoc
CPAN shell
perl -MCPAN -e shell install Test::JsonAPI::Autodoc
For more information on module installation, please visit the detailed CPAN module installation guide.