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