demoman 0.8.1 → 0.8.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/THIRD_PARTY_NOTICES +1 -1
- package/dist/demoman.mjs +7541 -4386
- package/dist/page/executor-entry.js +102 -17
- package/dist/page/mux-entry.js +184 -59
- package/dist/page/render-entry.js +764 -613
- package/dist/recipe.md +200 -236
- package/dist/skills/record-demo/SKILL.md +5 -4
- package/dist/studio/assets/confirm-dialog-BGEp6bKH.css +1 -0
- package/dist/studio/assets/confirm-dialog-F4BR4FU0.js +72 -0
- package/dist/studio/assets/editor-63atCcDn.js +4 -0
- package/dist/studio/assets/{editor-inline-7e387eed.css → editor-inline-d74caea2.css} +10 -0
- package/dist/studio/assets/library-L3IU8F5q.js +1 -0
- package/dist/studio/assets/library-inline-3627d15c.css +1426 -0
- package/dist/studio/assets/settings-g3t2C3Eo.js +1 -0
- package/dist/studio/assets/{settings-inline-7bb8bf61.css → settings-inline-2f59fbb0.css} +4 -0
- package/dist/studio/assets/state-eyG4SxVq.js +1 -0
- package/dist/studio/assets/topbar-CgsXzkpk.js +1 -0
- package/dist/studio/assets/view-DzaxHB2c.js +1 -0
- package/dist/studio/editor.html +11 -10
- package/dist/studio/library.html +9 -8
- package/dist/studio/settings.html +8 -7
- package/dist/studio/studio-build.json +3 -3
- package/package.json +1 -1
- package/dist/studio/assets/confirm-dialog-B20ZVWlP.css +0 -1
- package/dist/studio/assets/confirm-dialog-DgJ946Hc.js +0 -72
- package/dist/studio/assets/editor-BC4sLdWT.js +0 -4
- package/dist/studio/assets/library-DVubUJtn.js +0 -1
- package/dist/studio/assets/library-inline-ff1b0c15.css +0 -635
- package/dist/studio/assets/settings-DLH9VoT0.js +0 -1
- package/dist/studio/assets/state-DyL2jOOv.js +0 -1
- package/dist/studio/assets/topbar-sSUyITjl.js +0 -1
- package/dist/studio/assets/view-Df6XUnyO.js +0 -1
package/dist/recipe.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Recording a demo with Demoman
|
|
2
2
|
|
|
3
3
|
You write a DemoScript. Demoman runs it in a browser of its own on
|
|
4
|
-
this machine and saves the
|
|
4
|
+
this machine and saves the video on disk; `export` renders that video to an
|
|
5
5
|
MP4. Every tool answers JSON. A refusal is an error result carrying
|
|
6
6
|
`reason`, a stable identifier to branch on, and `detail`, a sentence for the
|
|
7
7
|
user; section 7 lists every reason.
|
|
@@ -14,9 +14,9 @@ user; section 7 lists every reason.
|
|
|
14
14
|
`secretsFile`, `expiry` and `update`.
|
|
15
15
|
`sessions` is `[{site, savedAt, refreshedAt, signInUrl}]`; it and
|
|
16
16
|
`display` can be `{unreadable}`: tell the user why. `accounts` and
|
|
17
|
-
`secretsFile` are the demo accounts below.
|
|
18
|
-
2. The browser is signed in only where the user ran `npx demoman signin <url
|
|
19
|
-
`status
|
|
17
|
+
`secretsFile` are the demo accounts below.
|
|
18
|
+
2. The browser is signed in only where the user ran `npx demoman signin <url>`
|
|
19
|
+
(`status.sessions` lists them). A demo account records best. A page
|
|
20
20
|
that sends this browser to its sign-in page answers `signedOut` (section
|
|
21
21
|
7) with the exact command in `detail`: give the user that command and
|
|
22
22
|
spend no run until they say they have run it, unless a demo account can
|
|
@@ -25,7 +25,7 @@ user; section 7 lists every reason.
|
|
|
25
25
|
signing in: when the user asks for one and gives demo values, start
|
|
26
26
|
the script at that form's page and type them; a password field's text is
|
|
27
27
|
hidden on disk and in reports.
|
|
28
|
-
3.
|
|
28
|
+
3. Videos are saved under `<DEMOMAN_HOME, default ~/.demoman>/takes/<id>/`.
|
|
29
29
|
No telemetry.
|
|
30
30
|
|
|
31
31
|
### Behind a login: demo accounts
|
|
@@ -33,10 +33,10 @@ user; section 7 lists every reason.
|
|
|
33
33
|
`status.accounts` is one of:
|
|
34
34
|
|
|
35
35
|
- `{file: null, searchedFrom}`: no `.demoman/accounts.json` was found from
|
|
36
|
-
`searchedFrom` upward (`status` reads from the folder this server
|
|
36
|
+
`searchedFrom` upward (`status` reads from the folder this server
|
|
37
37
|
started in and takes no `project`). Create one (below), or pass `project` on `snapshot`/`run`.
|
|
38
|
-
- `{file, invalid, field}`: the file
|
|
39
|
-
|
|
38
|
+
- `{file, invalid, field}`: the file cannot be used; `invalid` is why and
|
|
39
|
+
`field` where. Fix it; every snapshot and run from that project
|
|
40
40
|
answers `accountsInvalid` until then.
|
|
41
41
|
- `{file, sites}`: each site is `{origin, default, accounts}`, each account
|
|
42
42
|
`{name, about, session}` with `session` `"saved"`, `"none"` or
|
|
@@ -45,8 +45,8 @@ user; section 7 lists every reason.
|
|
|
45
45
|
`sessionsUnreadable`, when present: the saved sessions could not be read; tell the user.
|
|
46
46
|
|
|
47
47
|
`status.sessions` lists an account's saved session with an `account` (and
|
|
48
|
-
|
|
49
|
-
|
|
48
|
+
`origin`) beside `site`; an entry without one is the site's manual session from
|
|
49
|
+
`npx demoman signin <url>`.
|
|
50
50
|
|
|
51
51
|
`status.secretsFile` is `null` (no usable accounts file), `{path, absent:
|
|
52
52
|
true}` (no secrets file: only `DEMOMAN_SECRET_*` can supply values),
|
|
@@ -55,19 +55,18 @@ true}` (no secrets file: only `DEMOMAN_SECRET_*` can supply values),
|
|
|
55
55
|
as `secretsFileNotIgnored` or `secretsFileInvalid` will be). Never a value.
|
|
56
56
|
|
|
57
57
|
A page behind a login answers `signedOut` and `status` shows no account for
|
|
58
|
-
its site. Then, in
|
|
58
|
+
its site. Then, in order:
|
|
59
59
|
|
|
60
60
|
1. **Reuse first.** Read each account's `about` and pick the one that fits
|
|
61
|
-
the demo. Name it in the script's `account`, or
|
|
62
|
-
site's `default`.
|
|
61
|
+
the demo. Name it in the script's `account`, or omit it for the `default`.
|
|
63
62
|
2. **The app's repo is open and runs against a local development database:**
|
|
64
63
|
create a demo account and the data the demo needs, with a seed script
|
|
65
64
|
committed in the app and safe to run twice (`priv/repo/demo_seeds.exs`,
|
|
66
65
|
`db/seeds/demo.rb`). Generate a random password of 20 or more characters.
|
|
67
66
|
Write `DEMOMAN_SECRET_<NAME>=…` and
|
|
68
67
|
`DEMOMAN_SECRET_<NAME>_ORIGIN=<the site's origin>` to
|
|
69
|
-
`.demoman/secrets.env`, and
|
|
70
|
-
account to `accounts.json
|
|
68
|
+
`.demoman/secrets.env`, and `.gitignore` it if missing. Add the
|
|
69
|
+
account to `accounts.json`, tell the user in a line, `snapshot` again.
|
|
71
70
|
3. **Two-factor or a magic link in the way:** add a dev-only "sign in as"
|
|
72
71
|
route, reachable only in development, and make the account's `signIn` one
|
|
73
72
|
`goto` to it. Phoenix:
|
|
@@ -78,8 +77,6 @@ its site. Then, in this order:
|
|
|
78
77
|
`npx demoman signin <url>`, which signs in by hand in a window: it is the
|
|
79
78
|
way for a real account, single sign-on and two-factor.
|
|
80
79
|
|
|
81
|
-
Only demo accounts; never the user's own password in `secrets.env`.
|
|
82
|
-
|
|
83
80
|
The file, with one account:
|
|
84
81
|
|
|
85
82
|
```jsonc
|
|
@@ -109,29 +106,25 @@ The file, with one account:
|
|
|
109
106
|
digits, `-` and `_`, at most 64: `seller`. `signIn` uses the script's steps and targets
|
|
110
107
|
(`type` names its field with `into`; copy targets from a `snapshot` of the
|
|
111
108
|
login page) plus `goto`, which must be the first step. `checkUrl` is
|
|
112
|
-
required: a
|
|
113
|
-
|
|
114
|
-
password form) and
|
|
115
|
-
opens it signed out first and treats where it lands as the sign-in page. `about` names who the account is and what data
|
|
116
|
-
it has.
|
|
109
|
+
required: a path on the origin behind the login, which a browser signed
|
|
110
|
+
in to nothing cannot open (it redirects to sign-in, or shows a
|
|
111
|
+
password form) and which shows no password field once signed in. Demoman
|
|
112
|
+
opens it signed out first and treats where it lands as the sign-in page. `about` names who the account is and what data it has.
|
|
117
113
|
- `{secret:NAME}` goes in a `signIn` step's `text`, `NAME` being
|
|
118
114
|
`[A-Z0-9_]+`, not ending in `_ORIGIN`. Demoman reads
|
|
119
115
|
`DEMOMAN_SECRET_NAME` from the environment, else `.demoman/secrets.env`
|
|
120
116
|
(only when git ignores it). A value
|
|
121
117
|
is at least 8 characters, typed only with `DEMOMAN_SECRET_NAME_ORIGIN`
|
|
122
|
-
beside it, naming the account's site.
|
|
123
|
-
|
|
118
|
+
beside it, naming the account's site. The user sets both in the
|
|
119
|
+
environment and you never change them; in `secrets.env` you write both.
|
|
124
120
|
A `{secret:…}` in a demo script is refused (`invalidScript`).
|
|
125
|
-
Environment secrets serve only the accounts.json of the repo Demoman
|
|
126
|
-
started in;
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
scriptVersion 5 (`"scriptVersion": 5`). `snapshot` takes `account` too. Both take `project`,
|
|
130
|
-
an absolute path, to use another checkout's `.demoman/`.
|
|
121
|
+
Environment secrets serve only the accounts.json of the repo Demoman
|
|
122
|
+
started in; a `project` one reads only its own `.demoman/secrets.env`.
|
|
123
|
+
- A script names its account: `"account": "seller"`; so does `snapshot`. Both take `project`,
|
|
124
|
+
an absolute path, for another checkout's `.demoman/`.
|
|
131
125
|
|
|
132
126
|
```json
|
|
133
127
|
{
|
|
134
|
-
"scriptVersion": 5,
|
|
135
128
|
"name": "Seller dashboard",
|
|
136
129
|
"target": "http://localhost:4000/admin/dashboard",
|
|
137
130
|
"account": "seller",
|
|
@@ -145,70 +138,63 @@ The file, with one account:
|
|
|
145
138
|
- Demoman signs in by itself: when the account has no saved session, and
|
|
146
139
|
once more when a call lands on a sign-in page; `signedIn`
|
|
147
140
|
(`{account, steps, ms}`) says it did. A second failure answers
|
|
148
|
-
`signInFailed`. A session that lapses mid-run keeps no
|
|
141
|
+
`signInFailed`. A session that lapses mid-run keeps no video; Demoman has
|
|
149
142
|
signed in again: just run again.
|
|
150
143
|
|
|
151
144
|
## 2. Look at the page
|
|
152
145
|
|
|
153
|
-
`snapshot(url)` opens `url` in Demoman's browser
|
|
154
|
-
|
|
155
|
-
`{ target, kind, text, rect, inFirstViewport }`. Every `target`
|
|
156
|
-
resolves in a run to exactly that element: Demoman checked it.
|
|
146
|
+
`snapshot(url)` opens `url` in Demoman's browser and lists the page's
|
|
147
|
+
targets, leaving the page open. Each entry is
|
|
148
|
+
`{ target, kind, text, value, rect, shown, inFirstViewport }`. Every `target` resolves in a run to that element.
|
|
157
149
|
|
|
158
150
|
- **Copy a `target` into a step verbatim. Never compose one**, and never
|
|
159
151
|
translate a name from another tool's accessibility tree: Demoman's roles
|
|
160
152
|
are not Chrome's.
|
|
161
153
|
- `landedElsewhere: true` - the app redirected, often to its sign-in page;
|
|
162
154
|
`landedUrl` says where. If it is a sign-in page, this browser is not
|
|
163
|
-
signed in there: see `session` below and spend no run. If it is
|
|
164
|
-
|
|
165
|
-
|
|
155
|
+
signed in there: see `session` below and spend no run. If it is not a sign-in page (a
|
|
156
|
+
trailing slash, `https`, a locale prefix), use `landedUrl` as the
|
|
157
|
+
script's `target`; this snapshot stands.
|
|
166
158
|
`landedElsewhere: null` means the page's address could not be read: not an
|
|
167
159
|
all-clear.
|
|
168
160
|
- `session` - `"saved"`: a session is saved for this site; `"none"`: none
|
|
169
161
|
is (normal for a public page); `"signedOut"`: the page is a sign-in page,
|
|
170
162
|
and `sessionDetail` holds the command to give the user (spend no run, or
|
|
171
163
|
set up a demo account: section 1);
|
|
172
|
-
`"unchecked"`:
|
|
173
|
-
|
|
174
|
-
not answer `signedOut`: a `landedUrl` that is plainly a sign-in page with
|
|
164
|
+
`"unchecked"`: `sessionDetail` says why. A sign-in page with only "Continue with Google" may
|
|
165
|
+
not answer `signedOut`: a plainly sign-in `landedUrl` with
|
|
175
166
|
`"none"` or `"unchecked"` means the same. Tell the user to run
|
|
176
|
-
`npx demoman signin <the page to record
|
|
177
|
-
`"unchecked"
|
|
178
|
-
page.
|
|
167
|
+
`npx demoman signin <the page to record>`; spend no run. Otherwise on
|
|
168
|
+
`"unchecked"`, carry on only if `landedUrl` is not a sign-in page.
|
|
179
169
|
- `settled: false` - the page was still loading; `settleNote` says what was
|
|
180
|
-
outstanding. Snapshot again before
|
|
181
|
-
- `rect` is in page coordinates; `inFirstViewport`:
|
|
182
|
-
scroll. `rect: null
|
|
183
|
-
|
|
184
|
-
|
|
170
|
+
outstanding. Snapshot again before concluding something is absent.
|
|
171
|
+
- `rect` is in page coordinates; `inFirstViewport`: in view before any
|
|
172
|
+
scroll. `rect: null`: no box yet (a closed FAQ answer), still a valid
|
|
173
|
+
`waitFor … until: "visible"` target after the step that opens it.
|
|
174
|
+
`shown: false`: transparent, hidden or a sliver now; `waitFor` waits.
|
|
185
175
|
- `size` is `{ width, height, from, error }`: the size the page was laid out
|
|
186
|
-
at,
|
|
176
|
+
at, as a run records. `from` is `screen` (this machine's screen),
|
|
187
177
|
or `device`. `from: "window"` with an `error`: Demoman could not read the
|
|
188
178
|
screen and listed the browser's smaller layout; tell the user the `error`.
|
|
189
|
-
- `
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
further.
|
|
179
|
+
- `positional: true`: the target is a `treePath` (shared or no name); snapshot
|
|
180
|
+
again after the page changes. `value`: a field's text, never a password's.
|
|
181
|
+
`unresolvable`: no target reaches it. `notExamined` above 0: pass `contains`
|
|
182
|
+
(name, text, stableId, kind, value) to narrow. `containsNote`: no match.
|
|
194
183
|
- Iframe and shadow-root elements are not listed.
|
|
195
|
-
- A snapshot sees only the page as it loads: hidden content
|
|
196
|
-
page is listed; content a click creates (a menu
|
|
197
|
-
opens,
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
take. Prefer demo data. `stopped` means a step did not play: fix it as a
|
|
203
|
-
run's stop with that reason says, and probe again. A page the flow
|
|
204
|
-
navigates to has its own URL to snapshot.
|
|
184
|
+
- A snapshot sees only the page as it loads: hidden content in the
|
|
185
|
+
page is listed; content a click creates (a menu, dialog, results, a new row) is not. To list it, `probe` your script
|
|
186
|
+
cut off after the step that opens it, and copy targets from that answer. A probe acts on the app for real: "Add item" adds one per
|
|
187
|
+
probe and again in the run, so a unique target can turn ambiguous;
|
|
188
|
+
a delete deletes; in the Studio an edit saves into the video. Server data
|
|
189
|
+
carries into the run; browser storage does not (a signed-in site's does). Prefer demo data. `stopped`: a step did not play; fix it as a
|
|
190
|
+
run's stop with that reason says, and probe again.
|
|
205
191
|
|
|
206
192
|
### Recording a phone demo
|
|
207
193
|
|
|
208
194
|
1. Call `snapshot` with `device` (`"phone"` or `"tablet"`), and
|
|
209
195
|
copy targets from that answer only: a phone shows a different page, and a
|
|
210
196
|
desktop target is often not on it.
|
|
211
|
-
2. `run` a script that names the same `device
|
|
197
|
+
2. `run` a script that names the same `device`.
|
|
212
198
|
3. Leave `look.canvas` at `auto`, which comes out portrait, or name `9:16`.
|
|
213
199
|
4. No `hover` steps: tap instead.
|
|
214
200
|
|
|
@@ -219,18 +205,14 @@ resolves in a run to exactly that element: Demoman checked it.
|
|
|
219
205
|
1. `snapshot` the page the flow starts on.
|
|
220
206
|
2. Write each step with a `target` copied from that snapshot.
|
|
221
207
|
3. A step that reveals hidden content (a FAQ answer, a panel) names its
|
|
222
|
-
targets from the same snapshot, then a `waitFor … until: "visible"`. A step that navigates: snapshot the new page's URL and put a
|
|
223
|
-
`waitForLoad` after the step. A step on content a click creates: see
|
|
224
|
-
section 2.
|
|
208
|
+
targets from the same snapshot, then a `waitFor … until: "visible"`. A step that navigates: snapshot the new page's URL and put a `waitForLoad` after it; the step after waits up to 10 s for its own target, so needs no `waitFor`. Content a click creates: section 2.
|
|
225
209
|
4. `snapshot`'s `kits` lists the user's brand kits by name, the default
|
|
226
|
-
marked. Use
|
|
227
|
-
|
|
228
|
-
version 1 is refused (`invalidScript`, `field` `scriptVersion`).
|
|
229
|
-
`{ "ok": false, "reason": … }`: the kits could not be read; say so, name none.
|
|
210
|
+
marked. Use one in `look.kit` only when the user asked for a look.
|
|
211
|
+
`{ "ok": false, "reason": … }`: kits unreadable; say so, name none.
|
|
230
212
|
|
|
231
|
-
### From a
|
|
213
|
+
### From a video made earlier
|
|
232
214
|
|
|
233
|
-
`derive(
|
|
215
|
+
`derive(videoId)` answers `{ report, script }`: the video's steps as a script
|
|
234
216
|
to change and run again.
|
|
235
217
|
|
|
236
218
|
- `report.outcome: "derived"` - `script` is a draft, with `holes[]` and
|
|
@@ -239,68 +221,65 @@ to change and run again.
|
|
|
239
221
|
|
|
240
222
|
| Hole `reason` | What to do |
|
|
241
223
|
| --- | --- |
|
|
242
|
-
| `scrubbedTarget` | `step` is null: the hole is the start URL. Demoman strips query values and secret-looking path segments from a
|
|
224
|
+
| `scrubbedTarget` | `step` is null: the hole is the start URL. Demoman strips query values and secret-looking path segments from a video; `recorded` shows `redacted` there. Set `target` to the real start URL - ask the user if unsure. |
|
|
243
225
|
| `redacted` | Add `"text"` with a **demo** value, never a real credential. |
|
|
244
226
|
| `unnameable`, `ambiguousAtCapture`, `brokenAtCapture` | Add the target, copied from a `snapshot` of that page. |
|
|
245
227
|
| `buttonNotScriptable` | Delete `"button"` only if a left click is acceptable - it is a different action. Otherwise tell the user the step cannot be scripted. |
|
|
246
228
|
| `hostField` | Deleting `"host"` makes the step **replace the whole rich-text editor's contents** on the live app. Ask the user first. |
|
|
247
229
|
|
|
248
|
-
`notes[]` lists steps the
|
|
230
|
+
`notes[]` lists steps the video cut or trimmed; they are kept. A
|
|
249
231
|
`landingOffscreen` note names a scroll that will centre its element. **Keep each step's `recorded`, each
|
|
250
|
-
scroll's `landing`, and the script's `recordedFrom`**:
|
|
251
|
-
|
|
252
|
-
`
|
|
253
|
-
`report.skeleton` is what the merge with the take's saved script said:
|
|
232
|
+
scroll's `landing`, and the script's `recordedFrom`**: the report
|
|
233
|
+
compares the new run with the video by them. A step you add has no `recorded`.
|
|
234
|
+
`report.skeleton` is what merging with the video's saved script said:
|
|
254
235
|
`noSkeleton` or `skeletonUnreadable` (the original's pauses were not
|
|
255
236
|
kept), `stepDropped`, `actionAdded` (kept in place), `verbChanged` (the
|
|
256
237
|
draft takes the verb in `scene.json` - check that step before running).
|
|
257
|
-
- `
|
|
258
|
-
- `unreadable` - a stored
|
|
238
|
+
- `videoNotFound` - no video has that id; `flows()` lists them.
|
|
239
|
+
- `unreadable` - a stored video cannot be read; report its `reason`.
|
|
259
240
|
- `threw` - report its `error`.
|
|
260
241
|
|
|
261
|
-
**Re-
|
|
262
|
-
|
|
263
|
-
`scene.json` (steps, name, look, pauses, added steps), as a new
|
|
264
|
-
run toward the three. Refused with `unfilledHoles` when the
|
|
265
|
-
|
|
242
|
+
**Re-filming an edited video.** `run({ flow: { id } })` with no `script`
|
|
243
|
+
re-films the flow's current video from its saved script and current
|
|
244
|
+
`scene.json` (steps, name, look, pauses, added steps), as a new video and a
|
|
245
|
+
run toward the three. Refused with `unfilledHoles` when the video kept no
|
|
246
|
+
value: `derive`, fill, `run`. `invalidScript` (`field` `steps.<i>.do`): a
|
|
266
247
|
verb was changed by hand: `derive`, check it, `run` the draft.
|
|
267
248
|
|
|
268
|
-
A
|
|
249
|
+
A flow in the repo (.demoman/flows) is rewritten by each run: commit that file with the change. To add one, run `npx demoman add <flow> --to <path>` in the repo.
|
|
269
250
|
|
|
270
251
|
## 4. Run and read
|
|
271
252
|
|
|
272
|
-
0. Name the
|
|
273
|
-
has an exported file of it, `
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
{ id } })` adds a version; `video: { new: "<name>" }` starts one.
|
|
253
|
+
0. Name the flow first: every run adds a video to one. If the repo
|
|
254
|
+
has an exported file of it, `flows({ file: <absolute path> })`. Else
|
|
255
|
+
`flows({ query: "<what the flow shows>" })`; `flows()` lists the repo's. Then `run({ script, flow:
|
|
256
|
+
{ id } })` adds a video; `flow: { new: "<name>" }` starts one.
|
|
277
257
|
`possibleDuplicate` lists `matches`: use one's `id`, or repeat with
|
|
278
258
|
`confirmedNew: true` for a different flow. `nameTaken` names the
|
|
279
|
-
`holder`: use its `id` or another name. The report's `
|
|
259
|
+
`holder`: use its `id` or another name. The report's `flow`
|
|
280
260
|
says what was made.
|
|
281
|
-
1. `run(script,
|
|
261
|
+
1. `run(script, flow)`. It answers the run's report, or
|
|
282
262
|
`{ "outcome": "stillRunning", "id": … }` after about 50 s; then call
|
|
283
263
|
`report(id)` until the outcome is neither `running` nor `stillRunning`.
|
|
284
264
|
2. The report's `outcome`:
|
|
285
265
|
- `refusedBeforeRun` - the door refused before opening anything; `reason`
|
|
286
266
|
and `field` name what to fix (section 7).
|
|
287
267
|
- `refused` - the replay policy refused; `refused.routes` names the
|
|
288
|
-
user's move. Tell
|
|
268
|
+
user's move. Tell them; do not work around it.
|
|
289
269
|
- `stopped` - `stopped.at` names the step and `stopped.sentence` says why.
|
|
290
270
|
A `steps[i].pageUrl` on a sign-in page means the app sent this browser
|
|
291
271
|
to sign in mid-run: tell the user; do not rewrite targets.
|
|
292
|
-
|
|
293
|
-
file or secret, or tell the user. (A run
|
|
294
|
-
that stopped short on the site's recorded sign-in page is relabelled
|
|
272
|
+
(A run stopped short on the site's recorded sign-in page is relabelled
|
|
295
273
|
`signedOut` (section 7); its detail ends "The run itself stopped at script
|
|
296
274
|
step N: ...".)
|
|
297
275
|
- `complete` - read `verdict`: `verdict.kind` is `"matches"` or
|
|
298
276
|
`"diverged"`, and `verdict.diverged[]` lists each step the video does not
|
|
299
|
-
show
|
|
300
|
-
|
|
277
|
+
show as the script asked. `still`, the image after the text, is
|
|
278
|
+
the last frame: the verdict says the actions happened; look at `still` against the brief before you export or run again.
|
|
279
|
+
`endPage`: the end page's `url`, `text` and `fields`.
|
|
301
280
|
- In any outcome, a step whose `textHidden` is set typed into a credential
|
|
302
281
|
field (`"credentialField"`, or `"credentialUnchecked"` if the page could
|
|
303
|
-
not say): its text is kept nowhere. Re-
|
|
282
|
+
not say): its text is kept nowhere. Re-filming or deriving that video
|
|
304
283
|
asks for a demo value. `landing.startedElsewhere` names where the start URL went; `landing.unchecked`: the page could not be checked for a
|
|
305
284
|
sign-in page. `notStored` with `what: "session"` means the saved
|
|
306
285
|
session could not be refreshed: name it to the user.
|
|
@@ -309,50 +288,52 @@ A video kept current in the repo (.demoman/videos) is rewritten by each run into
|
|
|
309
288
|
about the video, not the script (`surfaceMismatch`: the browser handed
|
|
310
289
|
back frames of the wrong size; `dragPictureMissing`: a native drag's item
|
|
311
290
|
jumps). `notDragged`: a drag changed nothing; `verdict.diverged` lists
|
|
312
|
-
it. Name them to the user; spend no run.
|
|
291
|
+
it. Name them to the user; spend no run. `clickUnconfirmed` is about a step: a click
|
|
313
292
|
could not be confirmed to have reached its target, and
|
|
314
293
|
`frames.unconfirmedClicks` names each such step and says why; check in
|
|
315
294
|
the video that the step did what it should before saying so.
|
|
316
|
-
- A re-
|
|
295
|
+
- A re-film's report carries `rerecord`: `from` (the old video), `notes`
|
|
317
296
|
(as `report.skeleton` above, `stepDropped` with `why` `actionGone` or
|
|
318
|
-
`neverPerformed`; `migrated`: a `sentence`) and `notCarried` (each `removed`, `split`,
|
|
319
|
-
mask, hold, gap or trim the old
|
|
320
|
-
each zoom
|
|
321
|
-
|
|
322
|
-
|
|
297
|
+
`neverPerformed`; `migrated`, `trimClampedToStep`, `zoomNotWritten`: a `sentence`) and `notCarried` (each `removed`, `split`,
|
|
298
|
+
mask, hold, gap or trim the old video had and the new one lacks, and
|
|
299
|
+
each zoom added or moved in the editor, `zoom`; others are remade
|
|
300
|
+
from clicks). Name each
|
|
301
|
+
to the user; a mask not carried may show what the old video hid.
|
|
323
302
|
3. **Read the video.** The report carries `video` and `recording`. Read
|
|
324
303
|
`video.summary` first (a count per label: `inside`, `atEdge`, `cutOff`,
|
|
325
304
|
`outOfFrame`, `strayArrival`, `detour`, `longStill`), then
|
|
326
305
|
`video.steps[i].framing.label`, and `video.journeys[j].arrival` /
|
|
327
306
|
`video.journeys[j].detour` for the cursor.
|
|
328
|
-
- **Which script step a video step is:** `video.steps` lists the
|
|
307
|
+
- **Which script step a video step is:** `video.steps` lists the video's
|
|
329
308
|
actions, and a `pause` makes no action. Find the report's `steps[k]`
|
|
330
309
|
whose `actionId` equals `video.steps[i].actionId`; `steps[k].index` is
|
|
331
310
|
its 0-based position in your script.
|
|
332
|
-
- `video` may be `{ "unavailable": … }` (`refused`, `
|
|
311
|
+
- `video` may be `{ "unavailable": … }` (`refused`, `noVideo`, `noFrames`,
|
|
333
312
|
`checkFailed` with `error`): not a clean bill; say so, do not retry. Likewise
|
|
334
313
|
`video.steps[i].unknown` and `video.noCursor: true`.
|
|
335
314
|
- `recording` is `{ "unavailable": … }` or
|
|
336
|
-
`{
|
|
337
|
-
the
|
|
315
|
+
`{ recordingVideoId, steps[], notInRecording[] }`, comparing the run with
|
|
316
|
+
the video a derived script came from. `unavailable` is again an answer.
|
|
338
317
|
|
|
339
318
|
| Finding | Whose | The move |
|
|
340
319
|
| --- | --- | --- |
|
|
341
320
|
| `cutOff`, `outOfFrame` | the script | add a `scrollTo` on that element before the step |
|
|
342
321
|
| `atEdge` | the script, if a run remains | as above; otherwise leave it |
|
|
343
322
|
| `longStill` beyond what a `pause` asked for | Demoman | leave it; do not rewrite steps |
|
|
323
|
+
| `opening` long | the script | add `trim.start` |
|
|
324
|
+
| `zoomNotes` | the script | set that click's `zoom` |
|
|
325
|
+
| `trimNotes` | the script | name another step in `trim` |
|
|
344
326
|
| stray arrival, `detour` | Demoman | leave it |
|
|
345
|
-
| drift from the earlier
|
|
327
|
+
| drift from the earlier video | the app | report it |
|
|
346
328
|
|
|
347
329
|
A finding that is Demoman's earns no run and is not passed on (the
|
|
348
|
-
user can change it in the Studio). A step's
|
|
349
|
-
`roomMs` is Demoman's own pacing, not a stall.
|
|
330
|
+
user can change it in the Studio). A step's `roomMs` is pacing, not a stall.
|
|
350
331
|
4. Tighten a step whose `candidates` is above 1 or whose `strategy` is weaker
|
|
351
332
|
than the target you named.
|
|
352
333
|
|
|
353
334
|
**Stop after three runs**, done or not, then export: every run drives the
|
|
354
|
-
user's real app. A
|
|
355
|
-
user's default brand kit; a derived draft keeps its
|
|
335
|
+
user's real app. A video zooms on every click and starts from `look.kit`, else the
|
|
336
|
+
user's default brand kit; a derived draft keeps its video's branding. `look.branding` says where it came from: `script`,
|
|
356
337
|
`kit` (you named it; `look.kit.name` says which), `defaultKit`, or
|
|
357
338
|
`defaults`. A non-null `look.brandKitError` (default kit unreadable),
|
|
358
339
|
`look.wallpaperError` (its image) or `size.error` goes into your hand-back;
|
|
@@ -360,48 +341,35 @@ user's default brand kit; a derived draft keeps its take's branding. The report'
|
|
|
360
341
|
|
|
361
342
|
## 5. Export and hand back
|
|
362
343
|
|
|
363
|
-
1. `export(
|
|
344
|
+
1. `export(videoId)` with the accepted run's `provenance.videoId`. It answers
|
|
364
345
|
the export report, or `stillRunning` with an `id`; then call `report(id)`
|
|
365
346
|
until the outcome is none of `exporting`, `stillRunning`.
|
|
366
|
-
`fileType
|
|
367
|
-
a GitHub PR or issue), or `stills` (a PNG per step, in a folder); only
|
|
368
|
-
if asked. An MP4 follows Settings
|
|
347
|
+
`fileType`, only if asked: `mp4` (the default), `gif`, or `stills`. An MP4 follows Settings
|
|
369
348
|
(unset: ~1 MB/s); `quality: "full"` is largest.
|
|
370
|
-
`export({
|
|
371
|
-
it could not
|
|
372
|
-
says
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
few pixels); a GIF over 10 MB at its narrowest says so: offer the MP4.
|
|
377
|
-
Stills take `stills: { width, zoom }`, both optional. A
|
|
378
|
-
still is by default the whole window, up to 2560 px wide (not wider than the recording). `width` asks for a size in
|
|
379
|
-
px (320-3840) or `"native"`, the recording's own size; `zoom: "step"`
|
|
380
|
-
frames each step the way the video zooms on it, all the way in. Pass
|
|
381
|
-
them only when asked.
|
|
349
|
+
`export({ videoId, maxMB: 9.5 })` fits GitHub's 10 MB drag-in, or says
|
|
350
|
+
it could not.
|
|
351
|
+
A GIF is as wide as fits 10 MB (`warnings.gifSize` says how wide and
|
|
352
|
+
which widths were refused); one over 10 MB at its narrowest says so: offer the MP4.
|
|
353
|
+
Stills take `stills: { width, zoom }`, both optional; by
|
|
354
|
+
default a still is the whole window, up to 2560 px wide. `width` is px (320-3840) or `"native"`, the video's own size; `zoom` is `"none"` or `"step"`, which frames each step as the video zooms on it, all the way in. Only when asked.
|
|
382
355
|
2. `saved` - the file is at `file.path`, absolute: in `~/Downloads`, or the
|
|
383
|
-
|
|
356
|
+
server's `--out-dir`. For `stills`, `fileType`
|
|
384
357
|
is `stills` and the answer carries `folder: { path, files }` instead of
|
|
385
358
|
`file`: give the user `folder.path`; `warnings.unplacedStills` lists steps
|
|
386
|
-
|
|
387
|
-
sentence: what was saved and anything
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
a GIF's widths, `targetCheck`). They are
|
|
391
|
-
not the user's to act on: do not pass them on. None is the script's to fix.
|
|
359
|
+
with no still. `summary` is one
|
|
360
|
+
sentence: what was saved and anything asked for that the file lacks (a logo, motion, a still, an edit). `warnings` holds more:
|
|
361
|
+
Demoman's calls (`zooms`, `detailViolations`, a size cap's `steps`,
|
|
362
|
+
a GIF's widths, `targetCheck`): not the user's to act on: do not pass them on. None is the script's.
|
|
392
363
|
Except `wallpaperWarning.sentence` (wallpaper left out: plain
|
|
393
364
|
gradient; or will look soft): quote it.
|
|
394
365
|
`warnings.editedSinceRecorded` lists steps whose `scene.json` no longer
|
|
395
|
-
matches the frames; the summary names the re-
|
|
396
|
-
(`run({
|
|
397
|
-
Re-record only on request. `warnings.untagged`: the
|
|
398
|
-
tag (`error` says why); not the user's to act on.
|
|
366
|
+
matches the frames; the summary names the re-film
|
|
367
|
+
(`run({ flow: { id } })`, or `derive` then `run` when a verb changed).
|
|
368
|
+
Re-record only on request. `warnings.untagged` and `taggedWithoutCommit`: not the user's to act on.
|
|
399
369
|
`links` holds the export's one-click actions, each present
|
|
400
370
|
only where it works: `studio`, `file` (the file itself) and `copy` (the
|
|
401
371
|
file to the clipboard; none for stills). `linksError`, set instead, says
|
|
402
372
|
why there are none: tell the user in one line.
|
|
403
|
-
Every export report carries a `summary` (`stillRunning`, this server's
|
|
404
|
-
own answer, does not).
|
|
405
373
|
3. `renderFailed` - export **once** more; never re-run the script for an
|
|
406
374
|
export failure. `saveFailed` - its `error` names the folder and the
|
|
407
375
|
system's reason (a folder that cannot be written): tell the user;
|
|
@@ -418,41 +386,40 @@ Before opening a PR, read `status.pullRequests` (`project` for
|
|
|
418
386
|
another checkout): `attach`, `ask`, `off`, or `{ unreadable, file }`,
|
|
419
387
|
which is not `off`: tell the user. `off`: only when asked. If the diff
|
|
420
388
|
changes what a user sees, record that one flow (only the change),
|
|
421
|
-
push
|
|
389
|
+
push, open the PR, then `attach({ videoId, into: "description" })`, or
|
|
422
390
|
`"comment"` on a PR that is not yours. The video carries its own line; write no other. On `line.notWritten`,
|
|
423
391
|
tell the user the video lacks it, quoting why. A later `gh pr edit --body` drops the video. `ask`: offer once; on a no, nothing to see or a failed run (say why),
|
|
424
392
|
the PR says nothing of it. `attach`: with no video, the PR description gets
|
|
425
393
|
one line, `No demo: <why>`, and so does the user.
|
|
426
394
|
`attach` caps at 9.5 MB; `maxMB` sets another. On `stillRunning`, `report(id)`
|
|
427
395
|
until the outcome is not `attaching` or `stillRunning`. On `busy`,
|
|
428
|
-
`report(id)` on the export in flight, then `attach
|
|
429
|
-
`ghOutdated`, `ghSignedOut`, `notGitHub` or `copyFailed`, call
|
|
430
|
-
`export({
|
|
431
|
-
into the PR, saying why. On `uploadRefused`, do as its `detail` says. On `partial` or `unconfirmed`, do not
|
|
396
|
+
`report(id)` on the export in flight, then `attach`. On `ghMissing`,
|
|
397
|
+
`ghOutdated`, `ghSignedOut`, `notGitHub`, `prUnreadable` or `copyFailed`, call
|
|
398
|
+
`export({ videoId, maxMB: 9.5 })` and give the user its `file.path` to drag
|
|
399
|
+
into the PR, saying why. On `uploadRefused` or `prNotFound`, do as its `detail` says. On `partial` or `unconfirmed`, do not
|
|
432
400
|
post again; tell the user to check the PR. Other reasons: section 7. An unsaved export answers as `export` does.
|
|
433
401
|
|
|
434
402
|
Hand back, on `saved`, two lines and nothing else: the `summary` as it is,
|
|
435
403
|
then the `links` as markdown links on one line, in this order, only
|
|
436
|
-
those present: `[Open in Studio](links.studio) · [<file name>](links.file) · [Copy video](links.copy)`
|
|
437
|
-
(`Copy GIF` for a GIF). Add one line only for `look.brandKitError`,
|
|
404
|
+
those present: `[Open in Studio](links.studio) · [<file name>](links.file) · [Copy video](links.copy)` (`Copy GIF` for a GIF). Add one line only for `look.brandKitError`,
|
|
438
405
|
`look.wallpaperError`, `size.error`, `linksError`, or something you could not fix. Any other
|
|
439
406
|
outcome: quote its `error` or `detail`.
|
|
440
407
|
|
|
441
408
|
When the `studio` tool is listed and there is no `links.studio`, **offer**
|
|
442
|
-
it; never open it unasked. `studio({
|
|
443
|
-
opens a window to edit and export
|
|
444
|
-
`{ outcome: "opened",
|
|
445
|
-
|
|
409
|
+
it; never open it unasked. `studio({ videoId })`
|
|
410
|
+
opens a window to edit and export it.
|
|
411
|
+
`{ outcome: "opened", videoId?, note? }`: say it is open; quote `note` if set.
|
|
412
|
+
Studio exports go to `~/Downloads`.
|
|
446
413
|
|
|
447
414
|
## 6. The format
|
|
448
415
|
|
|
449
416
|
```json
|
|
450
417
|
{
|
|
451
|
-
"scriptVersion": 1,
|
|
452
418
|
"name": "Checkout with a coupon",
|
|
453
419
|
"target": "https://app.example.com/cart",
|
|
454
420
|
"steps": [
|
|
455
421
|
{ "do": "waitForLoad" },
|
|
422
|
+
{ "do": "scrollTo", "on": { "treePath": "body:1/main:1/section:2/div:1" }, "landing": { "top": 280 } },
|
|
456
423
|
{ "do": "click", "on": { "role": "button", "name": "Apply coupon" } },
|
|
457
424
|
{ "do": "waitFor", "on": { "role": "textbox", "name": "Coupon code" }, "until": "visible" },
|
|
458
425
|
{ "do": "type", "into": { "role": "textbox", "name": "Coupon code" }, "text": "SPRING25" },
|
|
@@ -463,62 +430,54 @@ quote `note` if set. Studio exports go to `~/Downloads`.
|
|
|
463
430
|
}
|
|
464
431
|
```
|
|
465
432
|
|
|
466
|
-
A derived draft keeps where its scrolls stopped (`landing`) and which
|
|
467
|
-
recorded action each step came from (`recorded`, in `recordedFrom`):
|
|
468
|
-
|
|
469
433
|
```json
|
|
470
|
-
{
|
|
471
|
-
|
|
472
|
-
"name": "Landing page tour",
|
|
473
|
-
"target": "https://app.example.com/",
|
|
474
|
-
"steps": [
|
|
475
|
-
{ "do": "scrollTo", "on": { "treePath": "body:1/main:1/section:2/div:1" }, "landing": { "top": 280 }, "recorded": "a-1" },
|
|
476
|
-
{ "do": "click", "on": { "role": "link", "name": "Get started" }, "recorded": "a-2" }
|
|
477
|
-
],
|
|
478
|
-
"recordedFrom": "take-7f3a"
|
|
479
|
-
}
|
|
434
|
+
{"name": "Move a card", "target": "https://app.example.com/board",
|
|
435
|
+
"steps": [{ "do": "drag", "from": { "on": { "text": "Card A" } }, "to": { "on": { "text": "Done" } } }]}
|
|
480
436
|
```
|
|
481
437
|
|
|
482
438
|
```json
|
|
483
|
-
{"
|
|
484
|
-
"steps": [
|
|
439
|
+
{"name": "Search", "target": "https://app.example.com/",
|
|
440
|
+
"steps": [
|
|
441
|
+
{ "do": "type", "into": { "role": "searchbox", "name": "Search" }, "text": "invoices" },
|
|
442
|
+
{ "do": "press", "key": "Enter" }
|
|
443
|
+
]}
|
|
485
444
|
```
|
|
486
445
|
|
|
487
|
-
- `
|
|
488
|
-
`scriptVersion` is the highest that applies: `1`; `2` when `look` names
|
|
489
|
-
a `kit`; `3` when it carries `motion`; `4` when the script names a
|
|
490
|
-
`device`; `5` when it names an `account`; `6` when it has a `drag`.
|
|
446
|
+
- `name` is required; a step's verb is `do`. Leave `scriptVersion` out: Demoman sets it. Keep a derived draft's `recorded` (on steps) and `recordedFrom`.
|
|
491
447
|
- **Targets** name exactly one strategy: `{ "stableId" }`, `{ "role", "name" }`,
|
|
492
448
|
`{ "text" }` or `{ "treePath" }`. Two in one target is refused. Copy them
|
|
493
449
|
from `snapshot` or a derived draft. A `treePath` is a position in the
|
|
494
|
-
page: it breaks when the structure changes,
|
|
495
|
-
- **Verbs:** `click`, `type` (replaces the field's contents), `hover`,
|
|
496
|
-
`scrollTo`, `waitFor` (`until`: `visible` | `hidden`;
|
|
497
|
-
|
|
498
|
-
`waitForLoad`, `pause` (`ms`),
|
|
450
|
+
page: it breaks when the structure changes, stopping the run.
|
|
451
|
+
- **Verbs:** `click` (optional `at: { x, y }`, a spot in the box, 0–1, as drag's; absent is the centre), `type` (replaces the field's contents), `hover`,
|
|
452
|
+
`scrollTo`, `waitFor` (`until`: `visible` | `hidden`; `opacity: 0` or
|
|
453
|
+
`visibility: hidden` is hidden),
|
|
454
|
+
`waitForLoad`, `pause` (`ms`), `press` (`key`: `Enter` | `Tab` | `Escape` |
|
|
455
|
+
`Backspace` | `Delete` | `ArrowUp` | `ArrowDown` | `ArrowLeft` | `ArrowRight` |
|
|
456
|
+
`Space`; names no element, goes to whatever holds focus), and `drag` (`from: { on, at? }`, `to`
|
|
499
457
|
the same or `{ "by": { x, y } }` px; `at` is a spot in the box, 0–1). An unknown key is refused and named.
|
|
500
|
-
- `
|
|
501
|
-
|
|
458
|
+
- `trim`: `{ "start"?: { "ms", "step"? }, "end"?: { "ms", "step"?, "after"? } }`, the video kept before the first and after the last shown step. `step` is 1-based, not a `pause`; `after` is `"zoomOut"` (default) or `"action"`. To end every video right after its last step, give every script `"trim": { "end": { "ms": 0 } }`.
|
|
459
|
+
- A `click` or `drag` takes `zoom`: `false` for none, or `{ "scale": 1.5 }` (over 1, at most 2.5).
|
|
460
|
+
- `scrollTo` takes `landing: { "top": <px> }`, optional: the viewport y of
|
|
461
|
+
the element's top edge once scrolled; absent is centred.
|
|
502
462
|
- `viewport` absent means the size the user chose: the screen's, which
|
|
503
463
|
`snapshot` measured `inFirstViewport` against. Leave `viewport` out unless the user asked.
|
|
504
464
|
- `device` is `"phone"` or `"tablet"`: the page is recorded as a phone (393x852)
|
|
505
|
-
or a tablet (820x1180)
|
|
506
|
-
`viewport`, not both. A device has no hover
|
|
465
|
+
or a tablet (820x1180). Name a device or a
|
|
466
|
+
`viewport`, not both. A device has no hover: a `hover` under one is
|
|
507
467
|
refused. `look` takes `branding` or `kit`, plus `cursor`, `canvas` and
|
|
508
|
-
`motion`; absent
|
|
509
|
-
`snapshot`'s `kits
|
|
510
|
-
branding, not both. An unknown key in `look` is refused and named. A
|
|
468
|
+
`motion`; absent is the user's default brand kit. `kit` names one of
|
|
469
|
+
`snapshot`'s `kits`; not both a kit and a branding. An unknown key in `look` is refused and named. A
|
|
511
470
|
`branding` is the whole of one: `background`, `logo` (or `null`) and
|
|
512
471
|
`padding`, the margin as a fraction of the frame's shorter side (0 to
|
|
513
472
|
0.2; left out is 0.12); a missing `background` or `logo` is refused.
|
|
514
473
|
A `background` may be `{ "kind": "wallpaper", "id" }` (`muted-1` to
|
|
515
474
|
`muted-4`, `vivid-1` to `vivid-6`, `light-1`, `light-2`, `dark-1`, `dark-2`;
|
|
516
475
|
another id is refused, naming them) or `{ "kind": "image", "ref": "<path>" }`, a file, absolute or
|
|
517
|
-
relative to the Demoman home; copied into the
|
|
476
|
+
relative to the Demoman home; copied into the video. Either takes
|
|
518
477
|
`"blur"`, 0-1 (default 0, sharp).
|
|
519
478
|
A `canvas` is `{ "aspect": "auto" | "16:9" | "9:16" }`; `auto`, the
|
|
520
|
-
default, is the
|
|
521
|
-
A `motion` is how the camera moves, `{ "smoothness": 0-1, "blur": 0-1, "follow": true | false }`; a derived draft carries
|
|
479
|
+
default, is the source's shape plus an even margin.
|
|
480
|
+
A `motion` is how the camera moves, `{ "smoothness": 0-1, "blur": 0-1, "follow": true | false }`; keep the one a derived draft carries.
|
|
522
481
|
- Refused at the door: a script whose every step is a `pause`; a `target`
|
|
523
482
|
that is not `http(s)`; a `click` with a `button`.
|
|
524
483
|
- No branching, loops or assertions. Add `pause` only where a viewer must read.
|
|
@@ -529,48 +488,49 @@ recorded action each step came from (`recorded`, in `recordedFrom`):
|
|
|
529
488
|
|
|
530
489
|
| Reason | Where | What it means, and the move |
|
|
531
490
|
| --- | --- | --- |
|
|
532
|
-
| `browserMissing` | `snapshot`, `run` (`refusedBeforeRun`), `studio` | Demoman's browser or
|
|
533
|
-
| `unsupportedPlatform` | `snapshot`, `run`, `export` | This machine cannot record (arm64 Linux, or another OS); quote `detail
|
|
534
|
-
| `sessionUnreadable` | `snapshot`, `run` (`refusedBeforeRun`) | A saved session file or folder could not be read, or
|
|
535
|
-
| `sessionNotLoaded` | `snapshot`, `run` (`refusedBeforeRun`) | The browser refused the saved sessions; `detail` says why. Tell the user to run `npx demoman signin` again
|
|
536
|
-
| `signInFailed` | `snapshot`, `run` (`refusedBeforeRun`) | Demoman signed in as the account and the page still showed a sign-in page, or a step could not run; `detail` says where. It tried once. Fix the account's steps or
|
|
537
|
-
| `secretMissing` | `snapshot`, `run` (`refusedBeforeRun`) | A `{secret:NAME}` has no `DEMOMAN_SECRET_NAME` and no line in `.demoman/secrets.env`; `detail` names both. Through `project` the environment is
|
|
538
|
-
| `secretTooShort` | `snapshot`, `run` (`refusedBeforeRun`) | The secret `NAME` is under 8 characters.
|
|
539
|
-
| `secretUnbound` | `snapshot`, `run` (`refusedBeforeRun`) | `DEMOMAN_SECRET_NAME` has no `DEMOMAN_SECRET_NAME_ORIGIN` beside it, or one that is
|
|
540
|
-
| `secretOffOrigin` | `snapshot`, `run` (`refusedBeforeRun`) | A secret was about to be typed off its site: a sign-in step's page is not the site's origin, or the
|
|
541
|
-
| `secretsFileNotIgnored` | `snapshot`, `run` (`refusedBeforeRun`) | Git does not ignore `.demoman/secrets.env`, so Demoman did not read it. Add
|
|
542
|
-
| `secretsFileInvalid` | `snapshot`, `run` (`refusedBeforeRun`) | A line of `.demoman/secrets.env` is not `DEMOMAN_SECRET_NAME=value`, a comment or blank; `detail` gives the line
|
|
491
|
+
| `browserMissing` | `snapshot`, `run` (`refusedBeforeRun`), `studio` | Demoman's browser or libraries are missing; `detail` gives the command. Ask the user to run it, then call again. |
|
|
492
|
+
| `unsupportedPlatform` | `snapshot`, `run`, `export` | This machine cannot record (arm64 Linux, or another OS); quote `detail`. |
|
|
493
|
+
| `sessionUnreadable` | `snapshot`, `run` (`refusedBeforeRun`) | A saved session file or folder could not be read, or is readable by others; `detail` names the fix. Tell the user. |
|
|
494
|
+
| `sessionNotLoaded` | `snapshot`, `run` (`refusedBeforeRun`) | The browser refused the saved sessions; `detail` says why. Tell the user to run `npx demoman signin` again there. |
|
|
495
|
+
| `signInFailed` | `snapshot`, `run` (`refusedBeforeRun`) | Demoman signed in as the account and the page still showed a sign-in page, or a step could not run; `detail` says where. It tried once. Fix the account's steps or secret, or tell the user; do not rerun unchanged. |
|
|
496
|
+
| `secretMissing` | `snapshot`, `run` (`refusedBeforeRun`) | A `{secret:NAME}` has no `DEMOMAN_SECRET_NAME` and no line in `.demoman/secrets.env`; `detail` names both. Through `project` the environment is unused. Write one (section 1), or ask the user. |
|
|
497
|
+
| `secretTooShort` | `snapshot`, `run` (`refusedBeforeRun`) | The secret `NAME` is under 8 characters. Write a longer one. |
|
|
498
|
+
| `secretUnbound` | `snapshot`, `run` (`refusedBeforeRun`) | `DEMOMAN_SECRET_NAME` has no `DEMOMAN_SECRET_NAME_ORIGIN` beside it, or one that is no origin; `detail` names the line and site. Nothing typed. Add it to `secrets.env` for an account you made; else tell the user. |
|
|
499
|
+
| `secretOffOrigin` | `snapshot`, `run` (`refusedBeforeRun`) | A secret was about to be typed off its site: a sign-in step's page is not the site's origin, or the `_ORIGIN` names another site; `detail` names both. Nothing typed. Check the account's site and `goto`, then tell the user. |
|
|
500
|
+
| `secretsFileNotIgnored` | `snapshot`, `run` (`refusedBeforeRun`) | Git does not ignore `.demoman/secrets.env`, so Demoman did not read it. Add it to `.gitignore` (`detail` says the line), or untrack it. |
|
|
501
|
+
| `secretsFileInvalid` | `snapshot`, `run` (`refusedBeforeRun`) | A line of `.demoman/secrets.env` is not `DEMOMAN_SECRET_NAME=value`, a comment or blank; `detail` gives the line. Fix it. |
|
|
543
502
|
| `accountsInvalid` | `snapshot`, `run` (`refusedBeforeRun`) | `.demoman/accounts.json` is malformed or breaks a rule; `detail` names the field and the rule. Fix the file. |
|
|
544
|
-
| `unknownAccount` | `snapshot`, `run` (`refusedBeforeRun`) | The script names an account the site
|
|
503
|
+
| `unknownAccount` | `snapshot`, `run` (`refusedBeforeRun`) | The script names an account the site lacks, or none and the site has no `default`; `detail` lists the accounts. Name one, or add it (section 1). |
|
|
545
504
|
| `invalidProject` | `snapshot`, `run` (`refusedBeforeRun`), `attach` | `project` is not an absolute path to a folder. Pass one, or leave it out. |
|
|
546
|
-
| `ghMissing`, `ghOutdated`, `ghSignedOut` | `attach` (`refusedBeforeAttach`) | `gh` is missing, too old or signed out;
|
|
547
|
-
| `notGitHub`, `prNotFound`, `prUnreadable` | `attach` (`refusedBeforeAttach`) | Not a GitHub remote; no such PR; the PR could not be read. Nothing was posted: quote `detail` to the user. |
|
|
505
|
+
| `ghMissing`, `ghOutdated`, `ghSignedOut`, `notGitHub`, `prNotFound`, `prUnreadable` | `attach` (`refusedBeforeAttach`) | `gh` is missing, too old or signed out; not a GitHub remote; no such PR, or GitHub did not answer. Nothing posted; do as `detail` says. |
|
|
548
506
|
| `invalidAttach` | `attach` (`refusedBeforeAttach`) | The call is malformed; `detail` says how. Fix it. |
|
|
549
507
|
| `uploadRefused` | `attach` (`notAttached`) | GitHub refused the video. Retry as the Pull requests text says. |
|
|
550
508
|
| `partial` | `attach` (`notAttached`) | `gh` failed but the video is on the PR; do not post again. |
|
|
551
509
|
| `unconfirmed` | `attach` (`notAttached`) | Unknown what landed. Do not post again; tell the user to look at the PR. |
|
|
552
|
-
| `copyFailed` | `attach` (`notAttached`) | The video could not be copied; nothing
|
|
510
|
+
| `copyFailed` | `attach` (`notAttached`) | The video could not be copied; nothing posted. Hand the user the capped export's file. |
|
|
553
511
|
| `windowDidNotOpen` | `snapshot`; `run` (`refusedBeforeRun`); `studio` | The window would not open; try once more. |
|
|
554
512
|
| `studioDidNotStart` | `studio` | The Studio did not start; `detail` quotes the end of `~/.demoman/studio.log`. Tell the user, quoting it. |
|
|
555
|
-
| `alreadyRunning` | `snapshot`, `probe`, `run`, `derive` | A run, probe, snapshot or export is in progress. Call `report(id)` on it;
|
|
556
|
-
| `busy` | `export` (`refusedBeforeExport`) | A run, probe or snapshot is in progress.
|
|
557
|
-
| `browserSilent` | `status`, `
|
|
558
|
-
| `libraryUnreadable` | `
|
|
559
|
-
| `libraryUnwritable` | `run` (in `notStored`) | Not a `reason`: the report has a `notStored` entry `{ "what": "
|
|
513
|
+
| `alreadyRunning` | `snapshot`, `probe`, `run`, `derive` | A run, probe, snapshot or export is in progress. Call `report(id)` on it; retry when it settles. |
|
|
514
|
+
| `busy` | `export` (`refusedBeforeExport`) | A run, probe or snapshot is in progress. `report(id)` it first. |
|
|
515
|
+
| `browserSilent` | `status`, `flows`, `derive`, `report` | The browser did not answer in about 50 s. Call `status` once; if again, tell the user. From `report` the run may still be going: call `report(id)` again. |
|
|
516
|
+
| `libraryUnreadable` | `flows`, `studio` | Unreadable; report it. |
|
|
517
|
+
| `libraryUnwritable` | `run` (in `notStored`) | Not a `reason`: the report has a `notStored` entry `{ "what": "video", "error": … }` and a null `provenance.videoId`. Nothing saved; quote the `error`. |
|
|
560
518
|
| `unknownRun` | `report` | This demoman-mcp never issued that id (ids do not survive a server restart). |
|
|
561
519
|
| `noReport` | `report` | No report for that id: this server keeps only its latest; `detail` says which. Do not run again. |
|
|
562
520
|
| `notAnObject` | `run` | The script is not a JSON object. |
|
|
563
521
|
| `invalidScript` | `run` | The schema refused the script; `field` names where. |
|
|
564
|
-
| `unfilledHoles` | `run` | A derived draft still has holes (section 3); also a re-
|
|
565
|
-
| `
|
|
566
|
-
| `possibleDuplicate`, `nameTaken` | `run` (`refusedBeforeRun`) | A similar
|
|
567
|
-
| `
|
|
568
|
-
| `
|
|
569
|
-
| `
|
|
570
|
-
| `
|
|
571
|
-
| `
|
|
572
|
-
| `
|
|
573
|
-
| `
|
|
522
|
+
| `unfilledHoles` | `run` | A derived draft still has holes (section 3); also a re-film of a video that did not keep a value. |
|
|
523
|
+
| `flowRequired` | `run` (`refusedBeforeRun`) | No `flow` was given. Find one (section 4), or pass `{ new }`. |
|
|
524
|
+
| `possibleDuplicate`, `nameTaken` | `run` (`refusedBeforeRun`) | A similar flow exists (`matches`) or the name is taken (`holder`). Section 4. |
|
|
525
|
+
| `repoFlowNameTaken`, `duplicateFlow`, `repoFlowUnreadable` | `run` (`refusedBeforeRun`); the first two also `flows` with `file` | Repo flows: this library has another flow with that name (`detail` gives the `join-flow` command to tell the user); two files in `.demoman/flows` or the old folder before it name one flow (delete one); a file there will not read (`detail` names it; fix or remove it). |
|
|
526
|
+
| `flowNotFound` | `run` (`refusedBeforeRun`) | No flow has that `id`; call `flows`. |
|
|
527
|
+
| `wrongIdKind` | any | Wrong kind of id; see `detail`. |
|
|
528
|
+
| `flowUnreadable`, `flowUnwritable` | `run` (`refusedBeforeRun`), `flows` | The flow records could not be read or written; quote `detail`. Nothing recorded. |
|
|
529
|
+
| `noTag`, `unknownFlow`, `fileNotFound` | `flows` | The file has no Demoman tag; its flow is not in this library; no file there. Use `query` instead. |
|
|
530
|
+
| `invalidArgs` | any | `file` with `query`, not absolute; an old name (`video`, `takeId`): `detail` gives the new. |
|
|
531
|
+
| `videoExpired` | `export` (`refusedBeforeExport`) | The video's frames expired: `run({ flow: { id } })`, then export. |
|
|
532
|
+
| `failed` | `status` (`expiry`) | Not a refusal: `expiry` is the last cleanup. Say nothing unless it is `{ failed }` or `{ unreadable }`: quote it. |
|
|
533
|
+
| `nothingToRerecord` | `run` (`refusedBeforeRun`) | The video has no step left that acts; tell the user. |
|
|
574
534
|
| `unknownKit` | `run` (`refusedBeforeRun`) | `look.kit` names no kit, or an unreadable one; `detail` lists the kits. Fix it from `snapshot`'s `kits`, or ask the user. |
|
|
575
535
|
| `kitsUnreadable` | `run` (`refusedBeforeRun`) | The kits file would not read, so `look.kit` went unchecked. Quote `detail`; keep the name. |
|
|
576
536
|
| `wallpaperUnreadable` | `run` (`refusedBeforeRun`) | The image would not open. Quote `detail`; fix or drop `look.branding`/`look.kit`. |
|
|
@@ -578,17 +538,21 @@ recorded action each step came from (`recorded`, in `recordedFrom`):
|
|
|
578
538
|
| `deviceFailed` | `snapshot`, `run` | The browser would not emulate the device; nothing was listed or recorded. Tell the user `detail`; do not run again. |
|
|
579
539
|
| `nonHttpTarget` | `run`, `snapshot` | The target or url is not `http(s)`, or its host contains `*`. |
|
|
580
540
|
| `invalidFileType` | `export` (`refusedBeforeExport`) | Not answered here: the schema takes only `mp4`, `gif`, `stills`. |
|
|
581
|
-
| `invalidStillsOptions` | `export` (`refusedBeforeExport`) | `stills` was given for an MP4 or GIF, or
|
|
541
|
+
| `invalidStillsOptions` | `export` (`refusedBeforeExport`) | `stills` was given for an MP4 or GIF, or breaks section 5's width or zoom; `detail` says which. Fix the call. |
|
|
582
542
|
| `invalidQuality`, `invalidMaxMB` | `export` (`refusedBeforeExport`), `attach` | Through these tools, only `quality` or `maxMB` given for a GIF or stills; the schema rejects a bad value first. |
|
|
583
|
-
| `
|
|
584
|
-
| `
|
|
543
|
+
| `noVideoId`, `noFrames` | `export` (`refusedBeforeExport`) | No video id; no frames to render. |
|
|
544
|
+
| `videoNotFound`, `videoUnreadable` | `export` (`refusedBeforeExport`), `run` re-film (`refusedBeforeRun`), `studio` (`videoNotFound`: call `flows`) | No such video; it could not be read (or, for `run`, built into a script). |
|
|
545
|
+
| `unresolvedAnchor`, `anchorNotRendered`, `waitTimeout` | `run` (`stopped.reason`) | The target was not there in the 10 s a step waits, or a `waitFor`/`waitForLoad` timed out. Check it against a `snapshot` and the step before; `scrollTo` first in a long list. |
|
|
546
|
+
| `ambiguousAnchor` | `run` (`stopped.reason`) | Several elements matched; name the target more exactly. |
|
|
547
|
+
| `anchorFrameMismatch`, `anchorUnreachable`, `occlusionTimeout` | `run` (`stopped.reason`) | `anchorFrameMismatch`: its frame changed; pick another target. The others are not the script (unmeasurable, or window covered): run again once. |
|
|
548
|
+
| `pageWentElsewhere`, `unperformableStep` | `run` (`stopped.reason`) | The app left the page unasked (sign-in expired, or a missing `waitForLoad`); or the step asks the impossible. |
|
|
585
549
|
| `dragEndOutOfView`, `dragNoDistance` | `run` (`stopped.reason`) | A drag's end was off screen (a drag cannot scroll), or on its start. Fix the script. |
|
|
586
|
-
| `clickNotDelivered` | `run` (`stopped.reason`) | The browser put a click elsewhere than
|
|
587
|
-
| `signedOut` | `run` (`stopped.reason`) | The app sent this browser to its sign-in page. Nothing
|
|
588
|
-
| `windowClosed` | `run` (`stopped.reason`) | `--headed` only: the window
|
|
589
|
-
| `pageDidNotLoad` | `snapshot` | The url did not load. Ask
|
|
590
|
-
| `pageSilent` | `snapshot` | The page never answered. Call once more; if again, the page blocked Demoman's script
|
|
591
|
-
| `pageFaulted` | `snapshot` | The page's
|
|
592
|
-
| `snapshotThrew` | `snapshot` | A fault
|
|
593
|
-
| `probeThrew` | `probe` | A fault
|
|
550
|
+
| `clickNotDelivered` | `run` (`stopped.reason`) | The browser put a click elsewhere than sent; `stopped.detail` says where. Not the script's fault: run again (it counts); tell the user if it repeats. |
|
|
551
|
+
| `signedOut` | `run` (`stopped.reason`) | The app sent this browser to its sign-in page. Nothing kept; not a script fault. Give the user the command in `stopped.detail`; run again only after they ran it. As an account there is no command: the detail says whether Demoman signed in again; repeat only if it does. |
|
|
552
|
+
| `windowClosed` | `run` (`stopped.reason`) | `--headed` only: the window closed mid-run; the script is fine. Ask the user to leave it open; run once more. In an export it answers `renderFailed`; export again. |
|
|
553
|
+
| `pageDidNotLoad` | `snapshot`, `probe` stop | The url did not load. Ask whether the app runs at that address; spend no run. |
|
|
554
|
+
| `pageSilent` | `snapshot` | The page never answered. Call once more; if again, the page blocked Demoman's script: tell the user. |
|
|
555
|
+
| `pageFaulted` | `snapshot` | The page's code threw; quote `detail`. |
|
|
556
|
+
| `snapshotThrew` | `snapshot` | A snapshot fault; quote `detail`. |
|
|
557
|
+
| `probeThrew` | `probe` | A probe fault; quote `detail`. |
|
|
594
558
|
| `portFailure` | `probe` | The browser gave way; not the script's fault. Probe once more; quote `detail` if it repeats. |
|