Repository navigation
Scripting the shell
sashfold --script <file> [--update-goldens] [--width N] [--height N] [--theme <file.json>] [--downloads <dir>]
--script replays a text file of commands against the shell, headless, and checks its assertions. It is the shell's test harness (the same script runs on every OS in CI and its screenshots are byte-identical) and the proof that a browser can be driven, and read back, from a text file.
- One command per line;
#starts a comment. - Relative paths resolve against the script's own directory.
- Coordinates are window coordinates; the window is 1024×720 unless
--width/--heightsay otherwise. - The built-in face alone is used, so screenshots match across machines (
--fonts systemopts out). - The clipboard is private to the process.
| Command | Does |
|---|---|
open <url|path> |
Navigate; a bare path becomes a file: URL |
navigate <typed> |
Address-bar semantics (https-first for a bare host) |
back, forward, reload
|
History |
new-tab, close-tab [n], select-tab <n>, duplicate-tab [n]
|
Tabs; key ctrl+shift+t brings the tab closed last back |
resize <w> <h> |
Resize the window (device px) |
scale <factor> |
The display's device px per CSS px from here on, as a window on a scaled display reports it: the chrome and the pages draw at the factor, scripts see it as devicePixelRatio
|
tick |
Let queued work run |
advance <ms> [<times>] |
Move the pages' clock and run the timers due, that many times over (a chain of timers each set by the last needs the steps) |
| Command | Does |
|---|---|
click <x> <y>, middle-click <x> <y>
|
A click at window coordinates |
click-text <text> |
Click the center of the first run containing the text (one run: a single word is safest) |
ctrl-click-text <text>, ctrl-shift-click-text <text>
|
The same with Ctrl held: a link opens in a tab of its own, behind the page; with Shift as well, in front of it |
right-click <x> <y>, right-click-text <text>
|
A right click: the menu of what is there |
shift-right-click <x> <y>, shift-right-click-text <text>
|
The same with Shift held: the shell's menu whatever the page says |
right-click-tab <index>, right-click-address, main-menu
|
A right click on that tab or on the address bar; a click on the main menu's button |
menu <label> |
Choose that item of the open menus, the innermost first: it runs, or its submenu opens |
menu-hover <level> <row>, menu-click <level> <row>
|
The pointer over, or a press on, that row of that open menu (the outermost is 0; a separator is a row) |
press <x> <y> [<button>], release [<button>]
|
The two halves of a click, for a button held while the pointer moves (1 left, 2 middle, 3 right); the release lands where the pointer was last moved |
set-clipboard <text> |
Put text on the clipboard, which a script keeps private to the process |
move <x> <y> |
Hover |
wheel <notches> |
Scroll the content (positive rolls up) |
wheel-at <x> <y> <notches> |
The same, over one window point — the box under it takes it if it can |
scroll-pixels <dy> |
Move the content at the window's center by that many device px, as a finger's drag does (positive brings what is below into view) |
type <text> |
Type into whatever has focus |
preedit <text> |
An input method's composing text at the caret of the focused field, underlined; no text clears it |
assert-text-input on|off |
Whether a field has a caret an input method would be told about |
window-controls on|off |
The frame is the shell's to draw, as on a compositor without server-side decorations |
assert-window-request <what> |
What the last press asked of the window, and takes it: none, move, minimize, maximize, close, or resize-<edge> (top, bottom-right, …) |
window-active on|off |
Whether the window is the one in front, as the system says when another takes its place |
assert-theme-problem none|<text> |
What the theme in use could not put on — a picture it names that is not there — holds the text, or is nothing |
import-theme <path> |
A Firefox or Chrome theme — its folder, its .xpi, its .crx, named relative to the script — converted and put on, as one dropped into the profile's themes folder is |
key <chord> |
A key, e.g. Enter, Escape, ctrl+l, alt+left, ctrl+shift+tab, f12, menu, shift+f10
|
drag <x1> <y1> <x2> <y2> |
Press, move, release the left button |
focus <name> |
Focus the first form control with that name |
select-text <text> |
Select the first run's occurrence of the text |
reader |
Toggle reader mode |
inspect-text <text> |
Devtools: inspect the element of the first run containing the text |
| Command | Checks |
|---|---|
assert-url <url>, assert-address <text>, assert-title <text>
|
The current page |
assert-text <text>, assert-no-text <text>
|
Text present or absent on the page |
assert-status <text> |
What the shell has to say — where a link leads, a notice, Done — whether or not it is showing: Done is never shown |
assert-tabs <n>, assert-scroll <n>, assert-scrolled
|
Tabs and the page's scrolling |
assert-tab-titles <A | [B] | C> |
Every tab's title in the strip's order, the tab in front in brackets |
assert-closed-tabs <n> |
How many closed tabs could come back |
assert-box-scroll <x> <y> <dx> <dy> |
How far the box that scrolls under that window point has moved its content |
assert-pixel <x> <y> <#rrggbb> |
One pixel of the frame |
assert-focus address|page |
Where keyboard focus is |
assert-value <name> <text> |
A control's current value |
assert-focused <name> |
The focused control ("" for none) |
assert-selection <text> |
The selected text (one line) |
assert-find <text> |
The find bar's count: 3 of 12, No matches, "" when closed |
assert-hints <n> |
The number of link-hint labels showing |
assert-menu <items> |
The innermost open menu, its items joined by |: a separator is -, an item that cannot be chosen is in parentheses, a checked one follows *, one with a submenu precedes >; nothing when no menu is open |
assert-menus <n> |
How many menus are open, submenus counted |
assert-clipboard <text> |
What the clipboard holds |
assert-inspected <tag#id.class> |
The inspected element |
assert-golden <png> |
The frame's bytes equal the file; --update-goldens blesses |
mark |
Records the restyle, relayout and paint counters as they stand; the assertions below read what changed since (the counters themselves are read, never set) |
assert-restyles <n> |
The number of restyles since the last mark
|
assert-relayouts <n> |
The number of relayouts since the last mark
|
assert-paints <n> |
The number of frames painted since the last mark
|
assert-pictures <n> |
The number of the page's pictures decoded so far |
| Command | Does |
|---|---|
screenshot <path> |
Write the frame as a PNG |
echo <text> |
Print a line |
print-pixel <x> <y> |
Say what the frame holds there; never fails |
find-pixel <#rrggbb> [<x> <y> <w> <h>] |
Say where the frame is exactly that color, in the box or anywhere: the first few places and how many in all; never fails |
tests/shell/ holds smoke.script, forms.script, selection.script, find.script, reader.script, hints.script and devtools.script, each with its goldens under tests/shell/goldens/, all run by CI; and live.script, which needs the network (Wikipedia, Hacker News, a real link click, example.org from the cache, badssl.com's certificate page, a Wikipedia search through a form, and Acid1) and is run by hand.
Getting started
What works today
Measured
Design decisions
Testing and tools