NAME

Test::JSON::RPC::Autodoc - Testing tools for auto generating documents of JSON-RPC applications

SYNOPSIS

use Test::More;
use Plack::Request;
use JSON qw/to_json from_json/;
use Test::JSON::RPC::Autodoc;

# Making a PSGI-based JSON-RPC application
my $app = sub {
    my $env  = shift;
    my $req  = Plack::Request->new($env);
    my $ref  = from_json( $req->content );
    my $data = {
        jsonrpc => '2.0',
        id      => 1,
        result  => $ref->{params},
    };
    my $json = to_json($data);
    return [ 200, [ 'Content-Type' => 'application/json' ], [$json] ];
};

# Let's test
my $test = Test::JSON::RPC::Autodoc->new(
    document_root => './docs',
    app           => $app,
    path          => '/rpc'
);

my $rpc_req = $test->new_request();
$rpc_req->params(
    language => { isa => 'Str', default => 'English', required => 1 },
    country  => { isa => 'Str', documentation => 'Your country' }
);
$rpc_req->post_ok( 'echo', { language => 'Perl', country => 'Japan' } );
my $res  = $rpc_req->response();
my $data = $res->from_json();
is_deeply $data->{result}, { language => 'Perl', country => 'Japan' };

$test->write('echo.md');
done_testing();

DESCRIPTION

Test::JSON::RPC::Autodoc is a software for testing JSON-RPC Web applications. These modules generate the Markdown formatted documentations about RPC parameters, requests, and responses. Using Test::JSON::RPC::Autodoc, we just write and run the integrated tests, then documents will be generated. So it will be useful to share the JSON-RPC parameter rules with other developers.

METHODS

Test::JSON::RPC::Autodoc

new(%options)

my $test = Test::JSON::RPC::Autodoc->new(
    app => $app,
    document_root => './documents',
    path => '/rpc'
);

Create a new Test::JSON::RPC::Autodoc instance. Possible options are:

• app => $app

  PSGI application, required.

• document_root => './documents'

  Output directory for documents, optional, default is './docs'.

• path => '/rpc'

  JSON-RPC endpoint path, optional, default is '/'.

new_request()

Return a new Test::JSON::RPC::Autodoc::Request instance.

write('echo.md')

Save the document named as a given parameter filename.

Test::JSON::RPC::Autodoc::Request

Test::JSON::RPC::Autodoc::Request is a sub-class of HTTP::Request. Extended with these methods.

$request->params(%options)

$request->params(
    language => { isa => 'Str', default => 'English', required => 1, documentation => 'Your language' },
    country => { isa => 'Str', documentation => 'Your country' }
);

Take parameters with the rules for calling JSON-RPC a method. To validate parameters this module use Data::Validator module internal. Attributes of rules are below:

• isa => $type: Str

  The type of the property, which can be Mouse Type constraint name.

• required => $value: Bool

  If true, the parameter must be set.

• default => $value: Str

  The default value for the parameter. If the argument is blank, this value will be used.

• documentation => $doc: Str

  Description of the parameter. This will be used when the Markdown documents are generated.

$request->post_ok($method, $params)

$request->post_ok('echo', { language => 'Perl', country => 'Japan' });

Post parameters to the specified method on your JSON-RPC application and check the parameters as tests. If the response code is 200, it will return OK.

$request->post_not_ok($method, $params)

If the parameters are not valid or the response code is not 200, it will be passed.

$request->response()

Return the last response as a Test::JSON::RPC::Autodoc::Response instance.

Test::JSON::RPC::Autodoc::Response

This module extends HTTP::Response with the methods below:

$response->from_json()

Return a Perl-Object of the JSON response content. That is parsed by JSON parser.

SEE ALSO

• Test::JsonAPI::Autodoc
• https://github.com/r7kamura/autodoc
• Shodo
• Data::Validator

LICENSE

Copyright (C) Yusuke Wada.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Yusuke Wada yusuke@kamawada.com