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>
|
Tabs |
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) |
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, …) |
key <chord> |
A key, e.g. Enter, Escape, ctrl+l, alt+left, ctrl+shift+tab, f12
|
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> |
The status bar |
assert-tabs <n>, assert-scroll <n>, assert-scrolled
|
Tabs and the page's scrolling |
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-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 |
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