uitest

Documentation

Overview

Package uitest provides means of testing UI interactions.

Index

• Constants
• func RunScripts(t *testing.T, ...)
• func Script(emu Emulator, script []byte, opts *ScriptOptions) error
• func SetupScript(params *testscript.Params) (setEmulator func(*testscript.TestScript, Emulator))
• type Emulator
• type EmulatorView
  • func NewEmulatorView(opts *EmulatorViewOptions) *EmulatorView
  • func (e *EmulatorView) Close() error
  • func (e *EmulatorView) FeedKeys(keys string) error
  • func (e *EmulatorView) Prompt(fs ...ui.Field) error
  • func (e *EmulatorView) Rows() []string
  • func (e *EmulatorView) Write(p []byte) (n int, err error)
• type EmulatorViewOptions
• type RobotView
  • func NewRobotView(fixtureFile string, opts *RobotViewOptions) (*RobotView, error)
  • func (s *RobotView) Close() error
  • func (s *RobotView) Prompt(fields ...ui.Field) error
  • func (s *RobotView) Write(bs []byte) (n int, err error)
• type RobotViewOptions
• type RunScriptsOptions
• type ScriptOptions

Constants

const (
	// DefaultWidth is the default terminal width.
	DefaultWidth = 80

	// DefaultHeight is the default terminal height.
	DefaultHeight = 24
)

Functions

func RunScripts

func RunScripts(
	t *testing.T,
	startView func(testing.TB, *testscript.TestScript, ui.InteractiveView),
	opts *RunScriptsOptions,
	files ...string,
)

RunScripts runs scripts defined in the given file or directory.

It provides an "init" command that runs the provided startView function inside a background goroutine with access to an in-memory terminal emulator. Other commands provided by SetupScript are also available in the script.

Files is a list of test script files or directories. For any directory specified in files, its direct children matching the name '*.txt' are run as scripts.

func Script

func Script(emu Emulator, script []byte, opts *ScriptOptions) error

Script runs a UI script defining terminal interactions against a terminal emulator.

UI scripts take the form of newline-separated commands.

await Enter a name
feed Foo\r
snapshot

The following commands are supported.

