shell

Documentation

Index

• type Call
  • func (c *Call) Exits(exitCode int) *Call
  • func (c *Call) ExitsNonZero() *Call
  • func (c *Call) Fails(err error) *Call
  • func (c *Call) WithStderr(output string) *Call
  • func (c *Call) WithStdout(output string) *Call
• type CmdDumpStyle
• type Command
  • func CmdFromArgs(args ...string) Command
  • func CmdFromFmt(fmt string, args ...interface{}) Command
  • func (c Command) PrettyFormat() string
• type Error
  • func (e *Error) Error() string
• type ExitError
  • func (e *ExitError) Error() string
• type LoggingWriter
  • func NewLoggingWriter(level zerolog.Level, logger zerolog.Logger, prefix string, inner io.Writer) *LoggingWriter
  • func (lw *LoggingWriter) Write(p []byte) (n int, err error)
• type MockOptions
• type MockRunner
  • func DefaultMockRunner() *MockRunner
  • func NewMockRunner(options MockOptions) *MockRunner
  • func (m *MockRunner) ExpectCmd(cmd Command) *Call
  • func (m *MockRunner) ExpectSubprocessCmd(cmd Command) *Call
  • func (m *MockRunner) PrepareSubprocess(cmd Command, options ...RunOption) Subprocess
  • func (m *MockRunner) Run(cmd Command, options ...RunOption) error
  • func (m *MockRunner) Test(t *testing.T)
• type RealRunner
  • func (r *RealRunner) PrepareSubprocess(cmd Command, options ...RunOption) Subprocess
  • func (r *RealRunner) Run(cmd Command, options ...RunOption) error
• type RunOption
• type RunOptions
• type Runner
  • func NewRunner() Runner
• type Subprocess

Types

type Call

type Call struct {
	*mock.Call
	// contains filtered or unexported fields
}

Call decorates testify's Call struct with additional methods for simulating stdout / stderr output from a mocked command

func (*Call) Exits

func (c *Call) Exits(exitCode int) *Call

Exits configures the mock command to exit with the given exit status

func (*Call) ExitsNonZero

func (c *Call) ExitsNonZero() *Call

ExitsNonZero configures the mock command to exit with a non-zero exit code

func (*Call) Fails

func (c *Call) Fails(err error) *Call

Fails configures the mock command to fail with a non-ExitError error

func (*Call) WithStderr

func (c *Call) WithStderr(output string) *Call

WithStderr configures the mock command to write the given data to stderr

func (*Call) WithStdout

func (c *Call) WithStdout(output string) *Call

WithStdout configures the mock command to write the given data to stdout

type CmdDumpStyle

type CmdDumpStyle int

CmdDumpStyle how to style commands when they are printed to the console

const (
	Default CmdDumpStyle = iota
	Pretty
	Spew
)

Default prints the command using "%v" Pretty formats commands using PrettyFormat Spew uses the spew library to spew the entire struct

type Command

type Command struct {
	Prog        string   // Prog Main CLI program to execute
	Args        []string // Args Arguments to pass to program
	Env         []string // Env List of environment variables, eg []string{ "FOO=BAR", "BAZ=QUUX" }, to set when executing
	Dir         string   // Dir Directory where command should be run
	PristineEnv bool     // PristineEnv When true, set only supplied Env vars without inheriting current process's env vars
}

Command encapsulates a shell command

func CmdFromArgs

func CmdFromArgs(args ...string) Command

CmdFromArgs Convenience function to build a shell.Command from a list of arguments

Eg. CmdFromArgs("FOO=BAR", "ls", "-al", ".") ->

Command{
  Env: []string{"FOO=BAR"},
  Prog: "ls",
  Args: []string{"-al", "."},
  Dir: ""
}

func CmdFromFmt

func CmdFromFmt(fmt string, args ...interface{}) Command

CmdFromFmt Convenience function to build a shell.Command from a format string and arguments

Eg. CmdFromFmt("HOME=%s FOO=BAR ls -al %s", "/tmp", "Documents") ->

