README

go-want

Go Reference

Go test library that delivers simple test assertions with useful verbose output.

Usage

import (
	"strings"
	"testing"
	"unicode"

	"4d63.com/want"
)

func Abs(i int) int {
	if i < 0 {
		return -i
	}
	return i
}

func TestAbs(t *testing.T) {
	want.Eq(t, Abs(-1), 1)
	want.Eq(t, Abs(-1), 0) // will fail
}

func Title(s string) string {
	sb := strings.Builder{}
	beginningWord := true
	for _, r := range s {
		if beginningWord {
			r = unicode.ToUpper(r)
			beginningWord = false
		} else if unicode.IsSpace(r) {
			beginningWord = true
		}
		sb.WriteRune(r)
	}
	return sb.String()
}

func TestTitle(t *testing.T) {
	want.Eq(t, Title("hello\nfriendly\nworld"), "Hello\nFriendly\nWorld")
	want.Eq(t, Title("hello\nfriendly\nworld"), "Hello\nfriendly\nWorld") // will fail
}
$ go test -v
--- FAIL: TestAbs (0.00s)
    readme_test.go:21: want.Eq(t, Abs(-1), 1): got 1
    readme_test.go:22: want.Eq(t, Abs(-1), 0): got 1, want 0
--- FAIL: TestTitle (0.00s)
    readme_test.go:41: want.Eq(t, Title("hello\nfriendly\nworld"), "Hello\nFriendly\nWorld"): got Hello
        Friendly
        World
    readme_test.go:42: want.Eq(t, Title("hello\nfriendly\nworld"), "Hello\nfriendly\nWorld"):
        --- Want
        +++ Got
        @@ -1,3 +1,3 @@
         Hello
        -friendly
        +Friendly
         World

Documentation

Overview

Package want is a package that provides equality functions for testing Go code. It is focused on making the most common action in test code simple, testing equality expectations.

A simple test function looks like this:

func TestAbs(t *testing.T) {
    want.Eq(t, Abs(-1), 1)
}

If the check passes, the verbose output looks like this:

--- PASS: TestAbs (0.00s)
    test.go:2: want.Eq(t, Abs(-1), 1): got 1

If the check fails, and the type is a bool, int, or float, the output looks like this:

--- PASS: TestAbs (0.00s)
    test.go:2: want.Eq(t, Abs(-1), 1): got 0, want 1

If the check fails, and the type is a string, array, slice, or complex type, the output looks like this:

--- FAIL: TestAbs (0.00s)
    test.go:2: want.Eq(t, Abs(-1), 1): int(
    -: 0
    +: 1
    )

Got and want

The terms got and want are used to describe what you got as a result of running the code, and what you want to have gotten. These terms are commonly found in the Go stdlib and it's own testing docs. In some other testing libraries they are sometimes referred to actual and expected.

Nesting

Checks can be nested using the bool return value of a prior check.

func TestAbs(t *testing.T) {
    if want.Eq(t, Abs(-1), 1) {
        ...
    }
}

Breaking early

Checks can cause a test to stop at a failure using the bool return value.

func TestAbs(t *testing.T) {
    if !want.Eq(t, Abs(-1), 1) {
        return
    }
    ...
}

Comparison

Comparison of got and want is done using Google's cmp Go module: https://github.com/google/go-cmp/cmp

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Eq

func Eq(tb testing.TB, got, want interface{}) bool

    Eq compares got to want and reports an error to tb if they are not equal. Returns true if equal.

    Example (Fail)
    Output:
    
    want.Eq(t, Abs(-1), 0): got 1, want 0
    
    Example (Pass)
    Output:
    
    want.Eq(t, Abs(-1), 1): got 1
    

    func False

    func False(tb testing.TB, got bool) bool

      False checks if got is false and reports an error to tb if it is not false. Returns true if false.

      func Nil

      func Nil(tb testing.TB, got interface{}) bool

        Nil checks if got is nil and reports an error to tb if it is not nil. Returns true if nil.

        Example (Fail)
        Output:
        
        want.Nil(t, thing): got 0, want <nil>
        
        Example (Pass)
        Output:
        
        want.Nil(t, nil): got <nil>
        

        func NotEq

        func NotEq(tb testing.TB, got, notWant interface{}) bool

          NotEq compares got to want and reports an error to tb if they are equal. Returns true if not equal.

          Example (Fail)
          Output:
          
          want.NotEq(t, Abs(-1), 1): got 1, want not 1
          
          Example (Pass)
          Output:
          
          want.NotEq(t, Abs(-1), -1): got 1, not -1
          

          func NotNil

          func NotNil(tb testing.TB, got interface{}) bool

            NotNil checks if got is not nil and reports an error to tb if it is nil. Returns true if not nil.

            Example (Fail)
            Output:
            
            want.NotNil(t, nil): got <nil>, want not <nil>
            
            Example (Pass)
            Output:
            
            want.NotNil(t, thing): got 0, not <nil>
            

            func True

            func True(tb testing.TB, got bool) bool

              True checks if got is true and reports an error to tb if it is not true. Returns true if true.

              Types

              type Want

              type Want struct{}

                A Want is a set of options for configuring the behavior of the library. Its zero value (Want{}) is usable and is equivalent to invoking the package functions Eq and NotEq.

                func (*Want) Eq

                func (w *Want) Eq(tb testing.TB, got, want interface{}) bool

                  Eq compares got to want and reports an error to tb if they are not equal. Returns true if equal.

                  func (*Want) False

                  func (w *Want) False(tb testing.TB, got bool) bool

                    False checks if got is false and reports an error to tb if it is not false. Returns true if false.

                    func (*Want) Nil

                    func (w *Want) Nil(tb testing.TB, got interface{}) bool

                      Nil checks if got is nil and reports an error to tb if it is not nil. Returns true if nil.

                      func (*Want) NotEq

                      func (w *Want) NotEq(tb testing.TB, got, notWant interface{}) bool

                        NotEq compares got to want and reports an error to tb if they are equal. Returns true if not equal.

                        func (*Want) NotNil

                        func (w *Want) NotNil(tb testing.TB, got interface{}) bool

                          NotNil checks if got is not nil and reports an error to tb if it is nil. Returns true if not nil.

                          func (*Want) True

                          func (w *Want) True(tb testing.TB, got bool) bool

                            True checks if got is true and reports an error to tb if it is not true. Returns true if true.