Building requests
Choose the handler under test, then set the method and URL of the request.
The handler under test
Handler accepts any http.Handler and HandlerFunc accepts a plain handler function. Routers from chi, gin, echo, gorilla and most other frameworks implement http.Handler, so they can be passed in directly. See frameworks.
// any http.Handler: a *http.ServeMux, a gin engine, a chi router...
apitest.New().
Handler(handler).
Get("/health").
Expect(t).
Status(http.StatusOK).
End()
// or a plain handler function
apitest.New().
HandlerFunc(myHandlerFunc).
Get("/health").
Expect(t).
Status(http.StatusOK).
End()apitest.Handler and apitest.HandlerFunc are shorthand for apitest.New().Handler(...):
apitest.Handler(handler).
Get("/health").
Expect(t).
Status(http.StatusOK).
End()apitest calls the handler's ServeHTTP method in the same process as the test, with a httptest.ResponseRecorder as the response writer. No network connection is made, which keeps tests fast and deterministic. To test a running server instead, see end-to-end tests.
Panics fail the test
If the handler panics, apitest recovers, then fails the test with the panic value and a stack trace.
Method and URL
Get, Post, Put, Patch and Delete set the method and URL in one call.
apitest.Handler(handler).Get("/user/1234").Expect(t).Status(http.StatusOK).End()
apitest.Handler(handler).Post("/user/1234").Expect(t).Status(http.StatusOK).End()
apitest.Handler(handler).Put("/user/1234").Expect(t).Status(http.StatusOK).End()
apitest.Handler(handler).Patch("/user/1234").Expect(t).Status(http.StatusOK).End()
apitest.Handler(handler).Delete("/user/1234").Expect(t).Status(http.StatusOK).End()Each has an f variant that formats the URL with fmt.Sprintf:
id := "1234"
apitest.Handler(handler).
Getf("/user/%s", id).
Expect(t).
Status(http.StatusOK).
End()Method covers every other verb. Set the URL with URL or URLf:
apitest.Handler(handler).
Method(http.MethodOptions).
URL("/user/1234").
Expect(t).
Status(http.StatusOK).
End()apitest.Handler(handler).
Method(http.MethodOptions).
URLf("/user/%d", 1234).
Expect(t).
Status(http.StatusOK).
End()The URL is usually just a path, because the request goes straight to the handler. It can include a query string, and Query adds more parameters.
Using an http.Request
To build the request yourself, pass a *http.Request to HttpRequest. The request is used as is, so builder methods such as Header and Query have no effect on it.
req := httptest.NewRequest(http.MethodGet, "/user/1234", nil)
req.Header.Set("X-Request-Id", "abc")
apitest.Handler(handler).
HttpRequest(req).
Expect(t).
Status(http.StatusOK).
End()Host
Requests sent to a handler have the Host set to sut, short for system under test. Use Host when the handler routes or behaves differently by host:
apitest.Handler(handler).
Host("api.example.com").
Get("/hello").
Expect(t).
Status(http.StatusOK).
End()