github.com/rogpeppe/go-internal@v1.12.1-0.20240509064211-c8567cf8e95f/cmd/testscript/README.md (about)

     1  ```
     2  The testscript command runs github.com/rogpeppe/go-internal/testscript scripts
     3  in a fresh temporary work directory tree.
     4  
     5  Usage:
     6      testscript [-v] [-e VAR[=value]]... [-u] [-work] files...
     7  
     8  The testscript command is designed to make it easy to create self-contained
     9  reproductions of command sequences.
    10  
    11  Each file is opened as a script and run as described in the documentation for
    12  github.com/rogpeppe/go-internal/testscript. The special filename "-" is
    13  interpreted as the standard input.
    14  
    15  As a special case, supporting files/directories in the .gomodproxy subdirectory
    16  will be served via a github.com/rogpeppe/go-internal/goproxytest server which
    17  is available to each script via the GOPROXY environment variable. The contents
    18  of the .gomodproxy subdirectory are not available to the script except via the
    19  proxy server. See the documentation for
    20  github.com/rogpeppe/go-internal/goproxytest for details on the format of these
    21  files/directories.
    22  
    23  Environment variables can be passed through to each script with the -e flag,
    24  where VAR is the name of the variable. Variables override testscript-defined
    25  values, with the exception of WORK which cannot be overridden. The -e flag can
    26  appear multiple times to specify multiple variables.
    27  
    28  The -u flag specifies that if a cmp command within a testscript fails and its
    29  second argument refers to a file inside the testscript file, the command will
    30  succeed and the testscript file will be updated to reflect the actual content.
    31  As such, this is the cmd/testcript equivalent of
    32  testscript.Params.UpdateScripts.
    33  
    34  The -work flag prints the temporary work directory path before running each
    35  script, and does not remove that directory when testscript exits.
    36  
    37  Examples
    38  ========
    39  
    40  The following example, fruit.txtar, shows a simple reproduction that includes
    41  .gomodproxy supporting files:
    42  
    43      go get -m fruit.com
    44      go list fruit.com/...
    45      stdout 'fruit.com/fruit'
    46  
    47      -- go.mod --
    48      module mod
    49  
    50      -- .gomodproxy/fruit.com_v1.0.0/.mod --
    51      module fruit.com
    52  
    53      -- .gomodproxy/fruit.com_v1.0.0/.info --
    54      {"Version":"v1.0.0","Time":"2018-10-22T18:45:39Z"}
    55  
    56      -- .gomodproxy/fruit.com_v1.0.0/fruit/fruit.go --
    57      package fruit
    58  
    59      const Name = "Apple"
    60  
    61  Running testscript -v fruit.txtar we get:
    62  
    63      ...
    64      > go get -m fruit.com
    65      [stderr]
    66      go: finding fruit.com v1.0.0
    67  
    68      > go list fruit.com/...
    69      [stdout]
    70      fruit.com/fruit
    71  
    72      [stderr]
    73      go: downloading fruit.com v1.0.0
    74  
    75      > stdout 'fruit.com/fruit'
    76      PASS
    77  
    78  
    79  The following example, goimports.txtar, shows a simple reproduction involving
    80  goimports:
    81  
    82      go install golang.org/x/tools/cmd/goimports
    83  
    84      # check goimports help information
    85      exec goimports -d main.go
    86      stdout 'import "math"'
    87  
    88      -- go.mod --
    89      module mod
    90  
    91      require golang.org/x/tools v0.0.0-20181221235234-d00ac6d27372
    92  
    93      -- main.go --
    94      package mod
    95  
    96      const Pi = math.Pi
    97  
    98  Running testscript -v goimports.txtar we get:
    99  
   100      ...
   101      > go install golang.org/x/tools/cmd/goimports
   102      [stderr]
   103      go: finding golang.org/x/tools v0.0.0-20181221235234-d00ac6d27372
   104      go: downloading golang.org/x/tools v0.0.0-20181221235234-d00ac6d27372
   105  
   106      # check goimports help information (0.015s)
   107      > exec goimports -d main.go
   108      [stdout]
   109      diff -u main.go.orig main.go
   110      --- main.go.orig        2019-01-08 16:03:35.861907738 +0000
   111      +++ main.go     2019-01-08 16:03:35.861907738 +0000
   112      @@ -1,3 +1,5 @@
   113       package mod
   114  
   115      +import "math"
   116      +
   117       const Pi = math.Pi
   118      > stdout 'import "math"'
   119      PASS
   120  ```