tutl

func AtInterrupt ¶

func AtInterrupt(f func()) func()

AtInterrupt registers a function to be called if the test run is interrupted (by the user typing Ctrl-C or whatever sends SIGINT). The function registered first is run last. You must have called ShowStackOnInterrupt() or AtInterrupt() will do nothing useful.

The function passed in is also returned. This can be useful for clean-up code that should be run whether the test run is interrupted or not:

defer tutl.AtInterrupt(cleanup)()

If you want to empower AtInterrupt() even if ShowStackOnInterrupt() has not been enabled, then your code can call:

go tutl.ShowStackOnInterrupt(false)

This does nothing if ShowStackOnInterrupt() had already been called (in particular, it does not disable the showing of stack traces). Otherwise, it does the work that it would normally do except, if a SIGINT is received, it will only run any functions registered via AtInterrupt() but will not show stack traces.

func Char ¶

func Char(c byte) string

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).

func Circa ¶ added in v1.2.0

func Circa(digits int, want, got float64, desc string, t TestingT) bool

Circa() tests that the 2nd and 3rd arguments are approximately equal to each other. If they are not, then a diagnostic is displayed which also causes the unit test to fail.

The diagnostic is similar to "Got {got} not {want} for {desc}.\n" where 'want' and 'got' are shown formatted via 'fmt.Sprintf("%.*g", digits, v)'. They are considered equal if that formatting produces the same string for both values. That is, 'want' and 'got' are considered roughly equal if they are the same to 'digits' significant digits. Passing 'digits' as less than 1 or more than 15 is not useful.

Circa() returns whether the test passed, which is useful for skipping tests that would make no sense to run given a prior failure or to display extra debug information only when a test fails.

func DoubleQuote ¶

func DoubleQuote(s string) string

DoubleQuote() returns the string enclosed in double quotes and with contained \ and " characters escaped.

func Escape ¶

func Escape(r rune) string

Escape() returns a string containing the passed-in rune, unless it is a control character. Runes '\n', '\r', and '\t' each return a 2-character string (\n, \r, or \t). Other 7-bit control characters are turned into strings like \x1B. The 8-bit control characters are turned into strings like \u009B. EscapeNewline(false) does not affect Escape().

func EscapeNewline ¶

func EscapeNewline(b bool)

After calling EscapeNewline(true), S() will escape '\n' characters. You can call EscapeNewline(false) to restore the default behavior.

func GetPanic ¶ added in v1.2.0

func GetPanic(run func()) (failure interface{})

GetPanic() calls the passed-in function and returns 'nil' or the argument that gets passed to panic() from within it. This can be used in other test functions, for example:

u := tutl.New(t)
u.Is(nil, u.GetPanic(func(){ obj.Method(nil) }), "Method panic")

func HasType ¶ added in v1.2.0

func HasType(want string, got interface{}, desc string, t TestingT) bool

HasType() tests that the type of the 2nd argument ('got') is equal to the first argument ('want', a string). That is, it checks that 'want == fmt.Sprintf("%T", got)'. If not, then a diagnostic is displayed which also causes the unit test to fail.

The diagnostic is similar to "Got {got} not {want} for {desc}.\n" where '{got}' is the data type of 'got' and '{want}' is just the 'want' string.

If 'got' is an 'interface' type, then the type string will be the type of the underlying object (or "nil"). If you actually wish to compare the 'interface' type, then place '&' before 'got' and prepend "*" to 'want':

got := GetReader() // Returns io.Reader interface to an *os.File
tutl.HasType("*os.File", got, "underlying type is *os.File", t)
tutl.HasType("*io.Reader", &got, "interface type is io.Reader", t)
//            ^            ^ insert these to test interface type

HasType() returns whether the test passed, which is useful for skipping tests that would make no sense to run given a prior failure.

func Is ¶

func Is(want, got interface{}, desc string, t TestingT) bool

Is() tests that the first two arguments are converted to the same string by V(). If they are not, then a diagnostic is displayed which also causes the unit test to fail.

