actually

README

Actually

A testing library focused on turning failure into success, actually.

• Builder interface to make test code obvious
• Consistent method name to reduce things you have to remember
• Specific fail report to save your time
• There are helpers to see details of a failure

Usage

package main

import (
	"testing"

	a "github.com/bayashi/actually"
	pb "github.com/bayashi/actually/testpb"
)

func TestObject(t *testing.T) {
	love, err := getLove()

	a.Got(err).NoError(t)
	a.Got(love).True(t)
}

func getLove() (bool, error) {
	return true, nil
}

func TestObjects(t *testing.T) {
	x := map[string]int{
		"foo": 123,
	}
	y := map[string]int{
		"foo": 123,
	}

	// `Same` method verifies that two objects are same in value and type.
	// Function type value is not acceptable. And not verify pointer address.
	// It will be fail, int(1) and uint(1), because of type.
	a.Got(x).Expect(y).Same(t)

	// Cmp method gets the differences between two objects by go-cmp.Diff.
	a.Got(x).Expect(y).Cmp(t)
}

func TestProtoMessages(t *testing.T) {
	x := &pb.Foo{Id: 123}
	y := &pb.Foo{Id: 123}

	// CmpProto method gets the differences between two Protobuf messages
	// by go-cmp.Diff with protocmp.Transform option.
	a.Got(x).Expect(y).CmpProto(t)

	a.Got(x).Expect(y).SamePointer(t) // This test will be failed
}

Assertion Methods

For 1 object

• True, False, Nil, NotNil, NoError

For 2 objects

• Same, SamePointer, SameType, SameConvertibleNumber
• NotSame, NotSamePointer, NotSameType, NotSameConvertibleNumber
• Cmp, CmpProto, CmpAllowUnexported, CmpIgnoreUnexported, (CmpOpt)

For panic

• Panic, NoPanic, PanicMessage

For string value by regexp

• Match, NotMatch

For length of an object

• Len

Here is a Wiki of full API documentation.

---

Fail reports

actually will help you with evident fail report:

package foo

import (
	"testing"

	a "github.com/bayashi/actually"
)

func Test(t *testing.T) {
	x := "foo\nbar\nbaz"
	y := "foo\nbar\nbug"

	a.Got(x).Expect(y).Same(t)
}

Above code will put fail report like below:

=== RUN   Test
    foo_test.go:13: Test
        Fail reason:    Not same value
        Type:           Expect:string, Got:string
        Expected:       "foo\nbar\nbug"
        Actually got:   "foo\nbar\nbaz"
        Diff details:   --- Expected
                        +++ Actually got
                        @@ -2,2 +2,2 @@
                         bar
                        -bug
                        +baz
        Trace:          /path/to/foo/foo_test.go:13
--- FAIL: Test (0.00s)

Helper Methods

There are helper functions: Name, Skip, Fi, X, Diff, Dump, etc...

Debug

actually has the Debug("label", any_variable) method to show additional data only in fail report.

Like below, src variable will be dumped nicely only on fail.

res := someFunc(src)
actually.Got(res).Debug("src", src).True(t)

See more helper functions.

ACTUALLY_TRACE_SOURCE

If you set true value (i.e. "1", "true" or "TRUE" etc) into ENV:ACTUALLY_TRACE_SOURCE on running a test, then you can see a piece of source code for each stack trace in fail report.

=== RUN   Test
    foo_test.go:13: Test
        Fail reason:    Not same value
        Type:           Expect:string, Got:string
        Expected:       "foo\nbar\nbug"
        Actually got:   "foo\nbar\nbaz"
        Diff details:   --- Expected
                        +++ Actually got
                        @@ -2,2 +2,2 @@
                         bar
                        -bug
                        +baz
        Trace:          /path/to/foo/foo_test.go:13
                         10     x := "foo\nbar\nbaz"
                         11     y := "foo\nbar\nbug"
                         12
                         13>    a.Got(x).Expect(y).Same(t)
                         14  }
--- FAIL: Test (0.00s)

---

Installation

go get github.com/bayashi/actually

License

MIT License

Author

Dai Okabayashi: https://github.com/bayashi

Special Thanks

Inspired by:

