func IgnoreMissedCoverage()
Deprecated: this option is no longer used.
func Run(t *testing.T, p Params)
RunDir runs the tests in the given directory. All files in dir with a ".txt" or ".txtar" extension are considered to be test files.
func RunMain(m TestingM, commands map[string]func() int) (exitCode int)
RunMain should be called within a TestMain function to allow subcommands to be run in the testscript context.
The commands map holds the set of command names, each with an associated run function which should return the code to pass to os.Exit. It's OK for a command function to exit itself, but this may result in loss of coverage information.
When Run is called, these commands are installed as regular commands in the shell path, so can be invoked with "exec" or via any other command (for example a shell script).
For backwards compatibility, the commands declared in the map can be run without "exec" - that is, "foo" will behave like "exec foo". This can be disabled with Params.RequireExplicitExec to keep consistency across test scripts, and to keep separate process executions explicit.
This function returns an exit code to pass to os.Exit, after calling m.Run.
func RunT(t T, p Params)
RunT is like Run but uses an interface type instead of the concrete *testing.T type to make it possible to use testscript functionality outside of go test.
Env holds the environment to use at the start of a test script invocation.
type Env struct {
// WorkDir holds the path to the root directory of the
// extracted files.
WorkDir string
// Vars holds the initial set environment variables that will be passed to the
// testscript commands.
Vars []string
// Cd holds the initial current working directory.
Cd string
// Values holds a map of arbitrary values for use by custom
// testscript commands. This enables Setup to pass arbitrary
// values (not just strings) through to custom commands.
Values map[interface{}]interface{}
// contains filtered or unexported fields
}
func (e *Env) Defer(f func())
Defer arranges for f to be called at the end of the test. If Defer is called multiple times, the defers are executed in reverse order (similar to Go's defer statement)
func (e *Env) Getenv(key string) string
Getenv retrieves the value of the environment variable named by the key. It returns the value, which will be empty if the variable is not present.
func (e *Env) Setenv(key, value string)
Setenv sets the value of the environment variable named by the key. It panics if key is invalid.
func (e *Env) T() T
T returns the t argument passed to the current test by the T.Run method. Note that if the tests were started by calling Run, the returned value will implement testing.TB. Note that, despite that, the underlying value will not be of type *testing.T because *testing.T does not implement T.
If Cleanup is called on the returned value, the function will run after any functions passed to Env.Defer.
Params holds parameters for a call to Run.
type Params struct {
// Dir holds the name of the directory holding the scripts.
// All files in the directory with a .txtar or .txt suffix will be
// considered as test scripts. By default the current directory is used.
// Dir is interpreted relative to the current test directory.
Dir string
// Setup is called, if not nil, to complete any setup required
// for a test. The WorkDir and Vars fields will have already
// been initialized and all the files extracted into WorkDir,
// and Cd will be the same as WorkDir.
// The Setup function may modify Vars and Cd as it wishes.
Setup func(*Env) error
// Condition is called, if not nil, to determine whether a particular
// condition is true. It's called only for conditions not in the
// standard set, and may be nil.
Condition func(cond string) (bool, error)
// Cmds holds a map of commands available to the script.
// It will only be consulted for commands not part of the standard set.
Cmds map[string]func(ts *TestScript, neg bool, args []string)
// TestWork specifies that working directories should be
// left intact for later inspection.
TestWork bool
// WorkdirRoot specifies the directory within which scripts' work
// directories will be created. Setting WorkdirRoot implies TestWork=true.
// If empty, the work directories will be created inside
// $GOTMPDIR/go-test-script*, where $GOTMPDIR defaults to os.TempDir().
WorkdirRoot string
// Deprecated: this option is no longer used.
IgnoreMissedCoverage bool
// UpdateScripts specifies that if a `cmp` command fails and its second
// argument refers to a file inside the testscript file, the command will
// succeed and the testscript file will be updated to reflect the actual
// content (which could be stdout, stderr or a real file).
//
// The content will be quoted with txtar.Quote if needed;
// a manual change will be needed if it is not unquoted in the
// script.
UpdateScripts bool
// RequireExplicitExec requires that commands passed to RunMain must be used
// in test scripts via `exec cmd` and not simply `cmd`. This can help keep
// consistency across test scripts as well as keep separate process
// executions explicit.
RequireExplicitExec bool
// RequireUniqueNames requires that names in the txtar archive are unique.
// By default, later entries silently overwrite earlier ones.
RequireUniqueNames bool
// ContinueOnError causes a testscript to try to continue in
// the face of errors. Once an error has occurred, the script
// will continue as if in verbose mode.
ContinueOnError bool
// Deadline, if not zero, specifies the time at which the test run will have
// exceeded the timeout. It is equivalent to testing.T's Deadline method,
// and Run will set it to the method's return value if this field is zero.
Deadline time.Time
}
T holds all the methods of the *testing.T type that are used by testscript.
type T interface {
Skip(...interface{})
Fatal(...interface{})
Parallel()
Log(...interface{})
FailNow()
Run(string, func(T))
// Verbose is usually implemented by the testing package
// directly rather than on the *testing.T type.
Verbose() bool
}
TFailed holds optional extra methods implemented on T. It's defined as a separate type for backward compatibility reasons.
type TFailed interface {
Failed() bool
}
A TestScript holds execution state for a single test script.
type TestScript struct {
// contains filtered or unexported fields
}
func (ts *TestScript) BackgroundCmds() []*exec.Cmd
BackgroundCmds returns a slice containing all the commands that have been started in the background since the most recent wait command, or the start of the script if wait has not been called.
func (ts *TestScript) Check(err error)
Check calls ts.Fatalf if err != nil.
func (ts *TestScript) Defer(f func())
Defer arranges for f to be called at the end of the test. If Defer is called multiple times, the defers are executed in reverse order (similar to Go's defer statement)
func (ts *TestScript) Exec(command string, args ...string) error
Exec runs the given command and saves its stdout and stderr so they can be inspected by subsequent script commands.
func (ts *TestScript) Fatalf(format string, args ...interface{})
fatalf aborts the test with the given failure message.
func (ts *TestScript) Getenv(key string) string
Getenv gets the value of the environment variable named by the key.
func (ts *TestScript) Logf(format string, args ...interface{})
Logf appends the given formatted message to the test log transcript.
func (ts *TestScript) MkAbs(file string) string
MkAbs interprets file relative to the test script's current directory and returns the corresponding absolute path.
func (ts *TestScript) Name() string
Name returns the short name or basename of the test script.
func (ts *TestScript) ReadFile(file string) string
ReadFile returns the contents of the file with the given name, intepreted relative to the test script's current directory. It interprets "stdout" and "stderr" to mean the standard output or standard error from the most recent exec or wait command respectively.
If the file cannot be read, the script fails.
func (ts *TestScript) Setenv(key, value string)
Setenv sets the value of the environment variable named by the key.
func (ts *TestScript) Stderr() io.Writer
Stderr returns an io.Writer that can be used by a user-supplied builtin command (delcared via Params.Cmds) to write to stderr. If this method is called outside of the execution of a user-supplied builtin command, the call panics.
func (ts *TestScript) Stdout() io.Writer
Stdout returns an io.Writer that can be used by a user-supplied builtin command (delcared via Params.Cmds) to write to stdout. If this method is called outside of the execution of a user-supplied builtin command, the call panics.
func (ts *TestScript) Value(key interface{}) interface{}
Value returns a value from Env.Values, or nil if no value was set by Setup.
TestingM is implemented by *testing.M. It's defined as an interface to allow testscript to co-exist with other testing frameworks that might also wish to call M.Run.
type TestingM interface {
Run() int
}
| Name | Synopsis |
|---|---|
| .. | |