ghttp

ghttp: testing HTTP clients

ghttp spins up a real test HTTP server so you can exercise code that makes outbound HTTP requests (clients, SDKs, anything calling net/http). You register handlers that assert on the incoming request and return a canned response; the server records every request it receives. It wraps net/http/httptest.

import (
	. "github.com/onsi/gomega"
	"github.com/onsi/gomega/ghttp"
	"net/http"
)

This skill assumes a dot-import of gomega. Docs: https://onsi.github.io/gomega/#ghttp-testing-http-clients. See gomega:matchers for the matchers used in assertions and gomega:async if the client is non-blocking.

Lifecycle

server := ghttp.NewServer()          // or ghttp.NewTLSServer()
defer server.Close()                 // ALWAYS defer Close

client := myapi.NewClient(server.URL())   // URL is random per run — inject it

The server URL is auto-generated and varies between runs, so you must inject server.URL() into the code under test rather than hard-coding it. With Ginkgo, server = ghttp.NewServer() in BeforeEach and server.Close() in AfterEach.

The handler model

server.AppendHandlers(handlers...) registers an ordered list of handlers, one per expected request. The first request is matched against the first handler, the second against the second, and so on. A handler is just an http.HandlerFunc.

server.AppendHandlers(
	ghttp.VerifyRequest("GET", "/sprockets"),
)

Gotchas (the core mental model):

• AppendHandlers is strictly ordered. Requests must arrive in exactly the registered order.
• Each handler handles exactly one request. To run several checks against a single request, combine them with ghttp.CombineHandlers (below).
• The request count is asserted by default. If the client sends more requests than there are handlers (or hits an unregistered route), the test fails. Guard the trivial false-positive (client made no request) with Expect(server.ReceivedRequests()).To(HaveLen(1)).