testagents

Documentation

Index

• Constants
• type Bin
  • func NewBin(t *testing.T, pm ProcMan, path, name, baseDir, rootDir string, ...) Bin
  • func (c *Bin) CD(path string)
  • func (c *Bin) Cmd(t *testing.T, i invocation) (*exec.Cmd, context.CancelFunc)
  • func (c *Bin) Command(stdin io.ReadCloser, subcmd string, f Flags, args ...string) (*PreparedCmd, error)
  • func (c *Bin) Configure(fms ...filemap.FileMap) error
  • func (c *Bin) ID() string
  • func (c *Bin) MustFail(t *testing.T, subcmd string, f Flags, args ...string) string
  • func (c *Bin) MustRun(t *testing.T, subcmd string, f Flags, args ...string) string
  • func (c *Bin) Run(t *testing.T, subcmd string, f Flags, args ...string) (*ExecutedCMD, error)
  • func (c *Bin) RunWithStdin(t *testing.T, stdin io.ReadCloser, subcmd string, f Flags, args ...string) (*ExecutedCMD, error)
• type ExecutedCMD
  • func (i ExecutedCMD) String() string
• type Flags
• type PreparedCmd
  • func (i PreparedCmd) String() string
• type ProcMan
  • func DefaultProcMan() ProcMan
  • func NewProcMan(opts ProcManOpts) ProcMan
• type ProcManOpts
• type Service
  • func NewService(bin Bin) *Service
  • func (s *Service) DumpTail(n int)
  • func (s *Service) Start(t *testing.T, subcmd string, flags Flags, args ...string)
  • func (s *Service) Stop() error

Constants

const DefaultPIDFile = ".procman-pids"

DefaultPIDFile is the default PIDFile if not specified in ProcManOpts.

Types

type Bin

type Bin struct {
	TestName string
	// BinPath is the absolute path to the executable file.
	BinPath string
	// BinName is the name of the executable file.
	BinName string
	// BaseDir is the root for logs/config files and other ancillary files.
	BaseDir   string
	ConfigDir string
	LogDir    string
	// InstanceName is used to identify this instance in test output.
	InstanceName string
	// RootDir is used to print current directory path in test output.
	// The printed path is Dir relative to RootDir.
	RootDir string

	// Dir is the working directory.
	Dir string
	// Env are persistent env vars to pass to invocations.
	Env map[string]string
	// MassageArgs is called on the total set of args passed to the command,
	// prior to execution; the args it returns are what is finally used.
	MassageArgs func([]string) []string

	// ShouldStillBeRunningAfterTest should is set to true for servers etc, it
	// enables crash detection.
	ShouldStillBeRunningAfterTest bool

	// Verbose if set to true, print all stdout and stderr output inline.
	// Note this output is printed to log files regardless.
	Verbose bool

	// LogFunc is called with realtime logs of command invocations and output
	// etc. Defaults to log.Printf from stdlib.
	LogFunc func(string, ...interface{})

	// ProcMan keeps track of PIDs created so you can clean them up later.
	ProcMan ProcMan
	// contains filtered or unexported fields
}

Bin represents a binary under test.

func NewBin

func NewBin(t *testing.T, pm ProcMan, path, name, baseDir, rootDir string, finished chan struct{}) Bin

NewBin returns a new minimal Bin, all files will be created in subdirectories of baseDir.

func (*Bin) CD

func (c *Bin) CD(path string)

CD changes directory (accepts relative or absolute paths).

func (*Bin) Cmd

func (c *Bin) Cmd(t *testing.T, i invocation) (*exec.Cmd, context.CancelFunc)

Cmd generates an *exec.Cmd and cancellation func from an invocation.

func (*Bin) Command

func (c *Bin) Command(stdin io.ReadCloser, subcmd string, f Flags, args ...string) (*PreparedCmd, error)

Command returns the prepared command.

func (*Bin) Configure

func (c *Bin) Configure(fms ...filemap.FileMap) error

Configure writes fm files relative to c.ConfigPath and ensures the log directory exists.

