1 This directory holds test scripts *.txt run during 'go test cmd/go'.
2 To run a specific script foo.txt
3
4 go test cmd/go -run=Script/^foo$
5
6 In general script files should have short names: a few words, not whole sentences.
7 The first word should be the general category of behavior being tested,
8 often the name of a go subcommand (list, build, test, ...) or concept (vendor, pattern).
9
10 Each script is a text archive (go doc cmd/go/internal/txtar).
11 The script begins with an actual command script to run
12 followed by the content of zero or more supporting files to
13 create in the script's temporary file system before it starts executing.
14
15 As an example, run_hello.txt says:
16
17 # hello world
18 go run hello.go
19 stderr 'hello world'
20 ! stdout .
21
22 -- hello.go --
23 package main
24 func main() { println("hello world") }
25
26 Each script runs in a fresh temporary work directory tree, available to scripts as $WORK.
27 Scripts also have access to these other environment variables:
28
29 GOARCH=<target GOARCH>
30 GOCACHE=<actual GOCACHE being used outside the test>
31 GOEXE=<executable file suffix: .exe on Windows, empty on other systems>
32 GOOS=<target GOOS>
33 GOPATH=$WORK/gopath
34 GOPROXY=<local module proxy serving from cmd/go/testdata/mod>
35 GOROOT=<actual GOROOT>
36 GOROOT_FINAL=<actual GOROOT_FINAL>
37 TESTGO_GOROOT=<GOROOT used to build cmd/go, for use in tests that may change GOROOT>
38 HOME=/no-home
39 PATH=<actual PATH>
40 TMPDIR=$WORK/tmp
41 GODEBUG=<actual GODEBUG>
42 devnull=<value of os.DevNull>
43 goversion=<current Go version; for example, 1.12>
44 :=<OS-specific path list separator>
45
46 The scripts' supporting files are unpacked relative to $GOPATH/src (aka $WORK/gopath/src)
47 and then the script begins execution in that directory as well. Thus the example above runs
48 in $WORK/gopath/src with GOPATH=$WORK/gopath and $WORK/gopath/src/hello.go
49 containing the listed contents.
50
51 The lines at the top of the script are a sequence of commands to be executed
52 by a tiny script engine in ../../script_test.go (not the system shell).
53 The script stops and the overall test fails if any particular command fails.
54
55 Each line is parsed into a sequence of space-separated command words,
56 with environment variable expansion and # marking an end-of-line comment.
57 Adding single quotes around text keeps spaces in that text from being treated
58 as word separators and also disables environment variable expansion.
59 Inside a single-quoted block of text, a repeated single quote indicates
60 a literal single quote, as in:
61
62 'Don''t communicate by sharing memory.'
63
64 A line beginning with # is a comment and conventionally explains what is
65 being done or tested at the start of a new phase in the script.
66
67 The command prefix ! indicates that the command on the rest of the line
68 (typically go or a matching predicate) must fail, not succeed. Only certain
69 commands support this prefix. They are indicated below by [!] in the synopsis.
70
71 The command prefix ? indicates that the command on the rest of the line
72 may or may not succeed, but the test should continue regardless.
73 Commands that support this prefix are indicated by [?].
74
75 The command prefix [cond] indicates that the command on the rest of the line
76 should only run when the condition is satisfied. The available conditions are:
77
78 - GOOS and GOARCH values, like [386], [windows], and so on.
79 - Compiler names, like [gccgo], [gc].
80 - Test environment details:
81 - [short] for testing.Short()
82 - [cgo], [msan], [asan], [race] for whether cgo, msan, asan, and the race detector can be used
83 - [fuzz] for whether 'go test -fuzz' can be used at all
84 - [fuzz-instrumented] for whether 'go test -fuzz' uses coverage-instrumented binaries
85 - [net] for whether the external network can be used
86 - [link] for testenv.HasLink()
87 - [root] for os.Geteuid() == 0
88 - [symlink] for testenv.HasSymlink()
89 - [case-sensitive] for whether the file system is case-sensitive
90 - [exec:prog] for whether prog is available for execution (found by exec.LookPath)
91 - [GODEBUG:value] for whether value is one of the comma-separated entries in the GODEBUG variable
92 - [buildmode:value] for whether -buildmode=value is supported
93
94 A condition can be negated: [!short] means to run the rest of the line
95 when testing.Short() is false. Multiple conditions may be given for a single
96 command, for example, '[linux] [amd64] skip'. The command will run if all conditions
97 are satisfied.
98
99 The commands are:
100
101 - [! | ?] cc args... [&]
102 Run the C compiler, the platform specific flags (i.e. `go env GOGCCFLAGS`) will be
103 added automatically before args.
104
105 - cd dir
106 Change to the given directory for future commands.
107 The directory must use slashes as path separator.
108
109 - chmod perm path...
110 Change the permissions of the files or directories named by the path arguments
111 to be equal to perm. Only numerical permissions are supported.
112
113 - [! | ?] cmp file1 file2
114 Check that the named files have (or do not have) the same content.
115 By convention, file1 is the actual data and file2 the expected data.
116 File1 can be "stdout" or "stderr" to use the standard output or standard error
117 from the most recent exec or go command.
118 (If the file contents differ and the command is not negated,
119 the failure prints a diff.)
120
121 - [! | ?] cmpenv file1 file2
122 Like cmp, but environment variables are substituted in the file contents
123 before the comparison. For example, $GOOS is replaced by the target GOOS.
124
125 - [! | ?] cp src... dst
126 Copy the listed files to the target file or existing directory.
127 src can include "stdout" or "stderr" to use the standard output or standard error
128 from the most recent exec or go command.
129
130 - env [-r] [key=value...]
131 With no arguments, print the environment to stdout
132 (useful for debugging and for verifying initial state).
133 Otherwise add the listed key=value pairs to the environment.
134 The -r flag causes the values to be escaped using regexp.QuoteMeta
135 before being recorded.
136
137 - [! | ?] exec program [args...] [&]
138 Run the given executable program with the arguments.
139 It must (or must not) succeed.
140 Note that 'exec' does not terminate the script (unlike in Unix shells).
141
142 If the last token is '&', the program executes in the background. The standard
143 output and standard error of the previous command is cleared, but the output
144 of the background process is buffered — and checking of its exit status is
145 delayed — until the next call to 'wait', 'skip', or 'stop' or the end of the
146 test. If any background processes remain at the end of the test, they
147 are terminated using os.Interrupt (if supported) or os.Kill and the test
148 must not depend upon their exit status.
149
150 - [!] exists [-readonly] [-exec] file...
151 Each of the listed files or directories must (or must not) exist.
152 If -readonly is given, the files or directories must be unwritable.
153 If -exec is given, the files or directories must be executable.
154
155 - [! | ?] go args... [&]
156 Run the (test copy of the) go command with the given arguments.
157 It must (or must not) succeed.
158
159 - [!] grep [-count=N] [-q] pattern file
160 The file's content must (or must not) match the regular expression pattern.
161 For positive matches, -count=N specifies an exact number of matches to require.
162 The -q flag disables printing the file content on a mismatch.
163
164 - mkdir path...
165 Create the listed directories, if they do not already exists.
166
167 - mv path1 path2
168 Rename path1 to path2. OS-specific restrictions may apply when path1 and path2
169 are in different directories.
170
171 - rm file...
172 Remove the listed files or directories.
173
174 - skip [message]
175 Mark the test skipped, including the message if given.
176
177 - [!] stale path...
178 The packages named by the path arguments must (or must not)
179 be reported as "stale" by the go command.
180
181 - [!] stderr [-count=N] pattern
182 Apply the grep command (see above) to the standard error
183 from the most recent exec, go, or wait command.
184
185 - [!] stdout [-count=N] pattern
186 Apply the grep command (see above) to the standard output
187 from the most recent exec, go, wait, or env command.
188
189 - stop [message]
190 Stop the test early (marking it as passing), including the message if given.
191
192 - symlink file -> target
193 Create file as a symlink to target. The -> (like in ls -l output) is required.
194
195 - wait
196 Wait for all 'exec' and 'go' commands started in the background (with the '&'
197 token) to exit, and display success or failure status for them.
198 After a call to wait, the 'stderr' and 'stdout' commands will apply to the
199 concatenation of the corresponding streams of the background commands,
200 in the order in which those commands were started.
201
202 When TestScript runs a script and the script fails, by default TestScript shows
203 the execution of the most recent phase of the script (since the last # comment)
204 and only shows the # comments for earlier phases. For example, here is a
205 multi-phase script with a bug in it:
206
207 # GOPATH with p1 in d2, p2 in d2
208 env GOPATH=$WORK/d1${:}$WORK/d2
209
210 # build & install p1
211 env
212 go install -i p1
213 ! stale p1
214 ! stale p2
215
216 # modify p2 - p1 should appear stale
217 cp $WORK/p2x.go $WORK/d2/src/p2/p2.go
218 stale p1 p2
219
220 # build & install p1 again
221 go install -i p11
222 ! stale p1
223 ! stale p2
224
225 -- $WORK/d1/src/p1/p1.go --
226 package p1
227 import "p2"
228 func F() { p2.F() }
229 -- $WORK/d2/src/p2/p2.go --
230 package p2
231 func F() {}
232 -- $WORK/p2x.go --
233 package p2
234 func F() {}
235 func G() {}
236
237 The bug is that the final phase installs p11 instead of p1. The test failure looks like:
238
239 $ go test -run=Script
240 --- FAIL: TestScript (3.75s)
241 --- FAIL: TestScript/install_rebuild_gopath (0.16s)
242 script_test.go:223:
243 # GOPATH with p1 in d2, p2 in d2 (0.000s)
244 # build & install p1 (0.087s)
245 # modify p2 - p1 should appear stale (0.029s)
246 # build & install p1 again (0.022s)
247 > go install -i p11
248 [stderr]
249 can't load package: package p11: cannot find package "p11" in any of:
250 /Users/rsc/go/src/p11 (from $GOROOT)
251 $WORK/d1/src/p11 (from $GOPATH)
252 $WORK/d2/src/p11
253 [exit status 1]
254 FAIL: unexpected go command failure
255
256 script_test.go:73: failed at testdata/script/install_rebuild_gopath.txt:15 in $WORK/gopath/src
257
258 FAIL
259 exit status 1
260 FAIL cmd/go 4.875s
261 $
262
263 Note that the commands in earlier phases have been hidden, so that the relevant
264 commands are more easily found, and the elapsed time for a completed phase
265 is shown next to the phase heading. To see the entire execution, use "go test -v",
266 which also adds an initial environment dump to the beginning of the log.
267
268 Note also that in reported output, the actual name of the per-script temporary directory
269 has been consistently replaced with the literal string $WORK.
270
271 The cmd/go test flag -testwork (which must appear on the "go test" command line after
272 standard test flags) causes each test to log the name of its $WORK directory and other
273 environment variable settings and also to leave that directory behind when it exits,
274 for manual debugging of failing tests:
275
276 $ go test -run=Script -work
277 --- FAIL: TestScript (3.75s)
278 --- FAIL: TestScript/install_rebuild_gopath (0.16s)
279 script_test.go:223:
280 WORK=/tmp/cmd-go-test-745953508/script-install_rebuild_gopath
281 GOARCH=
282 GOCACHE=/Users/rsc/Library/Caches/go-build
283 GOOS=
284 GOPATH=$WORK/gopath
285 GOROOT=/Users/rsc/go
286 HOME=/no-home
287 TMPDIR=$WORK/tmp
288 exe=
289
290 # GOPATH with p1 in d2, p2 in d2 (0.000s)
291 # build & install p1 (0.085s)
292 # modify p2 - p1 should appear stale (0.030s)
293 # build & install p1 again (0.019s)
294 > go install -i p11
295 [stderr]
296 can't load package: package p11: cannot find package "p11" in any of:
297 /Users/rsc/go/src/p11 (from $GOROOT)
298 $WORK/d1/src/p11 (from $GOPATH)
299 $WORK/d2/src/p11
300 [exit status 1]
301 FAIL: unexpected go command failure
302
303 script_test.go:73: failed at testdata/script/install_rebuild_gopath.txt:15 in $WORK/gopath/src
304
305 FAIL
306 exit status 1
307 FAIL cmd/go 4.875s
308 $
309
310 $ WORK=/tmp/cmd-go-test-745953508/script-install_rebuild_gopath
311 $ cd $WORK/d1/src/p1
312 $ cat p1.go
313 package p1
314 import "p2"
315 func F() { p2.F() }
316 $
317
318
View as plain text