diff options
Diffstat (limited to 'man/go-testflag.7')
| -rw-r--r-- | man/go-testflag.7 | 323 |
1 files changed, 323 insertions, 0 deletions
diff --git a/man/go-testflag.7 b/man/go-testflag.7 new file mode 100644 index 0000000..aabd409 --- /dev/null +++ b/man/go-testflag.7 @@ -0,0 +1,323 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GO-TESTFLAG 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 takes both flags that apply to \(oqgo test\(cq itself +and flags that apply to the resulting test binary. + +Several of the flags control profiling and write an execution profile +suitable for "go tool pprof"; run "go tool pprof \-h" for more +information. The \-\-alloc_space, \-\-alloc_objects, and \-\-show_bytes +options of pprof control how the information is presented. + +The following flags are recognized by the \(oqgo test\(cq command and +control the execution of any test: +.TP +.BI \-bench " regexp" +Run only those benchmarks matching a regular expression. +By default, no benchmarks are run. +To run all benchmarks, use \(oq\-bench .\(cq or \(oq\-bench=.\(cq. +The regular expression is split by unbracketed slash (/) +characters into a sequence of regular expressions, and each +part of a benchmark\[cq]s identifier must match the corresponding +element in the sequence, if any. Possible parents of matches +are run with b.N=1 to identify sub-benchmarks. For example, +given \-bench=X/Y, top-level benchmarks matching X are run +with b.N=1 to find any sub-benchmarks matching Y, which are +then run in full. +.TP +.BI \-benchtime " t" +Run enough iterations of each benchmark to take \fIt\fP, specified +as a time.Duration (for example, \-benchtime 1h30s). +.br +The default is 1 second (1s). +.br +The special syntax \fIN\fPx means to run the benchmark \fIN\fP times +(for example, \-benchtime 100x). +.TP +.BI \-count " n" +Run each test, benchmark, and fuzz seed \fIn\fP times (default 1). +.br +If \-cpu is set, run n times for each GOMAXPROCS value. +.br +Examples are always run once. \-count does not apply to +fuzz tests matched by \-fuzz. +.TP +.B \-cover +Enable coverage analysis. +.br +Note that because coverage works by annotating the source +code before compilation, compilation and test failures with +coverage enabled may report line numbers that don\(cqt correspond +to the original sources. +.TP +.BR \-covermode " set,count,atomic" +Set the mode for coverage analysis for the package[s] +being tested. The default is "set" unless \-race is enabled, +in which case it is "atomic". +.br +The values: + set: bool: does this statement run? + count: int: how many times does this statement run? + atomic: int: count, but correct in multithreaded tests; + significantly more expensive. +.br +Sets \-cover. +.TP +.BI "\-coverpkg " pattern1 , pattern2 , pattern3 +Apply coverage analysis in each test to packages matching the patterns. +The default is for each test to analyze only the package being tested. +.br +See \(oqgo help packages\(cq for a description of package patterns. +.br +Sets \-cover. +.TP +.BI "\-cpu " 1 , 2 , 4 +Specify a list of GOMAXPROCS values for which the tests, benchmarks or +fuzz tests should be executed. The default is the current value +of GOMAXPROCS. \-cpu does not apply to fuzz tests matched by \-fuzz. +.TP +.B \-failfast +Do not start new tests after the first test failure. +.TP +.BI \-fuzz " regexp" +Run the fuzz test matching the regular expression. When specified, +the command line argument must match exactly one package within the +main module, and regexp must match exactly one fuzz test within +that package. Fuzzing will occur after tests, benchmarks, seed corpora +of other fuzz tests, and examples have completed. See the Fuzzing +section of the testing package documentation for details. +.TP +.BI \-fuzztime " t" +Run enough iterations of the fuzz target during fuzzing to take \fIt\fP, +specified as a time.Duration (for example, \-fuzztime 1h30s). + The default is to run forever. +.br +The special syntax \fIN\fPx means to run the fuzz target \fIN\fP times +(for example, \-fuzztime 1000x). +.TP +.BI \-fuzzminimizetime " t" +Run enough iterations of the fuzz target during each minimization +attempt to take \fIt\fP, as specified as a time.Duration (for example, +\-fuzzminimizetime 30s). + The default is 60s. +.br +The special syntax \fIN\fPx means to run the fuzz target \fIN\fP times +(for example, \-fuzzminimizetime 100x). +.TP +.B \-json +Log verbose output and test results in JSON. This presents the +same information as the \-v flag in a machine-readable format. +.TP +.BI \-list " regexp" +List tests, benchmarks, fuzz tests, or examples matching the regular +expression. No tests, benchmarks, fuzz tests, or examples will be run. +This will only list top-level tests. No subtest or subbenchmarks will be +shown. +.TP +.BI \-parallel " n" +Allow parallel execution of test functions that call t.Parallel, and +fuzz targets that call t.Parallel when running the seed corpus. +The value of this flag is the maximum number of tests to run +simultaneously. +.br +While fuzzing, the value of this flag is the maximum number of +subprocesses that may call the fuzz function simultaneously, regardless of +whether T.Parallel is called. +.br +By default, \-parallel is set to the value of GOMAXPROCS. +Setting \-parallel to values higher than GOMAXPROCS may cause degraded +performance due to CPU contention, especially when fuzzing. +Note that \-parallel only applies within a single test binary. +The \(oqgo test\(cq command may run tests for different packages +in parallel as well, according to the setting of the \-p flag +(see \(oqgo help build\(cq). +.TP +.BI \-run " regexp" +Run only those tests, examples, and fuzz tests matching the regular +expression. For tests, the regular expression is split by unbracketed +slash (/) characters into a sequence of regular expressions, and each +part of a test\(cqs identifier must match the corresponding element in +the sequence, if any. Note that possible parents of matches are +run too, so that \-run=X/Y matches and runs and reports the result +of all tests matching X, even those without sub-tests matching Y, +because it must run them to look for those sub-tests. +.TP +.B \-short +Tell long-running tests to shorten their run time. +It is off by default but set during all.bash so that installing +the Go tree can run a sanity check but not spend time running +exhaustive tests. +.TP +.BR "\-shuffle " off,on,N +Randomize the execution order of tests and benchmarks. +It is off by default. If \-shuffle is set to on, then it will seed +the randomizer using the system clock. If \-shuffle is set to an +integer N, then N will be used as the seed value. In both cases, +the seed will be reported for reproducibility. +.TP +.BI \-timeout " d" +If a test binary runs longer than duration \fId\fP, panic. +.br +If \fId\fP is 0, the timeout is disabled. +.br +The default is 10 minutes (10m). +.TP +.B \-v +Verbose output: log all tests as they are run. Also print all +text from Log and Logf calls even if the test succeeds. +.TP +.BI \-vet " list" +Configure the invocation of "go vet" during "go test" +to use the comma-separated list of vet checks. +.br +If list is empty, "go test" runs "go vet" with a curated list of +checks believed to be always worth addressing. +.br +If list is "off", "go test" does not run "go vet" at all. +.P +The following flags are also recognized by \(oqgo test\(cq and can be used to +profile the tests during execution: +.TP +.B \-benchmem +Print memory allocation statistics for benchmarks. +.TP +.B \-blockprofile \fRblock.out +Write a goroutine blocking profile to the specified file +when all tests are complete. +.br +Writes test binary as \-c would. +.TP +.BI \-blockprofilerate " n" +Control the detail provided in goroutine blocking profiles by +calling runtime.SetBlockProfileRate with \fIn\fP. +.br +See \(oqgo doc runtime.SetBlockProfileRate\(cq. +.br +The profiler aims to sample, on average, one blocking event every +n nanoseconds the program spends blocked. By default, +if \-test.blockprofile is set without this flag, all blocking events +are recorded, equivalent to \-test.blockprofilerate=1. +.TP +.B \-coverprofile \fRcover.out +Write a coverage profile to the file after all tests have passed. +.br +Sets \-cover. +.TP +.B \-cpuprofile \fRcpu.out +Write a CPU profile to the specified file before exiting. +.br +Writes test binary as \-c would. +.TP +.B \-memprofile \fRmem.out +Write an allocation profile to the file after all tests have passed. +.br +Writes test binary as \-c would. +.TP +.BI \-memprofilerate " n" +Enable more precise (and expensive) memory allocation profiles by +setting runtime.MemProfileRate. See \(oqgo doc runtime.MemProfileRate\(cq. +To profile all memory allocations, use \-test.memprofilerate=1. +.TP +.B \-mutexprofile \fRmutex.out +Write a mutex contention profile to the specified file +when all tests are complete. +.br +Writes test binary as \-c would. +.TP +.BI \-mutexprofilefraction " n" +Sample 1 in \fIn\fP stack traces of goroutines holding a +contended mutex. +.TP +.B \-outputdir \fIdirectory +Place output files from profiling in the specified directory, +by default the directory in which "go test" is running. +.TP +.B \-trace trace.out +Write an execution trace to the specified file before exiting. +.P +Each of these flags is also recognized with an optional \(oqtest.\(cq prefix, +as in \-test.v. When invoking the generated test binary (the result of +\(oqgo test \-c\(cq) directly, however, the prefix is mandatory. + +The \(oqgo test\(cq command rewrites or removes recognized flags, +as appropriate, both before and after the optional package list, +before invoking the test binary. + +For instance, the command + + go test \-v \-myflag testdata \-cpuprofile=prof.out \-x + +will compile the test binary and then run it as + + pkg.test \-test.v \-myflag testdata \-test.cpuprofile=prof.out + +(The \-x flag is removed because it applies only to the go command\(cqs +execution, not to the test itself.) + +The test flags that generate profiles (other than for coverage) also +leave the test binary in pkg.test for use when analyzing the profiles. + +When \(oqgo test\(cq runs a test binary, it does so from within the +corresponding package\(cqs source code directory. Depending on the test, +it may be necessary to do the same when invoking a generated test +binary directly. Because that directory may be located within the +module cache, which may be read-only and is verified by checksums, the +test must not write to it or any other directory within the module +unless explicitly requested by the user (such as with the \-fuzz flag, +which writes failures to testdata/fuzz). + +The command-line package list, if present, must appear before any +flag not known to the go test command. Continuing the example above, +the package list would have to appear before \-myflag, but could appear +on either side of \-v. + +When \(oqgo test\(cq runs in package list mode, \(oqgo test\(cq caches successful +package test results to avoid unnecessary repeated running of tests. 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. + +To keep an argument for a test binary from being interpreted as a +known flag or a package name, use \-args (see \(oqgo help test\(cq) which +passes the remainder of the command line through to the test binary +uninterpreted and unaltered. + +For instance, the command + + go test \-v \-args \-x \-v + +will compile the test binary and then run it as + + pkg.test \-test.v \-x \-v + +Similarly, + + go test \-args math + +will compile the test binary and then run it as + + pkg.test math + +In the first example, the \-x and the second \-v are passed through to the +test binary unchanged and with no effect on the go command itself. +In the second example, the argument math is passed through to the test +binary, instead of being interpreted as the package list. +.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 testflag\(cq +for the Debian project (and may be used by others). |