summaryrefslogtreecommitdiffstats
path: root/man/go-testfunc.7
blob: b890934e584d497ae980cbb5bb52d3c1616fa13d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
.\"                                      Hey, EMACS: -*- nroff -*-
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.TH GO-TESTFUNC 7 "2022-03-15"
.\" Please adjust this date whenever revising the manpage.
.SH NAME
go \- tool for managing Go source code
.SH DESCRIPTION
The \(oqgo test\(cq command expects to find test, benchmark, and example functions
in the "*_test.go" files corresponding to the package under test.

A test function is one named TestXxx (where Xxx does not start with a
lower case letter) and should have the signature,

.Vb 6
\&      func TestXxx(t *testing.T) { ... }
.Ve

A benchmark function is one named BenchmarkXxx and should have the signature,

.Vb 6
\&      func BenchmarkXxx(b *testing.B) { ... }
.Ve

A fuzz test is one named FuzzXxx and should have the signature,

.Vb 6
\&      func FuzzXxx(f *testing.F) { ... }
.Ve

An example function is similar to a test function but, instead of using
*testing.T to report success or failure, prints output to os.Stdout.
If the last comment in the function starts with "Output:" then the output
is compared exactly against the comment (see examples below). If the last
comment begins with "Unordered output:" then the output is compared to the
comment, however the order of the lines is ignored. An example with no such
comment is compiled but not executed. An example with no text after
"Output:" is compiled, executed, and expected to produce no output.

Godoc displays the body of ExampleXxx to demonstrate the use
of the function, constant, or variable Xxx. An example of a method M with
receiver type T or *T is named ExampleT_M. There may be multiple examples
for a given function, constant, or variable, distinguished by a trailing _xxx,
where xxx is a suffix not beginning with an upper case letter.

Here is an example of an example:

.Vb 6
\&      func ExamplePrintln() {
\&          Println("The output of\\nthis example.")
\&          // Output: The output of
\&          // this example.
\&      }
.Ve

Here is another example where the ordering of the output is ignored:

.Vb 6
\&      func ExamplePerm() {
\&          for _, value := range Perm(4) {
\&              fmt.Println(value)
\&          }
\&
\&          // Unordered output: 4
\&          // 2
\&          // 1
\&          // 3
\&          // 0
\&      }
.Ve

The entire test file is presented as the example when it contains a single
example function, at least one other function, type, variable, or constant
declaration, and no tests, benchmarks, or fuzz tests.

See the documentation of the testing package for more information.
.SH AUTHOR
.PP
This manual page was written by Michael Stapelberg <stapelberg@debian.org>
and is maintained by the
Debian Go Compiler Team <team+go-compiler@tracker.debian.org>
based on the output of \(oqgo help testfunc\(cq
for the Debian project (and may be used by others).