Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/karenetheridge/Test-JSON-Schema-Acceptance

Acceptance testing for JSON-Schema based validators
https://github.com/karenetheridge/Test-JSON-Schema-Acceptance

Last synced: 5 months ago
JSON representation

Acceptance testing for JSON-Schema based validators

Awesome Lists containing this project

README 

        
=pod



=encoding UTF-8



=for stopwords validators Schemas ANDed ORed TODO



=head1 NAME



Test::JSON::Schema::Acceptance - Acceptance testing for JSON-Schema based validators



=head1 VERSION



version 1.026



=head1 SYNOPSIS



This module allows the

L tests to be used in

perl to test a module that implements the JSON Schema specification ("json-schema"). These are the

same tests that many modules (libraries, plugins, packages, etc.) use to confirm support of

json-schema. Using this module to confirm support gives assurance of interoperability with other

modules that run the same tests in different languages.



In the JSON::Schema::Modern module, a test could look like the following:



  use Test::More;

  use JSON::Schema::Modern;

  use Test::JSON::Schema::Acceptance;



  my $accepter = Test::JSON::Schema::Acceptance->new(specification => 'draft7');



  $accepter->acceptance(

    validate_data => sub ($schema, $input_data) {

      return JSON::Schema::Modern->new($schema)->validate($input_data);

    },

    todo_tests => [ { file => 'dependencies.json' } ],

  );



  done_testing();



This would determine if JSON::Schema::Modern's C method returns the right result for all

of the cases in the JSON Schema Test Suite, except for those listed in C.



=head1 DESCRIPTION



L is an IETF draft (at time of writing) which allows you to

define the structure of JSON.



From the overview of the L:



=over 4



This document proposes a new media type "application/schema+json" to identify a JSON Schema for

describing JSON data. It also proposes a further optional media type,

"application/schema-instance+json", to provide additional integration features. JSON Schemas are

themselves JSON documents. This, and related specifications, define keywords allowing authors to

describe JSON data in several ways.



JSON Schema uses keywords to assert constraints on JSON instances or annotate those instances with

additional information. Additional keywords are used to apply assertions and annotations to more

complex JSON data structures, or based on some sort of condition.



=back



This module allows other perl modules (for example JSON::Schema::Modern) to test that they are JSON

Schema-compliant, by running the tests from the official test suite, without having to manually

convert them to perl tests.



You are unlikely to want this module, unless you are attempting to write a module which implements

JSON Schema the specification, and want to test your compliance.



=head1 CONSTRUCTOR



  Test::JSON::Schema::Acceptance->new(specification => $specification_version)



Create a new instance of Test::JSON::Schema::Acceptance.



Available options (which are also available as accessor methods on the object) are:



=head2 specification



This determines the draft version of the schema to confirm compliance to.

Possible values are:



=over 4



=item *



C



=item *



C



=item *



C



=item *



C



=item *



C



=item *



C



=item *



C (alias for C)



=item *



C



=back



The default is C, but in the synopsis example, L is testing draft 7

compliance.



(For backwards compatibility, C can be called with a single numeric argument of 3 to 7, which

maps to C through C.)



=head2 supported_specifications



The version(s) that the implementation supports; used to skip adding remote resources that reference

unsupported schema versions (for cross-schema tests). Defaults to C<< [ $self->specification ] >>.



=head2 test_dir



Instead of specifying a draft specification to test against, which will select the most appropriate

tests, you can pass in the name of a directory of tests to run directly. Files in this directory

should be F<.json> files following the format described in

L.



=head2 additional_resources



A directory of additional resources which should be made available to the implementation under the

base URI C. This is automatically provided if you did not override

L; otherwise, you need to supply it yourself, if any tests require it (for example by

containing C<< {"$ref": "http://localhost:1234/foo.json/#a/b/c"} >>). If you supply an

L value to L (see below), this will be done for you.



=head2 verbose



Optional. When true, prints version information and the test result table such that it is visible

during C or C.



=head2 include_optional



