test(laravel): cover POST, attribute resolution, and tuple idempotency

wadakatu · wadakatu · commit 714b9f2da02b · 2026-04-23T02:14:26.000+09:00
Addresses PR #54 review feedback (pr-test-analyzer, comment-analyzer): - Integration: POST auto-assert, #[OpenApiSpec] attribute interaction, invalid-config fail-loud, truthy-string acceptance. - Unit: non-bool-value fails loudly, truthy-string validates, and a different (method, path) signature re-validates the same response instead of silently no-oping (the tuple-keyed idempotency guarantee). - Renamed auto_assert_then_manual_assert_does_not_raise_for_invalid_response to accurately describe what it tests (same-signature coverage de-duplication, not a caught-failure scenario). - Removed redundant WHAT-style comments duplicated by test names.
diff --git a/tests/Integration/Laravel/AutoAssertIntegrationTest.php b/tests/Integration/Laravel/AutoAssertIntegrationTest.php
@@ -11,15 +11,18 @@
 use Studio\OpenApiContractTesting\Laravel\OpenApiContractTestingServiceProvider;
 use Studio\OpenApiContractTesting\Laravel\ValidatesOpenApiSchema;
 use Studio\OpenApiContractTesting\OpenApiCoverageTracker;
+use Studio\OpenApiContractTesting\OpenApiSpec;
 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.
+ * Exercises the full `$this->get()` / `$this->post()` → Laravel kernel →
+ * `MakesHttpRequests::createTestResponse` → trait override pipeline under a
+ * real Testbench app. Complements the unit tests (which call
+ * `maybeAutoAssertOpenApiSchema` directly) by proving the framework-boundary
+ * integration — the trait-provided `createTestResponse` actually wins over
+ * the one Laravel merges in from `MakesHttpRequests`.
  */
 class AutoAssertIntegrationTest extends TestCase
 {
@@ -43,14 +46,11 @@ protected function tearDown(): void
     }
 
     #[Test]
-    public function auto_assert_true_validates_http_response_without_explicit_call(): void
+    public function auto_assert_true_validates_get_response(): 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();
@@ -59,57 +59,110 @@ public function auto_assert_true_validates_http_response_without_explicit_call()
     }
 
     #[Test]
-    public function auto_assert_true_raises_assertion_error_on_schema_mismatch(): void
+    public function auto_assert_true_validates_post_response(): void
+    {
+        // Pins POST specifically: the hook is verb-agnostic in theory, but a
+        // regression that guards createTestResponse behind `method === 'GET'`
+        // would otherwise go undetected.
+        config()->set('openapi-contract-testing.auto_assert', true);
+
+        $response = $this->postJson('/v1/pets', ['name' => 'Buddy']);
+        $response->assertCreated();
+
+        $covered = OpenApiCoverageTracker::getCovered();
+        $this->assertArrayHasKey('POST /v1/pets', $covered['petstore-3.0'] ?? []);
+    }
+
+    #[Test]
+    public function auto_assert_true_raises_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
+    public function auto_assert_false_does_not_validate(): 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);
+        $this->assertArrayNotHasKey('petstore-3.0', OpenApiCoverageTracker::getCovered());
     }
 
     #[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();
+
+        $this->assertArrayNotHasKey('petstore-3.0', OpenApiCoverageTracker::getCovered());
+    }
+
+    #[Test]
+    public function auto_assert_with_invalid_config_value_fails_loudly(): void
+    {
+        // Common user mistake: config value is a non-boolean-compatible value
+        // (e.g. typo in a cast). The trait must surface this as a clear test
+        // failure rather than silently treating it as "off".
+        config()->set('openapi-contract-testing.auto_assert', 'definitely-not-a-bool');
+
+        $this->expectException(AssertionFailedError::class);
+        $this->expectExceptionMessage('auto_assert must be a boolean');
 
+        $this->get('/v1/pets');
+    }
+
+    #[Test]
+    public function auto_assert_accepts_string_true_as_truthy(): void
+    {
+        // env('X') returns strings — `'auto_assert' => env('AUTO_ASSERT')`
+        // would yield "true" (not boolean true). FILTER_VALIDATE_BOOLEAN
+        // treats this as truthy, so the user isn't punished for common
+        // env-var wiring.
+        config()->set('openapi-contract-testing.auto_assert', 'true');
+
+        $response = $this->get('/v1/pets');
         $response->assertOk();
 
         $covered = OpenApiCoverageTracker::getCovered();
-        $this->assertArrayNotHasKey('petstore-3.0', $covered);
+        $this->assertArrayHasKey('GET /v1/pets', $covered['petstore-3.0'] ?? []);
     }
 
     #[Test]
