I've seen a lot of developers struggle when they first move from testing simple functions to testing HTTP handlers. The instinct is usually to actually start a server on a random port, send a real network request to it, and then shut it down. That's slow, flaky, and completely unnecessary. Go provides the httptest package specifically to avoid that headache.

Let's look at a piece of code I recently reviewed. The developer was trying to test a handler that updates a user's email address via a JSON payload. They were getting a 400 Bad Request, but they had no idea why because their test was too simplistic.

package main

import (
	"encoding/json"
	"net/http"
)

type UserUpdate struct {
	Email string `json:"email"`
}

func UpdateEmailHandler(w http.ResponseWriter, r *http.Request) {
	var update UserUpdate
	if err := json.NewDecoder(r.Body).Decode(&update); err != nil {
		http.Error(w, "Invalid request body", http.StatusBadRequest)
		return
	}
	// Imagine database logic here
	w.WriteHeader(http.StatusOK)
}

// The buggy test
func TestUpdateEmailHandler(t *testing.T) {
	req, _ := http.NewRequest("POST", "/update-email", nil) // Mistake here
	rr := httptest.NewRecorder()
	
	UpdateEmailHandler(rr, req)

	if rr.Code != http.StatusOK {
		t.Errorf("expected 200, got %d", rr.Code)
	}
}

The Silent 400 Bad Request

If you run the test above, it fails. The developer's frustration was that the handler looked correct, and they were sending a POST request, so why the 400? The problem is right here: http.NewRequest("POST", "/update-email", nil). They passed nil as the body. When json.NewDecoder(r.Body).Decode(&update) hits a nil or empty body, it returns an EOF error, which triggers that 400 response.

Another issue here is that the test is "blind." It only checks the status code. When a test fails in a real project, the first thing I do is look at the response body to see what the API is actually complaining about. Without inspecting the ResponseRecorder, you're just guessing.

Wiring up NewRequest and ResponseRecorder

To fix this, we need to simulate a real payload and use the httptest utilities properly. Instead of http.NewRequest, we should use httptest.NewRequest—it's a thinner wrapper that's slightly more convenient for testing. More importantly, we need to actually send the JSON the handler expects.

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"net/http/httptest"
	"testing"
)

func TestUpdateEmailHandler_Fixed(t *testing.T) {
	// 1. Create the payload
	payload := UserUpdate{Email: "test@example.com"}
	body, _ := json.Marshal(payload)

	// 2. Use httptest.NewRequest to create a request with the body
	req := httptest.NewRequest("POST", "/update-email", bytes.NewBuffer(body))
	req.Header.Set("Content-Type", "application/json")

	// 3. Create the ResponseRecorder (this acts as our ResponseWriter)
	rr := httptest.NewRecorder()

	// 4. Call the handler directly
	UpdateEmailHandler(rr, req)

	// 5. Inspect the results
	if rr.Code != http.StatusOK {
		// I always log the body on failure. It saves me 10 minutes of debugging.
		t.Errorf("expected 200, got %d. Body: %s", rr.Code, rr.Body.String())
	}
}

The httptest.ResponseRecorder is the secret sauce here. It implements the http.ResponseWriter interface, but instead of sending bytes over a network socket, it just captures everything (status code, headers, body) into a buffer that you can inspect after the handler finishes. I love this approach because it's purely in-memory; you can run thousands of these tests in a fraction of a second.

One quick tip: notice how I manually set the Content-Type header. Even if your current handler doesn't check it, real-world middleware often does. It's a good habit to make your test requests look exactly like what a real client (like a browser or a mobile app) would send.

📋 Practical Task

Test the API Key Validation Handler

You are building a secure API. You have a handler called AuthHandler that checks for a specific API key in the request header X-API-KEY. If the key is "secret-123", it returns 200 OK. If the key is missing or incorrect, it returns 401 Unauthorized.

Your task: Write two tests using httptest.NewRequest and httptest.NewRecorder:

1. TestAuthHandler_ValidKey: Verify that providing the correct key results in a 200 status code.
2. TestAuthHandler_InvalidKey: Verify that providing an incorrect key results in a 401 status code.

Here is the handler code to get you started:

func AuthHandler(w http.ResponseWriter, r *http.Request) {
	key := r.Header.Get("X-API-KEY")
	if key != "secret-123" {
		http.Error(w, "Unauthorized", http.StatusUnauthorized)
		return
	}
	w.WriteHeader(http.StatusOK)
}