Adding upstream version 2:1.19~1.upstream/2%1.19_1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 150 insertions, 0 deletions

diff --git a/man/go-test.1 b/man/go-test.1
new file mode 100644
index 0000000..8636e67
--- /dev/null
+++ b/man/go-test.1
@@ -0,0 +1,150 @@
+.\"                                      Hey, EMACS: -*- nroff -*-
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.TH GO-TEST 1 "2022-08-02"
+.\" Please adjust this date whenever revising the manpage.
+.SH NAME
+go-test \- test packages
+.SH SYNOPSIS
+.B go test
+.RI [ "build/test flags" ]
+.RI [ packages ]
+.RI [ "build/test flags & test binary flags" ]
+.SH DESCRIPTION
+"Go test" automates testing the packages named by the import paths.
+It prints a summary of the test results in the format:
+
+.Vb 6
+\&      ok   archive/tar   0.011s
+\&      FAIL archive/zip   0.022s
+\&      ok   compress/gzip 0.033s
+\&      ...
+.Ve
+
+followed by detailed output for each failed package.
+.P
+"Go test" recompiles each package along with any files with names matching
+the file pattern "*_test.go".
+These additional files can contain test functions, benchmark functions, fuzz
+tests and example functions. See \(oqgo help testfunc\(cq for more.
+.br
+Each listed package causes the execution of a separate test binary.
+Files whose names begin with "_" (including "_test.go") or "." are ignored.
+.P
+Test files that declare a package with the suffix "_test" will be compiled as a
+separate package, and then linked and run with the main test binary.
+.P
+The go tool will ignore a directory named "testdata", making it available
+to hold ancillary data needed by the tests.
+.P
+As part of building a test binary, go test runs go vet on the package
+and its test source files to identify significant problems. If go vet
+finds any problems, go test reports those and does not run the test
+binary. Only a high-confidence subset of the default go vet checks are
+used. That subset is: \(oqatomic\(cq, \(oqbool\(cq, \(oqbuildtags\(cq, \(oqerrorsas\(cq, \(oqifaceassert\(cq, \(oqnilfunc\(cq, \(oqprintf\(cq, and \(oqstringintconv\(cq. You can see
+the documentation for these and other vet tests via "go doc cmd/vet".
+To disable the running of go vet, use the \-vet=off flag. To run all
+checks, use the \-vet=all flag.
+.P
+All test output and summary lines are printed to the go command\(cqs
+standard output, even if the test printed them to its own standard
+error. (The go command\(cqs standard error is reserved for printing
+errors building the tests.)
+.P
+Go test runs in two different modes:
+.P
+The first, called local directory mode, occurs when go test is
+invoked with no package arguments (for example, \(oqgo test\(cq or \(oqgo
+test \-v\(cq). In this mode, go test compiles the package sources and
+tests found in the current directory and then runs the resulting
+test binary. In this mode, caching (discussed below) is disabled.
+After the package test finishes, go test prints a summary line
+showing the test status (\(oqok\(cq or \(oqFAIL\(cq), package name, and elapsed
+time.
+.P
+The second, called package list mode, occurs when go test is invoked
+with explicit package arguments (for example \(oqgo test math\(cq, \(oqgo
+test ./...\(cq, and even \(oqgo test .\(cq). In this mode, go test compiles
+and tests each of the packages listed on the command line. If a
+package test passes, go test prints only the final \(oqok\(cq summary
+line. If a package test fails, go test prints the full test output.
+If invoked with the \-bench or \-v flag, go test prints the full
+output even for passing package tests, in order to display the
+requested benchmark results or verbose logging. After the package
+tests for all of the listed packages finish, and their output is
+printed, go test prints a final \(oqFAIL\(cq status if any package test
+has failed.
+.P
+In package list mode only, go test caches successful package test
+results to avoid unnecessary repeated running of tests. When the
+result of a test can be recovered from the cache, go test will
+redisplay the previous output instead of running the test binary
+again. When this happens, go test prints \(oq(cached)\(cq in place of the
+elapsed time in the summary line.
+.P
+The rule for a match in the cache is that the run involves the same
+test binary and the flags on the command line come entirely from a
+restricted set of \[oq]cacheable\[cq] test flags, defined as \-benchtime, \-cpu,
+\-list, \-parallel, \-run, \-short, \-timeout, \-failfast, and \-v.
+If a run of go test has any test or non-test flags outside this set,
+the result is not cached. To disable test caching, use any test flag
+or argument other than the cacheable flags. The idiomatic way to disable
+test caching explicitly is to use \-count=1. Tests that open files within
+the package\(cqs source root (usually $GOPATH) or that consult environment
+variables only match future runs in which the files and environment
+variables are unchanged. A cached test result is treated as executing
+in no time at all, so a successful package test result will be cached and
+reused regardless of \-timeout setting.
+.SH OPTIONS
+In addition to the build flags, the flags handled by \(oqgo test\(cq itself are:
+.TP
+.B \-args
+Pass the remainder of the command line (everything after \-args)
+to the test binary, uninterpreted and unchanged.
+Because this flag consumes the remainder of the command line,
+the package list (if present) must appear before this flag.
+.TP
+.B \-c
+Compile the test binary to pkg.test but do not run it
+(where pkg is the last element of the package\(cqs import path).
+The file name can be changed with the \-o flag.
+.TP
+.BI "\-exec " xprog
+Run the test binary using xprog. The behavior is the same as
+in \(oqgo run\(cq. See \(oqgo help run\(cq for details.
+.TP
+.B \-i
+Install packages that are dependencies of the test.
+Do not run the test.
+.TP
+.B \-json
+Convert test output to JSON suitable for automated processing.
+See \(oqgo doc test2json\(cq for the encoding details.
+.TP
+.BI "\-o " file
+Compile the test binary to the named file.
+The test still runs (unless \-c or \-i is specified).
+.P
+The test binary also accepts flags that control execution of the test; these
+flags are also accessible by \(oqgo test\(cq.  See \fBgo-testflag\fP(7) for details.
+.P
+For more about build flags, see \fBgo-build\fP(1).
+.P
+For more about specifying packages, see \fBgo-packages\fP(7).
+.SH SEE ALSO
+.BR go-build (1),
+.BR go-vet (1).
+.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 test\(cq
+for the Debian project (and may be used by others).