Command{
  Env: []string{"HOME=/tmp", "FOO=BAR"},
  Prog: "ls",
  Args: []string{"-al", "Documents},
  Dir: ""
}

func (Command) PrettyFormat

func (c Command) PrettyFormat() string

PrettyFormat converts a command into a simple string for easy inspection. Eg.

&Command{
  Prog: []string{"echo"},
  Args: []string{"foo", "bar", "baz"},
  Dir:  "/tmp",
  Env:  []string{"A=B", "C=D"}
}

-> "A=B C=D echo foo bar baz"

type Error

type Error struct {
	Command Command // the command that generated this error e
	// contains filtered or unexported fields
}

Error is a generic error that is returned in situations other than the command failing. (eg. if the Command's Directory does not exist)

func (*Error) Error

func (e *Error) Error() string

Error generates a user-friendly error message

type ExitError

type ExitError struct {
	Command  Command // the command that generated this error
	ExitCode int     // exit code of command
	Stderr   string  // stderr output
}

ExitError is returned when a command fails

func (*ExitError) Error

func (e *ExitError) Error() string

Error generates a user-friendly error message for failed shell commands

type LoggingWriter

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

LoggingWriter an io.Writer that logs messages that are sent to it with Write() and optionally forwards to another io.Writer

func NewLoggingWriter

func NewLoggingWriter(level zerolog.Level, logger zerolog.Logger, prefix string, inner io.Writer) *LoggingWriter

func (*LoggingWriter) Write

func (lw *LoggingWriter) Write(p []byte) (n int, err error)

type MockOptions

type MockOptions struct {
	VerifyOrder   bool         // VerifyOrder If true, verify commands are run in the order they were declared
	DumpStyle     CmdDumpStyle // DumpStyle how to style the dump
	IgnoreEnvVars []string     // Array of environment variable names to strip when matching shell.Command arguments
	IgnoreDir     bool         // If true, ignore Dir field of shell.Command arguments
}

options for a MockRunner

type MockRunner

type MockRunner struct {
	mock.Mock
	// contains filtered or unexported fields
}

MockRunner is an implementation of Runner interface for use with testify/mock.

func DefaultMockRunner

func DefaultMockRunner() *MockRunner

DefaultMockRunner returns a new mock runner instance with default settings

func NewMockRunner

func NewMockRunner(options MockOptions) *MockRunner

NewMockRunner constructor for MockRunner

func (*MockRunner) ExpectCmd

func (m *MockRunner) ExpectCmd(cmd Command) *Call

ExpectCmd sets an expectation for a command that should be run.

func (*MockRunner) ExpectSubprocessCmd

func (m *MockRunner) ExpectSubprocessCmd(cmd Command) *Call

ExpectSubprocessCmd sets an expectation for a command run from a Subprocess.

func (*MockRunner) PrepareSubprocess

func (m *MockRunner) PrepareSubprocess(cmd Command, options ...RunOption) Subprocess

PrepareSubprocess creates a Subprocess with a Start method that has the same mock behavior as Run. Note that this isn't sufficient to fully mock parallel execution; this exists largely to maintain type compatibility with the very real implementation offered by RealRunner.

func (*MockRunner) Run

func (m *MockRunner) Run(cmd Command, options ...RunOption) error

Run Instead of executing the command, logs an info message and registers the call with testify mock

func (*MockRunner) Test

func (m *MockRunner) Test(t *testing.T)

Test decorates Testify's mock.Mock#Test() function by adding a cleanup hook to the test object that dumps the set of expected command matchers to stderr in the event of a test failure. This is useful because most command matchers are functions and so Testify can't generate a pretty diff for them; you end up with:

(shell.Command={...}) not matched by func(Command) bool

type RealRunner

type RealRunner struct{}

RealRunner is an implementation of the Runner interface that actually executes shell commands

func (*RealRunner) PrepareSubprocess

func (r *RealRunner) PrepareSubprocess(cmd Command, options ...RunOption) Subprocess

PrepareSubprocess sets up a Subprocess to run a Command asynchronously

func (*RealRunner) Run

func (r *RealRunner) Run(cmd Command, options ...RunOption) error

Run runs a Command, returning an error if the command exits non-zero

type RunOption

type RunOption func(*RunOptions)

RunOption can be used to configure RunOptions for a Run invocation

type RunOptions

type RunOptions struct {
	// optional logger to use for logging this command
	Logger *zerolog.Logger
	// optional level at which command should be logged
	LogLevel zerolog.Level
	// optional level at which command output (stdout/stderr) should be logged
	OutputLogLevel zerolog.Level
	// optional writer where stdout should be written
	Stdout io.Writer
	// optional writer where stderr should be written
	Stderr io.Writer
	// if false, do not send stdout to logging system
	LogStdout bool
}

RunOptions are option for a RunWith() invocation

type Runner

type Runner interface {
	// Run runs a Command, streaming stdout and stderr to the log at debug level.
	// Behavior can be customized by passing in one or more RunOption functions
	Run(cmd Command, opts ...RunOption) error
	// PrepareSubprocess sets up a Subprocess to run a Command, similar to Run but asynchronous.
	PrepareSubprocess(cmd Command, opts ...RunOption) Subprocess
}

Runner is an interface for running shell commands. It exists to support mocking shell commands in unit tests.

https://joshrendek.com/2014/06/go-lang-mocking-exec-dot-command-using-interfaces/

func NewRunner

func NewRunner() Runner

NewRunner constructs a new Runner

type Subprocess

type Subprocess interface {
	// Start begins running the actual Command the Subprocess is configured for
	Start() error
	// Wait synchronously blocks until normal completion of the Command
	Wait() error
	// Stop signals the process to exit, and synchronously waits until it does; after three seconds it will be forcibly
	// killed and an error returned
	Stop() error
}

Subprocess allows running a shell command in parallel with Thelma's main process