• await [txt]: Wait up to 1 second for the given text to become visible on the screen. If [txt] is absent, wait until contents of the screen change compared to the last captured snapshot or last await empty.
• clear: Ignore current screen contents when awaiting text.
• snapshot [name]: Take a picture of the screen as it is right now, and print it to Output. If name is provided, the output will include that as a header.
• feed txt: Feed the given string into the terminal. Go string-style escape codes are permitted without quotes. Examples: \r, \x1b[B

Snapshots are written to [ScriptOptions.Output] if provided.

New scripts should prefer using SetupScript for this purpose.

func SetupScript

func SetupScript(params *testscript.Params) (setEmulator func(*testscript.TestScript, Emulator))

SetupScript may be used from testscripts to control a fake terminal emulator. Install this in a testscript.Params, and use the returned setEmulator to provide an emulator to a test script with another command (e.g. "init").

The source of input for the emulator should run in the background.

The following commands are added to scripts:

clear
	Ignore current screen contents when awaiting text.
await [txt]
	Wait for the given text to be visible on screen.
	If [txt] is absent, wait until the contents of the screen
	change compared to the last 'snapshot' call.
snapshot
	Print a copy of the screen to the script's stdout.
feed [-r N] txt
	Post the given text to the command's stdin.
	If -count is given, the input is repeated N times.

Types

type Emulator

type Emulator interface {
	FeedKeys(string) error
	Rows() []string
}

Emulator is a terminal emulator that receives input and allows querying the terminal state.

type EmulatorView

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

EmulatorView is a ui.InteractiveView that renders to an in-memory terminal emulator, and allows interacting with it programmatically.

func NewEmulatorView

func NewEmulatorView(opts *EmulatorViewOptions) *EmulatorView

NewEmulatorView creates a new EmulatorView with the given dimensions.

The EmulatorView must be closed with Close when done.

func (*EmulatorView) Close

func (e *EmulatorView) Close() error

Close closes the EmulatorView and frees its resources.

func (*EmulatorView) FeedKeys

func (e *EmulatorView) FeedKeys(keys string) error

FeedKeys feeds the given keys to the terminal emulator.

func (*EmulatorView) Prompt

func (e *EmulatorView) Prompt(fs ...ui.Field) error

Prompt prompts the user for input with the given interactive fields.

func (*EmulatorView) Rows

func (e *EmulatorView) Rows() []string

Rows returns a list of rows in the terminal emulator.

func (*EmulatorView) Write

func (e *EmulatorView) Write(p []byte) (n int, err error)

Write posts messages to the user.

type EmulatorViewOptions

type EmulatorViewOptions struct {
	// Dimensions of the terminal screen.
	// If not provided, defaults to 24 rows and 80 columns.
	Rows, Cols int

	// NoAutoResize disables automatic resizing of the terminal
	// as output is written to it.
	NoAutoResize bool

	// Log function to use, if any.
	Logf func(string, ...any)
}

EmulatorViewOptions are options for creating an EmulatorView.

type RobotView

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

RobotView is an ui.InteractiveView that simulates user input in tests.

It is backed by a fixture file that contains the inputs. The file is divided into sections by a line containing only `===`. Each section corresponds to a prompt and contains JSON-encoded input for that prompt.

===
"Alice"
===
["branch1", "branch2"]

For convenience, the first "===" is optional. The JSON input is fed into the corresponding field's UnmarshalValue method.

">"-prefixed lines before the JSON-encoded input are treated as comments.

> This is a comment
> across multiple lines
"Alice"

If an output file is provided, the fixture is reproduced to it, along with a comment containing each prompt's rendered form. This allows comparing the resulting prompts with the prompts that the input was written for.

===
> Enter a name:
"Alice"
===
> Pick branches:
>  - branch1
>  - branch2
>  - branch3
["branch1", "branch2"]

Non-prompt output from the application is also written to the output file.

The current position in the fixture file is recorded in a separate file to allow resuming from where the test left off. This allows reusing the same fixture file across multiple executions.

func NewRobotView

func NewRobotView(fixtureFile string, opts *RobotViewOptions) (*RobotView, error)

NewRobotView creates a new RobotView that reads from the given fixture file and writes to the given output file. If outputFile is empty, output is discarded.

The returned RobotView must be closed once you're done with it.

func (*RobotView) Close

func (s *RobotView) Close() error

Close flushes the output buffer to the output file.

func (*RobotView) Prompt

func (s *RobotView) Prompt(fields ...ui.Field) error

Prompt runs the given fields as prompts, reading the remaining input values from the fixture file. If the fixture file is exhausted, an error is returned.

func (*RobotView) Write

func (s *RobotView) Write(bs []byte) (n int, err error)

Write writes non-prompt output.

This is buffered in-memory until the next prompt, or until the view is closed.

type RobotViewOptions

type RobotViewOptions struct {
	// OutputFile is the file to write the output to.
	//
	// This will contain all the original inputs from the fixture file,
	// alongside rendered prompts for those inputs.
	//
	// If unset, the output is discarded.
	OutputFile string

	// LogOutput is the writer to log messages to.
	//
	// If unset, messages are discarded.
	LogOutput io.Writer

	// Size of the terminal window.
	//
	// Defaults to DefaultWidth and DefaultHeight.
	Width, Height int
}

RobotViewOptions customizes a RobotView.

type RunScriptsOptions

type RunScriptsOptions struct {
	// Size of the terminal. Defaults to 80x40.
	Rows, Cols int

	// Update specifies whether 'cmp' commands in scripts
	// should update the test file in case of mismatch.
	Update bool

	// Cmds defines additional commands to provide to the test script.
	Cmds map[string]func(*testscript.TestScript, bool, []string)
}

RunScriptsOptions defines options for RunScripts.

type ScriptOptions

type ScriptOptions struct {
	// Logf is a function that logs messages.
	//
	// No logging is done if Logf is nil.
	Logf func(string, ...any)

	// Output is the writer to which snapshots are written.
	Output io.Writer
}

ScriptOptions are options for running a script against