func (*Bin) ID

func (c *Bin) ID() string

ID returns the unique ID of this instance, formatted as: "test-name:instance-name".

func (*Bin) MustFail

func (c *Bin) MustFail(t *testing.T, subcmd string, f Flags, args ...string) string

MustFail fails the test if the command succeeds with a non-zero exit code. If the command fails for a different reason (e.g. failure to connect pipes), then the test also fails, as that is not the kind of failure we are looking for. It returns stderr from the command.

func (*Bin) MustRun

func (c *Bin) MustRun(t *testing.T, subcmd string, f Flags, args ...string) string

MustRun fails the test if the command fails; else returns the stdout from the command.

func (*Bin) Run

func (c *Bin) Run(t *testing.T, subcmd string, f Flags, args ...string) (*ExecutedCMD, error)

Run runs the command.

func (*Bin) RunWithStdin

func (c *Bin) RunWithStdin(t *testing.T, stdin io.ReadCloser, subcmd string, f Flags, args ...string) (*ExecutedCMD, error)

RunWithStdin runs the command, attaching stdin.

type ExecutedCMD

type ExecutedCMD struct {
	Stdout, Stderr, Combined *bytes.Buffer
	// contains filtered or unexported fields
}

ExecutedCMD represents the reasult of a command having been run.

func (ExecutedCMD) String

func (i ExecutedCMD) String() string

String returns this invocation roughly as a copy-pastable shell command. Note: if args contain quotes some manual editing may be required.

type Flags

type Flags interface {
	// FlagMap returns a map of flag name -> flag value.
	FlagMap() map[string]string
	// FlagPrefix returns the standard flag prefix for this set of flags.
	// Typically this will be either "-" or "--".
	FlagPrefix() string
}

Flags represents a set of flags to be passed to a Binary.

type PreparedCmd

type PreparedCmd struct {
	Cmd     *exec.Cmd
	Cancel  func()
	PreRun  func() error
	PostRun func() error
	// contains filtered or unexported fields
}

PreparedCmd is a command ready to run.

func (PreparedCmd) String

func (i PreparedCmd) String() string

String returns this invocation roughly as a copy-pastable shell command. Note: if args contain quotes some manual editing may be required.

type ProcMan

type ProcMan interface {
	WritePID(t *testing.T, pid int)
	StopPIDs() error
}

ProcMan manages processes via a pidfile that also contains the name of the process for a bit of extra safety when killing things. It's far from perfect, but quite useful nonetheless.

func DefaultProcMan

func DefaultProcMan() ProcMan

DefaultProcMan returns a ProcMan configured with the defaults.

func NewProcMan

func NewProcMan(opts ProcManOpts) ProcMan

NewProcMan returns a new ProcMan. Your tests should create a ProcMan using this func and share it with each Bin or Service you create. Call StopPIDs to stop any such processes that have not already stopped.

type ProcManOpts

type ProcManOpts struct {
	// PIDFile is the file this ProcMan stores state in.
	// Defaults to DefaultPIDFile if left empty.
	PIDFile string
	// LogFunc is called to emit realtime logs.
	// Defaults to log.Printf if left nil.
	LogFunc func(string, ...interface{})
	// Verbose can be set to true to emit more logs to LogFunc.
	Verbose bool
}

ProcManOpts optionally configures a ProcMan.

type Service

type Service struct {
	Bin
	Cmd     *exec.Cmd
	Stopped chan struct{}
	// contains filtered or unexported fields
}

Service represents a binary that is intended to be run as a long-running process. It includes things like crash detection.

func NewService

func NewService(bin Bin) *Service

NewService returns a new service bound to the provided binary.

func (*Service) DumpTail

func (s *Service) DumpTail(n int)

DumpTail prints out the last n lines of combined (stdout + stderr) output from this service.

func (*Service) Start

func (s *Service) Start(t *testing.T, subcmd string, flags Flags, args ...string)

Start starts this service.

func (*Service) Stop

func (s *Service) Stop() error

Stop stops this service and waits for it to exit.