From c4f6d09c07f0f4be15dd1a5e901bd27fc9ead8c4 Mon Sep 17 00:00:00 2001 From: RubenPari Date: Sat, 8 Aug 2026 11:11:44 +0200 Subject: [PATCH] docs(test): document status code flushing behavior in CreateTestContext CreateTestContext does not flush the response at the end of a handler, unlike Engine.ServeHTTP. This caused confusion (issue #3443) when ctx.Status(http.StatusCreated) was not observable in the httptest.ResponseRecorder without calling ctx.Writer.WriteHeaderNow(). Added documentation to CreateTestContext and CreateTestContextOnly explaining this behavior, plus a regression test verifying that Status() buffers the code and WriteHeaderNow() flushes it. Fixes #3443 --- context_test.go | 15 +++++++++++++++ test_helpers.go | 10 ++++++++++ 2 files changed, 25 insertions(+) diff --git a/context_test.go b/context_test.go index e8d305e4..85a5dcb1 100644 --- a/context_test.go +++ b/context_test.go @@ -3513,6 +3513,21 @@ func TestCreateTestContextWithRouteParams(t *testing.T) { assert.Equal(t, "hello gin", w.Body.String()) } +func TestCreateTestContextStatusRequiresFlush(t *testing.T) { + w := httptest.NewRecorder() + c, _ := CreateTestContext(w) + c.Request = httptest.NewRequest(http.MethodGet, "/", nil) + + // Status() buffers the code but does not flush to the ResponseWriter + c.Status(http.StatusCreated) + assert.Equal(t, http.StatusCreated, c.Writer.Status()) + assert.Equal(t, http.StatusOK, w.Code, "status not yet flushed to recorder") + + // After WriteHeaderNow, the recorder observes the status code + c.Writer.WriteHeaderNow() + assert.Equal(t, http.StatusCreated, w.Code) +} + type interceptedWriter struct { ResponseWriter b *bytes.Buffer diff --git a/test_helpers.go b/test_helpers.go index 146be8f3..6894c3de 100644 --- a/test_helpers.go +++ b/test_helpers.go @@ -14,6 +14,13 @@ import ( // This is useful for tests that need to set up a new Gin engine instance // along with a context, for example, to test middleware that doesn't depend on // specific routes. The ResponseWriter `w` is used to initialize the context's writer. +// +// Unlike Engine.ServeHTTP, CreateTestContext does not flush the response at the +// end of the handler. The status code set by Context.Status is buffered until +// the response body is written (Context.Writer.Write/WriteString) or +// Context.Writer.WriteHeaderNow is called. To observe the status code in the +// ResponseWriter after a handler that only calls Context.Status, call +// c.Writer.WriteHeaderNow() explicitly. func CreateTestContext(w http.ResponseWriter) (c *Context, r *Engine) { r = New() c = r.allocateContext(0) @@ -27,6 +34,9 @@ func CreateTestContext(w http.ResponseWriter) (c *Context, r *Engine) { // Gin engine instance and need a new context for it. // The ResponseWriter `w` is used to initialize the context's writer. // The context is allocated with the `maxParams` setting from the provided engine. +// +// Unlike Engine.ServeHTTP, CreateTestContextOnly does not flush the response at the +// end of the handler. See CreateTestContext for details on observing the status code. func CreateTestContextOnly(w http.ResponseWriter, r *Engine) (c *Context) { c = r.allocateContext(r.maxParams) c.reset()