Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท Networking and the Web

Go net/http/httptest package

Reference for Go net/http/httptest: NewRequest, ResponseRecorder, NewServer and NewTLSServer for testing handlers and HTTP clients without real network setup.

The package net/http/httptest contains helpers for testing HTTP code. It gives you two styles. For handler unit tests you build a fake request with httptest.NewRequest and a fake response with httptest.NewRecorder, then call the handler directly, with no sockets involved. For client tests, or tests that need the whole stack, httptest.NewServer starts a real server on a free loopback port.

Because nothing needs a fixed port, these tests run in parallel and on any machine.

Go
req := httptest.NewRequest("GET", "/hello?name=Ann", nil)
rec := httptest.NewRecorder()
handler.ServeHTTP(rec, req)
fmt.Println(rec.Code, rec.Body.String())

Try it

Go Recorder: call a handler directly

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go NewServer: test a client against a fake backend

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

Go
func NewRequest(method, target string, body io.Reader) *http.Request
func NewRequestWithContext(ctx context.Context, method, target string, body io.Reader) *http.Request // Go 1.23
func NewRecorder() *ResponseRecorder
func NewServer(handler http.Handler) *Server
func NewTLSServer(handler http.Handler) *Server
func NewUnstartedServer(handler http.Handler) *Server
Name Description
NewRequest Builds an incoming server request. target can be a path (/x?y=1) or a full URL. body may be nil. Sets Host to example.com and RemoteAddr to 192.0.2.1:1234.
ResponseRecorder An http.ResponseWriter that stores the status in Code, the body in Body, and headers you can read via Result().
Server A listening server. URL is its base address, Client() returns a client configured for it (for TLS, one that trusts its certificate), Close() shuts it down and waits for requests to finish.
NewUnstartedServer Creates the server without starting it, so you can change Config, Listener or TLS and then call Start() or StartTLS().

Panics: NewRequest panics on a bad method or URL (it is meant for tests). Use http.NewRequest when you need an error value.

Usage notes

  • Read the result, not the fields. rec.Code is 200 until something calls WriteHeader. rec.Result() returns a real *http.Response whose headers include the sniffed Content-Type, which the raw rec.Header() map may not.
  • Recorders do not run middleware or routing for you. Call mux.ServeHTTP(rec, req) to include path patterns. Path values from patterns work only when the request goes through the mux.
  • Always defer srv.Close(). An open server leaks goroutines and a port; Close blocks until in-flight requests end.
  • NewTLSServer. Use srv.Client() to talk to it. The default client rejects the self-signed certificate.
  • Streaming. A recorder collects everything and has no real connection, so test streaming and timeouts with NewServer.
  • Parallel tests. Each server has its own port, so t.Parallel() is safe.
  • Fixed address. Replace srv.Listener on an unstarted server if you need a particular port.