command

Documentation

Overview

Package command is a wrapper for os/exec that provides a mock-able interface to make testing easier.

Index

• func CombinedOutput(cmd string, options ...Opt) (string, error)
• func Output(cmd string, options ...Opt) (string, error)
• func Run(cmd string, options ...Opt) error
• func StderrFromError(e error) string
• type Executor
  • func NewExecExecutor() Executor
• type Expectation
  • func (e *Expectation) Once() *Expectation
  • func (e *Expectation) Return(vals ...interface{}) *Expectation
  • func (e *Expectation) Times(i int64) *Expectation
• type ExpectedCommand
• type MockExecutor
  • func NewMockExecutor(t *testing.T, opts ...MockExecutorOption) *MockExecutor
  • func (m *MockExecutor) AssertAllCalled()
  • func (m *MockExecutor) CombinedOutput(cmd string, opts ...Opt) (string, error)
  • func (m *MockExecutor) Expect(funcName string, e ExpectedCommand) *Expectation
  • func (m *MockExecutor) Output(cmd string, opts ...Opt) (string, error)
  • func (m *MockExecutor) Run(cmd string, opts ...Opt) error
  • func (m *MockExecutor) Start(cmd string, opts ...Opt) (WaitFunc, error)
• type MockExecutorImpl
  • func (m *MockExecutorImpl) CombinedOutput(cmd string, opts ...Opt) (string, error)
  • func (m *MockExecutorImpl) Output(cmd string, opts ...Opt) (string, error)
  • func (m *MockExecutorImpl) Run(cmd string, opts ...Opt) error
  • func (m *MockExecutorImpl) Start(cmd string, opts ...Opt) (WaitFunc, error)
• type MockExecutorOption
  • func Passthrough(e Executor) MockExecutorOption
• type Opt
  • func Args(args ...string) Opt
  • func AsUser(username string) Opt
  • func Context(ctx context.Context) Opt
  • func Envvar(key string, value string) Opt
  • func PipeFrom(filename string) Opt
  • func PipeTo(filename string) Opt
  • func Stderr(i io.Writer) Opt
  • func Stdin(i io.Reader) Opt
  • func Stdout(i io.Writer) Opt
  • func Timeout(t time.Duration) Opt
• type WaitFunc
  • func Start(cmd string, options ...Opt) (WaitFunc, error)

Functions

func CombinedOutput

func CombinedOutput(cmd string, options ...Opt) (string, error)

CombinedOutput runs the given command, returning the standard output and standard error from the command. An error is returned if the command fails. This is a convenience method for when an Executor isn't needed (often because it is unlikely to be injected in test

func Output

func Output(cmd string, options ...Opt) (string, error)

Output runs the given command, returning the standard output. An error if the command fails. This is a convenience method for when an Executor isn't needed (often because it is unlikely to be injected in test code)

func Run

func Run(cmd string, options ...Opt) error

Run runs the given command, returning an error if it fails. This is a convenience method for when an Executor isn't needed (often because it is unlikely to be injected in test code)

func StderrFromError

func StderrFromError(e error) string

StderrFromError returns the standard error output from the command that returned an error, if available.

Types

type Executor

type Executor interface {
	Run(string, ...Opt) error
	Start(string, ...Opt) (WaitFunc, error)
	Output(string, ...Opt) (string, error)
	CombinedOutput(string, ...Opt) (string, error)
}

Executor is an interface for running commands on the underlying system. The functions available are the same API exposed by exec.Cmd object, but modified to prefer string return, functional option, and hopefully more consistent error behavior.

var DefaultExecutor Executor = &execExecutor{}

func NewExecExecutor

func NewExecExecutor() Executor

NewExecExecutor returns an Executor backed by os.exec

type Expectation

type Expectation struct {
	// contains filtered or unexported fields
}

An Expectation represents one or more allowed function calls against the MockExecutor.

func (*Expectation) Once

func (e *Expectation) Once() *Expectation

Once sets the expected call count on an expectation. If a matching command is called more than once, the test will fail.

func (*Expectation) Return

func (e *Expectation) Return(vals ...interface{}) *Expectation

Return sets the return value for an expectation

func (*Expectation) Times

func (e *Expectation) Times(i int64) *Expectation

Times sets the expected call count on an expectation. If a matching command is called more than the given number of times, the test will fail. If the command is called under the expected number of times, AssertAllCalled() will fail.

type ExpectedCommand

type ExpectedCommand struct {
	Cmd              string
	Args             []string
	Env              []string
	PipeToFilename   string
	PipeFromFilename string
	Timeout          time.Duration
	Stdout           io.Writer
}

An ExpectedCommand represents a command that we expect the MockExecutor will be used to run. Calls to the MockExecutor are checked against expectations which include the ExpectedCommand. An empty ExpectedCommand can be used to match any command.

type MockExecutor

