ArlecchinoTestHost class

Namespace: Arlecchino.Testing · Assembly: Arlecchino.Testing

A whole application wired up for a test: real services, a terminal in memory, and no loop in the background. Frames are drawn when asked for, so a test presses keys and then reads the screen.

public sealed class ArlecchinoTestHost : IDisposable

Implements IDisposable

Constructors

Member	Summary
ArlecchinoTestHost(int, int, Action<ArlecchinoBuilder>)	Builds the application, with the minimum size dropped to one cell and color fixed at ColorSupport.TrueColor. Assign TerminalCapabilities.Color to change it.

Properties

Member	Summary
Clock	The clock scheduled work runs on, moved by ArlecchinoTestHost.Advance.
History	Undo history. It is resolved as the host is built, so edits are recorded from the start.
Navigator	Navigation, for checking or forcing which view is current.
Options	The settings, for changing them after the application is built.
Repaint	The repaint flag, for checking that something actually asked for a frame.
Screen	What the screen holds after every frame drawn so far. ArlecchinoTestHost.FrameLines reads the last frame as it was written, which is the whole picture only while frames are written whole; this is the picture itself, diffed frames and all.
Services	The container, for reaching whatever the test registered.
State	The shared state, for opening dialogs or reading the output line.
Surface	The cell grid, for tests that draw into it directly.
Terminal	The terminal being drawn to, for asserting on raw output or resizing mid-test.

Methods

Member	Summary
Advance(TimeSpan)	Moves the clock forward and runs whatever fell due, exactly as the frame loop would. The frame is not drawn by this — ask for one afterward.
Click(int, int, MouseButton)	Clicks a cell, in the terminal's own coordinates.
Dispose()	Disposes the container and everything in it, and drops work still posted to the frame.
DrainInput()	Routes whatever the reader has queued, which is what the frame loop does before it draws. ArlecchinoTestHost.ReadFromTerminal and ArlecchinoTestHost.Frame do it for you; call it yourself after driving TerminalInputReader directly, since the reader queues rather than routes.
Frame()	Draws a frame as the difference from the last one, the way a running application does, and returns the whole screen afterward with the styling stripped away.
FrameContains(string)	Whether a frame holds some text anywhere. Text split across rows will not be found.
FrameLineContaining(string)	The first row holding some text, which is how a test reads what was drawn beside a label.
FrameLines()	Draws a frame and returns the rows on screen afterward.
Press(ConsoleKey, KeyModifiers)	Presses a key, routed exactly as a real key press is.
ReadFromTerminal(string)	Feeds raw characters through the reader that recognizes escape sequences. This is the way to test what a real terminal sends for arrows, function keys and mouse reports.
Scroll(int, int, bool)	Turns the wheel over a cell.
Send(KeyPress)	Routes a key exactly as the terminal reported it, character and all, for a key played back from a SessionTape. A test writing keys by hand reaches for ArlecchinoTestHost.Press instead.
Send(MouseEvent)	Routes a mouse event exactly as the terminal reported it.
SendPaste(string)	Pastes a block of text, as bracketed paste delivers it.
Styles()	Draws a frame whole and returns the color sequences in it, in order. A diffed frame would carry only the styles of the cells it rewrote.
Type(string)	Types text one character at a time. The presses carry a character but no key, which is what a terminal reports for ordinary typing.

Constructors in detail

ArlecchinoTestHost(int, int, Action<ArlecchinoBuilder>)

public ArlecchinoTestHost(
    int width = 80,
    int height = 24,
    Action<ArlecchinoBuilder>? configure = null);

Builds the application, with the minimum size dropped to one cell and color fixed at ColorSupport.TrueColor. Assign TerminalCapabilities.Color to change it.

Parameters

Name	Type	Description
width	int	Columns of the fake terminal.
height	int	Rows of the fake terminal.
configure	Action<T><ArlecchinoBuilder>	Registers the views, commands and services under test.

Properties in detail

Clock

public TestClock Clock { get; }

The clock scheduled work runs on, moved by ArlecchinoTestHost.Advance.

Type TestClock

History

public AtomHistory History { get; }

Undo history. It is resolved as the host is built, so edits are recorded from the start.

Type AtomHistory

Navigator

public Navigator Navigator { get; }

Navigation, for checking or forcing which view is current.

Type Navigator

Options

public ArlecchinoOptions Options { get; }

The settings, for changing them after the application is built.

Type ArlecchinoOptions

Repaint

public Repaint Repaint { get; }

