Categorygithub.com/Unity-Technologies/go-tutl-internal
modulepackage
1.2.0
Repository: https://github.com/unity-technologies/go-tutl-internal.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
10
Dependents
5
Files
495 SLOC

# README

go-tutl

go-tutl is a Tiny Unit Testing Library (for Go). "Tutl" is also the Faroese word for "whisper", a nod to it's light-weight nature.

TUTL provides a few helper routines that make simple unit testing in Go much easier and that encourage you to write tests that, when they fail, it is easy to figure out what broke.

It started as the 2 small functions that I have felt worth writing every time I needed to do unit tests in Go, Is() and S(). Plus 2 other small functions that I usually eventually end up writing when I get further along with a project, Like() and ShowStackOnInterrupt(). And it has been collecting small improvements over the years.

Example usage:

package duration
import (
    "testing"

    u "github.com/Unity-Technologies/go-tutl-internal"
    _ "github.com/Unity-Technologies/go-tutl-internal/hang" // ^C gives stack dumps.
)

func TestDur(t *testing.T) {
    u.Is("1m 1s", DurationAsText(61), "61", t)

    got, err := TextAsDuration("1h 5s")
    u.Is(nil, err, "Error from '1h 5s'", t)
    u.Is(60*60+5, got, "'1h 5s'", t)

    got, err = TextAsDuration("3 fortnight")
    u.Like(err, "Error from '3 fortnight'", t,
        "(Unknown|Invalid) unit", "*fortnight")
}

Sample output from a failing run of the above tests:

dur_test.go:10: Got "1m 61s" not "1m 1s" for 61.
dur_test.go:14: Got 3600 not 3605 for '1h 5s'.
dur_test.go:17:
    Not like /(Unknown|Invalid) unit/...
    and No <fortnight>...
    In <"Bad unit (ortnight) in duration.
    "> for Error from '3 fortnight'.

It also provides a special module to deal with infinite loops in your code. If you include:

import (
    _ "github.com/Unity-Technologies/go-tutl-internal/hang" // ^C gives stack dumps.
)

in just one of your *_test.go files, then you can interrupt (such as via typing Ctrl-C) an infinite loop or otherwise hanging test run and be shown, in response, the stack traces of everything that is running.

# Packages

Include: import ( _ "github.com/Unity-Technologies/go-tutl-internal/hang" // ^C gives stack dumps.
A couple of simple helper functions to make it easy to get CPU or blocking profile data from your tests.

# Functions

AtInterrupt registers a function to be called if the test run is interrupted (by the user typing Ctrl-C or whatever sends SIGINT).
Char(c) is similar to Rune(rune(c)), except it escapes all byte values of 0x80 and above into 6-character strings like '\x9B' (rather then converting them UTF-8).
Circa() tests that the 2nd and 3rd arguments are approximately equal to each other.
DoubleQuote() returns the string enclosed in double quotes and with contained \ and " characters escaped.
Escape() returns a string containing the passed-in rune, unless it is a control character.
After calling EscapeNewline(true), S() will escape '\n' characters.
GetPanic() calls the passed-in function and returns 'nil' or the argument that gets passed to panic() from within it.
HasType() tests that the type of the 2nd argument ('got') is equal to the first argument ('want', a string).
Is() tests that the first two arguments are converted to the same string by V().
IsNot() tests that the first two arguments are converted to different strings by V().
Like() is most often used to test error messages (or other complex strings).
A unit test can have a huge number of calls to Is().
ReplaceNewlines() returns a string with each newline replaced with either an escaped newline (a \ then an 'n') or with the string "\n...." (so that subsequent lines of a multi-line value are indented to make them easier to distinguish from subsequent lines of a test diagnostic).
Rune() returns a string consisting of the rune enclosed in single quotes, except that control characters are escaped [see Escape()].
S() returns a single string composed by converting each argument into a string and concatenating all of those strings.
If you have a TestMain() function, then you can add go tutl.ShowStackOnInterrupt() to it to allow you to interrupt it (such as via typing Ctrl-C) in order to see stack traces of everything that is running.
V() just converts a value to a string.

# Constants

No description provided by the author
No description provided by the author

# Variables

The 'tutl.Default' global contains the user preferences to be used unless you make a copy and use it, such as via New() (see Options for more).
The 'tutl.StdoutTester' is a replacement for a '*testing.T' that just writes output to 'os.Stdout'.

# Structs

A FakeTester is a replacement for a '*testing.T' so that you can use TUTL's functionality outside of a real 'go test' run.
Options contains user preference options.
TUTL is a type used to allow an alternate calling style, especially for Is() and Like().

# Interfaces

TestingT is an interface covering the methods of '*testing.T' that TUTL uses.