The diagnostic is similar to "Got {got} not {want} for {desc}.\n" except that; 1) S() is used for 'got' and 'want' so control characters will be escaped and their values may be in quotes and 2) it will be split onto multiple lines if the values involved are long enough.

Note that you pass 'want' before 'got' when calling Is() because the 'want' value is often a simple constant while 'got' can be a complex call and code is easier to read if you put shorter things first. But the output shows 'got' before 'want' as "Got X not Y" is the shortest way to express that concept in English.

Is() returns whether the test passed, which is useful for skipping tests that would make no sense to run given a prior failure or to display extra debug information only when a test fails.

func IsNot ¶

func IsNot(hate, got interface{}, desc string, t TestingT) bool

IsNot() tests that the first two arguments are converted to different strings by V(). If they are not, then a diagnostic is displayed which also causes the unit test to fail. The diagnostic is similar to "Got unwanted {got} for {desc}.\n" except that S() is used for 'got' so control characters will be escaped and their values may be in quotes.

IsNot() returns whether the test passed, which is useful for skipping tests that would make no sense to run given a prior failure.

func Like ¶

func Like(got interface{}, desc string, t TestingT, match ...string) int

Like() is most often used to test error messages (or other complex strings). It lets you perform multiple tests against a single value. Each test checks that the value converts into a string that either contains a specific sub-string (ignoring letter case) or that it matches a regular expression. You must pass at least one string to be matched.

Strings that start with "*" have the "*" stripped before a substring match is performed (ignoring letter case). If a string does not start with a "*", then it must be a valid regular expression that will be matched against the value's string representation.

Except that strings that start with "!" have that stripped before checking for a subsequent "*". The "!" negates the match so that the test will only pass if the string does not match. To specify a regular expression that starts with a "!" character, simply escape it as `\!` or "[!]".

Like() returns the number of matches that failed.

If 'got' is 'nil', the empty string, or becomes the empty string, then no comparisons are done and a single failure is reported (but the number returned is the number of match strings as it is assumed that none of them would have matched the empty string).

func ReplaceNewlines ¶ added in v1.2.0

func ReplaceNewlines(s string) string

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).

func Rune ¶

func Rune(r rune) string

Rune() returns a string consisting of the rune enclosed in single quotes, except that control characters are escaped [see Escape()].

Note that neither ' nor \ characters are escaped so Char('\”) returns "”'" (3 apostrophes) and Char('\\') returns `'\'` (partly because `'\”` and `'\\'` are rather ugly).

func S ¶

func S(vs ...interface{}) string

S() returns a single string composed by converting each argument into a string and concatenating all of those strings. It is similar to but not identical to 'fmt.Sprint()'. S() never inserts spaces between your values (if you want spaces, it is easy for you to add them). S() puts single quotes around 'byte' (and 'uint8') values. S() treats '[]byte' values like 'string's. S() puts double quotes around '[]byte' and 'error' values (escaping enclosed " and \ characters).

S() escapes control characters except for newlines [but see EscapeNewline()]. S() also escapes non-UTF-8 byte sequences.

If S() is passed a single argument that is a 'string', then it will put double quotes around it and escape any contained " and \ characters.

See V() for how 'float32', 'float64', '[]float32', or '[]float64' values are converted.

Note that S() does not put single quotes around 'rune' values as 'rune' is just an alias for 'int32' so S('x') == S(int32('x')) == "120" while S("x"[0]) == S(byte('x')) == S(uint8('x')) = "'x'".

func ShowStackOnInterrupt ¶

func ShowStackOnInterrupt(show ...bool)

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. This is particularly useful if your code has an infinite loop.

See also "go doc github.com/Unity-Technologies/go-tutl-internal/hang".

ShowStackOnInterrupt() can also be used from non-test programs.

ShowStackOnInterrupt(false) has a special meaning; see AtInterrupt().

func V ¶

func V(v interface{}) string

V() just converts a value to a string. It is similar to 'fmt.Sprint(v)'. But it treats '[]byte' values as 'string's. It also (by default) uses fewer significant digits when converting 'float32', 'float64', '[]float32', and '[]float64' values (see Options for details).