handlertest

Documentation

Overview

Package handlertest reports test-fixture assertion failures raised by code that does not run on the goroutine running the test: httptest handlers, RoundTrippers, injected dependency stubs, and worker goroutines.

t.Fatal, t.Fatalf, and t.FailNow may only be called from the goroutine running the test. Calling them from an httptest handler skips the response write and leaves the client under test waiting for a reply that never arrives. Calling them from a worker goroutine terminates that goroutine before it can send its result, so the test deadlocks on the channel or wait group instead of failing, and the package eventually panics on the test timeout with the original failure buried in the dump.

An Asserter records the failure with Errorf, which is safe from any goroutine, and returns a value the fixture can hand back to its caller, so the code under test observes a deterministic failure and unwinds normally.

Index

• type Asserter
  • func New(tb testing.TB) *Asserter
  • func (a *Asserter) Errorf(format string, args ...any) error
  • func (a *Asserter) Respond(w http.ResponseWriter, format string, args ...any)
  • func (a *Asserter) Response(format string, args ...any) *http.Response

Types

type Asserter

type Asserter struct {
	// contains filtered or unexported fields
}

Asserter reports fixture failures from off-test-goroutine code.

func New

func New(tb testing.TB) *Asserter

New returns an Asserter that reports failures to tb.

func (*Asserter) Errorf

func (a *Asserter) Errorf(format string, args ...any) error

Errorf records a failure and returns an error carrying the same message.

Use it wherever the fixture can hand an error back to the code under test: a RoundTripper, an injected dependency stub, or a worker goroutine that reports through a channel. The message is rendered with fmt.Errorf, so %w keeps wrapping the operand and still prints readably in the test log.

return nil, fixture.Errorf("unexpected request: %s %s", req.Method, req.URL)

func (*Asserter) Respond

func (a *Asserter) Respond(w http.ResponseWriter, format string, args ...any)

Respond records a failure and writes an HTTP 500 JSON error body to w.

Use it from httptest handlers, which cannot return an error. The client under test receives a complete response instead of blocking until its own timeout, and the recorded failure fails the test.

default:
    fixture.Respond(w, "unexpected request: %s %s", req.Method, req.URL.Path)
    return

func (*Asserter) Response

func (a *Asserter) Response(format string, args ...any) *http.Response

Response records a failure and returns a synthetic HTTP 500 JSON response.

Use it from fixture helpers that must return an *http.Response and have no way to signal an error, such as a response builder called from inside a RoundTripper.

body, err := json.Marshal(payload)
if err != nil {
    return fixture.Response("marshal territory response: %v", err)
}