Professional lightweight testing mini-framework for Go.


is GoDoc Go Report Card Build Status

Professional lightweight testing mini-framework for Go.

  • Easy to write and read
  • Beautifully simple API with everything you need: is.Equal, is.True, is.NoErr, and is.Fail
  • Use comments to add descriptions (which show up when tests fail)

Failures are very easy to read:

Examples of failures


The following code shows a range of useful ways you can use the helper methods:

func Test(t *testing.T) {

	is := is.New(t)
	signedin, err := isSignedIn(ctx)
	is.NoErr(err)            // isSignedIn error
	is.Equal(signedin, true) // must be signed in
	body := readBody(r)
	is.True(strings.Contains(body, "Hi there"))


To turn off the colors, run go test with the -nocolor flag, or with the env var IS_NO_COLOR=true.

go test -nocolor
IS_NO_COLOR=true go test
  • Additional error assertations

    Additional error assertations

    Hi, let me first say that the library is great, thank you for creating it!

    I find myself repeating few checks for errors that could be made into assertation. It would be my pleasure to contribute this upgrades if we agree on their form.

    1. is.NoErr(err) is great but in lots of situations I need to check the opposite, that error is present. Using is.True(err != nil) works but does not have the same approach to assertation. I suggest adding is.Err(err) that would assert err is not nil.

    2. Usually, I add context to errors but I do not use custom error types as there is no behavior associated with this errors. When I have this situation, I would like to check that error contains a particular substring. I suggest adding is.ErrContains(err, "part of error message") that would assert if error contains given substring.

    What do you think about this two additions?

    opened by matejb 8
  • flag.Parse in init() prevents own flags in tests

    flag.Parse in init() prevents own flags in tests

    With the commit the parsing of the flags has changed to the use of flag.Parse(). Because flag.Parse() is called in init(), it prevents the source package (the one, that uses from defining and using it's own flags, because the calls to e.g. flag.Bool(...) will be after the execution of flag.Parse() and therefore these flags are not considered and the execution of go test fails with flag provided but not defined: ....

    This leaves us with two options:

    1. Revert the above mentioned commit
    2. Under the assumption, that this package is mainly (only) used for testing with go test, then it would also be save to remove the call to flag.Parse() in init(), because go test will execute flag.Parse()
    opened by breml 7
  • Change comment color to red

    Change comment color to red

    This changes the comment color to from green to red. Green implies success, whereas red stands out.

    There's no related issue (I can create one, if needed).


    opened by WTFox 5
  • My editor thinks this is bad practice

    My editor thinks this is bad practice

    Hi Mat!

    Big fan (of Go of course 😏), long time listener of GoTime and working with Go full time for 4 years next month!

    So... I just tried this nice little assert library and the first thing I notice is that my editor thinks I shouldn't do this:

    is := is.New(t)

    It says: Variable 'is' collides with imported package name (And I hate to disappoint my editor!)

    What is your defence? (Trying to be funny 😂)

    opened by tehsphinx 4
  • Add Helper method

    Add Helper method

    Helper marks the calling function as a test helper function. When printing file and line information, that function will be skipped.

    Adopted from testings.Helper from the stdlib.

    Related: #30

    opened by breml 4
  • -nocolor flag not supported by Go Test in go-1.11.4

    -nocolor flag not supported by Go Test in go-1.11.4

    go test without -nocolor works:

    [email protected]:~/go/src/ (master)
    $ go test ./model/
    	permissions_test.go:11: model.Permission(2) != int(1)
    --- FAIL: TestPermissionBits (0.00s)
    FAIL	0.009s

    But go test with -nocolor gives an error:

    [email protected]:~/go/src/ (master)
    $ go test ./model/ -nocolor
    flag provided but not defined: -nocolor
    opened by sbward 4
  • Consider using a more open license

    Consider using a more open license

    Is there a specific reason why this project uses the restrictive GPL 3 license? I for one would be able to use it in a much more relaxed way if it used a more open license like MIT.

    @matryer, would you consider switching?

    opened by cloudlena 4
  • Refactor New methods to use T interface

    Refactor New methods to use T interface


    There is no need to depend on testing package in the "production" code.


    • New and NewRelaxed methods accept t T instead of t *t.testing.
    opened by pellared 3
  • Use instead of

    Use instead of

    Traffic from redirects to the corresponding page on

    P.S. Thank you for talking about this package on the Go Time podcast. Always enjoy hearing from you.


    opened by justinpage 3
  • Add a Contains method

    Add a Contains method

    Hi! Watched the talk you gave on The Art of Testing and really liked it. That's why I'm trying out this package, and I really like its simplicity.

    One thing though that I'm missing is a Contains method (basically this).

    As there is none so far, I guess there is some other way to do it? For example, I have a function that returns [][]string, and I wanna check if some []string are in that slice, but do not wanna specify the order.


    opened by tommyknows 3
  • Create release with MIT license

    Create release with MIT license

    The current v1.0.0 release still contains the old GPL license. Could we create a new release with the new MIT license or move the existing release tag to include it?

    opened by cloudlena 2
  • Use ANSI dim instead of hardcoding colour

    Use ANSI dim instead of hardcoding colour

    Instead of hardcoding the colour for file and types, use the dim escape code to let the terminal decide the colour. Specifically this makes it more readable if your terminal happens to be slightly gray.

    Also includes some gofmt edits of package comment.

    opened by kse 0
  • Proposal: value matcher interface in is.Equal

    Proposal: value matcher interface in is.Equal

    I sometimes have cases, where I would like to alter or extend the way is.Equal is deciding, if the values are considered equal. After trying several approaches, I came up with the following solution, which does not extend the current API surface, but adds a maximum of flexibility and freedom to the user in regards to how is.Equal decides if two inputs are equal.

    The proposal is to value a newly defined matcher interface, which is defined as follows (the matcher interface does not need to become part of the public API of, in fact it can just be defined inline where needed):

    type matcher interface{
    	Match(interface{}) bool

    The actual change, that I am proposing is, to extend the existing areEqual function like this (lines 9-11):

    // areEqual gets whether a equals b or not.
    func areEqual(a, b interface{}) bool {
    	if isNil(a) && isNil(b) {
    		return true
    	if isNil(a) || isNil(b) {
    		return false
    	if matcher, ok := a.(interface{ Match(interface{}) bool }); ok {
    		return matcher.Match(b)
    	if reflect.DeepEqual(a, b) {
    		return true
    	aValue := reflect.ValueOf(a)
    	bValue := reflect.ValueOf(b)
    	return aValue == bValue

    In theory, this change does alter the working of is.Equal. In practice, I assume the chances of this change having negative side effects for users of this package to be extremely low. Only users, that use this package to compare types, that implement this exact interface would be affected. I rate the profit of this change to be way higher than the risk of negative side effects. If you think, that the current signature (Match(interface{}) bool) is too likely to cause problems, the name of the method can easily be altered such that the chance of a collision become negligible (e.g. MatRyerIsMatch(interface{}) bool 😜).

    If I find acceptance for this proposal, I am happy to provide the necessary PR to update the code, the tests and the documentation.

    As a side note, the areEqual function could be minimally simplified by replacing:

    	if isNil(a) && isNil(b) {
    		return true
    	if isNil(a) || isNil(b) {
    		return false


    	if isNil(a) || isNil(b) {
    		return isNil(a) && isNil(b)
    opened by breml 0
  • Potential issue when running go test -json

    Potential issue when running go test -json

    Hey Mat, long time. Ran into a curious issue worth filing.


    Running go test -json ... and using this package reports incorrect test names in JSON events. This could very well be a bug in Go (test2json), but figured I'd start here because if I remove is and use regular std. lib primitives it reports the correct thing.

    Reproducible example

    I noticed this happening in and put together a PR to showcase the problem.

    In this commit I purposefully changed a test to trigger a failure. Note the name of the test is TestNotAllowMissing.

    When I run go test -v -json -count=1 ./tests/e2e -dialect=postgres I happily get JSON output. But, the test name in the JSON event doesn't line up with the Output.

    I was expecting Output that is prints to be associated with test named TestNotAllowMissing, but instead it was associated with another test named TestMigrateFull. (the name is non-deterministic, it changes between runs).

    The raw output can be found here. But I've copied and trimmed the relevant bits:

    {"Test":"TestMigrateFull","Output":"\t\u001b[90mallow_missing_test.go:30: \u001b[39m7 != 8\n"}
    {"Test":"TestNotAllowMissing","Output":"--- FAIL: TestNotAllowMissing (3.73s)\n"}

    The first JSON event refers to allow_missing_test.go:30, in the code base the call site on line 30 is located within the test named: TestNotAllowMissing, but the test name is TestMigrateFull.

    The second JSON event correctly outputs the failure under the test named TestNotAllowMissing.

    This could very well be a bug in how go test prints JSON events, but I suspect it may be something within this library. I say this because if I remove is from that specific test (TestNotAllowMissing) I see the expected output associated with the correct Test name:

    Raw output can be found here

    {"Test":"TestNotAllowMissing","Output":"    allow_missing_test.go:35: got 7: want: 8\n"}
    {"Test":"TestNotAllowMissing","Output":"--- FAIL: TestNotAllowMissing (2.81s)\n"}
    opened by mfridman 0
  • Small simplification

    Small simplification

    The following code

    	if isNil(a) || isNil(b) {
    		is.logf("%s != %s", is.valWithType(a), is.valWithType(b))
    	} else if reflect.ValueOf(a).Type() == reflect.ValueOf(b).Type() {
    		is.logf("%v != %v", a, b)
    	} else {
    		is.logf("%s != %s", is.valWithType(a), is.valWithType(b))

    can be simplified to

            if isNil(a) || isNil(b) || reflect.ValueOf(a).Type() != reflect.ValueOf(b).Type() {
    		is.logf("%s != %s", is.valWithType(a), is.valWithType(b))
    	} else {
    		is.logf("%v != %v", a, b)
    opened by kpym 0
  • Add a boolean return value to test functions

    Add a boolean return value to test functions

    I find it useful to be able to control the flow of execution in my tests depending on the outcome of previous tests. This PR adds a bool return value from test test functions.

    opened by jli-cparta 9
Mat Ryer and - Gopher, developer, speaker, author (Go Programming Blueprints) - Xbar (BitBar reboot) (now in beta)
Mat Ryer
A yaml data-driven testing format together with golang testing library

Specimen Yaml-based data-driven testing Specimen is a yaml data format for data-driven testing. This enforces separation between feature being tested

Design it, Run it 1 Nov 24, 2022
Golang HTTP client testing framework

flute Golang HTTP client testing framework Presentation Overview flute is the

Shunsuke Suzuki 17 Sep 27, 2022
API testing framework inspired by frisby-js

frisby REST API testing framework inspired by frisby-js, written in Go Proposals I'm starting to work on frisby again with the following ideas: Read s

_Hofstadter 274 Sep 27, 2022
Minimal and Beautiful Go testing framework

Goblin A Mocha like BDD testing framework written in Go that requires no additional dependencies. Requires no extensive documentation nor complicated

null 868 Nov 23, 2022
Testing framework for Go. Allows writing self-documenting tests/specifications, and executes them concurrently and safely isolated. [UNMAINTAINED]

GoSpec GoSpec is a BDD-style testing framework for the Go programming language. It allows writing self-documenting tests/specs, and executes them in p

Esko Luontola 114 Sep 27, 2022
🚀🌏 Orbital is a simple end-to-end testing framework for Go

Orbital is a test framework which enables a developer to write end to end tests just like one would writing unit tests. We do this by effectively copying the testing.T API and registering tests to be run periodically on a configured schedule.

Segment 79 Nov 18, 2022
An always-on framework that performs end-to-end functional network testing for reachability, latency, and packet loss

Arachne Arachne is a packet loss detection system and an underperforming path detection system. It provides fast and easy active end-to-end functional

Uber Open Source 369 Nov 27, 2022
BDD Testing Framework for Go

Jump to the docs | 中文文档 to learn more. To start rolling your Ginkgo tests now keep reading! If you have a question, comment, bug report, feature reque

Onsi Fakhouri 6.6k Dec 2, 2022
Framework of performance testing

Framework of performance testing fperf is a powerful and flexible framework which allows you to develop your own benchmark tools so much easy. You cre

null 337 Nov 8, 2022
Full-featured test framework for Go! Assertions, mocking, input testing, output capturing, and much more! 🍕

testza ?? Testza is like pizza for Go - you could life without it, but why should you? Get The Module | Documentation | Contributing | Code of Conduct

Marvin Wendt 408 Nov 15, 2022
espresso - a framework for testing BigQuery queries

espresso - a framework for testing BigQuery queries Goals Componentization: compose complex queries from smaller, reusable components Test driven deve

Tufin 7 Nov 18, 2022
Testy is a Go test running framework designed for Gametime's API testing needs.

template_library import "" Overview Index Overview Package template_library is a template repository for buildin

Gametime United, Inc. 4 Jun 21, 2022
Fortio load testing library, command line tool, advanced echo server and web UI in go (golang). Allows to specify a set query-per-second load and record latency histograms and other useful stats.

Fortio Fortio (Φορτίο) started as, and is, Istio's load testing tool and now graduated to be its own project. Fortio is also used by, among others, Me

Fortio (Φορτίο) 2.8k Nov 28, 2022
:exclamation:Basic Assertion Library used along side native go testing, with building blocks for custom assertions

Package assert Package assert is a Basic Assertion library used along side native go testing Installation Use go get. go get

Go Playgound 50 Nov 26, 2022
Expressive end-to-end HTTP API testing made easy in Go

baloo Expressive and versatile end-to-end HTTP API testing made easy in Go (golang), built on top of gentleman HTTP client toolkit. Take a look to the

Tom 746 Nov 19, 2022
Simple Go snapshot testing

Incredibly simple Go snapshot testing: cupaloy takes a snapshot of your test output and compares it to a snapshot committed alongside your tests. If t

Bradley Kemp 240 Nov 24, 2022
Clean database for testing, inspired by database_cleaner for Ruby

DbCleaner Clean database for testing, inspired by database_cleaner for Ruby. It uses flock syscall under the hood to make sure the test can runs in pa

Scott Le 146 Nov 17, 2022
Mutation testing for Go source code

go-mutesting go-mutesting is a framework for performing mutation testing on Go source code. Its main purpose is to find source code, which is not cove

Markus Zimmermann 563 Nov 18, 2022
Extremely flexible golang deep comparison, extends the go testing package and tests HTTP APIs

go-testdeep Extremely flexible golang deep comparison, extends the go testing package. Latest news Synopsis Description Installation Functions Availab

Maxime Soulé 329 Nov 26, 2022