The repaint flag, for checking that something actually asked for a frame.

Type Repaint

Screen

public ScreenGrid Screen { get; }

What the screen holds after every frame drawn so far. ArlecchinoTestHost.FrameLines reads the last frame as it was written, which is the whole picture only while frames are written whole; this is the picture itself, diffed frames and all.

Type ScreenGrid

Services

public IServiceProvider Services { get; }

The container, for reaching whatever the test registered.

Type IServiceProvider

State

public ArlecchinoState State { get; }

The shared state, for opening dialogs or reading the output line.

Type ArlecchinoState

Surface

public Surface Surface { get; }

The cell grid, for tests that draw into it directly.

Type Surface

Terminal

public FakeTerminal Terminal { get; }

The terminal being drawn to, for asserting on raw output or resizing mid-test.

Type FakeTerminal

Methods in detail

Advance(TimeSpan)

public void Advance(TimeSpan amount);

Moves the clock forward and runs whatever fell due, exactly as the frame loop would. The frame is not drawn by this — ask for one afterward.

Parameters

Name	Type	Description
amount	TimeSpan	How far to move the clock.

Click(int, int, MouseButton)

public void Click(int row, int column, MouseButton button = Left);

Clicks a cell, in the terminal's own coordinates.

Parameters

Name	Type	Description
row	int	Row, counted from the top of the terminal.
column	int	Column, counted from its left edge.
button	MouseButton	Which button was pressed.

Dispose()

public void Dispose();

Disposes the container and everything in it, and drops work still posted to the frame.

DrainInput()

public void DrainInput();

Routes whatever the reader has queued, which is what the frame loop does before it draws. ArlecchinoTestHost.ReadFromTerminal and ArlecchinoTestHost.Frame do it for you; call it yourself after driving TerminalInputReader directly, since the reader queues rather than routes.

Frame()

public string Frame();

Draws a frame as the difference from the last one, the way a running application does, and returns the whole screen afterward with the styling stripped away.

Returns string — The screen.

FrameContains(string)

public bool FrameContains(string text);

Whether a frame holds some text anywhere. Text split across rows will not be found.

Parameters

Name	Type	Description
text	string	What to look for.

Returns bool — true when it is there.

FrameLineContaining(string)

public string FrameLineContaining(string text);

The first row holding some text, which is how a test reads what was drawn beside a label.

Parameters

Name	Type	Description
text	string	What to look for.

Returns string — The whole row, or an empty string when no row holds it.

FrameLines()

public string[] FrameLines();

Draws a frame and returns the rows on screen afterward.

Returns string[] — One string per row.

Press(ConsoleKey, KeyModifiers)

public void Press(ConsoleKey key, KeyModifiers modifiers = None);

Presses a key, routed exactly as a real key press is.

Parameters

Name	Type	Description
key	ConsoleKey	The key.
modifiers	KeyModifiers	What was held with it.

ReadFromTerminal(string)

public void ReadFromTerminal(string sequence);

Feeds raw characters through the reader that recognizes escape sequences. This is the way to test what a real terminal sends for arrows, function keys and mouse reports.

Parameters

Name	Type	Description
sequence	string	The characters, escapes included.

Scroll(int, int, bool)

public void Scroll(int row, int column, bool down);

Turns the wheel over a cell.

Parameters

Name	Type	Description
row	int	Row the pointer is over.
column	int	Column the pointer is over.
down	bool	Whether the wheel turned down.

Send(KeyPress)

public void Send(KeyPress key);

Routes a key exactly as the terminal reported it, character and all, for a key played back from a SessionTape. A test writing keys by hand reaches for ArlecchinoTestHost.Press instead.

Parameters

Name	Type	Description
key	KeyPress	The key as the terminal reported it.

Send(MouseEvent)

public void Send(MouseEvent mouse);

Routes a mouse event exactly as the terminal reported it.

Parameters

Name	Type	Description
mouse	MouseEvent	The event.

SendPaste(string)

public void SendPaste(string text);

Pastes a block of text, as bracketed paste delivers it.

Parameters

Name	Type	Description
text	string	What was pasted.

Styles()

public IReadOnlyList<string> Styles();

Draws a frame whole and returns the color sequences in it, in order. A diffed frame would carry only the styles of the cells it rewrote.

Returns IReadOnlyList<T><string> — The sequences as they appeared.

Type(string)

public void Type(string text);

Types text one character at a time. The presses carry a character but no key, which is what a terminal reports for ordinary typing.

Parameters

Name	Type	Description
text	string	What to type.