type MockExecutor struct {
	// contains filtered or unexported fields
}

A MockExecutor is an Executor that can be used to mock calls to external commands during the tests.

func NewMockExecutor

func NewMockExecutor(t *testing.T, opts ...MockExecutorOption) *MockExecutor

NewMockExecutor returns a MockExecutor. A MockExecutor will fail the test if any unexpected function calls are received. Expected function calls can be added with the Expect function. At the end of the tests, expectations can be checked with the CheckAllCalled() function.

func (*MockExecutor) AssertAllCalled

func (m *MockExecutor) AssertAllCalled()

AssertAllCalled will fail the tests if any expected commands have not been called during the test.

func (*MockExecutor) CombinedOutput

func (m *MockExecutor) CombinedOutput(cmd string, opts ...Opt) (string, error)

CombinedOutput is a mock of the Executor.CombinedOutput function

func (*MockExecutor) Expect

func (m *MockExecutor) Expect(funcName string, e ExpectedCommand) *Expectation

Expect adds an expectation to the MockExecutor, returning it for further modification. If future calls to the MockExecutor match the expectation, any results (see Returns) are returned to the user.

func (*MockExecutor) Output

func (m *MockExecutor) Output(cmd string, opts ...Opt) (string, error)

Output is a mock of the Executor.Output function

func (*MockExecutor) Run

func (m *MockExecutor) Run(cmd string, opts ...Opt) error

Run is a mock of the Executor.Run function

func (*MockExecutor) Start

func (m *MockExecutor) Start(cmd string, opts ...Opt) (WaitFunc, error)

Start is a mock of the Executor.Start function

type MockExecutorImpl

type MockExecutorImpl struct {
	RunFunc            func(string, ...Opt) error
	StartFunc          func(string, ...Opt) (WaitFunc, error)
	OutputFunc         func(string, ...Opt) (string, error)
	CombinedOutputFunc func(string, ...Opt) (string, error)
}

func (*MockExecutorImpl) CombinedOutput

func (m *MockExecutorImpl) CombinedOutput(cmd string, opts ...Opt) (string, error)

func (*MockExecutorImpl) Output

func (m *MockExecutorImpl) Output(cmd string, opts ...Opt) (string, error)

func (*MockExecutorImpl) Run

func (m *MockExecutorImpl) Run(cmd string, opts ...Opt) error

func (*MockExecutorImpl) Start

func (m *MockExecutorImpl) Start(cmd string, opts ...Opt) (WaitFunc, error)

type MockExecutorOption

type MockExecutorOption func(m *MockExecutor)

func Passthrough

func Passthrough(e Executor) MockExecutorOption

Passthrough allows us to both make assertions about what commands are being called while still executing them using the provided executor.

type Opt

type Opt func(c *cmd) error

Opt is an option that can be applied to a command run by the Executor.

func Args

func Args(args ...string) Opt

Args returns a command.Opt that sets the arguments for the command to be run. Note, this should NOT include the name of the command itself.

func AsUser

func AsUser(username string) Opt

AsUser returns a command.Opt that sets the user a command should be run as.

func Context

func Context(ctx context.Context) Opt

Context returns a command.Opt that sets the context for the command execution. If the context is expires or is cancels during the command execution, the command will be killed and the command will return an error. Cannot be used with command.Timeout.

func Envvar

func Envvar(key string, value string) Opt

Envvar returns a command.Opt that sets the given environment variable in the commands environment. Environment variables are added to the environment of the current process.

func PipeFrom

func PipeFrom(filename string) Opt

PipeFrom returns a command.Opt that sets the standard input of the command to the given file. Cannot be used with command.Stdin.

func PipeTo

func PipeTo(filename string) Opt

PipeTo returns a command.Opt that sets the standard output of the command to the given file. Can only be used with the Run() function.

func Stderr

func Stderr(i io.Writer) Opt

Stderr returns a command.Opt that sets the standard error of the command to a file descriptor connected to the given io.Writer. Only supported by the Run function.

func Stdin

func Stdin(i io.Reader) Opt

Stdin returns a command.Opt that sets the standard input of the command to a file descriptor fed by the given io.Reader. Cannot be used with command.PipeFrom.

func Stdout

func Stdout(i io.Writer) Opt

Stdout returns a command.Opt that sets the standard output of the command to a file descriptor connected to the given io.Writer. Only supported by the Run function.

func Timeout

func Timeout(t time.Duration) Opt

Timeout returns a command.Opt that sets a timeout for the command execution. If the timeout expires, the command will be killed and the command will return an error. Cannot be used with command.Context.

type WaitFunc

type WaitFunc func() error

func Start

func Start(cmd string, options ...Opt) (WaitFunc, error)

Start starts the given command, returning an error if it fails. This is a convenience method for when an Executor isn't needed (often because it is unlikely to be injected in test code). The underlying files are closed once WaitFunc is called