mygo-automation
mygo-automation drives a running MyGo app through the socket of its
automation plugin (github.com/egoist/mygo/plugins/automation). It is
the guide of the version you run, as mygo-automation version tells. If
the app's MyGo is another version, install the matching one (see
"Installing").
The loop is: snapshot → act with --settle → read the diff → act
again. Diffs carry the refs you act on next, so a new snapshot is
seldom needed.
mygo-automation open --socket /tmp/app.sock
mygo-automation snapshot -i
# @e2 [button] "Add" key=add
# @e3 [textField] "Name" key=name
mygo-automation press @e2 --settle
# - @e1 [text] "Count: 0"
# + @e1 [text] "Count: 1"
# = @e2 [button] "Add" key=add
mygo-automation fill @e3 "Ada" --settle
mygo-automation screenshot /tmp/app.png
mygo-automation close
The app
The app must link the plugin and be started with MYGO_AUTOMATION, the
path of the socket it listens on. A file of the app's, kept out of its
release by a build tag:
//go:build e2e
package main
import _ "github.com/egoist/mygo/plugins/automation"
go build -tags e2e -o /tmp/app . && MYGO_AUTOMATION=/tmp/app.sock /tmp/app &
Any way of starting it works if the variable reaches it; mygo dev
passes its environment to the app. Builds without the inspector
(-tags mygo_noinspector, release builds of mygo build without
-debug) leave the plugin out: they say so on standard error and never
listen. The socket is the user's alone. Pick a path in a directory only
the user can write to; nothing else is needed to connect, and there is
no discovery: the path is the one you gave MYGO_AUTOMATION.
Sessions
open [--socket <path>] attaches a session to the app and lists its
windows. Without --socket it takes $MYGO_AUTOMATION. Opening again
keeps the session's name but forgets what it saw: every ref given
before goes stale.
close ends the session and forgets its refs. The app keeps
running. To quit it, choose its menu item (menu <App> Quit, when
it has one) or end its process yourself.
- Every command takes
--session <name> (default:
$MYGO_AUTOMATION_SESSION, else default), letters, digits, .,
_ and -. Sessions keep their socket, chosen window and refs apart,
in files of their own in the user's cache directory
(mygo/automation/<name>.json). Give each agent, or each app, a session
of its own; run one command at a time in a session.
Reading the UI
snapshot prints the elements of a window of native UI, one per line, a
child indented under the element shown above it, in tree order:
@e1 [dialog] "Settings"
@e2 [checkBox] "Dark mode" key=dark checked focused
@e3 [textField] "Name" value="Ada" key=name
@e4 [slider] "Volume" value=0.25
@e5 [button] "Save" disabled
announced "Saved"
A line is the element's ref, [role], its label in quotes, then what
it has of value=, placeholder= (when it has no label), key= (the
app's own name for it), its states, current= (what it is the current
one of, as the last crumb of a breadcrumb trail is the page),
autocomplete= (what a field's suggestions complete as you type: list
for a popup of them, inline for the text completed in place, or
both), haspopup=, roledescription= and focused. Empty fields are left
out, and so is focusable, which every control is. webview marks a web
view inside native UI: its page has no elements here. announced lines
are what the app announced to screen readers. Labels and values longer
than 120 characters are cut, ending in …" (N more).
keyshortcuts= (after key=) is the keys the app says press or focus
the element, as screen readers read them (aria-keyshortcuts): "⌘K"
on macOS, "Ctrl+K" elsewhere, several separated by spaces.
-i (--interactive) keeps controls and elements with actions:
buttons, fields, check boxes, links, list items you can press, and so
on. Elements left out still get refs, and diffs show them.
--full adds placeholders, descriptions, ranges (range=0..1 step=0.1), text selections (selection=3,3, in characters), levels,
positions in sets (item=2/5), the size of a table or a grid and
the place of a row or a cell in it as the app gave them
(rowcount=10001 colcount=5, rowindex=4122 colindex=2), the rows
and columns a cell covers (colspan=2), actions, bounds=x,y,wxh and the full
element ID (id=…), and writes long text whole.
--json prints the plugin's answer as it is (IDs, keys, bounds, all
fields) on one line. It still takes the window's elements for later
diffs and gives refs, which it does not print.
--window <w> reads another window (see "Windows and pages").
Roles are group, text, heading, button, link, checkBox,
radio, switch, slider, progress, meter, stepper,
textField, comboBox, popUpButton, menuButton, toggleButton,
image, list, listItem, table, grid, treeGrid, row, cell, columnHeader,
tree, treeItem, tabList, tab, scroll, dialog, alertDialog,
popup, tooltip, splitter, status, toolbar, radioGroup,
disclosure, colorWell, menu, menuBar, menuItem,
menuItemCheckBox, menuItemRadio, region, log, timer, alert,
separator, rowHeader, search, article, navigation, deletion,
insertion, tabPanel, main, banner, contentInfo and
complementary. States are disabled, checked,
mixed, selected, expanded, expandable, multiline, password,
readOnly, selectable, multiselectable, offscreen, segment,
search, invalid, sortAscending, sortDescending, sortOther,
vertical, horizontal and busy. current= is true, page, step, location,
date or time; haspopup= the kind of popup the element opens
(menu, listbox, tree, grid or dialog), and roledescription=
what the app calls its role.
Only what assistive technology reads is there: rows and columns that
only lay out others have no line.
Selectors
Commands that act on an element take one of:
| Selector |
Names |
@e7 (or e7) |
the element a snapshot or diff gave that ref, in its window |
key=<key> |
the one element of the window whose key the app set (Element.Key, Context.Key) |
id=<digits> |
the element with that ID, as --full and --json show |
Write keys as lines show them: key=add, key=7 (a number), key=true
(a boolean), key='"7"' or key='"two words"' (strings that need JSON's
quotes, quoted again for the shell). A key two elements share is refused:
use a ref. Prefer keys when the app gives them; they last across runs.
Refs
- Refs come from
snapshot, diff and --settle. Use the refs of the
latest output for a window.
- An element keeps its ref while the window shows it: after
press @e2 --settle, @e2 still names the same button, printed or not.
- New elements get new numbers. A ref is never given twice in a session,
so it can't come to name another element.
- A ref goes stale once a snapshot or diff of its window shows its
element gone, or the app answers that it is gone. A stale ref is
refused, never retargeted:
error: stale ref @e4: its element is gone; use a ref from the latest snapshot or diff (run snapshot).
An element that comes back gets a new ref.
- A ref carries its window: commands on it go there, whatever
window
or --window says.
open again, or close, ends every ref of the session.
Acting
| Command |
Does |
press <sel> |
presses, as assistive technology does: clicks a button, toggles a check box, opens a menu button |
focus <sel> |
gives the element the keyboard focus |
fill <sel> <text> |
replaces a text field's text ("" empties it) |
act <sel> <action> [args] |
any action: press, focus, increment, decrement, setValue <text>, insertText <text> (at the caret), selectText <from> <to> (characters), scrollIntoView, expand, collapse |
click <sel> or click <x> <y> |
a pointer click at the element's center, or at a point; --button left|right|middle, --clicks 2 for a double click, --mods shift,ctrl,alt,super,cmdOrCtrl |
pointer move|down|up <sel>|<x> <y> |
one pointer event, with the same flags, for drags and hovers |
wheel <sel>|<x> <y> <dx> <dy> |
scrolls by dx, dy DIPs (negative dy scrolls up); --precise as a touchpad, --mods |
type <text> |
types text into the focused element, as the keyboard does |
key <key>... |
presses and releases keys in order, written as menu accelerators: Enter, Escape, Tab, Shift+Tab, Backspace, Delete, Up, PageDown, Home, F2, a, CmdOrCtrl+A, CmdOrCtrl+Shift+Z; --down or --up sends only the press or the release |
menu <label>... |
chooses an item of the application menu by the labels along its path: menu File "New Window" |
Points are in DIPs, from the top left corner of the window's content, as
bounds= shows. Prefer press and fill to click and type: they
need no coordinates and no focus. A key types no text: send text with
type. A modifier alone (key Shift) is no key. Without --settle, an
action prints ok once the app took it, which may be before it drew.
press, focus, fill, act, click, pointer, wheel, type,
key, menu and wait take --window <w> (for coordinates, keys,
text and menus), --settle and --timeout <d>.
Settle and diff
--settle waits until the window has drawn every frame it asked for (the
plugin's idle), for --timeout (default 10s; 500ms, a number of
milliseconds, or 0 to wait as long as it takes), then prints what
changed since the last snapshot or diff of that window, and takes what it
shows now for the next diff:
= @e2 [button] "Add" key=add
- @e3 [textField] "Name" key=name
+ @e3 [textField] "Name" value="Ada" key=name focused
+ @e4 [text] "Hello, Ada"
- @e9 [dialog] "Unsaved changes"
+ an element that came, with its new ref, or an element as it is now.
- an element that went, with its now stale ref, or an element as it
was before: a changed element shows as - then +, with one ref.
= an unchanged element next to a change, for context, with its ref.
(no changes) when nothing changed. Moves and bounds are not changes.
A window that never settles, as one with a spinner, warns on standard
error after --timeout and prints the diff anyway. diff prints the
same without acting or waiting. An action on a ref diffs the ref's
window. One that names no window (type, key, menu, points) while
the session targets the focused window diffs the window focused once it
settled: a window it opened comes as + lines.
Waiting
wait waits for the window to settle (--timeout, as above).
wait <sel> waits until the window shows the element; wait --text <s> until an element's label or value contains s (case sensitive).
These check the condition while the window keeps drawing; --settle
waits for it to settle after the condition is met.
--gone waits until it no longer shows it, as a dialog closing.
- It prints
ok, or with --settle the diff. After --timeout it fails
with timeout. Never sleep: wait for what you expect.
Windows and pages
windows lists the windows: w1 [content] "Title" focused; [content]
shows native UI, [page] a web page, with its url=; hidden and
selected mark windows not shown and the one the session targets.
--json prints the plugin's answer.
window <w> makes commands target window w (w2 or 2) unless they
name one with --window; window auto goes back to the focused window,
the default, else the first.
- Native UI windows have elements:
snapshot, selectors, press, input.
- Page windows have none:
snapshot and input fail with unsupported.
Read and drive them with eval <script>, which prints a string as it
is and other values as JSON (--json: always JSON); eval - reads the
script from standard input. An expression's value is printed, promises
awaited, or what statements return.
- A web view inside native UI is one
webview element: neither
snapshot nor eval reaches its page.
Screenshots
screenshot <file.png> [--window <w>] saves the window as a PNG file and
prints <file> <width>x<height> in device pixels. It never prints the
image. Take one only when text does not tell you enough.
Output and errors
Output goes to standard output; errors go to standard error as
error: <message>, with exit status 1, or 2 for a command line used
wrong. Errors from the app start with its code:
| Error |
Means |
Do |
no session "<name>" |
no open for this session |
open --socket <path> |
cannot reach the app at <path> |
nothing listens: the app quit, never set MYGO_AUTOMATION, or lacks the plugin |
start the app, then open |
stale ref @eN |
the ref's element or window is gone |
snapshot, use a ref it gives |
no_window |
no window has that ID, or the app has none |
windows |
no_element |
the window shows no such element or key |
snapshot |
unsupported |
the window cannot do it, as snapshot of a page or eval in native UI |
use the other one |
timeout |
wait did not see what it waited for, or the window never settled |
look at a snapshot; raise --timeout |
invalid_request |
a value the app can't use, as an unknown key name |
fix the command |
failed |
the app could not do it, as a script that threw, or a menu item it lacks |
read the message |
Limits
- Context menus, and the menus of the Dock and of tray icons, can't be
chosen: don't open a context menu with
click --button right.
- Settling waits for frames asked for, not for timers the app set
(
Context.After) or work it does in the background: use wait <sel>
or wait --text for those.
- On Linux and Windows,
menu chooses from the window's menu bar, which
shows the application menu.
- The command does not start or quit the app.
Installing
# In the app's module directory: the version of MyGo its go.mod requires.
go install github.com/egoist/mygo/plugins/automation/cmd/mygo-automation
# Anywhere else: name that version, which this prints in the app's module.
go list -m github.com/egoist/mygo
go install github.com/egoist/mygo/plugins/automation/cmd/mygo-automation@vX.Y.Z
version prints the version of MyGo the command was built from (as
v0.8.0; (devel) or a pseudo-version for a build from a checkout), and
skills prints this guide. go install puts mygo-automation in
$(go env GOBIN), else
$(go env GOPATH)/bin. Upgrading the app's MyGo does not upgrade the
installed command: install it again, and this guide comes with it.
1---2name: mygo-automation3description: Drive a running MyGo app from the shell. Read the elements of its native UI as compact text with short refs, press, fill, click, type, send keys and wheel events, choose application menu items, evaluate scripts in windows showing a web page, wait for the UI to settle and read what changed, save screenshots.4metadata:5 source: https://skillmd.com/skills/egoist/mygo-automation6---78# mygo-automation910`mygo-automation` drives a running MyGo app through the socket of its11automation plugin (`github.com/egoist/mygo/plugins/automation`). It is12the guide of the version you run, as `mygo-automation version` tells. If13the app's MyGo is another version, install the matching one (see14"Installing").1516The loop is: **snapshot → act with `--settle` → read the diff → act17again**. Diffs carry the refs you act on next, so a new snapshot is18seldom needed.1920```sh21mygo-automation open --socket /tmp/app.sock22mygo-automation snapshot -i23# @e2 [button] "Add" key=add24# @e3 [textField] "Name" key=name25mygo-automation press @e2 --settle26# - @e1 [text] "Count: 0"27# + @e1 [text] "Count: 1"28# = @e2 [button] "Add" key=add29mygo-automation fill @e3 "Ada" --settle30mygo-automation screenshot /tmp/app.png31mygo-automation close32```3334## The app3536The app must link the plugin and be started with `MYGO_AUTOMATION`, the37path of the socket it listens on. A file of the app's, kept out of its38release by a build tag:3940```go41//go:build e2e4243package main4445import _ "github.com/egoist/mygo/plugins/automation"46```4748```sh49go build -tags e2e -o /tmp/app . && MYGO_AUTOMATION=/tmp/app.sock /tmp/app &50```5152Any way of starting it works if the variable reaches it; `mygo dev`53passes its environment to the app. Builds without the inspector54(`-tags mygo_noinspector`, release builds of `mygo build` without55`-debug`) leave the plugin out: they say so on standard error and never56listen. The socket is the user's alone. Pick a path in a directory only57the user can write to; nothing else is needed to connect, and there is58no discovery: the path is the one you gave `MYGO_AUTOMATION`.5960## Sessions6162- `open [--socket <path>]` attaches a session to the app and lists its63 windows. Without `--socket` it takes `$MYGO_AUTOMATION`. Opening again64 keeps the session's name but forgets what it saw: every ref given65 before goes stale.66- `close` ends the session and forgets its refs. **The app keeps67 running.** To quit it, choose its menu item (`menu <App> Quit`, when68 it has one) or end its process yourself.69- Every command takes `--session <name>` (default:70 `$MYGO_AUTOMATION_SESSION`, else `default`), letters, digits, `.`,71 `_` and `-`. Sessions keep their socket, chosen window and refs apart,72 in files of their own in the user's cache directory73 (`mygo/automation/<name>.json`). Give each agent, or each app, a session74 of its own; run one command at a time in a session.7576## Reading the UI7778`snapshot` prints the elements of a window of native UI, one per line, a79child indented under the element shown above it, in tree order:8081```82@e1 [dialog] "Settings"83 @e2 [checkBox] "Dark mode" key=dark checked focused84 @e3 [textField] "Name" value="Ada" key=name85 @e4 [slider] "Volume" value=0.2586@e5 [button] "Save" disabled87announced "Saved"88```8990A line is the element's ref, `[role]`, its label in quotes, then what91it has of `value=`, `placeholder=` (when it has no label), `key=` (the92app's own name for it), its states, `current=` (what it is the current93one of, as the last crumb of a breadcrumb trail is the `page`),94`autocomplete=` (what a field's suggestions complete as you type: `list`95for a popup of them, `inline` for the text completed in place, or96`both`), `haspopup=`, `roledescription=` and `focused`. Empty fields are left97out, and so is `focusable`, which every control is. `webview` marks a web98view inside native UI: its page has no elements here. `announced` lines99are what the app announced to screen readers. Labels and values longer100than 120 characters are cut, ending in `…" (N more)`.101`keyshortcuts=` (after `key=`) is the keys the app says press or focus102the element, as screen readers read them (`aria-keyshortcuts`): `"⌘K"`103on macOS, `"Ctrl+K"` elsewhere, several separated by spaces.104105- `-i` (`--interactive`) keeps controls and elements with actions:106 buttons, fields, check boxes, links, list items you can press, and so107 on. Elements left out still get refs, and diffs show them.108- `--full` adds placeholders, descriptions, ranges (`range=0..1109 step=0.1`), text selections (`selection=3,3`, in characters), levels,110 positions in sets (`item=2/5`), the size of a table or a grid and111 the place of a row or a cell in it as the app gave them112 (`rowcount=10001 colcount=5`, `rowindex=4122 colindex=2`), the rows113 and columns a cell covers (`colspan=2`), actions, `bounds=x,y,wxh` and the full114 element ID (`id=…`), and writes long text whole.115- `--json` prints the plugin's answer as it is (IDs, keys, bounds, all116 fields) on one line. It still takes the window's elements for later117 diffs and gives refs, which it does not print.118- `--window <w>` reads another window (see "Windows and pages").119120Roles are `group`, `text`, `heading`, `button`, `link`, `checkBox`,121`radio`, `switch`, `slider`, `progress`, `meter`, `stepper`,122`textField`, `comboBox`, `popUpButton`, `menuButton`, `toggleButton`,123`image`, `list`, `listItem`, `table`, `grid`, `treeGrid`, `row`, `cell`, `columnHeader`,124`tree`, `treeItem`, `tabList`, `tab`, `scroll`, `dialog`, `alertDialog`,125`popup`, `tooltip`, `splitter`, `status`, `toolbar`, `radioGroup`,126`disclosure`, `colorWell`, `menu`, `menuBar`, `menuItem`,127`menuItemCheckBox`, `menuItemRadio`, `region`, `log`, `timer`, `alert`,128`separator`, `rowHeader`, `search`, `article`, `navigation`, `deletion`,129`insertion`, `tabPanel`, `main`, `banner`, `contentInfo` and130`complementary`. States are `disabled`, `checked`,131`mixed`, `selected`, `expanded`, `expandable`, `multiline`, `password`,132`readOnly`, `selectable`, `multiselectable`, `offscreen`, `segment`,133`search`, `invalid`, `sortAscending`, `sortDescending`, `sortOther`,134`vertical`, `horizontal` and `busy`. `current=` is `true`, `page`, `step`, `location`,135`date` or `time`; `haspopup=` the kind of popup the element opens136(`menu`, `listbox`, `tree`, `grid` or `dialog`), and `roledescription=`137what the app calls its role.138Only what assistive technology reads is there: rows and columns that139only lay out others have no line.140141## Selectors142143Commands that act on an element take one of:144145| Selector | Names |146| --- | --- |147| `@e7` (or `e7`) | the element a snapshot or diff gave that ref, in its window |148| `key=<key>` | the one element of the window whose key the app set (`Element.Key`, `Context.Key`) |149| `id=<digits>` | the element with that ID, as `--full` and `--json` show |150151Write keys as lines show them: `key=add`, `key=7` (a number), `key=true`152(a boolean), `key='"7"'` or `key='"two words"'` (strings that need JSON's153quotes, quoted again for the shell). A key two elements share is refused:154use a ref. Prefer keys when the app gives them; they last across runs.155156## Refs157158- Refs come from `snapshot`, `diff` and `--settle`. Use the refs of the159 latest output for a window.160- An element keeps its ref while the window shows it: after `press @e2161 --settle`, `@e2` still names the same button, printed or not.162- New elements get new numbers. A ref is never given twice in a session,163 so it can't come to name another element.164- A ref goes **stale** once a snapshot or diff of its window shows its165 element gone, or the app answers that it is gone. A stale ref is166 refused, never retargeted:167 `error: stale ref @e4: its element is gone; use a ref from the latest snapshot or diff (run snapshot)`.168 An element that comes back gets a new ref.169- A ref carries its window: commands on it go there, whatever `window`170 or `--window` says.171- `open` again, or `close`, ends every ref of the session.172173## Acting174175| Command | Does |176| --- | --- |177| `press <sel>` | presses, as assistive technology does: clicks a button, toggles a check box, opens a menu button |178| `focus <sel>` | gives the element the keyboard focus |179| `fill <sel> <text>` | replaces a text field's text (`""` empties it) |180| `act <sel> <action> [args]` | any action: `press`, `focus`, `increment`, `decrement`, `setValue <text>`, `insertText <text>` (at the caret), `selectText <from> <to>` (characters), `scrollIntoView`, `expand`, `collapse` |181| `click <sel>` or `click <x> <y>` | a pointer click at the element's center, or at a point; `--button left\|right\|middle`, `--clicks 2` for a double click, `--mods shift,ctrl,alt,super,cmdOrCtrl` |182| `pointer move\|down\|up <sel>\|<x> <y>` | one pointer event, with the same flags, for drags and hovers |183| `wheel <sel>\|<x> <y> <dx> <dy>` | scrolls by `dx`, `dy` DIPs (negative `dy` scrolls up); `--precise` as a touchpad, `--mods` |184| `type <text>` | types text into the focused element, as the keyboard does |185| `key <key>...` | presses and releases keys in order, written as menu accelerators: `Enter`, `Escape`, `Tab`, `Shift+Tab`, `Backspace`, `Delete`, `Up`, `PageDown`, `Home`, `F2`, `a`, `CmdOrCtrl+A`, `CmdOrCtrl+Shift+Z`; `--down` or `--up` sends only the press or the release |186| `menu <label>...` | chooses an item of the application menu by the labels along its path: `menu File "New Window"` |187188Points are in DIPs, from the top left corner of the window's content, as189`bounds=` shows. Prefer `press` and `fill` to `click` and `type`: they190need no coordinates and no focus. A key types no text: send text with191`type`. A modifier alone (`key Shift`) is no key. Without `--settle`, an192action prints `ok` once the app took it, which may be before it drew.193194`press`, `focus`, `fill`, `act`, `click`, `pointer`, `wheel`, `type`,195`key`, `menu` and `wait` take `--window <w>` (for coordinates, keys,196text and menus), `--settle` and `--timeout <d>`.197198## Settle and diff199200`--settle` waits until the window has drawn every frame it asked for (the201plugin's `idle`), for `--timeout` (default `10s`; `500ms`, a number of202milliseconds, or `0` to wait as long as it takes), then prints what203changed since the last snapshot or diff of that window, and takes what it204shows now for the next diff:205206```207= @e2 [button] "Add" key=add208- @e3 [textField] "Name" key=name209+ @e3 [textField] "Name" value="Ada" key=name focused210+ @e4 [text] "Hello, Ada"211- @e9 [dialog] "Unsaved changes"212```213214- `+` an element that came, with its new ref, or an element as it is now.215- `-` an element that went, with its now stale ref, or an element as it216 was before: a changed element shows as `-` then `+`, with one ref.217- `=` an unchanged element next to a change, for context, with its ref.218- `(no changes)` when nothing changed. Moves and bounds are not changes.219220A window that never settles, as one with a spinner, warns on standard221error after `--timeout` and prints the diff anyway. `diff` prints the222same without acting or waiting. An action on a ref diffs the ref's223window. One that names no window (`type`, `key`, `menu`, points) while224the session targets the focused window diffs the window focused once it225settled: a window it opened comes as `+` lines.226227## Waiting228229- `wait` waits for the window to settle (`--timeout`, as above).230- `wait <sel>` waits until the window shows the element; `wait --text231 <s>` until an element's label or value contains `s` (case sensitive).232 These check the condition while the window keeps drawing; `--settle`233 waits for it to settle after the condition is met.234- `--gone` waits until it no longer shows it, as a dialog closing.235- It prints `ok`, or with `--settle` the diff. After `--timeout` it fails236 with `timeout`. Never sleep: wait for what you expect.237238## Windows and pages239240- `windows` lists the windows: `w1 [content] "Title" focused`; `[content]`241 shows native UI, `[page]` a web page, with its `url=`; `hidden` and242 `selected` mark windows not shown and the one the session targets.243 `--json` prints the plugin's answer.244- `window <w>` makes commands target window `w` (`w2` or `2`) unless they245 name one with `--window`; `window auto` goes back to the focused window,246 the default, else the first.247- Native UI windows have elements: `snapshot`, selectors, `press`, input.248- Page windows have none: `snapshot` and input fail with `unsupported`.249 Read and drive them with `eval <script>`, which prints a string as it250 is and other values as JSON (`--json`: always JSON); `eval -` reads the251 script from standard input. An expression's value is printed, promises252 awaited, or what statements `return`.253- A web view inside native UI is one `webview` element: neither254 `snapshot` nor `eval` reaches its page.255256## Screenshots257258`screenshot <file.png> [--window <w>]` saves the window as a PNG file and259prints `<file> <width>x<height>` in device pixels. It never prints the260image. Take one only when text does not tell you enough.261262## Output and errors263264Output goes to standard output; errors go to standard error as265`error: <message>`, with exit status 1, or 2 for a command line used266wrong. Errors from the app start with its code:267268| Error | Means | Do |269| --- | --- | --- |270| `no session "<name>"` | no `open` for this session | `open --socket <path>` |271| `cannot reach the app at <path>` | nothing listens: the app quit, never set `MYGO_AUTOMATION`, or lacks the plugin | start the app, then `open` |272| `stale ref @eN` | the ref's element or window is gone | `snapshot`, use a ref it gives |273| `no_window` | no window has that ID, or the app has none | `windows` |274| `no_element` | the window shows no such element or key | `snapshot` |275| `unsupported` | the window cannot do it, as `snapshot` of a page or `eval` in native UI | use the other one |276| `timeout` | `wait` did not see what it waited for, or the window never settled | look at a `snapshot`; raise `--timeout` |277| `invalid_request` | a value the app can't use, as an unknown key name | fix the command |278| `failed` | the app could not do it, as a script that threw, or a menu item it lacks | read the message |279280## Limits281282- Context menus, and the menus of the Dock and of tray icons, can't be283 chosen: don't open a context menu with `click --button right`.284- Settling waits for frames asked for, not for timers the app set285 (`Context.After`) or work it does in the background: use `wait <sel>`286 or `wait --text` for those.287- On Linux and Windows, `menu` chooses from the window's menu bar, which288 shows the application menu.289- The command does not start or quit the app.290291## Installing292293```sh294# In the app's module directory: the version of MyGo its go.mod requires.295go install github.com/egoist/mygo/plugins/automation/cmd/mygo-automation296# Anywhere else: name that version, which this prints in the app's module.297go list -m github.com/egoist/mygo298go install github.com/egoist/mygo/plugins/automation/cmd/mygo-automation@vX.Y.Z299```300301`version` prints the version of MyGo the command was built from (as302`v0.8.0`; `(devel)` or a pseudo-version for a build from a checkout), and303`skills` prints this guide. `go install` puts `mygo-automation` in304`$(go env GOBIN)`, else305`$(go env GOPATH)/bin`. Upgrading the app's MyGo does not upgrade the306installed command: install it again, and this guide comes with it.