Skip to content

Extensible, type-safe, fluent assertion Go library. Do NOT use it (sic!).

License

Notifications You must be signed in to change notification settings

fluentassert/verify

Folders and files

NameName
Last commit message
Last commit date

Latest commit

9f8f436 · Feb 13, 2025
Nov 19, 2024
Sep 10, 2024
Nov 25, 2024
May 11, 2021
May 11, 2021
Sep 10, 2024
Oct 1, 2022
Sep 10, 2024
Jun 20, 2023
Nov 13, 2023
May 11, 2021
Feb 13, 2025
Oct 21, 2022
Oct 21, 2022
Oct 22, 2022
Feb 19, 2024
Sep 10, 2024
Oct 4, 2022
Oct 4, 2022
Oct 22, 2022
Oct 22, 2022
Oct 4, 2022
Oct 22, 2022
Oct 22, 2022
Oct 23, 2022
Oct 22, 2022
Sep 10, 2024
Sep 10, 2024
Oct 16, 2023
Oct 16, 2023
Oct 14, 2022
Oct 14, 2022
Oct 22, 2022
Feb 6, 2024
Feb 6, 2024
Feb 24, 2023
Oct 22, 2022
Mar 9, 2023
Oct 4, 2022
Oct 21, 2022
Oct 21, 2022
Mar 9, 2023
Oct 22, 2022
Nov 1, 2022
Oct 21, 2022
Feb 6, 2024
Feb 19, 2024
Feb 6, 2024
Feb 6, 2024

Repository files navigation

fluentassert

Extensible, type-safe, fluent assertion Go library.

Go Reference Keep a Changelog GitHub Release go.mod LICENSE

Build Status Go Report Card Codecov Mentioned in Awesome Go

Please ⭐ Star this repository if you find it valuable and worth maintaining.

Description

The fluent API makes the assertion code easier to read and write (more).

The generics (type parameters) make the usage type-safe.

The library is extensible by design.

Caution

Avoid using assertion libraries. Instead, use go-cmp and write custom test helpers. Using the popular testify may be also an acceptable choice, especially together with testifylint to avoid common mistakes. Use this library if you still want to. Consider yourself warned.

Quick start

package test

import (
	"testing"

	"github.com/fluentassert/verify"
)

func Foo() (string, error) {
	return "wrong", nil
}

func TestFoo(t *testing.T) {
	got, err := Foo()

	verify.NoError(err).Require(t)           // Require(f) uses t.Fatal(f), stops execution if fails
	verify.String(got).Equal("ok").Assert(t) // Assert(f) uses t.Error(f), continues execution if fails
}
$ go test
--- FAIL: TestFoo (0.00s)
    basic_test.go:17:
        the objects are not equal
        got: "wrong"
        want: "ok"

⚠ Do not forget calling Assert(t) or Require(t) which executes the actual assertion.

Supported types

Out-of-the-box the package provides fluent assertions for the following types. The more specific function you use, the more assertions you get.

Go type Assertion entry point
interface{} (any) verify.Any()
comparable verify.Obj()
constraints.Ordered verify.Ordered()
constraints.Number verify.Number()
string verify.String()
error verify.Error()
[]T (slice) verify.Slice()
map[K]V (map) verify.Map()

Below you can find some convenience functions.

Deep equality

For testing deep equality use DeepEqual() or NotDeepEqual().

package test

import (
	"testing"

	"github.com/fluentassert/verify"
)

type A struct {
	Str   string
	Bool  bool
	Slice []int
}

func TestDeepEqual(t *testing.T) {
	got := A{Str: "wrong", Slice: []int{1, 4}}

	verify.Any(got).DeepEqual(
		A{Str: "string", Bool: true, Slice: []int{1, 2}},
	).Assert(t)
}
$ go test
--- FAIL: TestDeepEqual (0.00s)
    deepeq_test.go:20:
        mismatch (-want +got):
          test.A{
        -       Str:  "string",
        +       Str:  "wrong",
        -       Bool: true,
        +       Bool: false,
                Slice: []int{
                        1,
        -               2,
        +               4,
                },
          }

Collection assertions

The library contains many collection assertion. Below is an example of checking unordered equality.

package test

import (
	"testing"

	"github.com/fluentassert/verify"
)

func TestSlice(t *testing.T) {
	got := []int { 3, 1, 2 }

	verify.Slice(got).Equivalent([]int { 2, 3, 4 }).Assert(t)
}
$ go test
--- FAIL: TestSlice (0.00s)
    slice_test.go:12:
        not equivalent
        got: [3 1 2]
        want: [2 3 4]
        extra got: [1]
        extra want: [4]

Periodic polling

For asynchronous testing you can use verify.Eventually() or verify.EventuallyChan().

package test

import (
	"net/http"
	"testing"
	"time"

	"github.com/fluentassert/verify"
)

func TestPeriodic(t *testing.T) {
	verify.Eventually(10*time.Second, time.Second, func() verify.FailureMessage {
		client := http.Client{Timeout: time.Second}
		resp, err := client.Get("http://not-existing:1234")
		if err != nil {
			return verify.NoError(err)
		}
		return verify.Number(resp.StatusCode).Lesser(300)
	}).Assert(t)
}
$ go test
--- FAIL: TestPeriodic (10.00s)
    async_test.go:19:
        function never passed, last failure message:
        Get "http://not-existing:1234": context deadline exceeded (Client.Timeout exceeded while awaiting headers)

Custom predicates

For the most basic scenarios, you can use one of the Check(), Should(), ShouldNot() assertions.

package test

import (
	"strings"
	"testing"

	"github.com/fluentassert/verify"
)

func TestShould(t *testing.T) {
	got := "wrong"

	chars := "abc"
	verify.Any(got).Should(func(got string) bool {
		return strings.ContainsAny(got, chars)
	}).Assertf(t, "does not contain any of: %s", chars)
}
$ go test
--- FAIL: TestShould (0.00s)
    should_test.go:16: does not contain any of: abc
        object does not meet the predicate criteria
        got: "wrong"

Panics

For testing panics use verify.Panics() and verify.NotPanics().

Custom assertion function

You can create a function that returns FailureMessage. Use verify.And() and verify.Or() functions together with Prefix() method to create complex assertions.

package test

import (
	"testing"

	"github.com/fluentassert/verify"
)

type A struct {
	Str string
	Ok  bool
}

func TestCustom(t *testing.T) {
	got := A{Str: "something was wrong"}

	verifyA(got).Assert(t)
}

func verifyA(got A) verify.FailureMessage {
	return verify.And(
		verify.String(got.Str).Contain("ok").Prefix("got.String: "),
		verify.True(got.Ok).Prefix("got.Ok: "),
	)
}
$ go test
--- FAIL: TestCustom (0.00s)
    custom_test.go:17:
        got.String: the value does not contain the substring
        got: "something was wrong"
        substr: "ok"

        got.Ok: the value is false

Extensibility

You can take advantage of the FailureMessage and Fluent* types to create your own fluent assertions for a given type.

For reference, take a look at the implementation of existing fluent assertions in this repository (for example comparable.go).

Supported Go versions

Minimal supported Go version is 1.18.

Contributing

See CONTRIBUTING.md if you want to help.

License

fluentassert is licensed under the terms of the MIT license.

github.com/google/go-cmp (license: BSD-3-Clause) is the only third-party dependency.