NAME
Test::Mojo::Role::OpenAPI::Modern - Test::Mojo role providing access to an OpenAPI document and parser
VERSION
version 0.006
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');DESCRIPTION
Provides methods on a Test::Mojo object suitable for using OpenAPI::Modern to validate the request and response.
ACCESSORS/METHODS
openapi
The OpenAPI::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 JSON::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 openapi key (see "new" in Test::Mojo), as for Mojolicious::Plugin::OpenAPI::Modern, or re-uses the object from the application itself if that plugin is applied.
test_openapi_verbose
When true, failing request and response validation tests will dump the actual validation result via "dump_request_validation_result" or "dump_response_validation_result".
Defaults to false.
request_valid
Passes $t->tx->req to "validate_request" in OpenAPI::Modern, as in "validate_request" in Mojolicious::Plugin::OpenAPI::Modern, producing a boolean test result.
request_not_valid, request_invalid
The inverse of "request_valid". May optionally take an error string, which is matched against the "recommended_response" in JSON::Schema::Modern::Result, and all error strings in the result.
response_valid
Passes $t->tx->res to "validate_response" in OpenAPI::Modern as in "validate_response" in Mojolicious::Plugin::OpenAPI::Modern, producing a boolean test result.
response_not_valid, response_invalid
The inverse of "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 Mojolicious::Plugin::OpenAPI::Modern) and log an error when this occurs.
operation_id_is
Test the operationId corresponding to the last validated request or response (the unique string used to identify the operation). See https://spec.openapis.org/oas/v3.1.0#operation-object.
request_validation_result
Returns the JSON::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.
dump_request_validation_result
Prints the JSON::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 "output_format" in JSON::Schema::Modern::Result. Defaults to data_only, which is the format used for comparing error responses in "request_not_valid".
Does not emit a test result.
response_validation_result
Returns the JSON::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.
dump_response_validation_result
Prints the JSON::Schema::Modern::Result object for the validation result for the last response (calculates it if not already available) to the test output stream.
Takes an optional argument indicating the result format, see "output_format" in JSON::Schema::Modern::Result. Defaults to data_only, which is the format used for comparing error responses in "response_not_valid".
Does not emit a test result.
FUTURE FEATURES
Lots of features are still to come, including:
request_invalid,response_invalidtest methods, including a mechanism for providing the expected validation error(s)stashing the validation results on the test object for reuse or diagnostic printing
integration with Mojolicious::Plugin::OpenAPI::Modern, including sharing the openapi object and customization options that are set in the application
SEE ALSO
SUPPORT
Bugs may be submitted through https://github.com/karenetheridge/Test-Mojo-Role-OpenAPI-Modern/issues.
There is also an irc channel available for users of this distribution, at #mojo on irc.libera.chat.
I am also usually active on irc, as 'ether' at irc.perl.org and irc.libera.chat.
AUTHOR
Karen Etheridge <ether@cpan.org>
COPYRIGHT AND LICENCE
This software is copyright (c) 2023 by Karen Etheridge.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.