httpexpect
A concise, declarative Go library for end-to-end HTTP and REST API testing with chainable request builders and assertions.
What is httpexpect?
httpexpect is a Go testing library for end-to-end HTTP and REST API testing. It provides a fluent, chainable interface for building HTTP requests and making assertions on responses, making API tests more readable and maintainable. The library supports testing via real HTTP clients or by directly invoking HTTP handlers, and includes features like WebSocket testing, JSON Schema validation, and detailed error reporting.
Go developers writing integration or end-to-end tests for HTTP servers, REST APIs, and WebSocket services. It is particularly useful for teams needing expressive, declarative test syntax that integrates with Go's standard testing tools.
Developers choose httpexpect for its comprehensive feature set, including WebSocket support, JSONPath queries, and JSON Schema validation, combined with a fluent API that improves test readability. Its flexibility in testing approaches—via real HTTP or direct handler invocation—and detailed, configurable error output make it stand out from simpler assertion libraries.
Overview
End-to-end HTTP and REST API testing for Go.
Use Cases
Best For
- Writing expressive, chainable end-to-end tests for REST APIs in Go
- Testing WebSocket endpoints alongside HTTP APIs within the same test suite
- Validating API responses against JSON Schema definitions
- Performing complex assertions on JSON payloads using JSONPath queries
- Testing HTTP servers with custom configurations like TLS, proxies, or OAuth2
- Creating reusable test builders and matchers for shared authentication or validation logic
Not Ideal For
- Simple HTTP unit tests where Go's standard httptest package suffices
- Projects with strict dependency minimization policies
- Teams needing integrated visual test reporting or GUI tools
- Performance-critical test suites where lightweight assertion libraries are preferred
Pros & Cons
Pros
Includes support for WebSocket testing, JSON Schema validation, and JSONPath queries, as detailed in the README's features section, going beyond basic HTTP assertions.
Allows testing via real HTTP client or direct handler invocation for frameworks like net/http, fasthttp, Gin, and Echo, demonstrated in multiple examples.
Provides verbose error messages with JSON diffs using gojsondiff and color support via fatih/color, making debugging easier with configurable printers.
Offers a declarative, chainable API that improves test readability, with builders and assertions shown in the quick start examples for intuitive test writing.
Cons
Relies on multiple third-party libraries such as gorilla/websocket, gojsonschema, and go-querystring, which can increase project complexity and potential versioning issues.
Setting up custom clients, formatters, and assertion handlers requires more initial effort, as seen in the extensive configuration examples and tuning sections.
Major version updates may introduce backwards-incompatible changes, requiring test updates, as noted in the versioning section with separate stable branches.
Frequently Asked Questions
Related Projects
TestifyA toolkit with common assertions and mocks that plays nicely with the standard library
KeployOpen-source platform for creating safe, isolated production sandboxes for API, integration, and E2E testing.
GoConveyGo testing in the browser. Integrates with `go test`. Write behavioral tests in Go.
testcontainers-goTestcontainers for Go is a Go package that makes it simple to create and clean up container-based dependencies for automated integration/smoke tests. The clean, easy-to-use API enables developers to programmatically define containers that should be run as part of a test and clean up those resources when the test is done.
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.