go-expect

You can hook into the lifecycle of Expect and Send operations using observers.

ExpectObserver

Called after each Expect operation.

• matchers: The list of active matchers when an error occurred, or the matchers that matched buf if err is nil.
• buf: The captured output that was matched against.
• err: The error that occurred (can be nil).

type ExpectObserver func(matchers []Matcher, buf string, err error)

SendObserver

Called after each Send operation.

• msg: The string that was sent.
• num: The number of bytes actually sent.
• err: The error that occurred (can be nil).

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

When working with SSH or other remote terminals, you can use the file descriptor of the go-expect TTY to perform operations like reading passwords. By accessing c.Tty().Fd(), you can pass the underlying file descriptor to functions like terminal.ReadPassword(fd) to simulate or capture interactive terminal behavior.

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)
}

If you need to interact with the underlying pseudoterminal or the master file descriptor:

• Tty() *os.File: Returns the slave part of the pty (the pseudoterminal).
• Fd() uintptr: Returns the file descriptor referencing the master part of the pty.
• Read(b []byte) (int, error): Reads bytes directly from the Console's tty.
• Write(b []byte) (int, error): Writes bytes directly to the Console's tty.

Use these functions to expect specific error conditions when reading from the console:

• Error(errs ...error): Matches if the read operation returns one of the specified errors.
• EOF(): A helper that expects io.EOF.
• PTSClosed(): A specialized matcher for Linux systems to detect when a pseudo-terminal (pts) has been closed, specifically matching the os.PathError with Op: "read", Path: "/dev/ptmx", and Err: syscall.Errno(0x5).

// Expect an EOF
expect.EOF()

// Expect a specific error
expect.Error(fmt.Errorf("connection reset"))

// Expect a closed PTS on Linux
expect.PTSClosed()

You can match console output using regular expressions in two ways:

1. Regexp(res ...*regexp.Regexp): Pass pre-compiled *regexp.Regexp objects.
2. RegexpPattern(ps ...string): Pass raw regex strings. This function will attempt to compile them and returns an error if any pattern is invalid.

// Using pre-compiled regex
re := regexp.MustCompile("error: [0-9]+")
expect.Regexp(re)

// Using raw strings
expect.RegexpPattern("user: [a-z]+", "id: [0-9]+")

Use ExpectString(s string) to read from the Console's tty until the exact string s is encountered. It returns the buffer read by the console and any error encountered. This is a convenience wrapper around Expect using the String option.

// s is the exact string you are looking for in the terminal output
output, err := console.ExpectString("Password: ")

The Then(f ConsoleCallback) method can be chained to an ExpectOpt to execute a callback function if a match is found. The callback receives a *bytes.Buffer containing the content read from the console at the time of the match.

expect.String("found data").Then(func(buf *bytes.Buffer) error {
    fmt.Printf("Matched content: %s\n", buf.String())
    return nil
})

The ExpectOpt type is a functional option used to configure Expect statements. You can use built-in functions to set timeouts, match specific content, or handle errors. Common patterns include using WithTimeout for read timeouts and various matchers like String, Regexp, or Error to define what the test should look for in the console output.

// Example of using ExpectOpt functions
expect.WithTimeout(5 * time.Second),
expect.String("login successful"),
expect.RegexpPattern("user: [a-z]+"),

To automate input into an interactive application, use the Send or SendLine methods.

• Send(s string) (int, error): Writes the exact string s to the Console's tty.
• SendLine(s string) (int, error): Writes the string s followed by a newline character (\n) to the Console's tty.

// Send a specific command
_, err := console.Send("ls -la")

// Send a command with a newline
_, err := console.SendLine("help")