feat(laravel): auto-validate responses via createTestResponse hook

Adds openapi-contract-testing.auto_assert config key (default false).
When true, every TestResponse produced by Laravel HTTP helpers is
validated against the OpenAPI spec without requiring an explicit
assertResponseMatchesOpenApiSchema() call in each test.

Implementation overrides Illuminate\Foundation\Testing\TestCase::
createTestResponse() from the ValidatesOpenApiSchema trait. Macros
cannot override existing methods like assertStatus(), so the hook
fires one level earlier, when Laravel wraps the HTTP response into
a TestResponse. A WeakMap guards against double-validation, making
auto-assert and manual assertResponseMatchesOpenApiSchema() calls
on the same response idempotent.

Closes #39

Author: wadakatu

README.md

@@ -85,6 +85,11 @@ return [
     // Maximum number of validation errors to report per response.
     // 0 = unlimited (reports all errors).
     'max_errors' => 20,
+
+    // Automatically validate every TestResponse produced by Laravel HTTP
+    // helpers (get(), post(), etc.) against the OpenAPI spec. Defaults to
+    // false for backward compatibility.
+    'auto_assert' => false,
 ];
 ```
 
@@ -223,6 +228,39 @@ $validator = new OpenApiResponseValidator(maxErrors: 1);
 
 For Laravel, set the `max_errors` key in `config/openapi-contract-testing.php`.
 
+#### Auto-assert every response
+
+Forgetting `$this->assertResponseMatchesOpenApiSchema($response)` in a test means the contract is silently unchecked. Enable `auto_assert` to validate every response produced by Laravel's HTTP helpers automatically — just include the trait:
+
+```php
+// config/openapi-contract-testing.php
+return [
+    'default_spec' => 'front',
+    'auto_assert'  => true,
+];
+```
+
+```php
+use Studio\OpenApiContractTesting\Laravel\ValidatesOpenApiSchema;
+
+class GetPetsTest extends TestCase
+{
+    use ValidatesOpenApiSchema;
+
+    public function test_list_pets(): void
+    {
+        // Contract is checked automatically — no explicit assert call needed.
+        $this->get('/api/v1/pets')->assertOk();
+    }
+}
+```
+
+Notes:
+
+- Defaults to `false` so existing test suites keep their explicit-assert behavior.
+- Auto-assert hooks into `createTestResponse()`, which is only invoked by Laravel's `MakesHttpRequests`. Responses you construct manually (outside `$this->get()`, `$this->post()`, etc.) are not touched.
+- Calling `$this->assertResponseMatchesOpenApiSchema($response)` on a response that auto-assert already validated is a no-op (idempotent), so mixing both styles is safe.
+
 ## Coverage Report
 
 After running tests, the PHPUnit extension prints a coverage report. The output format is controlled by the `console_output` parameter (or `OPENAPI_CONSOLE_OUTPUT` environment variable).

src/Laravel/ValidatesOpenApiSchema.php

@@ -10,6 +10,8 @@
 use Studio\OpenApiContractTesting\OpenApiCoverageTracker;
 use Studio\OpenApiContractTesting\OpenApiResponseValidator;
 use Studio\OpenApiContractTesting\OpenApiSpecResolver;
+use Symfony\Component\HttpFoundation\Response;
+use WeakMap;
 
 use function is_numeric;
 use function is_string;
@@ -22,10 +24,45 @@ trait ValidatesOpenApiSchema
     private static ?OpenApiResponseValidator $cachedValidator = null;
     private static ?int $cachedMaxErrors = null;
 
+    /** @var null|WeakMap<TestResponse, true> */
+    private static ?WeakMap $validatedResponses = null;
+
     public static function resetValidatorCache(): void
     {
         self::$cachedValidator = null;
         self::$cachedMaxErrors = null;
+        self::$validatedResponses = null;
+    }
+
+    /**
+     * Overrides Illuminate\Foundation\Testing\TestCase::createTestResponse so
+     * every HTTP test call runs schema validation when auto_assert is enabled.
+     * When the library is used outside Laravel, this method is never called.
+     *
+     * @param Response $response
+     */
+    protected function createTestResponse($response, $request = null): TestResponse
+    {
+        $testResponse = parent::createTestResponse($response, $request);
+        $this->maybeAutoAssertOpenApiSchema($testResponse);
+
+        return $testResponse;
+    }
+
+    protected function maybeAutoAssertOpenApiSchema(
+        TestResponse $response,
+        ?HttpMethod $method = null,
+        ?string $path = null,
+    ): void {
+        if (config('openapi-contract-testing.auto_assert') !== true) {
+            return;
+        }
+
+        if (self::isAlreadyValidated($response)) {
+            return;
+        }
+
+        $this->assertResponseMatchesOpenApiSchema($response, $method, $path);
     }
 
     protected function openApiSpec(): string
@@ -49,6 +86,11 @@ protected function assertResponseMatchesOpenApiSchema(
         ?HttpMethod $method = null,
         ?string $path = null,
     ): void {
+        if (self::isAlreadyValidated($response)) {
+            return;
+        }
+        self::markValidated($response);
+
         $specName = $this->resolveOpenApiSpec();
         if ($specName === '') {
             $this->fail(
@@ -97,6 +139,18 @@ protected function assertResponseMatchesOpenApiSchema(
         );
     }
 
+    private static function isAlreadyValidated(TestResponse $response): bool
+    {
+        return self::$validatedResponses !== null &&
+            isset(self::$validatedResponses[$response]);
+    }
+
+    private static function markValidated(TestResponse $response): void
+    {
+        self::$validatedResponses ??= new WeakMap();
+        self::$validatedResponses[$response] = true;
+    }
+
     private static function getOrCreateValidator(): OpenApiResponseValidator
     {
         $maxErrors = config('openapi-contract-testing.max_errors', 20);

src/Laravel/config.php

@@ -8,4 +8,10 @@
     // Maximum number of validation errors to report per response.
     // 0 = unlimited (reports all errors).
     'max_errors' => 20,
+
+    // When true, every TestResponse produced by Laravel HTTP test helpers
+    // (get(), post(), etc.) is validated against the OpenAPI spec at creation
+    // time, without requiring an explicit assertResponseMatchesOpenApiSchema()
+    // call in each test. Defaults to false for backward compatibility.
+    'auto_assert' => false,
 ];

tests/Integration/Laravel/AutoAssertIntegrationTest.php

@@ -0,0 +1,131 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Studio\OpenApiContractTesting\Tests\Integration\Laravel;
+
+use Illuminate\Support\Facades\Route;
+use Orchestra\Testbench\TestCase;
+use PHPUnit\Framework\AssertionFailedError;
+use PHPUnit\Framework\Attributes\Test;
+use Studio\OpenApiContractTesting\Laravel\OpenApiContractTestingServiceProvider;
+use Studio\OpenApiContractTesting\Laravel\ValidatesOpenApiSchema;
+use Studio\OpenApiContractTesting\OpenApiCoverageTracker;
+use Studio\OpenApiContractTesting\OpenApiSpecLoader;
+
+use function dirname;
+
+/**
+ * Full Laravel integration test proving that applying the
+ * ValidatesOpenApiSchema trait with auto_assert=true is sufficient for
+ * $this->get() / post() / etc. to trigger OpenAPI validation — no explicit
+ * assertResponseMatchesOpenApiSchema() call required.
+ */
+class AutoAssertIntegrationTest extends TestCase
+{
+    use ValidatesOpenApiSchema;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        OpenApiSpecLoader::reset();
+        OpenApiSpecLoader::configure(dirname(__DIR__, 2) . '/fixtures/specs');
+        OpenApiCoverageTracker::reset();
+        config()->set('openapi-contract-testing.default_spec', 'petstore-3.0');
+    }
+
+    protected function tearDown(): void
+    {
+        self::resetValidatorCache();
+        OpenApiSpecLoader::reset();
+        OpenApiCoverageTracker::reset();
+        parent::tearDown();
+    }
+
+    #[Test]
+    public function auto_assert_true_validates_http_response_without_explicit_call(): void
+    {
+        config()->set('openapi-contract-testing.auto_assert', true);
+
+        // No explicit assertResponseMatchesOpenApiSchema call — trait alone
+        // must trigger validation when auto_assert=true.
+        $response = $this->get('/v1/pets');
+
+        $response->assertOk();
+
+        $covered = OpenApiCoverageTracker::getCovered();
+        $this->assertArrayHasKey('petstore-3.0', $covered);
+        $this->assertArrayHasKey('GET /v1/pets', $covered['petstore-3.0']);
+    }
+
+    #[Test]
+    public function auto_assert_true_raises_assertion_error_on_schema_mismatch(): void
+    {
+        config()->set('openapi-contract-testing.auto_assert', true);
+
+        $this->expectException(AssertionFailedError::class);
+        $this->expectExceptionMessage('OpenAPI schema validation failed');
+
+        // Auto-assert must surface the mismatch without an explicit assert.
+        $this->get('/v1/pets?bad=1');
+    }
+
+    #[Test]
+    public function auto_assert_false_does_not_validate_automatically(): void
+    {
+        config()->set('openapi-contract-testing.auto_assert', false);
+
+        // Invalid body but auto_assert=false — no exception, no coverage.
+        $response = $this->get('/v1/pets?bad=1');
+
+        $response->assertOk();
+
+        $covered = OpenApiCoverageTracker::getCovered();
+        $this->assertArrayNotHasKey('petstore-3.0', $covered);
+    }
+
+    #[Test]
+    public function auto_assert_not_set_defaults_to_skip(): void
+    {
+        // auto_assert not explicitly set — config merge default (false) applies.
+        $response = $this->get('/v1/pets?bad=1');
+
+        $response->assertOk();
+
+        $covered = OpenApiCoverageTracker::getCovered();
+        $this->assertArrayNotHasKey('petstore-3.0', $covered);
+    }
+
+    #[Test]
+    public function explicit_and_auto_assert_are_idempotent(): void
+    {
+        config()->set('openapi-contract-testing.auto_assert', true);
+
+        // Auto-assert runs during $this->get(). A subsequent explicit call on
+        // the same response must not re-run validation nor re-record coverage.
+        $response = $this->get('/v1/pets');
+        $this->assertResponseMatchesOpenApiSchema($response);
+
+        $covered = OpenApiCoverageTracker::getCovered();
+        $this->assertCount(1, $covered['petstore-3.0'] ?? []);
+    }
+
+    /** @return array<int, class-string> */
+    protected function getPackageProviders($app): array
+    {
+        return [OpenApiContractTestingServiceProvider::class];
+    }
+
+    protected function defineRoutes($router): void
+    {
+        Route::get('/v1/pets', static function () {
+            $bad = request()->query('bad') === '1';
+
+            return response()->json(
+                $bad
+                    ? ['wrong_key' => 'value']
+                    : ['data' => [['id' => 1, 'name' => 'Fido', 'tag' => null]]],
+            );
+        });
+    }
+}