1 This file is generated by 'go generate cmd/go'. DO NOT EDIT.
2
3 This directory holds test scripts *.txt run during 'go test cmd/go'.
4 To run a specific script foo.txt
5
6 go test cmd/go -run=Script/^foo$
7
8 In general script files should have short names: a few words, not whole sentences.
9 The first word should be the general category of behavior being tested,
10 often the name of a go subcommand (list, build, test, ...) or concept (vendor, pattern).
11
12 Each script is a text archive (go doc internal/txtar).
13 The script begins with an actual command script to run
14 followed by the content of zero or more supporting files to
15 create in the script's temporary file system before it starts executing.
16
17 As 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
28 Each script runs in a fresh temporary work directory tree, available to scripts as $WORK.
29 Scripts 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
46 On Plan 9, the variables $path and $home are set instead of $PATH and $HOME.
47 On Windows, the variables $USERPROFILE and $TMP are set instead of
48 $HOME and $TMPDIR.
49
50 The lines at the top of the script are a sequence of commands to be executed by
51 a small script engine configured in ../../script_test.go (not the system shell).
52
53 The scripts' supporting files are unpacked relative to $GOPATH/src
54 (aka $WORK/gopath/src) and then the script begins execution in that directory as
55 well. Thus the example above runs in $WORK/gopath/src with GOPATH=$WORK/gopath
56 and $WORK/gopath/src/hello.go containing the listed contents.
57
58 Each line of a script is parsed into a sequence of space-separated command
59 words, with environment variable expansion within each word and # marking
60 an end-of-line comment. Additional variables named ':' and '/' are expanded
61 within script arguments (expanding to the value of os.PathListSeparator and
62 os.PathSeparator respectively) but are not inherited in subprocess environments.
63
64 Adding single quotes around text keeps spaces in that text from being treated
65 as word separators and also disables environment variable expansion. Inside a
66 single-quoted block of text, a repeated single quote indicates a literal single
67 quote, as in:
68
69 'Don''t communicate by sharing memory.'
70
71 A line beginning with # is a comment and conventionally explains what is being
72 done or tested at the start of a new section of the script.
73
74 Commands are executed one at a time, and errors are checked for each command;
75 if any command fails unexpectedly, no subsequent commands in the script are
76 executed. The command prefix ! indicates that the command on the rest of the
77 line (typically go or a matching predicate) must fail instead of succeeding.
78 The command prefix ? indicates that the command may or may not succeed, but the
79 script should continue regardless.
80
81 The command prefix [cond] indicates that the command on the rest of the line
82 should only run when the condition is satisfied.
83
84 A condition can be negated: [!root] means to run the rest of the line only if
85 the user is not root. Multiple conditions may be given for a single command,
86 for example, '[linux] [amd64] skip'. The command will run if all conditions are
87 satisfied.
88
89 When TestScript runs a script and the script fails, by default TestScript shows
90 the execution of the most recent phase of the script (since the last # comment)
91 and only shows the # comments for earlier phases. For example, here is a
92 multi-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
124 The 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
150 Note that the commands in earlier phases have been hidden, so that the relevant
151 commands are more easily found, and the elapsed time for a completed phase
152 is shown next to the phase heading. To see the entire execution, use "go test -v",
153 which also adds an initial environment dump to the beginning of the log.
154
155 Note also that in reported output, the actual name of the per-script temporary directory
156 has been consistently replaced with the literal string $WORK.
157
158 The cmd/go test flag -testwork (which must appear on the "go test" command line after
159 standard test flags) causes each test to log the name of its $WORK directory and other
160 environment variable settings and also to leave that directory behind when it exits,
161 for 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
205 The available commands are:
206 cat files...
207 concatenate files and print to the script's stdout buffer
208
209
210 cc args...
211 run the platform C compiler
212
213
214 cd dir
215 change the working directory
216
217
218 chmod 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
225 cmp [-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
234 cmpenv [-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
244 cp 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
250 echo string...
251 display a line of text
252
253
254 env [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
261 exec program [args...] [&]
262 run an executable program with arguments
263
264 Note that 'exec' does not terminate the script (unlike Unix
265 shells).
266
267 exists [-readonly] [-exec] file...
268 check that files exist
269
270
271 go [args...] [&]
272 run the 'go' program provided by the script host
273
274
275 grep [-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
282 help [-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
290 mkdir path...
291 create directories, if they do not already exist
292
293 Unlike Unix mkdir, parent directories are always created if
294 needed.
295
296 mv 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
302 replace [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
308 rm path...
309 remove a file or directory
310
311 If the path is a directory, its contents are removed
312 recursively.
313
314 skip [msg]
315 skip the current test
316
317
318 sleep duration [&]
319 sleep for a specified duration
320
321 The duration must be given as a Go time.Duration string.
322
323 stale target...
324 check that build targets are stale
325
326
327 stderr [-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
334 stdout [-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
341 stop [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
347 symlink 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
353 wait
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
365 The 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
View as plain text