expect

Documentation

Overview

Package expect implements support for checking expectations against a buffered input stream. It supports literal and pattern based matching. It is line oriented; all of the methods (expect ReadAll) strip trailing newlines from their return values. It places a timeout on all its operations. It will generally be used to read from the stdout stream of subprocesses in tests and other situations and to make 'assertions' about what is to be read.

A Session type is used to store state, in particular error state, across consecutive invocations of its method set. If a particular method call encounters an error then subsequent calls on that Session will have no effect. This allows for a series of assertions to be made, one per line, and for errors to be checked at the end. In addition Session is designed to be easily used with the testing package; passing a *testing.T instance to NewSession allows it to set errors directly and hence tests will pass or fail according to whether the expect assertions are met or not.

Care is taken to ensure that the file and line number of the first failed assertion in the session are recorded in the error stored in the Session.

Examples

func TestSomething(t *testing.T) {
    buf := []byte{}
    buffer := bytes.NewBuffer(buf)
    buffer.WriteString("foo\n")
    buffer.WriteString("bar\n")
    buffer.WriteString("baz\n")
    s := expect.NewSession(t, bufio.NewReader(buffer), time.Second)
    s.Expect("foo")
    s.Expect("bars)
    if got, want := s.ReadLine(), "baz"; got != want {
        t.Errorf("got %v, want %v", got, want)
    }
}

Index

• Variables
• type Session
  • func NewSession(t testing.TB, input io.Reader, timeout time.Duration) *Session
  • func (s *Session) Error() error
  • func (s *Session) Expect(expected string)
  • func (s *Session) ExpectEOF() error
  • func (s *Session) ExpectRE(pattern string, n int) [][]string
  • func (s *Session) ExpectSetEventuallyRE(expected ...string) [][]string
  • func (s *Session) ExpectSetRE(expected ...string) [][]string
  • func (s *Session) ExpectVar(name string) string
  • func (s *Session) Expectf(format string, args ...interface{})
  • func (s *Session) Failed() bool
  • func (s *Session) Finish(w io.Writer) (string, error)
  • func (s *Session) OriginalError() error
  • func (s *Session) ReadAll() (string, error)
  • func (s *Session) ReadLine() string
  • func (s *Session) SetContinueOnError(value bool)
  • func (s *Session) SetTimeout(timeout time.Duration)
  • func (s *Session) SetVerbosity(v bool)

Variables

var (
	//nolint:golint // API change required.
	Timeout = errors.New("timeout")
)

Types

type Session

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

Session represents the state of an expect session.

func NewSession

func NewSession(t testing.TB, input io.Reader, timeout time.Duration) *Session

NewSession creates a new Session. The parameter t may be safely be nil.

func (*Session) Error

func (s *Session) Error() error

Error returns the error code (possibly nil) currently stored in the Session. This will include the file and line of the calling function that experienced the error. Use OriginalError to obtain the original error code.

func (*Session) Expect

func (s *Session) Expect(expected string)

Expect asserts that the next line in the input matches the supplied string.

func (*Session) ExpectEOF

func (s *Session) ExpectEOF() error

func (*Session) ExpectRE

func (s *Session) ExpectRE(pattern string, n int) [][]string

ExpectRE asserts that the next line in the input matches the pattern using regexp.MustCompile(pattern).FindAllStringSubmatch(..., n).

func (*Session) ExpectSetEventuallyRE

func (s *Session) ExpectSetEventuallyRE(expected ...string) [][]string

ExpectSetEventuallyRE is like ExpectSetRE except that it reads as much output as required rather than just the next n lines. The value returned is either:

• nil in the case of an error, or
• nil if EOF is encountered before all expressions are matched, or
• an array of length len(expected), whose ith element contains the result of FindStringSubmatch of expected[i] on the matching string (never nil). If there are no capturing groups in expected[i], the return value's [i][0] will contain the entire matching string

This function stops consuming output as soon as all regular expressions are matched.

func (*Session) ExpectSetRE

func (s *Session) ExpectSetRE(expected ...string) [][]string

ExpectSetRE verifies whether the supplied set of regular expression parameters matches the next n (where n is the number of parameters) lines of input. Each line is read and matched against the supplied patterns in the order that they are supplied as parameters. Consequently the set may contain repetitions if the same pattern is expected multiple times. The value returned is either:

• nil in the case of an error, or
• nil if n lines are read or EOF is encountered before all expressions are matched, or
• an array of length len(expected), whose ith element contains the result of FindStringSubmatch of expected[i] on the matching string (never nil). If there are no capturing groups in expected[i], the return value's [i][0] element will be the entire matching string

func (*Session) ExpectVar

func (s *Session) ExpectVar(name string) string

ExpectVar asserts that the next line in the input matches the pattern <name>=<value> and returns <value>.

func (*Session) Expectf

func (s *Session) Expectf(format string, args ...interface{})

Expectf asserts that the next line in the input matches the result of formatting the supplied arguments. It's equivalent to Expect(fmt.Sprintf(args)).

func (*Session) Failed

func (s *Session) Failed() bool

Failed returns true if an error has been encountered by a prior call.

func (*Session) Finish

func (s *Session) Finish(w io.Writer) (string, error)

Finish reads all remaining input on the stream regardless of any prior errors and writes it to the supplied io.Writer parameter if non-nil. It returns both the data read and the prior error, if any, otherwise it returns any error that occurred reading the rest of the input.

func (*Session) OriginalError

func (s *Session) OriginalError() error

OriginalError returns any error code (possibly nil) returned by the underlying library routines called.

func (*Session) ReadAll

func (s *Session) ReadAll() (string, error)

ReadAll reads all remaining input on the stream. Unlike all of the other methods it does not strip newlines from the input. ReadAll has no effect if an error has already occurred.

func (*Session) ReadLine

func (s *Session) ReadLine() string

ReadLine reads the next line, if any, from the input stream. It will set the error state to io.EOF if it has read past the end of the stream. ReadLine has no effect if an error has already occurred.

func (*Session) SetContinueOnError

func (s *Session) SetContinueOnError(value bool)

SetContinueOnError controls whether to invoke TB.FailNow on error, i.e. whether to panic on error.

func (*Session) SetTimeout

func (s *Session) SetTimeout(timeout time.Duration)

SetTimeout sets the timeout for subsequent operations on this session.

func (*Session) SetVerbosity

func (s *Session) SetVerbosity(v bool)

SetVerbosity enables/disables verbose debugging information, in particular, every line of input read will be logged via t.Logf or, if t is nil, to stderr.