Optional. When true, tests in subdirectories (most notably F are also included.



=head2 skip_dir



Optional. Pass a string or arrayref consisting of relative path name(s) to indicate directories

(within the test directory as specified above with L or L) which will be

skipped. Note that this is only useful currently with C<< include_optional => 1 >>, as otherwise all

subdirectories would be skipped anyway.



=head2 results



After calling L, a list of test results are provided here. It is an arrayref of

hashrefs with four keys:



=over 4



=item *



file - the filename



=item *



pass - the number of pass results for that file



=item *



todo_fail - the number of fail results for that file that were marked TODO



=item *



fail - the number of fail results for that file (not including TODO tests)



=back



=head2 results_text



After calling L, a text string tabulating the test results are provided here. This is

the same table that is printed at the end of the test run.



=head2 test_schemas



=for stopwords metaschema



Optional. A boolean that, when true, will test every schema against its

specification metaschema. (When set, L must also be set.)



This normally should not be set as the official test suite has already been

sanity-tested, but you may want to set this in development environments if you

are using your own test files.



Defaults to false.



=head1 SUBROUTINES/METHODS



=head2 acceptance



=for stopwords truthy falsey



Accepts a hash of options as its arguments.



(Backwards-compatibility mode: accepts a subroutine which is used as L,

and a hashref of arguments.)



Available options are:



=head3 validate_data



A subroutine reference, which is passed two arguments: the JSON Schema, and the B data

structure to be validated. This is the main entry point to your JSON Schema library being tested.



The subroutine should return truthy or falsey depending on if the schema was valid for the input or

not (an object with a boolean overload is acceptable).



Either L or L is required.



=head3 validate_json_string



A subroutine reference, which is passed two arguments: the JSON Schema, and the B

containing the data to be validated. This is an alternative to L above, if your

library only accepts JSON strings.



The subroutine should return truthy or falsey depending on if the schema was valid for the input or

not (an object with a boolean overload is acceptable).



Exactly one of L or L is required.



=head3 add_resource



Optional. A subroutine reference, which will be called at the start of L multiple

times, with two arguments: a URI (string), and a data structure containing schema data to be

associated with that URI, for use in some tests that use additional resources (see above). If you do

not provide this option, you will be responsible for ensuring that those additional resources are

made available to your implementation for the successful execution of the tests that rely on them.



For more information, see .



=head3 tests



Optional. Restricts tests to just those mentioned (the conditions are ANDed together, not ORed).

The syntax can take one of many forms:



  # run tests in this file

  tests => { file => 'dependencies.json' }



  # run tests in these files

  tests => { file => [ 'dependencies.json', 'refRemote.json' ] }



  # run tests in this file with this group description

  tests => {

    file => 'refRemote.json',

    group_description => 'remote ref',

  }



  # run tests in this file with these group descriptions

  tests => {

    file => 'const.json',

    group_description => [ 'const validation', 'const with object' ],

  }



  # run tests in this file with this group description and test description

  tests => {

    file => 'const.json',

    group_description => 'const validation',

    test_description => 'another type is invalid',

  }



  # run tests in this file with this group description and these test descriptions

  tests => {

    file => 'const.json',

    group_description => 'const validation',

    test_description => [ 'same value is valid', 'another type is invalid' ],

  }



=head3 todo_tests



Optional. Mentioned tests will run as L<"TODO"|Test::More/TODO: BLOCK>. Uses arrayrefs of

the same hashref structure as L above, which are ORed together.



  todo_tests => [

    # all tests in this file are TODO

    { file => 'dependencies.json' },

    # just some tests in this file are TODO

    { file => 'boolean_schema.json', test_description => 'array is invalid' },

    # .. etc

  ]



=head2 json_prettyprint



JSON-encodes a data structure in a format suitable for human view, used for printing test diagnostics.



=head2 json_encoder



Provides access to the object that provides the L method.



=head1 ACKNOWLEDGEMENTS



=for stopwords Perrett Signes



Daniel Perrett  for the concept and help in design.



Ricardo Signes  for direction to and creation of Test::Fatal.



Various others in #perl-help.



=for stopwords OpenAPI



=head1 SUPPORT



Bugs may be submitted through L.



You can also find me on the L and L, which are also great resources for finding help.



=head1 AUTHOR



Ben Hutton (@relequestual) 



=head1 CONTRIBUTORS



=for stopwords Karen Etheridge Daniel Perrett



=over 4



=item *



Karen Etheridge 



=item *



Daniel Perrett 



=back



=head1 COPYRIGHT AND LICENCE



This software is Copyright (c) 2015 by Ben Hutton.



This is free software, licensed under:



  The MIT (X11) License



This distribution includes data from the L test suite, which carries its own

licence (see F).



Permission is explicitly B granted to repackage or redistribute this distribution with any

files altered or added (such as with a different set of test data) than what was originally

published to the Perl Programming Authors Upload Server (PAUSE), as dependencies of this

distribution have specific expectations as to the contents of this test data depending on version.

If it is desired to use a different dataset at runtime, please refer to the L

configuration option.



=for Pod::Coverage BUILDARGS BUILD json_decoder



=cut