Skip to content

Commit bf0c1d7

Browse files
committed
A picture or a reason on every command page
42 of 76 command pages had no screenshot. The capture plan now covers the gestures on MobiumApp's screens that report them, the reading commands on the screens they read, a call and a message arriving, a position the app receives, offline mode, the time zone, the WebView tools, uncheck, terminate and a link opened in the app it belongs to. grid, test, show-report, mcp and batch show the guides' own pictures, with a link to the guide. The 28 pages where nothing on the screen shows the command say why, and the build fails on a page with neither. Before a picture of the shade or a heads-up, the shade is cleared, so it shows this run's notifications only; the position is shown after granting the app location, and put back after. A non-verbatim capture is named for its command, so two of one tool no longer overwrite each other.
1 parent cde87c6 commit bf0c1d7

68 files changed

Lines changed: 343 additions & 53 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎data/runs.json‎

Lines changed: 165 additions & 25 deletions
Large diffs are not rendered by default.

‎examples/cli-extra.json‎

Lines changed: 64 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,82 @@
11
{
22
"daemon": [
3-
{"title": "Look at the daemon, then stop it", "cli": "mobium daemon status && mobium daemon stop"}
3+
{
4+
"title": "Look at the daemon, then stop it",
5+
"cli": "mobium daemon status && mobium daemon stop"
6+
}
47
],
58
"daemon status": [
6-
{"title": "Is the daemon running?", "cli": "mobium daemon status"}
9+
{
10+
"title": "Is the daemon running?",
11+
"cli": "mobium daemon status"
12+
}
713
],
814
"daemon stop": [
9-
{"title": "Stop the daemon, after rebuilding mobium", "cli": "mobium daemon stop"}
15+
{
16+
"title": "Stop the daemon, after rebuilding mobium",
17+
"cli": "mobium daemon stop"
18+
}
1019
],
1120
"daemon up": [
12-
{"title": "Start the daemon ahead of the first command", "cli": "mobium daemon up"}
21+
{
22+
"title": "Start the daemon ahead of the first command",
23+
"cli": "mobium daemon up"
24+
}
1325
],
1426
"grid": [
15-
{"title": "The devices of two nodes, and who holds them", "cli": "MOBIUM_GRID=node1,node2 mobium grid status"}
27+
{
28+
"title": "The devices of two nodes, and who holds them",
29+
"cli": "MOBIUM_GRID=node1,node2 mobium grid status",
30+
"image": "/img/guides/grid-ui.jpg",
31+
"caption": "The same answers as a page, from `mobium grid ui` — from [the grid guide](/guides/grid#4-tests-on-a-grid)"
32+
}
1633
],
1734
"grid status": [
18-
{"title": "The devices of two nodes, and who holds them", "cli": "MOBIUM_GRID=node1,node2 mobium grid status"}
35+
{
36+
"title": "The devices of two nodes, and who holds them",
37+
"cli": "MOBIUM_GRID=node1,node2 mobium grid status",
38+
"image": "/img/guides/grid-ui.jpg",
39+
"caption": "The same answers as a page, from `mobium grid ui` — from [the grid guide](/guides/grid#4-tests-on-a-grid)"
40+
}
1941
],
2042
"grid ui": [
21-
{"title": "Serve the grid as a page on this machine", "cli": "MOBIUM_GRID=node1,node2 mobium grid ui --port 8080"}
43+
{
44+
"title": "Serve the grid as a page on this machine",
45+
"cli": "MOBIUM_GRID=node1,node2 mobium grid ui --port 8080",
46+
"image": "/img/guides/grid-ui.jpg",
47+
"caption": "`mobium grid ui` during a test run: 14 devices, 2 held, 0 waiting, emulator-5554 and emulator-5556 each held by a grid run — from [the grid guide](/guides/grid#4-tests-on-a-grid)"
48+
}
2249
],
2350
"show-report": [
24-
{"title": "Open the report of the last test run", "cli": "mobium test && mobium show-report"}
51+
{
52+
"title": "Open the report of the last test run",
53+
"cli": "mobium test && mobium show-report",
54+
"image": "/img/guides/test-runner-report.jpg",
55+
"caption": "The HTML report it opens: one test failed, its message, a screenshot of the Login Demo showing \"Incorrect username or password.\", and the map — from [the test runner guide](/guides/test-runner#3-a-failure-and-what-it-leaves)"
56+
}
57+
],
58+
"test": [
59+
{
60+
"title": "Run the suite, and write the HTML report",
61+
"cli": "mobium test --reporter list,html",
62+
"image": "/img/guides/test-runner-report.jpg",
63+
"caption": "The HTML report of a run with a failure — from [the test runner guide](/guides/test-runner#3-a-failure-and-what-it-leaves)"
64+
}
65+
],
66+
"mcp": [
67+
{
68+
"title": "Register it with an agent",
69+
"cli": "claude mcp add mobium -- mobium mcp",
70+
"image": "/img/guides/mcp-agent-result.jpg",
71+
"caption": "What an agent left on screen after driving the Login Demo through `mobium mcp` — from [the MCP guide](/guides/mcp)"
72+
}
73+
],
74+
"batch": [
75+
{
76+
"title": "Log in to the Login Demo in one call",
77+
"cli": "mobium batch login.json",
78+
"image": "/img/guides/cli-3-welcome.jpg",
79+
"caption": "The Login Demo after a batch that filled both fields and tapped Log In — from [the CLI guide](/guides/cli)"
80+
}
2581
]
2682
}

