Skip to content

Testing your UI

Every Tessel app can run headless: without opening a window, driven by a script of clicks and key presses. It can print the view tree so you can check what’s on screen, and render screenshots. That makes UI tests easy to write and fast to run, and it’s how Tessel tests its own UI and IDE.

Take the counter app:

app Counter(width: 320, height: 200) {
state count = 0
VStack(spacing: 12) {
Text("Count: {count}")
.font(size: 32, weight: .bold)
HStack(spacing: 8) {
Button("-") { count -= 1 }
Button("+") { count += 1 }
}
}
.padding(24)
}

Build it, then run it with the TESSEL_SCRIPT environment variable set to a script. Commands are separated by ; or new lines:

Terminal window
tessel build counter -o counter-app
TESSEL_SCRIPT='tree; click "+"; click "+"; dump' ./counter-app

Instead of opening a window, the app runs the script and prints:

Root
View
VStack
Text "Count: 0"
HStack
Button "-"
Button "+"
Root [0,0 320x200]
View [73,37 174x126]
VStack [73,37 174x126]
Text "Count: 2" [97,61 126x38]
HStack [121,111 78x28]
Button "-" [121,111 34x28]
Button "+" [163,111 36x28]

tree printed the views, click "+" pressed the plus button twice, and dump printed the views again, this time with their positions. When the script ends, the app exits.

tessel run passes the environment on to your program, so TESSEL_SCRIPT='…' tessel run counter works too. Without TESSEL_SCRIPT, it opens a window as usual.

CommandWhat it does
size 400 300Sets the window size, in points. The app starts at the size its app declaration gives.
click "Save"Clicks the first view with this label (see below).
click 40 60Clicks at a point, in points from the window’s top left corner.
click shift "Alan"Clicks with Shift held (or cmd): for selecting a table’s rows.
click button 2Clicks the 2nd view of a kind: button, toggle, field, text, editor, slider, stepper or colorpicker. Counting starts at 1.
click editor "print(|count"Clicks in a code editor’s text, where it first has this text: the caret goes before the character after the | (or the first one, without a |). It’s the editor being edited, or else the first one shown. click cmd editor "…" is a Cmd-click there, for onDefinition.
hover "Save"Moves the mouse pointer over the first view with this label, to show hover backgrounds.
hover 40 60Moves the pointer to a point.
hover editor "le|t count"Moves the pointer over a character of a code editor’s text, found as click editor finds it, for its onHover.
close "main.tsl"Clicks the close button of the tab with this title.
clicktext 3 5Clicks at line 3, column 5 (both from 1) of the code editor being edited, or of the first one. clicktext alt 3 5 adds a cursor there, clicktext shift 3 5 selects up to there.
clickfold 3Clicks the fold arrow beside line 3 of the code editor being edited (or the first one), to fold or unfold its block.
type hello worldTypes text into the text field or code editor being edited.
type "two words "The same, in quotes to keep spaces at the start or end.
key enterPresses a key, optionally with modifiers (see below). key shift presses a modifier on its own.
keyup spaceLets a key go, for .onKeyEvent(releases: true).
drag 150 100 40 0Presses the mouse at a point and moves it by 40 points across and 0 down, for views with .onDrag, sliders and scroll bars.
dragto "Roads" "Parcels"Drags the view with .draggable at the first label onto the second, and lets go there (or dragto 40 60 40 200, with points).
scroll 0 120Scrolls the scroll view (or code editor) under the middle of the window down by 120 points. A negative number scrolls up.
wheel 40 60 0 120The same, for what’s at a point: here (40, 60).
press 40 60Presses the mouse on a view with .onPointer or .draggable (also press "Label"). Add right or middle for another button.
move 80 60Moves the mouse there (or move "Label"): a drag while it’s pressed.
releaseLets the mouse button go (release 90 60: somewhere else).
rightclick 40 60A click with the right button, on a view with .onPointer, or one with a context menu, which opens (rightclick "Roads": on a labelled view; rightclick editor "…": on a code editor’s text, as click editor finds it).
doubleclick 40 60Two clicks in a row there.
pinch 40 60 0.2A trackpad pinch that makes things a fifth larger.
mods shift+altHolds modifier keys for the mouse commands that follow; mods none lets them go.
drop "/tmp/a.csv"Drops a file on the window, for .onDrop.
open "/tmp/a.note"The system asks the app to open a file, for .onOpenFile.
menu "File" "Save"Chooses an item of the menu bar, by the titles of its menus and its own.
menusPrints the menu bar: every menu and item, with shortcuts.
menubar drawnDraws the menu bar in the window, as on Windows (menubar native: as on macOS, outside the window). Scripts start as the platform does.
close windowThe user closes the window: .onCloseRequest runs, or it closes.
quitThe user quits the app (Cmd+Q).
window "Table"Sends the commands after it to another window (window main: back to the main one).
answer "notes/a.note"Sets the path the next file dialog returns.
answer cancelMakes the next file dialog return nil, as if the user cancelled.
wait 1.5Lets 1.5 seconds pass, running any timers that are due and letting background work they start finish. See Time and background work.
waitfor "Done"Waits until a view with this label is there: for what a load, a timer, or a program started with runCommand and input: true brings about, which wait doesn’t wait for. See Time and background work.
repeat 20 key downRuns a command several times.
compose "ni"Text an input method is composing in the field being edited; tree shows it. A type after it is what it became.
reloadWith tessel run --hot: takes the program’s new code now, if its files changed. (A scripted run doesn’t watch the files by itself.)
appearance darkSwitches to the dark (or light) appearance. Scripted runs start light, whatever the system’s setting, unless the app asks for one.
animations onTurns animations on. Scripted runs have them off, so views are at once where they end up; with them on, wait lets them move, and dump and snapshot show them on their way.
snapshot out.pngRenders the window to a PNG file, at twice the size in pixels (like a Retina screen).
layout out.jsonWrites the views on screen to a file as JSON: each one’s depth in the tree, kind and place. tessel preview uses it.
treePrints the view tree, with the open menu after it, the menu bar’s titles first, and the app’s other open windows last. A window’s status bar is StatusBar, after its other views.
dumpPrints the view tree with each view’s position and size.
editingPrints the text being edited with its cursors marked (see Checking the cursors).
accessibilityPrints what a screen reader is told is in the window: each control and text, with what it’s called and what it holds.

