https://github.com/go-spring/gs-assert
A minimal, fluent, and highly readable assertion library for Go unit testing.
https://github.com/go-spring/gs-assert
Last synced: 11 months ago
JSON representation
A minimal, fluent, and highly readable assertion library for Go unit testing.
- Host: GitHub
- URL: https://github.com/go-spring/gs-assert
- Owner: go-spring
- License: apache-2.0
- Created: 2025-06-20T23:53:23.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-07-28T06:03:33.000Z (11 months ago)
- Last Synced: 2025-07-28T08:18:14.764Z (11 months ago)
- Language: Go
- Size: 109 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# gs-assert
[English](README.md) | [中文](README_CN.md)
gs-assert is an assertion library for Go unit tests,
designed to enhance test code readability and maintainability.
It provides functional and fluent assertion styles and
supports assertions for multiple data structures,
including generic values, strings, numbers, slices, maps, and `error`.
## Installation Guide
To use the `gs-assert` library, ensure you have Go installed.
Then, install `gs-assert` using the following command:
```bash
go get github.com/go-spring/gs-assert
```
## Features
- **Functional Assertions**：
Offers a rich set of assertion functions such as `Nil`, `NotNil`, `Equal`, `NotEqual`, etc.
- **Fluent Assertions**：
Improves code readability through method chaining, e.g., `assert.That(t).NotNil(obj).Equal(...)`.
- **Data Structure Support**：
Supports assertions for common data structures like generic values, maps, slices, strings, numbers, and `error`.
- **`require` Module**：
Provides stricter assertion methods that immediately terminate the test when an assertion fails.
### Supported Data Structures and Assertion Methods
#### Generic Value Assertions (assert.Assertion)
Created via `assert.That(t, value)`, supports the following methods:
- `True() / False()` - Assert boolean values.
- `Nil() / NotNil()` - Assert whether a value is nil or not.
- `Equal(expect) / NotEqual(expect)` - Assert equality or inequality.
- `Same(expect) / NotSame(expect)` - Assert identity or non-identity.
- `TypeOf(expect)` - Assert type compatibility.
- `Implements(expect)` - Assert interface implementation.
- `Has(expect)` - Assert element inclusion（via Has method）
- `Contains(expect)` - Assert element inclusion（via Contains method）
#### String Assertions (assert.StringAssertion)
Created via `assert.ThatString(t, value)`, supports the following methods:
- `Length(length)` - Assert string length.
- `Blank() / NonBlank()` - Assert whether the string is blank or not.
- `Equal(expect) / NotEqual(expect)` - Assert string equality or inequality.
- `EqualFold(expect)` - Assert case-insensitive equality.
- `JSONEqual(expect)` - Assert JSON structure equality.
- `Matches(pattern)` - Assert regex match.
- `HasPrefix(prefix) / HasSuffix(suffix)` - Assert prefix/suffix.
- `Contains(substr)` - Assert substring inclusion.
- `IsLowerCase() / IsUpperCase()` - Assert case status.
- `IsNumeric() / IsAlpha() / IsAlphaNumeric()` - Assert character type.
- `IsEmail() / IsURL() / IsIPv4() / IsHex() / IsBase64()` - Assert specific formats.
#### Number Assertions (assert.NumberAssertion)
Created via `assert.ThatNumber(t, value)`, supports the following methods:
- `Equal(expect) / NotEqual(expect)` - Assert numeric equality or inequality.
- `GreaterThan(expect) / GreaterOrEqual(expect)` - Assert greater than or equal.
- `LessThan(expect) / LessOrEqual(expect)` - Assert less than or equal.
- `Zero() / NonZero()` - Assert zero or non-zero.
- `Positive() / NotPositive()` - Assert positive or non-positive.
- `Negative() / NotNegative()` - Assert negative or non-negative.
- `Between(lower, upper) / NotBetween(lower, upper)` - Assert within or outside a range.
- `InDelta(expect, delta)` - Assert within a delta range.
- `IsNaN() / IsInf(sign) / IsFinite()` - Assert special numeric states.
#### Slice Assertions (assert.SliceAssertion)
Created via `assert.ThatSlice(t, value)`, supports the following methods:
- `Length(length)` - Assert slice length.
- `Nil() / NotNil()` - Assert whether the slice is nil or not.
- `Equal(expect) / NotEqual(expect)` - Assert slice equality or inequality.
- `Contains(element) / NotContains(element)` - Assert element inclusion/exclusion.
- `ContainsSlice(sub) / NotContainsSlice(sub)` - Assert sub-slice inclusion/exclusion.
- `HasPrefix(prefix) / HasSuffix(suffix)` - Assert prefix/suffix.
- `AllUnique()` - Assert all elements are unique.
- `AllMatches(fn) / AnyMatches(fn) / NoneMatches(fn)` - Assert element conditions.
#### Map Assertions (assert.MapAssertion)
Created via `assert.ThatMap(t, value)`, supports the following methods:
- `Length(length)` - Assert map length.
- `Nil() / NotNil()` - Assert whether the map is nil or not.
- `Equal(expect) / NotEqual(expect)` - Assert map equality or inequality.
- `ContainsKey(key) / NotContainsKey(key)` - Assert key inclusion/exclusion.
- `ContainsValue(value) / NotContainsValue(value)` - Assert value inclusion/exclusion.
- `ContainsKeyValue(key, value)` - Assert key-value pair inclusion.
- `ContainsKeys(keys) / NotContainsKeys(keys)` - Assert multiple key inclusions/exclusions.
- `ContainsValues(values) / NotContainsValues(values)` - Assert multiple value inclusions/exclusions.
- `SubsetOf(expect) / SupersetOf(expect)` - Assert subset/superset.
- `HasSameKeys(expect) / HasSameValues(expect)` - Assert same keys/values.
#### Error Assertions (assert.ErrorAssertion)
Created via `assert.ThatError(t, value)`, supports the following methods:
- `Nil() / NotNil()` - Assert error is nil or not.
- `Is(target) / NotIs(target)` - Assert error matches or does not match a target.
- `Matches(expr)` - Assert error message matches regex.
#### Panic Assertions
Use `assert.Panic(t, fn, expr)` to assert a function panics and
the panic message matches an expression.
## Usage Examples
```go
import "github.com/go-spring/gs-assert/assert"
import "github.com/go-spring/gs-assert/require"
func TestAssertExample(t *testing.T) {
// Use assert module for assertions, test continues on failure
assert.That(t, t).NotNil().NotSame(nil)
assert.That(t, 1+1).Equal(2).NotEqual(3)
}
func TestRequireExample(t *testing.T) {
// Use require module for assertions, test stops on failure
require.That(t, t).NotNil().NotSame(nil)
require.That(t, 1+1).Equal(2).NotEqual(3)
}
func TestPanicExample(t *testing.T) {
// Assert function panics and message matches the expression
require.Panic(t, func () {
panic("something went wrong")
}, "something went wrong")
}
```
## Contribution Guide
We welcome any form of contribution!
If you have suggestions or find bugs, please submit an issue or pull request.
Before submitting contributions, ensure your code adheres to
the project's coding standards and passes all tests.
## License
The Go-Spring is released under version 2.0 of the Apache License.