actually

KO | EN

gitlite — search

#typescript #llm #android #rust #docker #macos #java #windows #awesome #awesome-list #vue #security #mcp #open-source

(★ 10)

A testing library focused on turning failure into success

actually Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Actually

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

* It is clear what is being tested by the builder interface
* Consistent method names to reduce things you have to memorize
* Explicit test failure results help you save time
* There are helper methods to see details of a failure

## Usage

Simple case

```go
package main

import (
	"testing"

a "github.com/bayashi/actually"
)

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
}
```

Compare objects

```go
package main

import (
	"testing"

a "github.com/bayashi/actually"
)

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)
}
```

Compare protocol buffers

```go
package main

import (
	"testing"

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

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
}
```

Guard block for fail-now

There is also a way to write fail-now as a guard block. A test usually has three steps:

1. prepare
1. run the action
1. confirm the result

By wrapping the preparation in a `FailNow` block, every assertion inside it becomes fail-now, so the test stops immediately if the setup goes wrong, and it reads clearly as "this is the preparation".

```go
package main

import (
	"testing"

a "github.com/bayashi/actually"
)

func TestGreet(t *testing.T) {
	var user *User

// prepare
	a.FailNow(func() {
		u, err := fetchUser(1)

// every assertion here fails now,
        // so the test stops as soon as one fails
		a.Got(err).NoError(t)
		a.Got(u).NotNil(t)

user = u
	})

// run the action
	greeting, err := user.Greet()

// confirm the result
	a.Got(err).NoError(t)
	a.Got(greeting).Expect("Hello, Gopher").Same(t)
}
```

Every `actually` assertion executed inside the func passed to `FailNow` behaves as fail-now (stops on the first failure), so you don't need a separate package like require/assert. It shares the wording with Go's own `t.FailNow`, and it is goroutine safe.

Wrapping the preparation in the guard block also keeps its temporary variables scoped to the block. In the example above, `u` and `err` stay inside the guard, while `user` is the only variable exposed to the rest of the test, which is exactly what the following steps need.

You can also mark fail-now per assertion, without the guard block:

```go
a.Got(v).FailNow().True(t)
```

## Assertion Methods

### [For 1 object](https://github.com/bayashi/actually/wiki/All-assertion-methods#assertion-for-1-object)

* True, False, Nil, NotNil, NoError

### [For 2 objects](https://github.com/bayashi/actually/wiki/All-assertion-methods#assertion-for-2-objects)

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

### [For panic](https://github.com/bayashi/actually/wiki/All-assertion-methods#assertion-for-panic)

* Panic, NoPanic, PanicMessage

### [For string value by regexp](https://github.com/bayashi/actually/wiki/All-assertion-methods#assertion-for-string-value-by-regexp)

* Match, NotMatch

### [For length of an object](https://github.com/bayashi/actually/wiki/All-assertion-methods#assertion-for-length-of-an-object)

* Len

## Helper Methods

* **FailNow**: Halt the test case immediately when the test fails
* **Diff**: Get diff of 2 objects on anywhere
* **Dump**: Get dumped string of objects on anywhere
* **Debug**: Show debug info only on failure

[See more helper functions](https://github.com/bayashi/actually/wiki/Helper-functions).

[Here is a Wiki of full API documentation](https://github.com/bayashi/actually/wiki).

-----

## Fail reports

`actually` will help you with evident fail report:

```go
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:

## 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
        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

actually

actually Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

actually

actually Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README