‎examples/no-picture.json‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{
2+
"apps": "it lists what is installed, and nothing on the screen changes.",
3+
"background": "the app is off the screen for the seconds it is away, and back in front when the command returns.",
4+
"battery": "it reads the battery, and nothing on the screen changes.",
5+
"clear-data": "it deletes an app's data, which shows only the next time the app starts.",
6+
"crashes": "it reads the device's crash reports, and nothing on the screen changes.",
7+
"current": "it names the app in front, and nothing on the screen changes.",
8+
"daemon": "the daemon runs on this machine, not the device.",
9+
"daemon-start": "the daemon runs on this machine, not the device.",
10+
"daemon-status": "the daemon runs on this machine, not the device.",
11+
"daemon-stop": "the daemon runs on this machine, not the device.",
12+
"daemon-up": "the daemon runs on this machine, not the device.",
13+
"devices": "it lists the devices this machine can see.",
14+
"dialogs": "a rule does nothing when it is declared; it answers a dialog that gets in the way of a later action, and that action's answer says so.",
15+
"doctor": "it checks this machine, and needs no device.",
16+
"grant": "it changes what an app may do, not what is on the screen; the next dialog that does not appear is the evidence.",
17+
"install": "it installs an app, which shows nowhere until the app is launched.",
18+
"lock": "a locked emulator's screen is off, so its screenshot is black.",
19+
"logs": "it reads a log, and nothing on the screen changes.",
20+
"record": "what it keeps is a video of the screen.",
21+
"reset-permissions": "it changes what an app may do, not what is on the screen.",
22+
"revoke": "it changes what an app may do, not what is on the screen.",
23+
"session": "a session is the connection to the device, and the screen shows nothing of it.",
24+
"shake": "an emulator shows nothing for a shake; whether the app reacts is up to the app.",
25+
"source": "it reads the hierarchy, and nothing on the screen changes.",
26+
"state": "it reads whether an app is running, and nothing on the screen changes.",
27+
"storage": "MobiumApp's WebView pages are inline HTML, which has no origin and so no storage to show — on one, the command refuses and says to load an http or https page first.",
28+
"time": "it reads the device's clock, and nothing on the screen changes.",
29+
"uninstall": "it removes an app, which shows nowhere on the screen in front."
30+
}

‎scripts/capture.py‎

Lines changed: 72 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,17 @@ def settings_root():
3434
return [f"terminate {SETTINGS}", f"launch {SETTINGS}"]
3535

3636

37+
def cleared_shade():
38+
"""The shade emptied first, so a picture of it shows this run's
39+
notifications and no earlier session's. "?" lets a step fail: with
40+
nothing in the shade there is no Clear all to tap."""
41+
return ["notifications --shade open", "?tap 'text=Clear all'", "?notifications --shade close"]
42+
43+
44+
def gesture(name):
45+
return app_screen("Gestures") + [f"tap 'text={name}'"]
46+
47+
3748
def app_screen(name):
3849
return [f"terminate {APP}", f"launch {APP}", f"tap 'text={name}'"]
3950

