This library provides a helper for transparently validating HTTP requests and responses against an OpenAPI 3.0 schema in Laravel feature tests. It automatically runs validations during your test runs, allowing you to constantly check for discrepancies between your API specification and its implementation.
- Transparent Validation: Utilizes the
RequestHandledevent to introduce validation with almost no changes to your existing test code. - Flexible Control: Easily enable or disable request/response validation on a per-test basis.
- API Prefix Support: Handles URL prefixes like
/apiseparately from the schema definition. - Easy Setup: Get started by simply using a trait in your
TestCaseand implementing a few methods. - Detailed Error Reporting: Outputs detailed messages on validation failure, indicating which part of the specification was violated.
Install via Composer.
composer require mimosafa/laravel-openapi-validation-helper --devUse the TestCaseHelper trait in your base test case (usually tests/TestCase.php) or in individual test classes.
// tests/TestCase.php
namespace Tests;
use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
use LaravelOpenAPIValidationHelper\TestCaseHelper;
abstract class TestCase extends BaseTestCase
{
use CreatesApplication;
use TestCaseHelper; // Add this trait
}In your test class's setUp() method, call setUpTransparentlyTest().
protected function setUp(): void
{
parent::setUp();
$this->setUpTransparentlyTest(); // Call this method
}Implement the three required abstract methods for validation. It is often convenient to define properties in the test class and override their values in each test method to set them dynamically.
// tests/Feature/ExampleTest.php
namespace Tests\Feature;
use LaravelOpenAPIValidationHelper\HttpRequestMethod;
use League\OpenAPIValidation\PSR7\ValidatorBuilder;
use Tests\TestCase;
class ExampleTest extends TestCase
{
// Set these properties in each test method
protected string $path = '/users/1';
protected HttpRequestMethod $operation = HttpRequestMethod::GET;
protected function path(): string
{
return $this->path;
}
protected function operation(): HttpRequestMethod
{
return $this->operation;
}
protected function getValidatorBuilder(): ValidatorBuilder
{
// Specify the path to your openapi.yml
return (new ValidatorBuilder)->fromYamlFile(base_path('tests/openapi.yml'));
}
protected function setUp(): void
{
parent::setUp();
$this->setUpTransparentlyTest();
}
/** @test */
public function a_user_can_be_retrieved(): void
{
// Set properties
$this->path = '/users/1';
$this->operation = HttpRequestMethod::GET;
// Method and URI can be omitted (automatically retrieved from operation() and path())
$response = $this->json();
$response->assertStatus(200);
// Or you can explicitly specify them as before
// $response = $this->getJson('/users/1');
}
}If your application routes have a prefix like /api/users, override the prefix() method.
class ExampleTest extends TestCase
{
protected string $path = '/users/1';
protected HttpRequestMethod $operation = HttpRequestMethod::GET;
// Override the method to return the prefix
protected function prefix(): string
{
return '/api';
}
protected function path(): string
{
return $this->path;
}
protected function operation(): HttpRequestMethod
{
return $this->operation;
}
protected function getValidatorBuilder(): ValidatorBuilder
{
return (new ValidatorBuilder)->fromYamlFile(base_path('tests/openapi.yml'));
}
protected function setUp(): void
{
parent::setUp();
$this->setUpTransparentlyTest();
}
/** @test */
public function a_user_can_be_retrieved(): void
{
$this->path = '/users/1';
$this->operation = HttpRequestMethod::GET;
// Request to /api/users/1, validated against schema /users/{id}
$response = $this->json();
$response->assertStatus(200);
}
}This library does not perform validation directly. Instead, it delegates the core validation logic to the league/openapi-psr7-validator package. The division of responsibilities is as follows:
- Acts as a "bridge".
- It captures the HTTP request and response executed within a Laravel test.
- It converts them into the PSR-7 standard format that
league/openapi-psr7-validatorcan understand. - During this conversion, it strips any defined prefix (like
/api) to align the path with the OpenAPI schema. - It then hands over the prepared request and response to the validation engine.
- Acts as the "validation engine".
- It reads the
openapi.ymlfile and fully understands the API specification. - It automatically determines which schema template (e.g.,
/users/{id}) corresponds to the concrete path of the request (e.g.,/users/456) passed fromTestCaseHelper. - Based on the matched schema definition, it rigorously checks if the request and response contents (parameters, body, headers, etc.) comply with the specification.
This collaboration allows developers to transparently test for OpenAPI specification compliance simply by writing their Laravel tests as they normally would.
Returns the OpenAPI schema path for the current test.
protected function path(): string
{
return '/users/{id}'; // or a concrete value like '/users/1'
}Returns the HTTP method to validate for the current test.
protected function operation(): HttpRequestMethod
{
return HttpRequestMethod::GET;
}Returns a ValidatorBuilder instance loaded with your OpenAPI schema.
protected function getValidatorBuilder(): ValidatorBuilder
{
return (new ValidatorBuilder)->fromYamlFile(base_path('tests/openapi.yml'));
}Returns the application's routing prefix. Defaults to an empty string. Override this method only if your application uses a prefix.
protected function prefix(): string
{
return '/api'; // Default is '' (empty string)
}Temporarily disables request validation for the current test.
public function test_with_invalid_request(): void
{
$this->ignoreRequestCompliance();
// Request validation will not run even for an invalid request
$this->postJson('/api/users', []);
}Temporarily disables response validation for the current test.
public function test_with_invalid_response(): void
{
$this->ignoreResponseCompliance();
// Response validation will not run
$this->postJson('/api/users', ['generate_invalid_response' => true]);
}The TestCaseHelper trait overrides the json() and call() methods to automatically set default values when arguments are omitted.
When HTTP method and URI are omitted, they are automatically retrieved from operation() and prefix() . path().
// Shorthand (recommended)
$this->json(); // Uses operation() and prefix() . path()
// Explicit specification also possible
$this->json('GET', '/api/users/1');
$this->getJson('/api/users/1'); // Traditional usage still workscall($method = '', $uri = '', $parameters = [], $cookies = [], $files = [], $server = [], $content = null)
Like json(), HTTP method and URI are automatically set to default values when omitted.
// Shorthand
$this->call(); // Uses operation() and prefix() . path()
// Explicit specification also possible
$this->call('POST', '/api/users', ['name' => 'John']);This library was heavily inspired by the development blog post "LaravelアプリケーションのAPIがSwagger/OpenAPIドキュメントに準拠していることを透過的にテストする" by 株式会社Nextat（ネクスタット）.
I would like to express my deep gratitude to the author for publishing such a wonderful idea and implementation hints.
This library is open-sourced software licensed under the MIT license.