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
- type EmulatorViewOptions
- type RobotView
- type RobotViewOptions
- type RunScriptsOptions
- type ScriptOptions
Constants ¶
const ( // DefaultWidth is the default terminal width. DefaultWidth = 80 // DefaultHeight is the default terminal height. DefaultHeight = 24 )
Variables ¶
This section is empty.
Functions ¶
func RunScripts ¶ added in v0.10.0
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 ¶ added in v0.10.0
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 ¶ added in v0.10.0
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 ¶ added in v0.10.0
Emulator is a terminal emulator that receives input and allows querying the terminal state.
type EmulatorView ¶ added in v0.10.0
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 ¶ added in v0.10.0
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 ¶ added in v0.10.0
func (e *EmulatorView) Close() error
Close closes the EmulatorView and frees its resources.
func (*EmulatorView) FeedKeys ¶ added in v0.10.0
func (e *EmulatorView) FeedKeys(keys string) error
FeedKeys feeds the given keys to the terminal emulator.
func (*EmulatorView) Prompt ¶ added in v0.10.0
func (e *EmulatorView) Prompt(fs ...ui.Field) error
Prompt prompts the user for input with the given interactive fields.
func (*EmulatorView) Rows ¶ added in v0.10.0
func (e *EmulatorView) Rows() []string
Rows returns a list of rows in the terminal emulator.
type EmulatorViewOptions ¶ added in v0.10.0
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.
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 ¶ added in v0.10.0
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 ¶ added in v0.10.0
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