gocrest
A Hamcrest-like assertion library for Go providing composable, self-describing matchers for readable tests.
What is gocrest?
GoCrest is a Hamcrest-inspired assertion library for the Go programming language. It enables developers to write expressive, readable, and flexible test assertions using composable matchers that clearly describe expected outcomes, improving test clarity and maintainability compared to traditional assertion methods.
Go developers writing unit and integration tests who want more readable and maintainable test assertions, particularly those familiar with or interested in Hamcrest-style matchers from other languages.
Developers choose GoCrest for its composable matchers that read like natural language, self-describing failure messages that clearly explain test failures, and a generic-based design that provides type safety and catches errors at compile time rather than relying heavily on reflection.
Overview
GoCrest - Hamcrest-like matchers for Go
Use Cases
Best For
- Writing expressive test assertions that read like natural language sentences
- Creating complex test conditions by combining multiple matchers with logical operators like AllOf and AnyOf
- Testing asynchronous operations involving channels, readers, or functions with configurable timeouts
- Validating complex data structures including strings, arrays, maps, and structs with specialized matchers
- Improving test failure diagnostics with clear, human-readable error messages
- Leveraging Go generics for type-safe assertions that catch errors at compile time
Not Ideal For
- Projects minimizing external dependencies or preferring Go's standard testing package without additional libraries
- Teams already deeply integrated with Testify or other assertion frameworks and unwilling to refactor tests
- Codebases heavily using complex structs or custom types that require comparison operators, as GoCrest's `is.LessThan` and `is.GreaterThan` matchers don't support them post-generics
- Developers needing drop-in, simple assertions for quick prototyping without learning matcher composition syntax
Pros & Cons
Pros
Matchers can be combined with logical operators like `AllOf` and `AnyOf` to create complex, readable assertions, as shown in the README example with `is.AllOf(is.StringContaining("abc"), is.LessThan("ghi"))`.
Self-describing error messages provide human-readable explanations of test failures, such as outputting 'Expected: value equal to <bye> but: <hi>', making debugging more efficient.
Uses Go generics to reduce reflection reliance, catching type errors at compile time, as highlighted in the v1.1.0 update where matchers were refactored for generic-based design.
Includes matchers for channels, readers, and functions with configurable timeouts via `Eventually` and `Within` helpers, demonstrated in the asynchronous examples for testing non-blocking operations.
Cons
Matchers like `has.Length` require separate variants for arrays, strings, and maps (e.g., `has.StringLength`, `has.MapLength`), and map matchers need explicit key-value type declarations, adding verbosity.
Post-generics, `is.LessThan` and `is.GreaterThan` no longer work on complex types due to Go's operator limitations, restricting their use for advanced data validation scenarios.
The need to import multiple packages (`by`, `then`, `is`, `has`) and master matcher composition syntax can be overwhelming compared to simpler assertion libraries like Testify's assert package.
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.