httpexpect

httpexpect is a declarative, chainable testing library for Go (golang) designed for end-to-end HTTP and REST API testing. It provides builders to construct HTTP requests and assertions to validate HTTP responses and their payloads.

Key capabilities include:

• Request Building: Construct URLs with interpolation, manage query parameters, headers, cookies, and various payload types (JSON, urlencoded, multipart, plain text).
• Response Assertions: Validate status codes, headers, cookies, and payloads (JSON, JSONP, forms, text).
• Payload Inspection: Recursive inspection of payloads with support for type-specific assertions (object, array, string, number, boolean, null, datetime, duration, cookie), regex, JSONPath queries, and JSON Schema validation.
• WebSocket Support: Upgrade HTTP connections to WebSockets and interact with WebSocket servers.
• Flexible Execution: Tests can communicate via a real HTTP client or by invoking net/http or fasthttp handlers directly.

The httpexpect workflow follows a hierarchical object tree where each object is linked via a chain struct. The typical user workflow is:

1. Create an Expect instance (root object) using httpexpect.Default or httpexpect.WithConfig.
2. Use Expect methods to create a Request instance (HTTP request builder).
3. Use Request methods to configure the request (e.g., WithHeader, WithText).
4. Use Request.Expect() to send the request and receive a Response instance (HTTP response matcher).
5. Use Response methods to make assertions on the response.
6. Use Response methods to create child matcher objects for the payload (e.g., Response.Headers() or Response.Body()).
7. Use methods of matcher objects to make assertions or create nested child matchers.

Note on Failure Propagation: If an assertion fails, the chain marks that branch as failed. Subsequent assertions on that failed branch (e.g., calling .Body() after a failed .Status() check) are automatically ignored to prevent cascading errors.

e.GET("/test").Expect().Status(http.StatusOK).Body().IsObject()

Use .JSON() to access the response body as a JSON object. You can then validate structure using methods like .Object(), .Array(), .ContainsKey(), and .HasValue(). For complex structures, you can use .Path(jsonPath) to run JSONPath queries and iterate over results. You can also decode the JSON directly into a Go struct using .Decode(&target).

// Validate JSON structure
obj := e.GET("/fruits/apple").
	Expect().
	Status(http.StatusOK).JSON().Object()

obj.Keys().ContainsOnly("colors", "weight")
obj.Value("colors").Array().ConsistsOf("green", "red")

// Validate using JSONPath
repos := e.GET("/repos/octocat").
	Expect().
	Status(http.StatusOK).JSON()

for _, private := range repos.Path("$..private").Array().Iter() {
	private.Boolean().IsFalse()
}

// Decode into a struct
type User struct {
	Name   string `json:"name"`
	Age    int    `json:"age"`
	Gender string `json:"gender"`
}

var user User
e.GET("/user").
	Expect().
	Status(http.StatusOK).
	JSON().
	Decode(&user)

Use httpexpect.WithConfig(httpexpect.Config{...}) to customize the behavior of the client. Key configuration options include:

• BaseURL: Prepend this URL to all requests.
• Client: Provide a custom *http.Client (useful for setting timeouts, cookie jars, or TLS config).
• Reporter: Choose how failures are reported (e.g., NewAssertReporter, NewRequireReporter, NewFatalReporter).
• Printers: A slice of httpexpect.Printer to output request/response details (e.g., NewDebugPrinter, NewCurlPrinter, NewCompactPrinter).
• Context: Provide a global context for cancellation/timeouts.

e := httpexpect.WithConfig(httpexpect.Config{
	BaseURL: "http://example.com",
	Client: &http.Client{
		Jar:     httpexpect.NewCookieJar(),
		Timeout: time.Second * 30,
	},
	Reporter: httpexpect.NewRequireReporter(t),
	Printers: []httpexpect.Printer{
		httpexpect.NewDebugPrinter(t, true),
	},
})