• https://github.com/stretchr/testify
• https://github.com/matryer/is
• https://github.com/fluentassert/verify
• https://metacpan.org/pod/Test::Arrow

Documentation

Overview

Yet another pithy testing framework `actually`

Index

• func Actual(g any) *testingA
• func Diff(a any, b any) string
• func Dump(a any) string
• func Expect(e any) *testingA
• func Expectf(format string, e ...any) *testingA
• func Fail(t *testing.T, reason string, got any, expect ...any)
• func FailNotNowOn(t *testing.T)
• func FailNow(t *testing.T, reason string, got any, expect ...any)
• func FailNowOn(t *testing.T)
• func Fatal(t *testing.T, reason string, got any, expect ...any)
• func FatalOn(t *testing.T)
• func Got(g any) *testingA
• func GotError(g error) *testingA
• func Skip(t *testing.T, skipReasons ...any)
• func Want(e any) *testingA

Functions

func Actual

func Actual(g any) *testingA

Actual is an alias of Got.

func Diff

func Diff(a any, b any) string

Diff is a helper function to get a diff string of 2 objects for debugging

func Dump

func Dump(a any) string

Dump is a helper function to get a dumped string of an object for debugging

func Expect

func Expect(e any) *testingA

Expect sets the value you expect to be the same as the one you got. Expect creates *testingA and returns it.

func Expectf

func Expectf(format string, e ...any) *testingA

Expectf sets the formatted string value you expect to be the same as the one you got. Expectf creates *testingA and returns it.

func Fail

func Fail(t *testing.T, reason string, got any, expect ...any)

Fail is to show decorated fail report. (Actual shortcut to witness.Fail)

if g != e {
	actually.Fail(t, "Not same", g, e)
}

func FailNotNowOn

func FailNotNowOn(t *testing.T)

FailNotNowOn function turns an ENV flag off to stop further test execution immediately if one test fails. If you want to turn the ENV flag on, then you should call `FailNowOn`.

func Test(t *testing.T) {
	// turn on to fail right now
	actually.FailNowOn(t)
	actually.Got(something).Nil(t)                    // Fail Now
	actually.Got(something).Expect(something).Same(t) // Fail Now

	// turn off
	actually.FailNotNowOn(t)
	actually.Got(something).Nil(t)                    // NOT Fail Now
	actually.Got(something).Expect(something).Same(t) // NOT Fail Now

	// Fail Now by FailNow() in the chain
	actually.Got(something).FailNow().Nil(t)          // Fail Now

	// Again, turn on to fail right now
	actually.FailNowOn(t)
	actually.Got(something).Nil(t)                    // Fail Now
}

This switch is enabled within the test. Not only during function.

func FailNow

func FailNow(t *testing.T, reason string, got any, expect ...any)

FailNow is to show decorated fail report by t.Fatal. (Actual shortcut to witness.FailNow)

if g != e {
	actually.FailNow(t, "Not same", g, e)
}

func FailNowOn

func FailNowOn(t *testing.T)

FailNowOn function turns an ENV flag on to stop further test execution immediately if one test fails. This switch is enabled within the test. Not only during function.

func Test(t *testing.T) {
	actually.FailNowOn(t)
	actually.Got(something).Nil(t)                    // Fail Now
	actually.Got(something).Expect(something).Same(t) // Fail Now
}

Warning: Do not use FailNowOn along with t.Parallel.

func Fatal

func Fatal(t *testing.T, reason string, got any, expect ...any)

Fatal is an alias of FailNow

func FatalOn

func FatalOn(t *testing.T)

FatalOn is an alias of FailNowOn.

func Got

func Got(g any) *testingA

Got sets the value you actually got. Got() creates *testingA and returns it.

func GotError

func GotError(g error) *testingA

GotError sets the error value you actually got. GotError creates `*testingA` and returns it.

func Skip

func Skip(t *testing.T, skipReasons ...any)

Skip provides shorthand to skip further tests within the same function for `-short` option.

func Test(t *testing.T) {
	Got(1).NotNil(t) // Run
	Skip(t)
	Got(2).NotNil(t) // Skip
	Got(3).NotNil(t) // Skip Also
}

func Want

func Want(e any) *testingA

Want is an alias of Expect.