test: add companion test demonstrating group catch-all masking

Addresses final review: converts the "verified empirically" comment into an
actual test. TestGroupRoute_catchAllMasksMethodHandling registers a group-wide
catch-all and asserts it masks both the 405 method-mismatch and the automatic
OPTIONS (204) response as 404 — the regression the 405/OPTIONS gate tests guard
against. Makes the rationale self-proving in-repo.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: vishr

group_method_handling_test.go

@@ -18,10 +18,9 @@ import (
 // They double as a regression gate. Registering a group-level catch-all — whether
 // manually via g.RouteNotFound("/*", ...) or automatically (as proposed in #2996 to
 // fix CORS-on-group preflight) — makes that catch-all match every method, which masks
-// both 405 and v5's automatic OPTIONS response as 404. Verified empirically: with such
-// a catch-all in place, "POST /api/users" returns 404 instead of 405 and
-// "OPTIONS /api/users" returns 404 instead of 204. If that behavior reaches this
-// branch, the first two tests below fail.
+// both 405 and v5's automatic OPTIONS response as 404 — demonstrated directly by
+// TestGroupRoute_catchAllMasksMethodHandling below. If that masking becomes the
+// default (e.g. #2996 lands), the first two tests below fail.
 
 // A method mismatch on an existing group route must return 405 with the allowed
 // methods, not be masked to 404.
@@ -83,3 +82,34 @@ func TestGroup_doesNotAffectRootRoutes(t *testing.T) {
 	assert.Equal(t, http.StatusOK, status)
 	assert.Equal(t, "root", body)
 }
+
+// Characterization of the regression the 405/OPTIONS tests above guard against:
+// registering a group-wide catch-all (the manual equivalent of #2996's auto-
+// registration) makes it match every method, so method mismatches and the automatic
+// OPTIONS response are masked as 404 even though the concrete route still resolves.
+// If a future change teaches the catch-all to preserve method semantics, update this.
+func TestGroupRoute_catchAllMasksMethodHandling(t *testing.T) {
+	e := New()
+	g := e.Group("/api")
+	g.GET("/users", func(c *Context) error { return c.String(http.StatusOK, "users") })
+	g.RouteNotFound("/*", func(c *Context) error { return c.NoContent(http.StatusNotFound) })
+
+	// The concrete route still resolves.
+	status, body := request(http.MethodGet, "/api/users", e)
+	assert.Equal(t, http.StatusOK, status)
+	assert.Equal(t, "users", body)
+
+	// But the catch-all masks the method mismatch (would be 405) ...
+	post := httptest.NewRequest(http.MethodPost, "/api/users", nil)
+	postRec := httptest.NewRecorder()
+	e.ServeHTTP(postRec, post)
+	assert.Equal(t, http.StatusNotFound, postRec.Code,
+		"a group-wide catch-all masks the 405 method-mismatch as 404")
+
+	// ... and the automatic OPTIONS response (would be 204).
+	opts := httptest.NewRequest(http.MethodOptions, "/api/users", nil)
+	optsRec := httptest.NewRecorder()
+	e.ServeHTTP(optsRec, opts)
+	assert.Equal(t, http.StatusNotFound, optsRec.Code,
+		"a group-wide catch-all masks the automatic OPTIONS (204) response as 404")
+}