Using an OpenAPI spec is a great way to create and share a contract to which your API adheres. This package will automatically verify both the request and response used in your integration and feature tests wherever the Laravel HTTP testing methods (->get('/uri'), etc) are used.
Behind the scenes this package connects the Laravel HTTP helpers to The PHP League's OpenAPI Validator.
You can install the package via composer:
composer require kirschbaum-development/laravel-openapi-validatorIn any feature/integration test (such as those that extend the framework's Tests\TestCase base class), add the ValidatesOpenApiSpec trait:
use Kirschbaum\OpenApiValidator\ValidatesOpenApiSpec;
class HttpTest extends TestCase
{
use ValidatesOpenApiSpec;
}In many situations, the defaults should handle configuration. If you need to customize your configuration (namely the location of the openapi.yaml or openapi.json file), publish the config with:
php artisan vendor:publish --provider="Kirschbaum\OpenApiValidator\OpenApiValidatorServiceProvider"and configure the path to the OpenAPI spec in config/openapi_validator.php to fit your needs.
After applying the trait to your test class, anytime you interact with an HTTP test method (get, post, put, delete, postJson, call, etc), the validator will validate both the request and the response.
Especially when initially writing tests (such as in TDD), it can be helpful to turn off the request or response validation until the tests are closer to complete. You can do so as follows:
public function testEndpointInProgress()
{
$response = $this->withoutRequestValidation()->get('/'); // Skips request validation, still validates response
// or
$response = $this->withoutResponseValidation()->get('/'); // Validates the request, but skips response
// or
$response = $this->withoutValidation()->get('/'); // No validation
}You are free to chain these methods as shown above, or call them on their own:
public function testEndpointInProgress()
{
$this->withoutRequestValidation();
$response = $this->get('/');
}Keep in mind that withoutRequestValidation(), withoutResponseValidation(), and withoutValidation() only apply to the next request/response and will reset afterwards.
We assume, by default, that any 5xx status code should not be validated. You may change this by setting the protected responseCodesToSkip property on your test class, or by using the skipResponseCode method to add response codes (single, array, or a regex pattern):
use Kirschbaum\OpenApiValidator\ValidatesOpenApiSpec;
class HttpTest extends TestCase
{
use ValidatesOpenApiSpec;
protected $responseCodesToSkip = [200]; // Will validate every response EXCEPT 200
public function testNoRedirects()
{
$this->skipResponseCode(300); // Will skip 200 and 300
$this->skipResponseCode(301, 302); // Will skip 200, 300, 301, 302
$this->skipResponseCode('3[1-2]1'); // Will skip 200, 300, 301, 302, 311, and 321
// ...
}
}In most tests, you're likely using Laravel's helpers such as actingAs($user) to handle auth. This package, by default, assumes you're using bearer token as an authorization header, and that this is specified in your OpenAPI spec. The validator will expect the authorization to be part of the request, even though Laravel does not send them. If you are using security other than a bearer token, you should override the getAuthenticatedRequest method and add the appropriate headers. Note that they do not need to be valid (unless your code will check them), they just need to be present to satisfy the validator.
Please see CONTRIBUTING for details.
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
Development of this package is sponsored by Kirschbaum Development Group, a developer driven company focused on problem solving, team building, and community. Learn more about us or join us!
The MIT License (MIT). Please see License File for more information.