-    public function explicit_and_auto_assert_are_idempotent(): void
+    public function explicit_assert_after_auto_assert_is_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'] ?? []);
     }
 
+    #[Test]
+    #[OpenApiSpec('petstore-3.1')]
+    public function method_level_attribute_resolves_spec_for_auto_assert(): void
+    {
+        // default_spec is set to petstore-3.0 in setUp, but this method is
+        // decorated with #[OpenApiSpec('petstore-3.1')] — auto-assert must
+        // respect the attribute and record coverage under 3.1, not 3.0.
+        config()->set('openapi-contract-testing.auto_assert', true);
+
+        $response = $this->get('/v1/pets');
+        $response->assertOk();
+
+        $covered = OpenApiCoverageTracker::getCovered();
+        $this->assertArrayHasKey('petstore-3.1', $covered);
+        $this->assertArrayNotHasKey('petstore-3.0', $covered);
+    }
+
     /** @return array<int, class-string> */
     protected function getPackageProviders($app): array
     {
@@ -127,5 +180,10 @@ protected function defineRoutes($router): void
                     : ['data' => [['id' => 1, 'name' => 'Fido', 'tag' => null]]],
             );
         });
+
+        Route::post('/v1/pets', static fn() => response()->json(
+            ['data' => ['id' => 42, 'name' => 'Buddy', 'tag' => null]],
+            201,
+        ));
     }
 }
diff --git a/tests/Unit/ValidatesOpenApiSchemaAutoAssertTest.php b/tests/Unit/ValidatesOpenApiSchemaAutoAssertTest.php
@@ -94,7 +94,6 @@ public function auto_assert_false_skips_validation_for_invalid_response(): void
         $body = (string) json_encode(['wrong_key' => 'value'], JSON_THROW_ON_ERROR);
         $response = $this->makeTestResponse($body, 200);
 
-        // No exception expected — validation is skipped.
         $this->maybeAutoAssertOpenApiSchema($response, HttpMethod::GET, '/v1/pets');
 
         $covered = OpenApiCoverageTracker::getCovered();
@@ -104,7 +103,6 @@ public function auto_assert_false_skips_validation_for_invalid_response(): void
     #[Test]
     public function auto_assert_not_set_skips_validation_for_invalid_response(): void
     {
-        // No auto_assert config key present — default should be false.
         $body = (string) json_encode(['wrong_key' => 'value'], JSON_THROW_ON_ERROR);
         $response = $this->makeTestResponse($body, 200);
 
@@ -115,7 +113,45 @@ public function auto_assert_not_set_skips_validation_for_invalid_response(): voi
     }
 
     #[Test]
