1This file is generated by 'go generate cmd/go'. DO NOT EDIT. 2 3This directory holds test scripts *.txt run during 'go test cmd/go'. 4To run a specific script foo.txt 5 6 go test cmd/go -run=Script/^foo$ 7 8In general script files should have short names: a few words, not whole sentences. 9The first word should be the general category of behavior being tested, 10often the name of a go subcommand (list, build, test, ...) or concept (vendor, pattern). 11 12Each script is a text archive (go doc internal/txtar). 13The script begins with an actual command script to run 14followed by the content of zero or more supporting files to 15create in the script's temporary file system before it starts executing. 16 17As an example, run_hello.txt says: 18 19 # hello world 20 go run hello.go 21 stderr 'hello world' 22 ! stdout . 23 24 -- hello.go -- 25 package main 26 func main() { println("hello world") } 27 28Each script runs in a fresh temporary work directory tree, available to scripts as $WORK. 29Scripts also have access to other environment variables, including: 30 31 GOARCH=<target GOARCH> 32 GOCACHE=<actual GOCACHE being used outside the test> 33 GOEXE=<executable file suffix: .exe on Windows, empty on other systems> 34 GOOS=<target GOOS> 35 GOPATH=$WORK/gopath 36 GOPROXY=<local module proxy serving from cmd/go/testdata/mod> 37 GOROOT=<actual GOROOT> 38 TESTGO_GOROOT=<GOROOT used to build cmd/go, for use in tests that may change GOROOT> 39 HOME=/no-home 40 PATH=<actual PATH> 41 TMPDIR=$WORK/tmp 42 GODEBUG=<actual GODEBUG> 43 devnull=<value of os.DevNull> 44 goversion=<current Go version; for example, 1.12> 45 46On Plan 9, the variables $path and $home are set instead of $PATH and $HOME. 47On Windows, the variables $USERPROFILE and $TMP are set instead of 48$HOME and $TMPDIR. 49 50The lines at the top of the script are a sequence of commands to be executed by 51a small script engine configured in ../../script_test.go (not the system shell). 52 53The scripts' supporting files are unpacked relative to $GOPATH/src 54(aka $WORK/gopath/src) and then the script begins execution in that directory as 55well. Thus the example above runs in $WORK/gopath/src with GOPATH=$WORK/gopath 56and $WORK/gopath/src/hello.go containing the listed contents. 57 58Each line of a script is parsed into a sequence of space-separated command 59words, with environment variable expansion within each word and # marking 60an end-of-line comment. Additional variables named ':' and '/' are expanded 61within script arguments (expanding to the value of os.PathListSeparator and 62os.PathSeparator respectively) but are not inherited in subprocess environments. 63 64Adding single quotes around text keeps spaces in that text from being treated 65as word separators and also disables environment variable expansion. Inside a 66single-quoted block of text, a repeated single quote indicates a literal single 67quote, as in: 68 69 'Don''t communicate by sharing memory.' 70 71A line beginning with # is a comment and conventionally explains what is being 72done or tested at the start of a new section of the script. 73 74Commands are executed one at a time, and errors are checked for each command; 75if any command fails unexpectedly, no subsequent commands in the script are 76executed. The command prefix ! indicates that the command on the rest of the 77line (typically go or a matching predicate) must fail instead of succeeding. 78The command prefix ? indicates that the command may or may not succeed, but the 79script should continue regardless. 80 81The command prefix [cond] indicates that the command on the rest of the line 82should only run when the condition is satisfied. 83 84A condition can be negated: [!root] means to run the rest of the line only if 85the user is not root. Multiple conditions may be given for a single command, 86for example, '[linux] [amd64] skip'. The command will run if all conditions are 87satisfied. 88 89When TestScript runs a script and the script fails, by default TestScript shows 90the execution of the most recent phase of the script (since the last # comment) 91and only shows the # comments for earlier phases. For example, here is a 92multi-phase script with a bug in it: 93 94 # GOPATH with p1 in d2, p2 in d2 95 env GOPATH=$WORK${/}d1${:}$WORK${/}d2 96 97 # build & install p1 98 env 99 go install -i p1 100 ! stale p1 101 ! stale p2 102 103 # modify p2 - p1 should appear stale 104 cp $WORK/p2x.go $WORK/d2/src/p2/p2.go 105 stale p1 p2 106 107 # build & install p1 again 108 go install -i p11 109 ! stale p1 110 ! stale p2 111 112 -- $WORK/d1/src/p1/p1.go -- 113 package p1 114 import "p2" 115 func F() { p2.F() } 116 -- $WORK/d2/src/p2/p2.go -- 117 package p2 118 func F() {} 119 -- $WORK/p2x.go -- 120 package p2 121 func F() {} 122 func G() {} 123 124The bug is that the final phase installs p11 instead of p1. The test failure looks like: 125 126 $ go test -run=Script 127 --- FAIL: TestScript (3.75s) 128 --- FAIL: TestScript/install_rebuild_gopath (0.16s) 129 script_test.go:223: 130 # GOPATH with p1 in d2, p2 in d2 (0.000s) 131 # build & install p1 (0.087s) 132 # modify p2 - p1 should appear stale (0.029s) 133 # build & install p1 again (0.022s) 134 > go install -i p11 135 [stderr] 136 can't load package: package p11: cannot find package "p11" in any of: 137 /Users/rsc/go/src/p11 (from $GOROOT) 138 $WORK/d1/src/p11 (from $GOPATH) 139 $WORK/d2/src/p11 140 [exit status 1] 141 FAIL: unexpected go command failure 142 143 script_test.go:73: failed at testdata/script/install_rebuild_gopath.txt:15 in $WORK/gopath/src 144 145 FAIL 146 exit status 1 147 FAIL cmd/go 4.875s 148 $ 149 150Note that the commands in earlier phases have been hidden, so that the relevant 151commands are more easily found, and the elapsed time for a completed phase 152is shown next to the phase heading. To see the entire execution, use "go test -v", 153which also adds an initial environment dump to the beginning of the log. 154 155Note also that in reported output, the actual name of the per-script temporary directory 156has been consistently replaced with the literal string $WORK. 157 158The cmd/go test flag -testwork (which must appear on the "go test" command line after 159standard test flags) causes each test to log the name of its $WORK directory and other 160environment variable settings and also to leave that directory behind when it exits, 161for manual debugging of failing tests: 162 163 $ go test -run=Script -work 164 --- FAIL: TestScript (3.75s) 165 --- FAIL: TestScript/install_rebuild_gopath (0.16s) 166 script_test.go:223: 167 WORK=/tmp/cmd-go-test-745953508/script-install_rebuild_gopath 168 GOARCH= 169 GOCACHE=/Users/rsc/Library/Caches/go-build 170 GOOS= 171 GOPATH=$WORK/gopath 172 GOROOT=/Users/rsc/go 173 HOME=/no-home 174 TMPDIR=$WORK/tmp 175 exe= 176 177 # GOPATH with p1 in d2, p2 in d2 (0.000s) 178 # build & install p1 (0.085s) 179 # modify p2 - p1 should appear stale (0.030s) 180 # build & install p1 again (0.019s) 181 > go install -i p11 182 [stderr] 183 can't load package: package p11: cannot find package "p11" in any of: 184 /Users/rsc/go/src/p11 (from $GOROOT) 185 $WORK/d1/src/p11 (from $GOPATH) 186 $WORK/d2/src/p11 187 [exit status 1] 188 FAIL: unexpected go command failure 189 190 script_test.go:73: failed at testdata/script/install_rebuild_gopath.txt:15 in $WORK/gopath/src 191 192 FAIL 193 exit status 1 194 FAIL cmd/go 4.875s 195 $ 196 197 $ WORK=/tmp/cmd-go-test-745953508/script-install_rebuild_gopath 198 $ cd $WORK/d1/src/p1 199 $ cat p1.go 200 package p1 201 import "p2" 202 func F() { p2.F() } 203 $ 204 205The available commands are: 206cat files... 207 concatenate files and print to the script's stdout buffer 208 209 210cc args... 211 run the platform C compiler 212 213 214cd dir 215 change the working directory 216 217 218chmod perm paths... 219 change file mode bits 220 221 Changes the permissions of the named files or directories to 222 be equal to perm. 223 Only numerical permissions are supported. 224 225cmp [-q] file1 file2 226 compare files for differences 227 228 By convention, file1 is the actual data and file2 is the 229 expected data. 230 The command succeeds if the file contents are identical. 231 File1 can be 'stdout' or 'stderr' to compare the stdout or 232 stderr buffer from the most recent command. 233 234cmpenv [-q] file1 file2 235 compare files for differences, with environment expansion 236 237 By convention, file1 is the actual data and file2 is the 238 expected data. 239 The command succeeds if the file contents are identical 240 after substituting variables from the script environment. 241 File1 can be 'stdout' or 'stderr' to compare the script's 242 stdout or stderr buffer. 243 244cp src... dst 245 copy files to a target file or directory 246 247 src can include 'stdout' or 'stderr' to copy from the 248 script's stdout or stderr buffer. 249 250echo string... 251 display a line of text 252 253 254env [key[=value]...] 255 set or log the values of environment variables 256 257 With no arguments, print the script environment to the log. 258 Otherwise, add the listed key=value pairs to the environment 259 or print the listed keys. 260 261exec program [args...] [&] 262 run an executable program with arguments 263 264 Note that 'exec' does not terminate the script (unlike Unix 265 shells). 266 267exists [-readonly] [-exec] file... 268 check that files exist 269 270 271go [args...] [&] 272 run the 'go' program provided by the script host 273 274 275grep [-count=N] [-q] 'pattern' file 276 find lines in a file that match a pattern 277 278 The command succeeds if at least one match (or the exact 279 count, if given) is found. 280 The -q flag suppresses printing of matches. 281 282help [-v] name... 283 log help text for commands and conditions 284 285 To display help for a specific condition, enclose it in 286 brackets: 'help [amd64]'. 287 To display complete documentation when listing all commands, 288 pass the -v flag. 289 290mkdir path... 291 create directories, if they do not already exist 292 293 Unlike Unix mkdir, parent directories are always created if 294 needed. 295 296mv old new 297 rename a file or directory to a new path 298 299 OS-specific restrictions may apply when old and new are in 300 different directories. 301 302replace [old new]... file 303 replace strings in a file 304 305 The 'old' and 'new' arguments are unquoted as if in quoted 306 Go strings. 307 308rm path... 309 remove a file or directory 310 311 If the path is a directory, its contents are removed 312 recursively. 313 314skip [msg] 315 skip the current test 316 317 318sleep duration [&] 319 sleep for a specified duration 320 321 The duration must be given as a Go time.Duration string. 322 323stale target... 324 check that build targets are stale 325 326 327stderr [-count=N] [-q] 'pattern' file 328 find lines in the stderr buffer that match a pattern 329 330 The command succeeds if at least one match (or the exact 331 count, if given) is found. 332 The -q flag suppresses printing of matches. 333 334stdout [-count=N] [-q] 'pattern' file 335 find lines in the stdout buffer that match a pattern 336 337 The command succeeds if at least one match (or the exact 338 count, if given) is found. 339 The -q flag suppresses printing of matches. 340 341stop [msg] 342 stop execution of the script 343 344 The message is written to the script log, but no error is 345 reported from the script engine. 346 347symlink path -> target 348 create a symlink 349 350 Creates path as a symlink to target. 351 The '->' token (like in 'ls -l' output on Unix) is required. 352 353wait 354 wait for completion of background commands 355 356 Waits for all background commands to complete. 357 The output (and any error) from each command is printed to 358 the log in the order in which the commands were started. 359 After the call to 'wait', the script's stdout and stderr 360 buffers contain the concatenation of the background 361 commands' outputs. 362 363 364 365The available conditions are: 366[GOARCH:*] 367 runtime.GOARCH == <suffix> 368[GODEBUG:*] 369 GODEBUG contains <suffix> 370[GOEXPERIMENT:*] 371 GOEXPERIMENT <suffix> is enabled 372[GOOS:*] 373 runtime.GOOS == <suffix> 374[abscc] 375 default $CC path is absolute and exists 376[asan] 377 GOOS/GOARCH supports -asan 378[buildmode:*] 379 go supports -buildmode=<suffix> 380[case-sensitive] 381 $WORK filesystem is case-sensitive 382[cc:*] 383 go env CC = <suffix> (ignoring the go/env file) 384[cgo] 385 host CGO_ENABLED 386[cgolinkext] 387 platform requires external linking for cgo 388[compiler:*] 389 runtime.Compiler == <suffix> 390[cross] 391 cmd/go GOOS/GOARCH != GOHOSTOS/GOHOSTARCH 392[exec:*] 393 <suffix> names an executable in the test binary's PATH 394[fuzz] 395 GOOS/GOARCH supports -fuzz 396[fuzz-instrumented] 397 GOOS/GOARCH supports -fuzz with instrumentation 398[git] 399 the 'git' executable exists and provides the standard CLI 400[go-builder] 401 GO_BUILDER_NAME is non-empty 402[link] 403 testenv.HasLink() 404[msan] 405 GOOS/GOARCH supports -msan 406[mustlinkext] 407 platform always requires external linking 408[net:*] 409 can connect to external network host <suffix> 410[pielinkext] 411 platform requires external linking for PIE 412[race] 413 GOOS/GOARCH supports -race 414[root] 415 os.Geteuid() == 0 416[short] 417 testing.Short() 418[symlink] 419 testenv.HasSymlink() 420[trimpath] 421 test binary was built with -trimpath 422[verbose] 423 testing.Verbose() 424 425