v.io: v.io/x/ref/test/expect Index | Files

package expect

import "v.io/x/ref/test/expect"

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

Package Files

expect.go

Variables

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

type Session Uses

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

Session represents the state of an expect session.

func NewSession Uses

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 Uses

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 Uses

func (s *Session) Expect(expected string)

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

func (*Session) ExpectEOF Uses

func (s *Session) ExpectEOF() error

func (*Session) ExpectRE Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

func (s *Session) Failed() bool

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

func (*Session) Finish Uses

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 Uses

func (s *Session) OriginalError() error

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

func (*Session) ReadAll Uses

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 Uses

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 Uses

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 Uses

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

SetTimeout sets the timeout for subsequent operations on this session.

func (*Session) SetVerbosity Uses

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.

Package expect imports 11 packages (graph) and is imported by 5 packages. Updated 2020-06-09. Refresh now. Tools for package owners.