| 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> |
| GOROOT_FINAL=<actual GOROOT_FINAL> |
| 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 |
| [cgo] |
| host CGO_ENABLED |
| [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 |
| [link] |
| testenv.HasLink() |
| [mismatched-goroot] |
| test's GOROOT_FINAL does not match the real GOROOT |
| [msan] |
| GOOS/GOARCH supports -msan |
| [net] |
| testenv.HasExternalNetwork() |
| [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() |
| |