-    public function double_manual_assert_is_idempotent(): void
+    public function auto_assert_with_non_bool_value_fails_loudly(): void
+    {
+        // A user who mis-configures auto_assert (e.g. via env without cast)
+        // should see a loud failure, not a silent skip.
+        $GLOBALS['__openapi_testing_config']['openapi-contract-testing.auto_assert'] = 'yolo';
+
+        $body = (string) json_encode(
+            ['data' => [['id' => 1, 'name' => 'Fido', 'tag' => null]]],
+            JSON_THROW_ON_ERROR,
+        );
+        $response = $this->makeTestResponse($body, 200);
+
+        $this->expectException(AssertionFailedError::class);
+        $this->expectExceptionMessage('auto_assert must be a boolean');
+
+        $this->maybeAutoAssertOpenApiSchema($response, HttpMethod::GET, '/v1/pets');
+    }
+
+    #[Test]
+    public function auto_assert_with_truthy_string_validates(): void
+    {
+        // env('X') returns strings; "true" must be treated as truthy so that
+        // `'auto_assert' => env('AUTO_ASSERT')` (the idiomatic Laravel
+        // pattern) works without an explicit cast.
+        $GLOBALS['__openapi_testing_config']['openapi-contract-testing.auto_assert'] = 'true';
+
+        $body = (string) json_encode(
+            ['data' => [['id' => 1, 'name' => 'Fido', 'tag' => null]]],
+            JSON_THROW_ON_ERROR,
+        );
+        $response = $this->makeTestResponse($body, 200);
+
+        $this->maybeAutoAssertOpenApiSchema($response, HttpMethod::GET, '/v1/pets');
+
+        $this->assertArrayHasKey('petstore-3.0', OpenApiCoverageTracker::getCovered());
+    }
+
+    #[Test]
+    public function double_manual_assert_with_same_signature_is_idempotent(): void
     {
         $body = (string) json_encode(
             ['data' => [['id' => 1, 'name' => 'Fido', 'tag' => null]]],
@@ -128,15 +164,11 @@ public function double_manual_assert_is_idempotent(): void
 
         $covered = OpenApiCoverageTracker::getCovered();
         $this->assertArrayHasKey('petstore-3.0', $covered);
-        $this->assertCount(
-            1,
-            $covered['petstore-3.0'],
-            'Coverage entries should not be duplicated when the same response is validated twice.',
-        );
+        $this->assertCount(1, $covered['petstore-3.0']);
     }
 
     #[Test]
-    public function manual_assert_then_auto_assert_is_idempotent(): void
+    public function manual_then_auto_assert_with_same_signature_is_idempotent(): void
     {
         $GLOBALS['__openapi_testing_config']['openapi-contract-testing.auto_assert'] = true;
 
@@ -147,27 +179,19 @@ public function manual_assert_then_auto_assert_is_idempotent(): void
         $response = $this->makeTestResponse($body, 200);
 
         $this->assertResponseMatchesOpenApiSchema($response, HttpMethod::GET, '/v1/pets');
+        $countBefore = count(OpenApiCoverageTracker::getCovered()['petstore-3.0'] ?? []);
 
-        $coveredBefore = OpenApiCoverageTracker::getCovered();
-        $countBefore = count($coveredBefore['petstore-3.0'] ?? []);
-
-        // A subsequent auto-assert on the same response must not re-validate or
-        // re-record coverage.
         $this->maybeAutoAssertOpenApiSchema($response, HttpMethod::GET, '/v1/pets');
 
-        $coveredAfter = OpenApiCoverageTracker::getCovered();
-        $this->assertCount($countBefore, $coveredAfter['petstore-3.0'] ?? []);
+        $this->assertCount($countBefore, OpenApiCoverageTracker::getCovered()['petstore-3.0'] ?? []);
     }
 
     #[Test]
-    public function auto_assert_then_manual_assert_does_not_raise_for_invalid_response(): void
+    public function auto_then_manual_assert_with_same_signature_does_not_duplicate_coverage(): void
     {
-        // When auto-assert has already failed (and been caught), a manual
-        // assert on the same response instance should no-op so the same error
-        // is not reported twice. We simulate this by recording the response as
-        // validated via a successful auto-assert first, then calling the
-        // manual API — which would normally raise on a subsequent mismatch —
-        // expecting no exception because the response is already marked.
+        // After a successful auto-assert, a manual call with the matching
+        // (method, path) signature must no-op — no second validator run,
+        // no second coverage entry.
         $GLOBALS['__openapi_testing_config']['openapi-contract-testing.auto_assert'] = true;
 
         $body = (string) json_encode(
@@ -177,11 +201,27 @@ public function auto_assert_then_manual_assert_does_not_raise_for_invalid_respon
         $response = $this->makeTestResponse($body, 200);
 
         $this->maybeAutoAssertOpenApiSchema($response, HttpMethod::GET, '/v1/pets');
-        // Calling manual assert afterwards must not throw or add another
-        // coverage entry.
         $this->assertResponseMatchesOpenApiSchema($response, HttpMethod::GET, '/v1/pets');
 
-        $covered = OpenApiCoverageTracker::getCovered();
-        $this->assertCount(1, $covered['petstore-3.0'] ?? []);
+        $this->assertCount(1, OpenApiCoverageTracker::getCovered()['petstore-3.0'] ?? []);
+    }
+
+    #[Test]
+    public function manual_assert_with_different_method_path_re_validates_same_response(): void
+    {
+        // Idempotency is keyed on (spec, method, path) — a second call with
+        // different (method, path) must re-validate, not silently no-op.
+        // We prove this by making the second call one that SHOULD fail:
+        // if idempotency wrongly skipped it, no exception would be raised.
+        //
+        // The empty 204 body validates against DELETE /v1/pets/{petId} but
+        // does NOT satisfy GET /v1/pets (which expects a JSON body). Before
+        // the tuple-keyed fix, this second call was silently skipped.
+        $response = $this->makeTestResponse('', 204);
+
+        $this->assertResponseMatchesOpenApiSchema($response, HttpMethod::DELETE, '/v1/pets/123');
+
+        $this->expectException(AssertionFailedError::class);
+        $this->assertResponseMatchesOpenApiSchema($response, HttpMethod::GET, '/v1/pets');
     }
 }
