| This file is generated by 'go generate cmd/go'. DO NOT EDIT. | |
| This directory holds test scripts *.txt run during 'go test cmd/go'. | |
| To run a specific script foo.txt | |
| go test cmd/go -run=Script/^foo$ | |
| In general script files should have short names: a few words, not whole sentences. | |
| The first word should be the general category of behavior being tested, | |
| often the name of a go subcommand (list, build, test, ...) or concept (vendor, pattern). | |
| Each script is a text archive (go doc internal/txtar). | |
| The script begins with an actual command script to run | |
| followed by the content of zero or more supporting files to | |
| create in the script's temporary file system before it starts executing. | |
| As an example, run_hello.txt says: | |
| # hello world | |
| go run hello.go | |
| stderr 'hello world' | |
| ! stdout . | |
| -- hello.go -- | |
| package main | |
| func main() { println("hello world") } | |
| Each script runs in a fresh temporary work directory tree, available to scripts as $WORK. | |
| Scripts also have access to other environment variables, including: | |
| GOARCH=<target GOARCH> | |
| GOCACHE=<actual GOCACHE being used outside the test> | |
| GOEXE=<executable file suffix: .exe on Windows, empty on other systems> | |
| GOOS=<target GOOS> | |
| GOPATH=$WORK/gopath | |
| GOPROXY=<local module proxy serving from cmd/go/testdata/mod> | |
| GOROOT=<actual GOROOT> | |
| TESTGO_GOROOT=<GOROOT used to build cmd/go, for use in tests that may change GOROOT> | |
| HOME=/no-home | |
| PATH=<actual PATH> | |
| TMPDIR=$WORK/tmp | |
| GODEBUG=<actual GODEBUG> | |
| devnull=<value of os.DevNull> | |
| goversion=<current Go version; for example, 1.12> | |
| On Plan 9, the variables $path and $home are set instead of $PATH and $HOME. | |
| On Windows, the variables $USERPROFILE and $TMP are set instead of | |
| $HOME and $TMPDIR. | |
| The lines at the top of the script are a sequence of commands to be executed by | |
| a small script engine configured in ../../script_test.go (not the system shell). | |
| The scripts' supporting files are unpacked relative to $GOPATH/src | |
| (aka $WORK/gopath/src) and then the script begins execution in that directory as | |
| well. Thus the example above runs in $WORK/gopath/src with GOPATH=$WORK/gopath | |
| and $WORK/gopath/src/hello.go containing the listed contents. | |
| Each line of a script is parsed into a sequence of space-separated command | |
| words, with environment variable expansion within each word and # marking | |
| an end-of-line comment. Additional variables named ':' and '/' are expanded | |
| within script arguments (expanding to the value of os.PathListSeparator and | |
| os.PathSeparator respectively) but are not inherited in subprocess environments. | |
| Adding single quotes around text keeps spaces in that text from being treated | |
| as word separators and also disables environment variable expansion. Inside a | |
| single-quoted block of text, a repeated single quote indicates a literal single | |
| quote, as in: | |
| 'Don''t communicate by sharing memory.' | |
| A line beginning with # is a comment and conventionally explains what is being | |
| done or tested at the start of a new section of the script. | |
| Commands are executed one at a time, and errors are checked for each command; | |
| if any command fails unexpectedly, no subsequent commands in the script are | |
| executed. The command prefix ! indicates that the command on the rest of the | |
| line (typically go or a matching predicate) must fail instead of succeeding. | |
| The command prefix ? indicates that the command may or may not succeed, but the | |
| script should continue regardless. | |
| The command prefix [cond] indicates that the command on the rest of the line | |
| should only run when the condition is satisfied. | |
| A condition can be negated: [!root] means to run the rest of the line only if | |
| the user is not root. Multiple conditions may be given for a single command, | |
| for example, '[linux] [amd64] skip'. The command will run if all conditions are | |
| satisfied. | |
| When TestScript runs a script and the script fails, by default TestScript shows | |
| the execution of the most recent phase of the script (since the last # comment) | |
| and only shows the # comments for earlier phases. For example, here is a | |
| multi-phase script with a bug in it: | |
| # GOPATH with p1 in d2, p2 in d2 | |
| env GOPATH=$WORK${/}d1${:}$WORK${/}d2 | |
| # build & install p1 | |
| env | |
| go install -i p1 | |
| ! stale p1 | |
| ! stale p2 | |
| # modify p2 - p1 should appear stale | |
| cp $WORK/p2x.go $WORK/d2/src/p2/p2.go | |
| stale p1 p2 | |
| # build & install p1 again | |
| go install -i p11 | |
| ! stale p1 | |
| ! stale p2 | |
| -- $WORK/d1/src/p1/p1.go -- | |
| package p1 | |
| import "p2" | |
| func F() { p2.F() } | |
| -- $WORK/d2/src/p2/p2.go -- | |
| package p2 | |
| func F() {} | |
| -- $WORK/p2x.go -- | |
| package p2 | |
| func F() {} | |
| func G() {} | |
| The bug is that the final phase installs p11 instead of p1. The test failure looks like: | |
| $ go test -run=Script | |
| --- FAIL: TestScript (3.75s) | |
| --- FAIL: TestScript/install_rebuild_gopath (0.16s) | |
| script_test.go:223: | |
| # GOPATH with p1 in d2, p2 in d2 (0.000s) | |
| # build & install p1 (0.087s) | |
| # modify p2 - p1 should appear stale (0.029s) | |
| # build & install p1 again (0.022s) | |
| > go install -i p11 | |
| [stderr] | |
| can't load package: package p11: cannot find package "p11" in any of: | |
| /Users/rsc/go/src/p11 (from $GOROOT) | |
| $WORK/d1/src/p11 (from $GOPATH) | |
| $WORK/d2/src/p11 | |
| [exit status 1] | |
| FAIL: unexpected go command failure | |
| script_test.go:73: failed at testdata/script/install_rebuild_gopath.txt:15 in $WORK/gopath/src | |
| FAIL | |
| exit status 1 | |
| FAIL cmd/go 4.875s | |
| $ | |
| Note that the commands in earlier phases have been hidden, so that the relevant | |
| commands are more easily found, and the elapsed time for a completed phase | |
| is shown next to the phase heading. To see the entire execution, use "go test -v", | |
| which also adds an initial environment dump to the beginning of the log. | |
| Note also that in reported output, the actual name of the per-script temporary directory | |
| has been consistently replaced with the literal string $WORK. | |
| The cmd/go test flag -testwork (which must appear on the "go test" command line after | |
| standard test flags) causes each test to log the name of its $WORK directory and other | |
| environment variable settings and also to leave that directory behind when it exits, | |
| for manual debugging of failing tests: | |
| $ go test -run=Script -work | |
| --- FAIL: TestScript (3.75s) | |
| --- FAIL: TestScript/install_rebuild_gopath (0.16s) | |
| script_test.go:223: | |
| WORK=/tmp/cmd-go-test-745953508/script-install_rebuild_gopath | |
| GOARCH= | |
| GOCACHE=/Users/rsc/Library/Caches/go-build | |
| GOOS= | |
| GOPATH=$WORK/gopath | |
| GOROOT=/Users/rsc/go | |
| HOME=/no-home | |
| TMPDIR=$WORK/tmp | |
| exe= | |
| # GOPATH with p1 in d2, p2 in d2 (0.000s) | |
| # build & install p1 (0.085s) | |
| # modify p2 - p1 should appear stale (0.030s) | |
| # build & install p1 again (0.019s) | |
| > go install -i p11 | |
| [stderr] | |
| can't load package: package p11: cannot find package "p11" in any of: | |
| /Users/rsc/go/src/p11 (from $GOROOT) | |
| $WORK/d1/src/p11 (from $GOPATH) | |
| $WORK/d2/src/p11 | |
| [exit status 1] | |
| FAIL: unexpected go command failure | |
| script_test.go:73: failed at testdata/script/install_rebuild_gopath.txt:15 in $WORK/gopath/src | |
| FAIL | |
| exit status 1 | |
| FAIL cmd/go 4.875s | |
| $ | |
| $ WORK=/tmp/cmd-go-test-745953508/script-install_rebuild_gopath | |
| $ cd $WORK/d1/src/p1 | |
| $ cat p1.go | |
| package p1 | |
| import "p2" | |
| func F() { p2.F() } | |
| $ | |
| The available commands are: | |
| cat files... | |
| concatenate files and print to the script's stdout buffer | |
| cc args... | |
| run the platform C compiler | |
| cd dir | |
| change the working directory | |
| chmod perm paths... | |
| change file mode bits | |
| Changes the permissions of the named files or directories to | |
| be equal to perm. | |
| Only numerical permissions are supported. | |
| cmp [-q] file1 file2 | |
| compare files for differences | |
| By convention, file1 is the actual data and file2 is the | |
| expected data. | |
| The command succeeds if the file contents are identical. | |
| File1 can be 'stdout' or 'stderr' to compare the stdout or | |
| stderr buffer from the most recent command. | |
| cmpenv [-q] file1 file2 | |
| compare files for differences, with environment expansion | |
| By convention, file1 is the actual data and file2 is the | |
| expected data. | |
| The command succeeds if the file contents are identical | |
| after substituting variables from the script environment. | |
| File1 can be 'stdout' or 'stderr' to compare the script's | |
| stdout or stderr buffer. | |
| cp src... dst | |
| copy files to a target file or directory | |
| src can include 'stdout' or 'stderr' to copy from the | |
| script's stdout or stderr buffer. | |
| echo string... | |
| display a line of text | |
| env [key[=value]...] | |
| set or log the values of environment variables | |
| With no arguments, print the script environment to the log. | |
| Otherwise, add the listed key=value pairs to the environment | |
| or print the listed keys. | |
| exec program [args...] [&] | |
| run an executable program with arguments | |
| Note that 'exec' does not terminate the script (unlike Unix | |
| shells). | |
| exists [-readonly] [-exec] file... | |
| check that files exist | |
| go [args...] [&] | |
| run the 'go' program provided by the script host | |
| grep [-count=N] [-q] 'pattern' file | |
| find lines in a file that match a pattern | |
| The command succeeds if at least one match (or the exact | |
| count, if given) is found. | |
| The -q flag suppresses printing of matches. | |
| help [-v] name... | |
| log help text for commands and conditions | |
| To display help for a specific condition, enclose it in | |
| brackets: 'help [amd64]'. | |
| To display complete documentation when listing all commands, | |
| pass the -v flag. | |
| mkdir path... | |
| create directories, if they do not already exist | |
| Unlike Unix mkdir, parent directories are always created if | |
| needed. | |
| mv old new | |
| rename a file or directory to a new path | |
| OS-specific restrictions may apply when old and new are in | |
| different directories. | |
| replace [old new]... file | |
| replace strings in a file | |
| The 'old' and 'new' arguments are unquoted as if in quoted | |
| Go strings. | |
| rm path... | |
| remove a file or directory | |
| If the path is a directory, its contents are removed | |
| recursively. | |
| skip [msg] | |
| skip the current test | |
| sleep duration [&] | |
| sleep for a specified duration | |
| The duration must be given as a Go time.Duration string. | |
| stale target... | |
| check that build targets are stale | |
| stderr [-count=N] [-q] 'pattern' file | |
| find lines in the stderr buffer that match a pattern | |
| The command succeeds if at least one match (or the exact | |
| count, if given) is found. | |
| The -q flag suppresses printing of matches. | |
| stdout [-count=N] [-q] 'pattern' file | |
| find lines in the stdout buffer that match a pattern | |
| The command succeeds if at least one match (or the exact | |
| count, if given) is found. | |
| The -q flag suppresses printing of matches. | |
| stop [msg] | |
| stop execution of the script | |
| The message is written to the script log, but no error is | |
| reported from the script engine. | |
| symlink path -> target | |
| create a symlink | |
| Creates path as a symlink to target. | |
| The '->' token (like in 'ls -l' output on Unix) is required. | |
| wait | |
| wait for completion of background commands | |
| Waits for all background commands to complete. | |
| The output (and any error) from each command is printed to | |
| the log in the order in which the commands were started. | |
| After the call to 'wait', the script's stdout and stderr | |
| buffers contain the concatenation of the background | |
| commands' outputs. | |
| The available conditions are: | |
| [GOARCH:*] | |
| runtime.GOARCH == <suffix> | |
| [GODEBUG:*] | |
| GODEBUG contains <suffix> | |
| [GOEXPERIMENT:*] | |
| GOEXPERIMENT <suffix> is enabled | |
| [GOOS:*] | |
| runtime.GOOS == <suffix> | |
| [abscc] | |
| default $CC path is absolute and exists | |
| [asan] | |
| GOOS/GOARCH supports -asan | |
| [buildmode:*] | |
| go supports -buildmode=<suffix> | |
| [case-sensitive] | |
| $WORK filesystem is case-sensitive | |
| [cc:*] | |
| go env CC = <suffix> (ignoring the go/env file) | |
| [cgo] | |
| host CGO_ENABLED | |
| [cgolinkext] | |
| platform requires external linking for cgo | |
| [compiler:*] | |
| runtime.Compiler == <suffix> | |
| [cross] | |
| cmd/go GOOS/GOARCH != GOHOSTOS/GOHOSTARCH | |
| [exec:*] | |
| <suffix> names an executable in the test binary's PATH | |
| [fuzz] | |
| GOOS/GOARCH supports -fuzz | |
| [fuzz-instrumented] | |
| GOOS/GOARCH supports -fuzz with instrumentation | |
| [git] | |
| the 'git' executable exists and provides the standard CLI | |
| [go-builder] | |
| GO_BUILDER_NAME is non-empty | |
| [link] | |
| testenv.HasLink() | |
| [msan] | |
| GOOS/GOARCH supports -msan | |
| [mustlinkext] | |
| platform always requires external linking | |
| [net:*] | |
| can connect to external network host <suffix> | |
| [pielinkext] | |
| platform requires external linking for PIE | |
| [race] | |
| GOOS/GOARCH supports -race | |
| [root] | |
| os.Geteuid() == 0 | |
| [short] | |
| testing.Short() | |
| [symlink] | |
| testenv.HasSymlink() | |
| [trimpath] | |
| test binary was built with -trimpath | |
| [verbose] | |
| testing.Verbose() | |