phauthentic/phpunit-openapi-assertions

dev-master 2025-06-04 14:49 UTC

Requires

• php: ^8.1
• league/openapi-psr7-validator: ^0.22.0

Requires (Dev)

• nyholm/psr7: ^1.0
• phpmd/phpmd: ^2.15
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^10.0||^11.0||^12.0
• squizlabs/php_codesniffer: ^3.13
• symfony/http-foundation: ^6.0||^7.0
• symfony/phpunit-bridge: ^7.2
• symfony/psr-http-message-bridge: ^6.0||^7.0
• symfony/test-pack: ^1.0

Suggests

• nyholm/psr7: f you want to use Symfony's HTTP Foundation Response and Request Objects
• symfony/http-foundation: If you want to use Symfony's HTTP Foundation Response and Request Objects
• symfony/psr-http-message-bridge: f you want to use Symfony's HTTP Foundation Response and Request Objects

MIT

• Florian Krämer

README

This small library will make it very easy for you to validate your request and response objects against a given Open API Schemas.

Under the hood league/openapi-psr7-validator is used but abstracted in a way that it can be replaced with any other implementation.

Testing the OpenAPI Schema

• Your test case must use the OpenAPIValidatorTrait or extend App\Tests\ApiTestCase
• Your test case must instantiate and set the App\Tests\OpenAPISchemaValidator with the right schema. If you don't do this, the next steps will fail with an exception.
• Call assertRequestMatchesOpenAPISchema($request) to validate the request against the OpenAPI schema.
• Call assertResponseMatchesOpenAPISchema($response) to validate the response against the OpenAPI schema.

Example:

use Phauthentic\PHPUnit\OpenAPIValidator\OpenAPIValidatorTrait;

class MyTestCase extends TestCase 
{
    use OpenAPIValidatorTrait;

    public function setUp(): void
    {
        parent::setUp();
    
        // Load your OpenAPI schema
        self::setOpenAPISchemaValidator = new OpenAPISchemaValidator(
            'path/to/openapi.yaml',
        );
    }
    
    public function testSomeAPIIntegration(): void
    {
        // Create a client and make a request or whatever your framework
        // provides you to make such calls.
        $client = $this->createClient();
        $client->request('POST', '/api/v1/products', [
            'productName' => 'PHP',
        ]);

        // Assert the request and response against the OpenAPI schema
        self::assertRequestMatchesOpenAPISchema($client->getRequest());
        self::assertResponseMatchesOpenAPISchema($client->getResponse());
            path: '/api/v1/follows',
            method: 'post'
        );
    }
}

Symfony Support

Symfony does not support the PSR-7 interface for requests and responses. This means that you cannot use the OpenAPISchemaValidator directly in your Symfony tests. This package provides a workaround for this limitation by using the Symfony Bridge for PHPUnit. This bridge provides a way to use the PSR-7 interface in your Symfony tests.

You need to add those dependencies to your project via Composer:

• nyholm/psr7
• symfony/phpunit-bridge

Instead of using the OpenAPISchemaValidator use the OpenAPISymfonySchemaValidator in your test case.

self::setOpenAPISchemaValidator = new OpenAPISymfonySchemaValidator(
    'path/to/openapi.yaml',
);

License

This bundle is under the MIT license.

Copyright Florian Krämer