termtest

README

termtest

An automatable terminal session with send/expect controls.

This package leverages the go-expect package to test terminal applications on Linux, MacOS and Windows.

It has been developed for CI testing of the ActiveState state tool

Example usage

import (
    "testing"

    "github.com/ActiveState/termtest"
    "github.com/stretchr/testify/suite"
)

func TestBash(t *testing.T) {
    opts := termtest.Options{
        ObserveSend: termtest.TestSendObserveFn(t),
        ObserveExpect: termtest.TestExpectObserveFn(t),
        CmdName: "/bin/bash",
    }
    cp, err := termtest.New(opts)
    require.NoError(t, err, "create console process")
    defer cp.Close()

    cp.SendLine("echo hello world")
    cp.Expect("hello world")
    cp.SendLine("exit")
    cp.ExpectExitCode(0)
}

Documentation

Index

• Variables
• func TestExpectObserveFn(t *testing.T) func([]expect.Matcher, string, string, error)
• func TestSendObserveFn(t *testing.T) func(string, int, error)
• type ConsoleProcess
  • func New(opts Options) (*ConsoleProcess, error)
  • func (cp *ConsoleProcess) Close() error
  • func (cp *ConsoleProcess) Executable() string
  • func (cp *ConsoleProcess) Expect(value string, timeout ...time.Duration)
  • func (cp *ConsoleProcess) ExpectExitCode(exitCode int, timeout ...time.Duration)
  • func (cp *ConsoleProcess) ExpectNotExitCode(exitCode int, timeout ...time.Duration)
  • func (cp *ConsoleProcess) ExpectRe(value string, timeout ...time.Duration)
  • func (cp *ConsoleProcess) Send(value string)
  • func (cp *ConsoleProcess) SendCtrlC()
  • func (cp *ConsoleProcess) SendLine(value string)
  • func (cp *ConsoleProcess) Signal(sig os.Signal) error
  • func (cp *ConsoleProcess) Snapshot() string
  • func (cp *ConsoleProcess) Stop() error
  • func (cp *ConsoleProcess) TrimmedSnapshot() string
  • func (cp *ConsoleProcess) Wait(timeout ...time.Duration)
  • func (cp *ConsoleProcess) WaitForInput(timeout ...time.Duration)
  • func (cp *ConsoleProcess) WorkDirectory() string
• type ExpectObserver
• type Options
  • func (opts *Options) CleanUp() error
  • func (opts *Options) Normalize() error
• type SendObserver

Variables

var (
	// ErrNoProcess is returned when a process was expected to be running
	ErrNoProcess = errors.New("no command process seems to be running")
)

Functions

func TestExpectObserveFn

func TestExpectObserveFn(t *testing.T) func([]expect.Matcher, string, string, error)

TestExpectObserveFn an example for a ExpectObserver function, it reports any error occurring durint expect calls to the supplied testing instance

func TestSendObserveFn

func TestSendObserveFn(t *testing.T) func(string, int, error)

TestSendObserveFn is an example for a SendObserver function, it reports any error during Send calls to the supplied testing instance

Types

type ConsoleProcess

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

ConsoleProcess bonds a command with a pseudo-terminal for automation

func New

func New(opts Options) (*ConsoleProcess, error)

New bonds a command process with a console pty.

func (*ConsoleProcess) Close

func (cp *ConsoleProcess) Close() error

Close cleans up all the resources allocated by the ConsoleProcess If the underlying process is still running, it is terminated with a SIGTERM signal.

func (*ConsoleProcess) Executable

func (cp *ConsoleProcess) Executable() string

Executable returns the command name to be executed

func (*ConsoleProcess) Expect

func (cp *ConsoleProcess) Expect(value string, timeout ...time.Duration)

Expect listens to the terminal output and returns once the expected value is found or a timeout occurs Default timeout is 10 seconds

func (*ConsoleProcess) ExpectExitCode

func (cp *ConsoleProcess) ExpectExitCode(exitCode int, timeout ...time.Duration)

ExpectExitCode waits for the program under test to terminate, and checks that the returned exit code meets expectations

func (*ConsoleProcess) ExpectNotExitCode

func (cp *ConsoleProcess) ExpectNotExitCode(exitCode int, timeout ...time.Duration)

ExpectNotExitCode waits for the program under test to terminate, and checks that the returned exit code is not the value provide

func (*ConsoleProcess) ExpectRe

func (cp *ConsoleProcess) ExpectRe(value string, timeout ...time.Duration)

ExpectRe listens to the terminal output and returns once the expected regular expression is matched or a timeout occurs Default timeout is 10 seconds

func (*ConsoleProcess) Send

func (cp *ConsoleProcess) Send(value string)

Send sends a string to the terminal as if a user typed it

func (*ConsoleProcess) SendCtrlC

func (cp *ConsoleProcess) SendCtrlC()

SendCtrlC tries to emulate what would happen in an interactive shell, when the user presses Ctrl-C Note: On Windows the Ctrl-C event is only reliable caught when the receiving process is listening for os.Interrupt signals.

func (*ConsoleProcess) SendLine

func (cp *ConsoleProcess) SendLine(value string)

SendLine sends a new line to the terminal, as if a user typed it

func (*ConsoleProcess) Signal

func (cp *ConsoleProcess) Signal(sig os.Signal) error

Signal sends an arbitrary signal to the running process

func (*ConsoleProcess) Snapshot

func (cp *ConsoleProcess) Snapshot() string

Snapshot returns a string containing a terminal snap-shot as a user would see it in a "real" terminal

func (*ConsoleProcess) Stop

func (cp *ConsoleProcess) Stop() error

Stop sends an interrupt signal for the tested process and fails if no process has been started yet. Note: This is not supported on Windows

func (*ConsoleProcess) TrimmedSnapshot

func (cp *ConsoleProcess) TrimmedSnapshot() string

TrimmedSnapshot displays the terminal output a user would see however the goroutine that creates this output is separate from this function so any output is not synced

func (*ConsoleProcess) Wait

func (cp *ConsoleProcess) Wait(timeout ...time.Duration)

Wait waits for the program under test to terminate, not caring about the exit code at all

func (*ConsoleProcess) WaitForInput

func (cp *ConsoleProcess) WaitForInput(timeout ...time.Duration)

WaitForInput returns once a shell prompt is active on the terminal Default timeout is 10 seconds

func (*ConsoleProcess) WorkDirectory

func (cp *ConsoleProcess) WorkDirectory() string

WorkDirectory returns the directory in which the command shall be run

type ExpectObserver

type ExpectObserver func(matchers []expect.Matcher, raw, pty string, err error)

ExpectObserver is called when an expectation could not be met Arguments are matchers that have been matched, the raw bytes that have been parsed, the terminal snapshot, and the error if any occurred during the matching. See TestExpectObserveFn for an example

type Options

type Options struct {
	DefaultTimeout time.Duration
	WorkDirectory  string
	RetainWorkDir  bool
	Environment    []string
	ObserveSend    SendObserver
	ObserveExpect  ExpectObserver
	CmdName        string
	Args           []string
}

Options contain optional values for ConsoleProcess construction and usage.

func (*Options) CleanUp

func (opts *Options) CleanUp() error

CleanUp cleans up the environment

func (*Options) Normalize

func (opts *Options) Normalize() error

Normalize fills in default options

type SendObserver

type SendObserver func(msg string, num int, err error)

SendObserver is function that is called when text is send to the console Arguments are the message, number of bytes written and an error message See TestSendObserveFn for an example