icmd

Documentation

Overview

Package icmd executes binaries and provides convenient assertions for testing the results.

Index

• Constants
• Variables
• type Cmd
  • func Command(command string, args ...string) Cmd
• type CmdOp
  • func Dir(path string) CmdOp
  • func WithEnv(env ...string) CmdOp
  • func WithExtraFile(f *os.File) CmdOp
  • func WithStderr(w io.Writer) CmdOp
  • func WithStdin(r io.Reader) CmdOp
  • func WithStdout(w io.Writer) CmdOp
  • func WithTimeout(timeout time.Duration) CmdOp
• type Expected
• type Result
  • func RunCmd(cmd Cmd, cmdOperators ...CmdOp) *Result
  • func RunCommand(command string, args ...string) *Result
  • func StartCmd(cmd Cmd, cmdOperators ...CmdOp) *Result
  • func WaitOnCmd(timeout time.Duration, result *Result) *Result
  • func (r *Result) Assert(t assert.TestingT, exp Expected) *Result
  • func (r *Result) Combined() string
  • func (r *Result) Compare(exp Expected) error
  • func (r *Result) Equal(exp Expected) cmp.Comparison
  • func (r *Result) Stderr() string
  • func (r *Result) Stdout() string
  • func (r *Result) String() string

Examples

• RunCmd
• RunCommand

Constants

const None = "[NOTHING]"

None is a token to inform Result.Assert that the output should be empty

Variables

var Success = Expected{}

Success is the default expected result. A Success result is one with a 0 ExitCode.

Types

type Cmd

type Cmd struct {
	Command    []string
	Timeout    time.Duration
	Stdin      io.Reader
	Stdout     io.Writer
	Stderr     io.Writer
	Dir        string
	Env        []string
	ExtraFiles []*os.File
}

Cmd contains the arguments and options for a process to run as part of a test suite.

func Command

func Command(command string, args ...string) Cmd

Command create a simple Cmd with the specified command and arguments

type CmdOp

type CmdOp func(*Cmd)

CmdOp is an operation which modified a Cmd structure used to execute commands

func Dir

func Dir(path string) CmdOp

Dir sets the working directory of the command

func WithEnv

func WithEnv(env ...string) CmdOp

WithEnv sets the environment variable of the command. Each arguments are in the form of KEY=VALUE

func WithExtraFile

func WithExtraFile(f *os.File) CmdOp

WithExtraFile adds a file descriptor to the command

func WithStderr

func WithStderr(w io.Writer) CmdOp

WithStderr sets the standard error of the command to the specified writer

func WithStdin

func WithStdin(r io.Reader) CmdOp

WithStdin sets the standard input of the command to the specified reader

func WithStdout

func WithStdout(w io.Writer) CmdOp

WithStdout sets the standard output of the command to the specified writer

func WithTimeout

func WithTimeout(timeout time.Duration) CmdOp

WithTimeout sets the timeout duration of the command

type Expected

type Expected struct {
	ExitCode int
	Timeout  bool
	Error    string
	Out      string
	Err      string
}

Expected is the expected output from a Command. This struct is compared to a Result struct by Result.Assert().

type Result

type Result struct {
	Cmd      *exec.Cmd
	ExitCode int
	Error    error
	// Timeout is true if the command was killed because it ran for too long
	Timeout bool
	// contains filtered or unexported fields
}

Result stores the result of running a command

func RunCmd

func RunCmd(cmd Cmd, cmdOperators ...CmdOp) *Result

RunCmd runs a command and returns a Result

Example

package main

import (
	"testing"

	"gotest.tools/v3/icmd"
)

var t = &testing.T{}

func main() {
	result := icmd.RunCmd(icmd.Command("cat", "/does/not/exist"))
	result.Assert(t, icmd.Expected{
		ExitCode: 1,
		Err:      "cat: /does/not/exist: No such file or directory",
	})
}

func RunCommand

func RunCommand(command string, args ...string) *Result

RunCommand runs a command with default options, and returns a result

Example

package main

import (
	"testing"

	"gotest.tools/v3/icmd"
)

var t = &testing.T{}

func main() {
	result := icmd.RunCommand("bash", "-c", "echo all good")
	result.Assert(t, icmd.Success)
}

func StartCmd

func StartCmd(cmd Cmd, cmdOperators ...CmdOp) *Result

StartCmd starts a command, but doesn't wait for it to finish

func WaitOnCmd

func WaitOnCmd(timeout time.Duration, result *Result) *Result

WaitOnCmd waits for a command to complete. If timeout is non-nil then only wait until the timeout.

func (*Result) Assert

func (r *Result) Assert(t assert.TestingT, exp Expected) *Result

Assert compares the Result against the Expected struct, and fails the test if any of the expectations are not met.

This function is equivalent to assert.Assert(t, result.Equal(exp)).

func (*Result) Combined

func (r *Result) Combined() string

Combined returns the stdout and stderr combined into a single string

func (*Result) Compare

func (r *Result) Compare(exp Expected) error

Compare the result to Expected and return an error if they do not match.

func (*Result) Equal

func (r *Result) Equal(exp Expected) cmp.Comparison

Equal compares the result to Expected. If the result doesn't match expected returns a formatted failure message with the command, stdout, stderr, exit code, and any failed expectations.

func (*Result) Stderr

func (r *Result) Stderr() string

Stderr returns the stderr of the process as a string

func (*Result) Stdout

func (r *Result) Stdout() string

Stdout returns the stdout of the process as a string

func (*Result) String

func (r *Result) String() string