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 (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)
Constants ¶
This section is empty.
Variables ¶
var (
Timeout = errors.New("timeout")
)
Functions ¶
This section is empty.
Types ¶
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session represents the state of an expect session.
func NewSession ¶
NewSession creates a new Session. The parameter t may be safely be nil.
func (*Session) 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 ¶
Expect asserts that the next line in the input matches the supplied string.
func (*Session) ExpectRE ¶
ExpectRE asserts that the next line in the input matches the pattern using regexp.MustCompile(pattern).FindAllStringSubmatch(..., n).
func (*Session) ExpectSetEventuallyRE ¶
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 ¶
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 ¶
ExpectVar asserts that the next line in the input matches the pattern <name>=<value> and returns <value>.
func (*Session) Expectf ¶
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) Finish ¶
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 ¶
OriginalError returns any error code (possibly nil) returned by the underlying library routines called.
func (*Session) ReadAll ¶
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 ¶
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 ¶
SetContinueOnError controls whether to invoke TB.FailNow on error, i.e. whether to panic on error.
func (*Session) SetTimeout ¶
SetTimeout sets the timeout for subsequent operations on this session.
func (*Session) SetVerbosity ¶
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.
Source Files