@@ -45,17 +56,17 @@ def app_screen(name):
4556
dict(tool="app_devices", i=0),
4657
dict(tool="app_launch", i=0, setup=[f"terminate {SETTINGS}"], after=True),
4758
dict(tool="app_map", i=0, setup=settings_root(), after=True),
48-
dict(tool="app_text", i=0, setup=settings_root()),
49-
dict(tool="app_find", i=0, setup=settings_root()),
59+
dict(tool="app_text", i=0, setup=settings_root(), after=True),
60+
dict(tool="app_find", i=0, setup=settings_root(), after=True),
5061
dict(tool="app_current", i=0),
5162
dict(tool="app_state", i=0),
5263
dict(tool="app_tap", i=0, setup=settings_root(), before=True, after=True),
5364
dict(tool="app_scroll_to", i=0, setup=settings_root(), after=True),
5465
dict(tool="app_swipe", i=0, setup=settings_root(), before=True, after=True),
5566
dict(tool="app_batch", i=0, setup=settings_root(), files={"steps.json": "steps"}, after=True),
5667
dict(tool="app_press", i=1, setup=settings_root(), after=True),
57-
dict(tool="app_press", i=0, setup=settings_root() + ["tap 'text=Network & internet'"]),
58-
dict(tool="app_terminate", i=0, setup=[f"launch {SETTINGS}"]),
68+
dict(tool="app_press", i=0, setup=settings_root() + ["tap 'text=Network & internet'"], before=True, after=True),
69+
dict(tool="app_terminate", i=0, setup=[f"launch {SETTINGS}"], before=True, after=True),
5970
dict(tool="app_appearance", i=0, setup=settings_root(), after=True, restore=["appearance light"]),
6071
dict(tool="app_orientation", i=0, setup=settings_root(), after=True, restore=["orientation portrait"]),
6172
dict(tool="app_screen", i=0),
@@ -64,7 +75,7 @@ def app_screen(name):
6475
dict(tool="app_accessibility", i=0),
6576
dict(tool="app_accessibility", i=1, setup=settings_root(), after=True,
6677
restore=["accessibility bold_text off"]),
67-
dict(tool="app_notifications", i=0),
78+
dict(tool="app_notifications", i=0, setup=cleared_shade()),
6879
dict(tool="app_notifications", i=1, after=True, restore=["notifications --shade close"]),
6980
dict(tool="app_check", i=0, setup=app_screen("Form Demo"), before=True, after=True),
7081
dict(tool="app_wait_for", i=2, setup=app_screen("Form Demo") + ["check testid=termsCheck"]),
@@ -80,27 +91,67 @@ def app_screen(name):
8091
setup=["terminate org.wikipedia", "locale org.wikipedia ja-JP"], after=True,
8192
restore=["locale org.wikipedia ''", "terminate org.wikipedia"]),
8293
dict(tool="app_screenshot", i=0, setup=settings_root(), shot_from="screen.png"),
83-
dict(tool="app_clipboard", i=0),
94+
dict(tool="app_clipboard", i=0, setup=settings_root(), after=True, pause=0.5),
8495
dict(tool="app_clipboard", i=1),
85-
dict(tool="app_location", i=0),
96+
dict(tool="app_location", i=0, setup=[f"grant {APP} location"] + app_screen("Location Demo"), after=True,
97+
pause=3.0, restore=[f"reset-permissions {APP}"]),
8698
dict(tool="app_location", i=1),
87-
dict(tool="app_timezone", i=0, restore=["timezone {timezone}"]),
99+
dict(tool="app_timezone", i=0, setup=settings_root() + ["scroll-to text=System", "tap text=System", "tap 'text=Date & time'",
100+
"wait 'text=Time zone'"],
101+
before=True, after=True, pause=2.0, restore=["timezone {timezone}"]),
88102
dict(tool="app_time", i=0),
89103
dict(tool="app_battery", i=0),
90-
dict(tool="app_network", i=0, restore=["network --reset"]),
104+
dict(tool="app_network", i=0, setup=settings_root() + ["tap 'text=Network & internet'"], before=True, after=True,
105+
pause=2.0, restore=["network --reset"]),
91106
dict(tool="app_network", i=1, restore=["network --reset"]),
92107
dict(tool="app_dialogs", i=0),
93108
dict(tool="app_dialogs", i=1),
94-
dict(tool="app_sms", i=0),
95-
dict(tool="app_call", i=0),
109+
dict(tool="app_sms", i=0, setup=cleared_shade() + settings_root(), after=True, pause=2.0),
110+
dict(tool="app_call", i=0, after=True, pause=2.0),
96111
dict(tool="app_call", i=1),
97112
dict(tool="app_background", i=0, setup=settings_root()),
98113
dict(tool="app_shake", i=0),
99-
dict(tool="app_zoom", i=0, setup=settings_root()),
114+
dict(tool="app_zoom", i=0, setup=gesture("Pinch and Spread"), before=True, after=True),
100115
dict(tool="app_record", i=0, setup=settings_root()),
101116
dict(tool="app_record", i=1, setup=["swipe up"]),
102117
dict(tool="app_list_apps", i=0),
103-
dict(tool="app_contexts", i=0, setup=app_screen("WebViews") + ["tap 'text=Plain page'", "wait text=Back"]),
118+
dict(tool="app_contexts", i=0, setup=app_screen("WebViews") + ["tap 'text=Plain page'", "wait text=Back"],
119+
after=True),
120+
# Gestures, each on the MobiumApp screen that reports what it received.
121+
dict(tool="app_tap", i=None, cmd="double-tap testid=pressTarget", setup=gesture("Tap and Press"),
122+
before=True, after=True),
123+
dict(tool="app_long_press", i=None, cmd="long-press testid=pressTarget", setup=gesture("Tap and Press"),
124+
before=True, after=True),
125+
dict(tool="app_drag", i=None, cmd="drag 'label=Drag source' 'label=Drop zone'", setup=gesture("Drag"),
126+
before=True, after=True),
127+
dict(tool="app_rotate", i=None, cmd="rotate 90", setup=gesture("Rotate") + ["wait text=Back"],
128+
before=True, after=True, pause=2.0),
129+
dict(tool="app_press_tap", i=None, cmd="press-tap 'label=Hold zone' 'label=Act zone'",
130+
setup=gesture("Multi-Touch"), after=True),
131+
dict(tool="app_press_drag", i=None, cmd="press-drag 'label=Hold zone' 'label=Act zone' 'label=Drag end'",
132+
setup=gesture("Multi-Touch"), after=True),
133+
# Reading and writing a field, on the Login Demo.
134+
dict(tool="app_type", i=None, cmd="type testid=username mobium", setup=app_screen("Login Demo"),
135+
before=True, after=True),
136+
dict(tool="app_wait_for", i=None,
137+
cmd="wait testid=loginError --for text --text 'Incorrect username or password.'",
138+
setup=app_screen("Login Demo") + ["fill testid=username mobium", "fill testid=password wrongpass1",
139+
"keyboard --hide", "tap testid=loginBtn"], after=True),
140+
# A WebView's content, on MobiumApp's plain page.
141+
dict(tool="app_eval", i=None, cmd="eval document.title",
142+
setup=app_screen("WebViews") + ["tap 'text=Plain page'", "wait text=Back", "context WEBVIEW_dev.mobium.mobiumapp"],
143+
after=True, restore=["context NATIVE_APP"]),
144+
# The rest of the WebView tools, on the same page.
145+
dict(tool="app_context", i=None, cmd="context WEBVIEW_dev.mobium.mobiumapp",
146+
setup=app_screen("WebViews") + ["tap 'text=Plain page'", "wait text=Back"], after=True,
147+
restore=["context NATIVE_APP"]),
148+
dict(tool="app_cookies", i=0,
149+
setup=app_screen("WebViews") + ["tap 'text=Plain page'", "wait text=Back", "context WEBVIEW_dev.mobium.mobiumapp"],
150+
after=True, restore=["context NATIVE_APP"]),
151+
dict(tool="app_check", i=None, cmd="uncheck testid=termsCheck",
152+
setup=app_screen("Form Demo") + ["check testid=termsCheck"], before=True, after=True),
153+
dict(tool="app_open_url", i=None, cmd="open https://en.wikipedia.org/wiki/Mobile_app",
154+
setup=["terminate org.wikipedia"], after=True, pause=3.0, restore=["terminate org.wikipedia"]),
104155
dict(tool="app_session", i=0),
105156
dict(tool="app_session", i=1),
106157
]
@@ -148,12 +199,16 @@ def save(png, name):
148199
continue
149200
key = f"{tool}[{i}]" if i is not None else f"{tool}:{p['cmd']}"
150201
for s in p.get("setup", []):
151-
mobium(s)
202+
if s.startswith("?"):
203+
mobium(s[1:], check=False)
204+
else:
205+
mobium(s)
152206
for fname, what in p.get("files", {}).items():
153207
(work / fname).write_text(json.dumps(canon[tool][i]["args"][what], indent=2) + "\n")
154208
entry = {"tool": tool, "index": i}
209+
stem = f"{tool}-{i}" if i is not None else f"{tool}-{re.sub(r'[^a-z0-9]+', '-', p['cmd'].lower()).strip('-')[:40]}"
155210
if p.get("before"):
156-
entry["before"] = shot(f"{tool}-{i if i is not None else 'x'}-before")
211+
entry["before"] = shot(f"{stem}-before")
157212
cmd = p.get("cmd") or canon[tool][i]["cli"]
158213
shown = cmd if p.get("cmd") is None else "mobium " + cmd
159214
run = cmd.removeprefix("mobium ") if p.get("cmd") is None else cmd
@@ -167,8 +222,8 @@ def save(png, name):
167222
out = "\n".join(l for l in out.splitlines() if l.startswith("emulator-"))
168223
entry.update(command=shown, verbatim=p.get("cmd") is None, exit=r.returncode, output=out)
169224
if p.get("after"):
170-
time.sleep(1.0)
171-
entry["after"] = shot(f"{tool}-{i if i is not None else 'x'}-after")
225+
time.sleep(p.get("pause", 1.0))
226+
entry["after"] = shot(f"{stem}-after")
172227
if p.get("shot_from"):
173228
entry["after"] = save(work / p["shot_from"], f"{tool}-{i}-after")
174229
for s in p.get("restore", []):