Before each command, the app is brought up to date: state changes from the previous command are applied, the views are rebuilt and laid out. .onAppear blocks have already run when the first command starts.

click "label" looks for the first view, from top to bottom through the tree, whose label is exactly the given text:

  • a Text’s text, a Button’s or Toggle’s label;
  • a TextField’s placeholder;
  • an Icon’s name, such as click "trash" for Icon(.trash);
  • a tab’s title in a TabView, or a DisclosureGroup’s title;
  • a color in an open ColorPicker’s palette, by its hex code, like click "#000000";
  • failing all of those, any view’s .accessibilityLabel or .tooltip, for views with no text, like a toolbar of Svg pictures or a Canvas.

It clicks the middle of that view. Hidden views, and pages of a TabView that aren’t selected, are skipped.

Clicking a text field or code editor starts editing it, as in a real window, so click "Name" followed by type Sam fills in the field with the placeholder “Name”.

When there’s nothing to click, the script stops with an error.

hover "label" finds a view the same way, but only moves the pointer over its middle without clicking, so a snapshot afterwards shows its hover background.

type inserts text at the cursor of the field being edited. Everything after type is typed; put it in quotes to keep leading or trailing spaces. Because ; separates commands, typed text can’t contain one. Typing into a code editor gets the same automatic indentation as real typing does. The text goes in as one edit, as a paste does, so the field’s onChange runs once for it. click on a toggle or a picker’s option, and key on one with the keyboard, run their onChange as a person’s clicks and keys do. While no field is being edited, each character is a key press instead, as it would be on a keyboard (with Shift for capitals and for symbols like %), so it reaches .onKeyEvent and .onKey.

key presses one key: backspace, delete, left, right, up, down, home, end, pageup, pagedown, enter, tab, escape, space, f1 to f12, or a character, which types it in a field being edited. Add modifiers in front, joined with +:

key shift+left select one character to the left
key alt+backspace delete a word
key cmd+a select all
key cmd+shift+z redo
key cmd+s run a .shortcut("s")
key shift+a type "A" (or an .onKeyEvent gets "a" with shift)
key shift+5 type "%", as on a US keyboard (an .onKeyEvent gets "5")
key repeat+down a key held down (repeated is true)

cmd and ctrl mean the same thing: the platform’s shortcut key (Cmd on macOS, Ctrl on Windows). alt is Option on macOS. So scripts behave the same on both systems. control is the Ctrl key itself, as KeyEvent’s control sees it.

The clipboard in a headless run is private to the script: cmd+c and cmd+v work, but never touch your real clipboard. copyToClipboard and clipboardText use that same private clipboard, so text copied with one can be pasted with the other. openURL doesn’t open anything; it prints (open …) instead.

tree shows a field’s or code editor’s text, but not where its cursor is. editing prints the text being edited, with | where each cursor is and « and » around each selection (the | inside shows which end moves). Each line of the text is indented by two spaces. For a code editor, the first line also says how many cursors it has and which lines start a folded block:

Editing CodeEditor, 2 cursors, folded [1]
fn a() {
let x = 1
}
«print|»(x)
«print|»(y)

When nothing is being edited, it prints Editing nothing.

In a headless run, the clock stands still unless you move it. wait 2 moves it forward by two seconds and runs every after and every timer that comes due, in order (including timers those timers start). So a test of a 10-second countdown finishes instantly.

now() reads the same clock: it starts at the real time when the script starts, and moves only with wait, so each timer sees the time it came due at. Code that works out how far along something is from now(), like an animation of its own, is tested the same way as one that counts timer ticks. (A loop that waits for now() to move never ends in a headless run; use after instead.)

