testexec

Documentation

Overview

Package testexec is a wrapper of the standard os/exec package optimized for use cases of Tast. Tast tests should always use this package instead of os/exec.

This package is designed to be a drop-in replacement of os/exec. Just rewriting imports should work. In addition, several methods are available, such as Kill and DumpLog.

Features

Automatic log collection. os/exec sends stdout/stderr to /dev/null unless explicitly specified to collect them. This default behavior makes it very difficult to debug external command failures. This wrapper automatically collects those uncaptured logs and allows to log them later.

Process group handling. On timeout, os/exec kills the direct child process only. This can often leave orphaned subprocesses in DUT and interfere with later tests. To avoid this issue, this wrapper will kill the whole tree of subprocesses on timeout by setting process group ID appropriately.

Usage

cmd := testexec.CommandContext(ctx, "some", "external", "command")
if err := cmd.Run(testexec.DumpLogOnError); err != nil {
    return err
}

Index

• Constants
• Variables
• func ExitCode(cmdErr error) (int, bool)
• func GetWaitStatus(err error) (status syscall.WaitStatus, ok bool)
• type Cmd
  • func CommandContext(ctx context.Context, name string, arg ...string) *Cmd
  • func CommandContextUser(ctx context.Context, username, name string, arg ...string) (*Cmd, error)
  • func (c *Cmd) CombinedOutput(opts ...RunOption) ([]byte, error)
  • func (c *Cmd) Cred(cred syscall.Credential)
  • func (c *Cmd) DumpLog(ctx context.Context) error
  • func (c *Cmd) Kill() error
  • func (c *Cmd) Output(opts ...RunOption) ([]byte, error)
  • func (c *Cmd) Run(opts ...RunOption) error
  • func (c *Cmd) SeparatedOutput(opts ...RunOption) (stdout, stderr []byte, err error)
  • func (c *Cmd) Signal(signal unix.Signal) error
  • func (c *Cmd) Start() error
  • func (c *Cmd) Wait(opts ...RunOption) error
• type RunOption

Constants

const DumpLogOnError = tastexec.DumpLogOnError

DumpLogOnError is an option to dump logs if the executed command fails (i.e., exited with non-zero status code).

Variables

var (
	// ErrNotStarted is the error returned when the process has not yet started.
	ErrNotStarted = errors.New("Start was not yet called")
	// ErrAlreadyWaited is the error returned when the process has been waited
	// and also returned.
	// Please see https://pkg.go.dev/os/exec#Cmd.ProcessState.
	ErrAlreadyWaited = errors.New("Wait was already called and the process has returned")
)

Functions

func ExitCode

func ExitCode(cmdErr error) (int, bool)

ExitCode extracts exit code from error returned by exec.Command.Run(). Returns exit code and true if exit code is extracted. (0, false) otherwise. Note that "true" does not mean that the process itself exited correctly, only that the exit code was extracted successfully.

func GetWaitStatus

func GetWaitStatus(err error) (status syscall.WaitStatus, ok bool)

GetWaitStatus extracts WaitStatus from error. WaitStatus is typically returned from Run, Output, CombinedOutput and Wait to indicate a child process's exit status. If err is nil, it returns WaitStatus representing successful exit.

Types

type Cmd

type Cmd struct {
	// Cmd is the underlying exec.Cmd object.
	*exec.Cmd
	// contains filtered or unexported fields
}

Cmd represents an external command being prepared or run.

This struct embeds Cmd in os/exec.

Callers may wish to use shutil.EscapeSlice when logging Args.

func CommandContext

func CommandContext(ctx context.Context, name string, arg ...string) *Cmd

CommandContext prepares to run an external command.

Timeout set in ctx is honored on running the command.

See os/exec package for details.

func CommandContextUser

func CommandContextUser(ctx context.Context, username, name string, arg ...string) (*Cmd, error)

CommandContextUser creates a CommandContext that will run as the given username.

The returned error is a result of the user/group lookup steps.

func (*Cmd) CombinedOutput

func (c *Cmd) CombinedOutput(opts ...RunOption) ([]byte, error)

CombinedOutput runs an external command, waits for its completion and returns stdout/stderr output of the command.

See os/exec package for details.

func (*Cmd) Cred

func (c *Cmd) Cred(cred syscall.Credential)

Cred is a helper function that sets SysProcAttr.Credential to control the credentials (e.g. UID, GID, etc.) used to run the command.

func (*Cmd) DumpLog

func (c *Cmd) DumpLog(ctx context.Context) error

DumpLog logs details of the executed external command, including uncaptured output.

This is a new method that does not exist in os/exec.

Call this function when the test is failing due to unexpected external command result. You should not call this function for every external command invocation to avoid spamming logs.

This function must be called after Wait.

func (*Cmd) Kill

func (c *Cmd) Kill() error

Kill sends SIGKILL to the process tree.

This is a new method that does not exist in os/exec.

Even after successful completion of this function, you still need to call Wait to release all associated resources.

func (*Cmd) Output

func (c *Cmd) Output(opts ...RunOption) ([]byte, error)

Output runs an external command, waits for its completion and returns stdout output of the command.

See os/exec package for details.

func (*Cmd) Run

func (c *Cmd) Run(opts ...RunOption) error

Run runs an external command and waits for its completion.

See os/exec package for details.

func (*Cmd) SeparatedOutput

func (c *Cmd) SeparatedOutput(opts ...RunOption) (stdout, stderr []byte, err error)

SeparatedOutput runs an external command, waits for its completion and returns stdout/stderr output of the command separately.

func (*Cmd) Signal

func (c *Cmd) Signal(signal unix.Signal) error

Signal sends the input signal to the process tree.

This is a new method that does not exist in os/exec.

Even after successful completion of this function, you still need to call Wait to release all associated resources.

func (*Cmd) Start

func (c *Cmd) Start() error

Start starts an external command.

See os/exec package for details.

func (*Cmd) Wait

func (c *Cmd) Wait(opts ...RunOption) error

Wait waits for the process to finish and releases all associated resources.

See os/exec package for details.

type RunOption

type RunOption = tastexec.RunOption

RunOption is enum of options which can be passed to Run, Output, CombinedOutput and Wait to control precise behavior of them.