README
¶
go-expect
Package expect provides an expect-like interface to automate control of applications. It is unlike expect in that it does not spawn or manage process lifecycle. This package only focuses on expecting output and sending input through it's pseudoterminal.
Usage
os.Exec example
package main
import (
"log"
"os"
"os/exec"
"time"
expect "github.com/Netflix/go-expect"
)
func main() {
c, err := expect.NewConsole(expect.WithStdout(os.Stdout))
if err != nil {
log.Fatal(err)
}
defer c.Close()
cmd := exec.Command("vi")
cmd.Stdin = c.Tty()
cmd.Stdout = c.Tty()
cmd.Stderr = c.Tty()
go func() {
c.ExpectEOF()
}()
err = cmd.Start()
if err != nil {
log.Fatal(err)
}
time.Sleep(time.Second)
c.Send("iHello world\x1b")
time.Sleep(time.Second)
c.Send("dd")
time.Sleep(time.Second)
c.SendLine(":q!")
err = cmd.Wait()
if err != nil {
log.Fatal(err)
}
}
golang.org/x/crypto/ssh/terminal example
package main
import (
"fmt"
"golang.org/x/crypto/ssh/terminal"
expect "github.com/Netflix/go-expect"
)
func getPassword(fd int) string {
bytePassword, _ := terminal.ReadPassword(fd)
return string(bytePassword)
}
func main() {
c, _ := expect.NewConsole()
defer c.Close()
donec := make(chan struct{})
go func() {
defer close(donec)
c.SendLine("hunter2")
}()
echoText := getPassword(int(c.Tty().Fd()))
<-donec
fmt.Printf("\nPassword from stdin: %s", echoText)
}
Documentation
¶
Overview ¶
Package expect provides an expect-like interface to automate control of applications. It is unlike expect in that it does not spawn or manage process lifecycle. This package only focuses on expecting output and sending input through it's psuedoterminal.
Index ¶
- func EOF(opts *ExpectOpts) error
- func NewChanReader(ctx context.Context, bytec <-chan byte) io.Reader
- func NewTestWriter(t *testing.T) (io.Writer, error)
- func PTSClosed(opts *ExpectOpts) error
- func StripTrailingEmptyLines(out string) string
- type CallbackMatcher
- type Console
- func (c *Console) Close() error
- func (c *Console) Expect(opts ...ExpectOpt) (string, error)
- func (c *Console) ExpectEOF() (string, error)
- func (c *Console) ExpectString(s string) (string, error)
- func (c *Console) Expectf(format string, args ...interface{}) (string, error)
- func (c *Console) Fd() uintptr
- func (c *Console) Log(v ...interface{})
- func (c *Console) Logf(format string, v ...interface{})
- func (c *Console) Read(b []byte) (int, error)
- func (c *Console) Send(s string) (int, error)
- func (c *Console) SendLine(s string) (int, error)
- func (c *Console) Tty() *os.File
- func (c *Console) Write(b []byte) (int, error)
- type ConsoleCallback
- type ConsoleOpt
- func WithCloser(closer ...io.Closer) ConsoleOpt
- func WithDefaultTimeout(timeout time.Duration) ConsoleOpt
- func WithExpectObserver(observers ...ExpectObserver) ConsoleOpt
- func WithLogger(logger *log.Logger) ConsoleOpt
- func WithSendObserver(observers ...SendObserver) ConsoleOpt
- func WithStdin(readers ...io.Reader) ConsoleOpt
- func WithStdout(writers ...io.Writer) ConsoleOpt
- type ConsoleOpts
- type ExpectObserver
- type ExpectOpt
- type ExpectOpts
- type Matcher
- type PassthroughPipe
- type ReaderLease
- type SendObserver
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EOF ¶
func EOF(opts *ExpectOpts) error
EOF adds an Expect condition to exit if io.EOF is returned from reading Console's tty.
func NewChanReader ¶
NewChanReader returns a io.Reader over a byte chan. If context is cancelled, future Reads will return io.EOF.
func NewTestWriter ¶
NewTestWriter returns an io.Writer where bytes written to the file are logged by go's testing logger. Bytes are flushed to the logger on line end.
func PTSClosed ¶
func PTSClosed(opts *ExpectOpts) error
PTSClosed adds an Expect condition to exit if we get an "read /dev/ptmx: input/output error" error which can occur on Linux while reading from the ptm after the pts is closed. Further Reading: https://github.com/kr/pty/issues/21#issuecomment-129381749
func StripTrailingEmptyLines ¶
StripTrailingEmptyLines returns a copy of s stripped of trailing lines that consist of only space characters.
Types ¶
type CallbackMatcher ¶
type CallbackMatcher interface {
// Callback executes the matcher's callback with the content buffer at the
// time of match.
Callback(buf *bytes.Buffer) error
}
CallbackMatcher is a matcher that provides a Callback function.
type Console ¶
type Console struct {
// contains filtered or unexported fields
}
Console is an interface to automate input and output for interactive applications. Console can block until a specified output is received and send input back on it's tty. Console can also multiplex other sources of input and multiplex its output to other writers.
Example (Echo) ¶
c, err := NewConsole(WithStdout(os.Stdout))
if err != nil {
log.Fatal(err)
}
defer c.Close()
cmd := exec.Command("echo")
cmd.Stdin = c.Tty()
cmd.Stdout = c.Tty()
cmd.Stderr = c.Tty()
err = cmd.Start()
if err != nil {
log.Fatal(err)
}
c.Send("Hello world")
c.ExpectString("Hello world")
c.Tty().Close()
c.ExpectEOF()
err = cmd.Wait()
if err != nil {
log.Fatal(err)
}
Output: Hello world
func NewConsole ¶
func NewConsole(opts ...ConsoleOpt) (*Console, error)
NewConsole returns a new Console with the given options.
func NewTestConsole ¶
func NewTestConsole(t *testing.T, opts ...ConsoleOpt) (*Console, error)
NewTestConsole returns a new Console that multiplexes the application's stdout to go's testing logger. Primarily so that outputs from parallel tests using t.Parallel() is not interleaved.
func (*Console) Close ¶
Close closes Console's tty. Calling Close will unblock Expect and ExpectEOF.
func (*Console) Expect ¶
Expect reads from Console's tty until a condition specified from opts is encountered or an error occurs, and returns the buffer read by console. No extra bytes are read once a condition is met, so if a program isn't expecting input yet, it will be blocked. Sends are queued up in tty's internal buffer so that the next Expect will read the remaining bytes (i.e. rest of prompt) as well as its conditions.
func (*Console) ExpectEOF ¶
ExpectEOF reads from Console's tty until EOF or an error occurs, and returns the buffer read by Console. We also treat the PTSClosed error as an EOF.
func (*Console) ExpectString ¶
ExpectString reads from Console's tty until the provided string is read or an error occurs, and returns the buffer read by Console.
func (*Console) Expectf ¶
Expectf reads from the Console's tty until the provided formatted string is read or an error occurs, and returns the buffer read by Console.
func (*Console) Log ¶
func (c *Console) Log(v ...interface{})
Log prints to Console's logger. Arguments are handled in the manner of fmt.Print.
func (*Console) Logf ¶
Logf prints to Console's logger. Arguments are handled in the manner of fmt.Printf.
type ConsoleCallback ¶
ConsoleCallback is a callback function to execute if a match is found for the chained matcher.
type ConsoleOpt ¶
type ConsoleOpt func(*ConsoleOpts) error
ConsoleOpt allows setting Console options.
func WithCloser ¶
func WithCloser(closer ...io.Closer) ConsoleOpt
WithCloser adds closers that are closed in order when Console is closed.
func WithDefaultTimeout ¶
func WithDefaultTimeout(timeout time.Duration) ConsoleOpt
WithDefaultTimeout sets a default read timeout during Expect statements.
func WithExpectObserver ¶
func WithExpectObserver(observers ...ExpectObserver) ConsoleOpt
WithExpectObserver adds an ExpectObserver to allow monitoring Expect operations.
func WithLogger ¶
func WithLogger(logger *log.Logger) ConsoleOpt
WithLogger adds a logger for Console to log debugging information to. By default Console will discard logs.
func WithSendObserver ¶
func WithSendObserver(observers ...SendObserver) ConsoleOpt
WithSendObserver adds a SendObserver to allow monitoring Send operations.
func WithStdin ¶
func WithStdin(readers ...io.Reader) ConsoleOpt
WithStdin adds readers that bytes read are written to Console's tty. If a listed reader returns an error, that reader will not be continued to read.
func WithStdout ¶
func WithStdout(writers ...io.Writer) ConsoleOpt
WithStdout adds writers that Console duplicates writes to, similar to the Unix tee(1) command.
Each write is written to each listed writer, one at a time. Console is the last writer, writing to it's internal buffer for matching expects. If a listed writer returns an error, that overall write operation stops and returns the error; it does not continue down the list.
type ConsoleOpts ¶
type ConsoleOpts struct {
Logger *log.Logger
Stdins []io.Reader
Stdouts []io.Writer
Closers []io.Closer
ExpectObservers []ExpectObserver
SendObservers []SendObserver
ReadTimeout *time.Duration
}
ConsoleOpts provides additional options on creating a Console.
type ExpectObserver ¶
ExpectObserver provides an interface for a function callback that will be called after each Expect operation. matchers will be the list of active matchers when an error occurred,
or a list of matchers that matched `buf` when err is nil.
buf is the captured output that was matched against. err is error that might have occurred. May be nil.
type ExpectOpt ¶
type ExpectOpt func(*ExpectOpts) error
ExpectOpt allows settings Expect options.
func All ¶
All adds an Expect condition to exit if the content read from Console's tty matches all of the provided ExpectOpt, in any order.
func Error ¶
Error adds an Expect condition to exit if reading from Console's tty returns one of the provided errors.
func Regexp ¶
Regexp adds an Expect condition to exit if the content read from Console's tty matches the given Regexp.
func RegexpPattern ¶
RegexpPattern adds an Expect condition to exit if the content read from Console's tty matches the given Regexp patterns. Expect returns an error if the patterns were unsuccessful in compiling the Regexp.
func String ¶
String adds an Expect condition to exit if the content read from Console's tty contains any of the given strings.
func WithTimeout ¶
WithTimeout sets a read timeout for an Expect statement.
func (ExpectOpt) Then ¶
func (eo ExpectOpt) Then(f ConsoleCallback) ExpectOpt
Then returns an Expect condition to execute a callback if a match is found for the chained matcher.
type ExpectOpts ¶
ExpectOpts provides additional options on Expect.
func (ExpectOpts) Match ¶
func (eo ExpectOpts) Match(v interface{}) Matcher
Match sequentially calls Match on all matchers in ExpectOpts and returns the first matcher if a match exists, otherwise nil.
type Matcher ¶
type Matcher interface {
// Match returns true iff a match is found.
Match(v interface{}) bool
Criteria() interface{}
}
Matcher provides an interface for finding a match in content read from Console's tty.
type PassthroughPipe ¶
type PassthroughPipe struct {
// contains filtered or unexported fields
}
PassthroughPipe is pipes data from a io.Reader and allows setting a read deadline. If a timeout is reached the error is returned, otherwise the error from the provided io.Reader is returned is passed through instead.
func NewPassthroughPipe ¶
func NewPassthroughPipe(reader io.Reader) (*PassthroughPipe, error)
NewPassthroughPipe returns a new pipe for a io.Reader that passes through non-timeout errors.
func (*PassthroughPipe) Close ¶
func (pp *PassthroughPipe) Close() error
func (*PassthroughPipe) SetReadDeadline ¶
func (pp *PassthroughPipe) SetReadDeadline(t time.Time) error
type ReaderLease ¶
type ReaderLease struct {
// contains filtered or unexported fields
}
ReaderLease provides cancellable io.Readers from an underlying io.Reader.
func NewReaderLease ¶
func NewReaderLease(reader io.Reader) *ReaderLease
NewReaderLease returns a new ReaderLease that begins reading the given io.Reader.
func (*ReaderLease) NewReader ¶
func (rm *ReaderLease) NewReader(ctx context.Context) io.Reader
NewReader returns a cancellable io.Reader for the underlying io.Reader. Readers can be cancelled without interrupting other Readers, and once a reader is a cancelled it will not read anymore bytes from ReaderLease's underlying io.Reader.
type SendObserver ¶
SendObserver provides an interface for a function callback that will be called after each Send operation. msg is the string that was sent. num is the number of bytes actually sent. err is the error that might have occured. May be nil.
Source Files