wait also first lets any running fetch, request, download, runCommand and background calls finish and delivers their callbacks. Use wait 0 after starting one to wait for its result, without moving the clock:

click "Check"
wait 0
tree

An open WebSocket doesn’t finish by itself, so wait doesn’t wait for it to close. Instead, while one is open, wait gives its messages real time to arrive: half a second, or the wait’s length if that’s longer.

Background work that starts while wait moves the clock finishes the same way. Before the clock passes the next timer, wait lets work in progress finish and runs its callbacks, also for work those callbacks start. So a timer that starts a fetch, whose result starts the next one, keeps going as it would in a window, and each result arrives at the time its timer fired. This waiting takes at most a minute of real time per wait; after that, the clock moves on without it.

waitfor "label" checks for the label, runs the callbacks of finished background work, and runs timers that are due. When nothing is running (no loads, background work, commands or open WebSockets), it moves the clock on to the next timer, so a label that only a timer brings about appears:

waitfor "Saved"
tree

waitfor gives up, and the script fails, if the label isn’t there after a minute of real time, or after it has moved the clock an hour on. (An app with an every timer always has a next timer, so without the hour it would never stop.)

A headless run never opens a window, so it can’t show an open or save dialog either. Instead, answer says in advance what the next openFile or saveFile call returns:

answer "tests/notes/groceries.note"
click "Save…"
answer cancel
click "Open…"
tree

Here the save dialog “chooses” tests/notes/groceries.note, and the open dialog is cancelled. Each answer is used by one dialog, in order, so you can queue several before a click that opens more than one. A dialog with no answer waiting returns nil, like a cancelled one.

A relative path is relative to the folder the app was started from. Like the real save dialog, a saveFile answer without the file type’s extension gets it added (answer "report" with types: ["och"] saves report.och).

tree and dump print one line per view, indented by nesting. Custom views and the body of the app show up as View. Values are shown where it helps:

TextField "What needs doing?" = "Buy milk"
Toggle "Gift wrap" = true
TabView ["Problems", "Console"] selected 0
CodeEditor errors [2] = "app Hello {\n Text(\"hi\")\n}"
Icon trash
Text "secret" hidden
Button "Send" disabled
Slider = 0.7 focused
Stepper = 1.5
ColorPicker = #3478f6 open
DisclosureGroup "Layers" open
LazyVStack 100000 rows, built 1990..2020
HStack dragged

focused marks the control the keyboard is on; during a drag, dragged marks the view being dragged and drop target the one under the mouse. A code editor’s errorRanges and highlights show as underlined [28..33 "cuont"] and highlights [4..9 "count"]: the byte offsets, and the text there.

dump adds [x,y widthxheight] in points after each view, which is useful for checking a layout. Anything your program prints with print appears in the same output, in order.

A Canvas shows what its block drew, like Canvas (2 fills, 1 stroke, 3 texts), and a tooltip that’s showing is printed after the tree: Tooltip "Delete the selected rows" (it comes up when a wait of 0.6 seconds or more follows a hover). So is a code editor’s hoverText: after hover editor "…", a wait 0.5 tells its onHover, and what that sets shows (a wait 0 more lets a command it starts finish first).

On a view with .onPointer, click, drag and hover send it the events a real mouse would: a press and a release, a press, a move and a release, or a move. key x (or type x) while no field is being edited goes to .onKeyEvent and .onKey.

press on a view with .draggable, then move, holds it over what’s there (a tree or snapshot shows the drag on its way), and release drops it; key escape before the release cancels it. dragto does it all in one go:

dragto "Roads" "Parcels"
press "Imagery"
move "Rivers"
snapshot dragging.png
release

snapshot renders exactly what the window would show, including the text cursor and selection (the screenshots on this site were made with it).

If a command is unknown, or a click, close or hover finds nothing, the app prints an error starting with script: and exits with code 2. Otherwise it exits with code 0 when the script is done.

A simple way to test an app is to keep a script and the output you expect, and compare:

Terminal window
tessel build todos -o todos-app
TESSEL_SCRIPT="$(cat todos.script)" ./todos-app > todos.actual
diff todos.out todos.actual

That’s exactly how Tessel’s own tests work. In the repository, each tests/run/app_*.tsl program has:

  • app_name.script, the script to run;
  • app_name.out, the expected output.

The test runner (cargo test, in crates/tessel-cli/tests/run.rs) builds each program, runs it from the repository root with TESSEL_SCRIPT set to the script, and fails if the output differs from the .out file or anything is printed to standard error. On macOS it also checks for memory leaks. For example, this is tests/run/app_todos.script, which adds to-dos (with a typo fixed by Backspace), ticks one off and tries the filter:

click "What needs doing?"
type Write the spec
click "Add"
click "What needs doing?"
type Build M3
click "Add"
click "What needs doing?"
type Ship itt
key backspace
key enter
click "Add"
click "Add"
tree
click toggle 1
click "Active"
tree
click "Done"
tree

The Tessel IDE is tested the same way: tests/ide/session.script creates a file, types code into the editor, undoes, saves with cmd+s, renames and deletes files, and checks the result.