package icmd

import "gotest.tools/icmd"

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
• type Expected
• type Result
• func RunCmd(cmd Cmd, cmdOperators ...CmdOp) *Result
• func RunCommand(command string, args ...string) *Result
• func StartCmd(cmd Cmd) *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
	Dir     string
	Env     []string
}

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

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

package main

import (
	"testing"

	"github.com/gotestyourself/gotestyourself/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

package main

import (
	"testing"

	"github.com/gotestyourself/gotestyourself/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) *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

Source Files ¶

command.go exitcode.go ops.go

Directories ¶