‎scripts/generate.py‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -173,6 +173,7 @@ def cli_pages(self):
173173
| --- | --- |
174174
""" + "\n".join(rows) + "\n")
175175
extra = json.loads((ROOT / "examples/cli-extra.json").read_text())
176+
self.no_picture = json.loads((ROOT / "examples/no-picture.json").read_text())
176177
for name, h in self.cli.items():
177178
self.cli_page(base, name, h, extra.get(name, []))
178179

@@ -216,14 +217,22 @@ def cli_page(self, base, name, h, extra):
216217
for e in extra:
217218
n += 1
218219
out.append(f"### {e['title']}\n\n```sh\n{e['cli']}\n```\n")
220+
if e.get("image"):
221+
alt = re.sub(r"\[([^\]]*)\]\([^)]*\)", r"\1", e["caption"]).replace("`", "")
222+
out.append(f"\n![{cell(alt)}]({e['image']})\n\n*{e['caption']}*\n")
219223
if h["examples"]:
220224
out.append(("### More, from `mobium " + name + " --help`\n\n" if n else "") + "```sh\n" + h["examples"] + "\n```\n")
221225
elif not n:
222226
raise SystemExit(f"mobium {name} has no example: add one to examples/cli-extra.json")
227+
pics = self.other_pictures(tool) if tool else ""
228+
if pics:
229+
out.append("## On a device\n" + pics)
230+
if not pics and not any(o.lstrip().startswith("![") or "\n![" in o or "| ![" in o for o in out):
231+
why = self.no_picture.get(name.replace(" ", "-"))
232+
if not why:
233+
raise SystemExit(f"mobium {name} has no picture and no reason in examples/no-picture.json")
234+
out.append(f"*No screenshot: {why}*\n")
223235
if tool:
224-
pics = self.other_pictures(tool)
225-
if pics:
226-
out.append("## On a device\n" + pics)
227236
out.append(f"## The tool\n\n`{name}` calls [`{tool}`](/reference/mcp/{slug(tool)}); "
228237
"its arguments and what every client calls it are there.\n")
229238
write(base / f"{name.replace(' ', '-')}.md", "\n".join(out))
102 Bytes
152 Bytes
147 Bytes
-1.8 KB
162 Bytes

0 commit comments

Comments
 (0)