HTTP mocking

Active contributors: Mislav, Sam Coe

Purpose

pkg/httpmock is the test-side counterpart to the api package. It implements an http.RoundTripper whose behaviour is configured by registered (matcher, responder) pairs. Every command that talks to the GitHub API uses it.

Directory layout

pkg/httpmock/
  registry.go              # Registry, Verify
  stub.go                  # REST, GraphQL, JSONResponse, FileResponse, ...
  legacy.go                # Older helpers retained for compat

Key abstractions

Symbol	File	Role
Registry	registry.go	An http.RoundTripper that matches requests against registered stubs.
Registry.Register(matcher, responder)	registry.go	Adds an expected interaction.
Registry.Verify(t)	registry.go	Asserts every registered stub was called.
REST(method, path)	stub.go	Matcher for path + method.
GraphQL(pattern)	stub.go	Matcher for a GraphQL query regex.
JSONResponse(body)	stub.go	Returns a 200 JSON response.
StringResponse(body)	stub.go	Plain string responder.
StatusStringResponse(status, body)	stub.go	Status + body responder.
FileResponse(path)	stub.go	Reads a fixture file.
WithHeader(key, value)	stub.go	Wraps a responder to inject extra headers.

How it works

reg := &httpmock.Registry{}
defer reg.Verify(t)

reg.Register(
    httpmock.REST("GET", "repos/OWNER/REPO/issues"),
    httpmock.JSONResponse(struct {
        Items []api.Issue `json:"items"`
    }{ Items: someIssues }),
)

client := &http.Client{Transport: reg}
opts.HttpClient = func() (*http.Client, error) { return client, nil }

The matcher is a simple func(*http.Request) bool; matchers built by REST and GraphQL are the dominant ones, but ad-hoc matchers are accepted. The responder is func(*http.Request) (*http.Response, error). JSONResponse and friends provide canned ones.

Verify(t) checks that every registered (matcher, responder) was hit at least once. This catches refactors that orphan a stub silently.

Integration points

• Used by every _test.go file under pkg/cmd/* that exercises business logic. Lookups into the registry are the primary signal that a command's HTTP traffic matches expectations.
• Compatible with httpretty debug logging; the registry is wired in front of any other transport, so GH_DEBUG=api does not affect tests.
• The httpmock API is intentionally tiny so the cost of writing a new test is low.

Entry points for modification

• New matcher: add a constructor to stub.go. Examples: a query-string matcher, a body-shape matcher, a pagination cursor matcher.
• New responder: same. Existing tests will not break because the existing responders are unchanged.
• Strict-ordering mode: not currently supported. Tests that need ordering wrap matchers with their own counter.

Key source files

File	Purpose
pkg/httpmock/registry.go	Registry + Verify.
pkg/httpmock/stub.go	Matchers and responders.

Related pages

• API client.
• Testing.