Open Source Ecosystems

=pod

=encoding UTF-8

=head1 NAME

Test::Mojo::Role::OpenAPI::Modern - Test::Mojo role providing access to an OpenAPI document and parser

=head1 VERSION

version 0.006

=head1 SYNOPSIS

my $openapi = OpenAPI::Modern->new(
openapi_uri => '/api',
openapi_schema => YAML::PP->new(boolean => 'JSON::PP')->load_string(<<'YAML'));

openapi: 3.1.0 info: title: Test API version: 1.2.3 paths: /foo/{foo_id}: parameters: - name: foo_id in: path required: true schema: type: integer post: operationId: my_foo_request requestBody: required: true content: application/json: schema: {} responses: 200: description: success content: application/json: schema: type: object required: [ status ] properties: status: const: ok YAML

my $t = Test::Mojo ->with_roles('+OpenAPI::Modern') ->new('MyApp', { ... }) ->openapi($openapi);

$t->post_ok('/foo/123') ->status_is(200) ->json_is('/status', 'ok') ->request_valid ->or->dump_validation_request_result('basic') ->response_valid ->or->dump_validation_response_result('basic') ->operation_id_is('my_foo_request');

$t->test_openapi_verbose(1); # automatically dump validation errors on test failure

$t->post_ok('/foo/123', form => { salutation => 'hi' }) ->status_is(400) ->request_not_valid('Unsupported Media Type') ->response_not_valid(q{'/response': no response object found for code 400});

$t->post('/foo/hello') ->status_is(400) ->request_not_valid(q{/request/path: 'wrong type: expected integer, got string'}, 'detected bad path parameter');

=head1 DESCRIPTION

Provides methods on a LTest::Mojo object suitable for using LOpenAPI::Modern to validate the request and response.

=for stopwords OpenAPI openapi

=head1 ACCESSORS/METHODS

=head2 openapi

The LOpenAPI::Modern object to use for validation. This object stores the OpenAPI schema used to describe requests and responses in your application, as well as the underlying LJSON::Schema::Modern object used for the validation itself. See that documentation for information on how to customize your validation and provide the specification document.

If not provided, the object is constructed using configuration values passed to the application under the C key (see LTest::Mojo/new), as for LMojolicious::Plugin::OpenAPI::Modern, or re-uses the object from the application itself if that plugin is applied.

=head2 test_openapi_verbose

When true, failing request and response validation tests will dump the actual validation result via L</dump_request_validation_result> or L</dump_response_validation_result>.

Defaults to false.

=head2 request_valid

Passes C<< $t->tx->req >> to LOpenAPI::Modern/validate_request, as in LMojolicious::Plugin::OpenAPI::Modern/validate_request, producing a boolean test result.

=head2 request_not_valid, request_invalid

The inverse of L</request_valid>. May optionally take an error string, which is matched against the LJSON::Schema::Modern::Result/recommended_response, and all error strings in the result.

=head2 response_valid

Passes C<< $t->tx->res >> to LOpenAPI::Modern/validate_response as in LMojolicious::Plugin::OpenAPI::Modern/validate_response, producing a boolean test result.

=head2 response_not_valid, response_invalid

The inverse of L</response_valid>. May optionally take an error string, which is matched against all error strings in the result.

Note that normally you shouldn't be testing for an invalid response, as all responses from your application should be valid according to the specification, but this method is provided for completeness. Instead, check for invalid responses right in your application (see LMojolicious::Plugin::OpenAPI::Modern) and log an error when this occurs.

=head2 operation_id_is

Test the C corresponding to the last validated request or response (the unique string used to identify the operation). See Lhttps://spec.openapis.org/oas/v3.1.0#operation-object.

=head2 request_validation_result

Returns the LJSON::Schema::Modern::Result object for the validation result for the last request, or calculates it if not already available.

Does not emit a test result.

=head2 dump_request_validation_result

Prints the LJSON::Schema::Modern::Result object for the validation result for the last request (calculates it if not already available) to the test output stream.

Takes an optional argument indicating the result format, see LJSON::Schema::Modern::Result/output_format. Defaults to C<data_only>, which is the format used for comparing error responses in L</request_not_valid>.

Does not emit a test result.

=head2 response_validation_result

Returns the LJSON::Schema::Modern::Result object for the validation result for the last response, or calculates it if not already available.

Does not emit a test result.

=head2 dump_response_validation_result

Prints the LJSON::Schema::Modern::Result object for the validation result for the last response (calculates it if not already available) to the test output stream.

Does not emit a test result.

=head1 FUTURE FEATURES

Lots of features are still to come, including:

=over 4

=item *

C<request_invalid>, C<response_invalid> test methods, including a mechanism for providing the expected validation error(s)

=item *

stashing the validation results on the test object for reuse or diagnostic printing

=item *

integration with LMojolicious::Plugin::OpenAPI::Modern, including sharing the openapi object and customization options that are set in the application

=back

=head1 SEE ALSO

=over 4

=item *

LMojolicious::Plugin::OpenAPI::Modern

=item *

LTest::Mojo

=item *

LTest::Mojo::WithRoles

=item *

LOpenAPI::Modern

=item *