The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


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


    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();
        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::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.




    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 '/'.


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


Save the document named as a given parameter filename.


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


        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.


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


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


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




Copyright (C) Yusuke Wada.

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


Yusuke Wada <>