expect

Documentation

Overview

Package expect uses the middleware concept in internal/exec to mock external commands.

Generally, you only want to use this package in testing code.

At a high level, this package operates by overriding created commands to invoke the current executable with a specific environment variable, which points to a temporary file with metadata on the behaviour that the command should implement. (This approach is shamelessly stolen from Go's os/exec test suite, but the details are somewhat different.)

This means that the main() function of the executable _must_ check the relevant environment variable as early as possible, and not perform its usual logic if it's found. An implementation of this is provided for TestMain functions in the Handle function, which is normally how this package is used.

Index

• Variables
• func Commands(t *testing.T, exp ...*Expectation)
• func Handle(m interface{ ... }) int
• type Behaviour
• type CommandValidator
  • func NewGlobValidator(wantName string, wantArg ...string) CommandValidator
• type Expectation
  • func NewGlob(behaviour Behaviour, wantName string, wantArg ...string) *Expectation
  • func NewLiteral(behaviour Behaviour, wantName string, wantArg ...string) *Expectation

Variables

var Success = Behaviour{}

Success defines a command behaviour that returns a 0 exit code and no other output.

Functions

func Commands

func Commands(t *testing.T, exp ...*Expectation)

Commands defines a set of expected commands for the given test. Commands may be called from any number of nested subtests, but must only be called once from a single test function, as it uses (*testing.T).Cleanup to manage per-test state.

func Handle

func Handle(m interface{ Run() int }) int

Handle should be called from TestMain. It intercepts expected commands and implements the expected behaviour.

m is defined as an interface rather than *testing.M to make this usable from outside of a testing context.

Types

type Behaviour

type Behaviour struct {
	// Stdout defines the data that will be returned on stdout.
	Stdout []byte

	// Stderr defines the data that will be returned on stderr.
	Stderr []byte

	// ExitCode is the exit code that the process will exit with.
	ExitCode int
}

Behaviour defines the behaviour of the mocked command.

type CommandValidator

type CommandValidator func(name string, arg ...string) error

CommandValidator is used to validate the command line that is would be executed.

func NewGlobValidator

func NewGlobValidator(wantName string, wantArg ...string) CommandValidator

NewGlobValidator creates a validation function that will validate a command using glob syntax against the given name and arguments.

type Expectation

type Expectation struct {
	Validator CommandValidator
	Behaviour Behaviour
}

Expectation represents a single command invocation.

func NewGlob

func NewGlob(behaviour Behaviour, wantName string, wantArg ...string) *Expectation

NewGlob is a convenience function that creates an Expectation that validates commands using a glob validator (as created by NewGlobValidator) and implements the given behaviour.

You don't need to use this, but it tends to make Commands() calls more readable.

func NewLiteral

func NewLiteral(behaviour Behaviour, wantName string, wantArg ...string) *Expectation

NewLiteral is a convenience function that creates an Expectation that validates commands literally.

You don't need to use this, but it tends to make Commands() calls more readable.