blockflow-mcp 0.0.0-stage → 1.0.0

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.
@@ -0,0 +1,800 @@
1
+ # BlockFlow usage guide (for people and AI tools)
2
+
3
+ BlockFlow is a browser extension (Chrome/Brave/Edge, Firefox; Safari later) for building browser
4
+ automations from connected blocks, n8n style: monitoring pages, filling forms, end-to-end tests,
5
+ scraping. Everything runs inside the user's own browser, with their logins.
6
+
7
+ This guide is written so that an AI assistant can **generate correct workflow files** and **explain
8
+ how to use BlockFlow** without reading the source code. Read it top to bottom once; then use:
9
+
10
+ | File | What it is |
11
+ | --- | --- |
12
+ | [`blocks.md`](blocks.md) | Every block: type id, settings (`config` keys), defaults, outputs. **Generated from the code.** |
13
+ | [`blocks.json`](blocks.json) | The same, machine-readable. |
14
+ | [`script.schema.json`](script.schema.json) | JSON Schema of a script file (the format to write): every block, alias, shorthand and branch key. |
15
+ | [`workflow.schema.json`](workflow.schema.json) | JSON Schema of a graph file (what the editor exports), with every block's config (unknown keys not allowed). |
16
+ | [`report.schema.json`](report.schema.json) | JSON Schema of the JSON report (Reports → Export JSON): runs, steps, [error codes](#error-codes). **Generated.** |
17
+ | [`suite-report.schema.json`](suite-report.schema.json) | JSON Schema of a suite's combined JSON report (Suites page, CLI `--report json`). **Generated.** |
18
+ | [`examples/`](examples) | Importable workflows, each as a script (`*.script.json`) and a graph (`*.blockflow.json`). A test checks both import without errors or warnings, to the same graph. |
19
+ | [Repair](#repair-what-import-errors-mean) | What each import error code means and how to fix it. |
20
+
21
+ If you are changing BlockFlow's code rather than using it, read `CLAUDE.md` and `docs/ARCHITECTURE.md`.
22
+
23
+ ---
24
+
25
+ ## Rules for AI tools generating workflows (read first)
26
+
27
+ 1. Output a JSON file in the **script format** (next section). Users import it with **Import** in the
28
+ sidebar or the All workflows page. Imported workflows always arrive **off**, with new ids. (The graph
29
+ format of section 2 also imports; write it only when a script cannot express the workflow.)
30
+ 2. Block `type` values and `config` keys must come from [`blocks.md`](blocks.md). Unknown types,
31
+ unknown config or step keys, wrong value types and options that do not exist are **errors**: the
32
+ whole file is refused, with a list of problems (code, JSON path, did-you-mean). Missing keys take the
33
+ block's default. When you get that list back, fix each path it names (see [Repair](#repair-what-import-errors-mean)).
34
+ 3. Every page block (Click, Fill, Fill Form, Select Option, Check, Press Key, Upload File, Scroll,
35
+ Dialogs, Wait For, Run Script, Assert on the page, Read Element without a URL, Extract List / Extract
36
+ Table / Page Info / Paginate from a tab, Navigate, Wait for Popup, Close Tab) needs an **Open Tab**
37
+ (`type: "open-url"`) **earlier on the same path**, with the same `tab` name (default `"main"`).
38
+ (Page Visited and Context Menu start blocks also provide `main`.)
39
+ 4. Steps run in list order. Branches are lists under `true`/`false` (If), `each` (For Each, Repeat,
40
+ Paginate) and `onError` (any block). The step after an If runs after either branch; the step after a
41
+ loop runs once, when it is done. The first step is the **start block**.
42
+ 5. Prefer readable locators: `role=button[name="Sign in"]`, `label=Email`, `text=Welcome`,
43
+ `testid=…`; fall back to CSS. A locator that matches two elements makes actions fail (strict).
44
+ 6. Put passwords and tokens in **secrets** (`{{secret.name}}`), never in the workflow. Tell the user
45
+ which secret names to create (Secrets tab).
46
+ 7. Do not add waits "just in case": every action already waits for its element. Add **Wait For** only
47
+ for page changes that no later action waits for (a URL change, a message appearing, a spinner
48
+ going away).
49
+ 8. For tests, check results with **Assert**; for monitoring, with **If** + **Notify**.
50
+ 9. Values in templates are **strings**. Compare numbers with the numeric operators (`greater`,
51
+ `less`…), which parse `1,250` and `$9.99`.
52
+ 10. Ask for a **page snapshot** before writing locators, and copy locators from it as they are
53
+ ([below](#getting-locators-from-a-page-snapshot)). When a run fails, read the step's **error code**
54
+ ([table](#error-codes)) and fix what it names.
55
+
56
+ ---
57
+
58
+ ## Script format (write this)
59
+
60
+ A workflow as a list of steps. Import compiles it into blocks and connections and lays them out.
61
+
62
+ ```json
63
+ {
64
+ "format": "blockflow-script",
65
+ "version": 1,
66
+ "name": "Login test",
67
+ "steps": [
68
+ { "open": "https://example.com/login" },
69
+ { "fill-form": {
70
+ "fields": [
71
+ { "locator": "label=Email", "value": "me@example.com" },
72
+ { "locator": "label=Password", "value": "{{secret.loginPassword}}" }
73
+ ],
74
+ "submit": "role=button[name=\"Sign in\"]" } },
75
+ { "id": "landed", "wait-for": { "mode": "url", "url": "/dashboard" }, "step": { "timeoutSeconds": 15 },
76
+ "onError": [ { "notify": { "title": "Login test failed", "message": "{{error}}" } } ] },
77
+ { "id": "greets", "assert": { "locator": "role=heading[level=1]", "expected": "Welcome" } }
78
+ ]
79
+ }
80
+ ```
81
+
82
+ - **A step** is `{ "<block>": settings }`: exactly one block key, a `type` from [`blocks.md`](blocks.md)
83
+ or an alias, whose value is the block's `config` (missing keys take the default). Optional: `id` (unique;
84
+ default `s<N>` for the Nth step from the top of the file), `step` (step settings, section 7) and branch
85
+ lists.
86
+ - **Order and branches**: a step connects to the next one from `out` (loops: from `done`). Lists under
87
+ `each` (For Each, Repeat, Paginate: the loop body) and `onError` (any block: runs when it fails, and sets
88
+ `step.onError: "port"`) end where they end. **If and Switch rejoin**: the step after an If runs after the
89
+ last step of `true` or of `false`; a missing branch goes straight to it. A Switch's branch keys are its
90
+ case names (`"port"` of each row in `cases`) plus `default`, and rejoin the same way:
91
+ `{ "switch": { "value": "{{status}}", "cases": [ { "port": "ok", "operator": "equals", "value": "200" } ] },
92
+ "ok": [ … ], "default": [ … ] }`.
93
+ - **Aliases**: `open` = `open-url`, `goto` = `navigate`, `press` = `press-key`, `select` = `select-option`.
94
+ - **A bare value** instead of settings: `open-url`/`navigate` → `url`; `click`/`check`/`wait-for` →
95
+ `locator`; `press-key` → `key`; `log`/`notify` → `message`; `run-script` → `code`; `run-workflow` →
96
+ `workflow`; `for-each` → `list`; `repeat` → `times`. E.g. `{ "click": "text=Save" }`, `{ "repeat": 3,
97
+ "each": [ … ] }`.
98
+ - **Several scripts**: `{ "format": "blockflow-script", "version": 1, "scripts": [ { "id": "login",
99
+ "name": "Log in", "steps": [ … ] }, … ] }`; Run Workflow names another script of the file by `id` or `name`.
100
+ - Mistakes are refused at import with a code and the JSON Pointer of the step, e.g. `error
101
+ node.type.unknown at /steps/1/clik: Unknown block "clik". Did you mean "click"?` or `error
102
+ config.key.unknown at /steps/2/click/locater`. All codes: [Repair](#repair-what-import-errors-mean).
103
+
104
+ The editor's **Export as script** turns a workflow back into this format when it is a tree of steps.
105
+
106
+ ---
107
+
108
+ ## 1. Concepts
109
+
110
+ - **Workflow**: a graph of blocks (`nodes`) and connections (`edges`), saved in the extension.
111
+ - **Block**: one step: open a tab, click, read a value, compare, notify… Each has settings (`config`).
112
+ - **Data (payload)**: a JSON object that flows along connections. Every block receives the data from
113
+ the block before it, and passes data on, usually the same object plus a few keys it adds
114
+ (Read Element adds `value`, `previous`, `changed`, `count`, `url`). Later blocks use it in
115
+ settings with `{{key}}`.
116
+ - **Start block**: a block nothing feeds. Timer, Schedule, Page Visited, Context Menu and Watch
117
+ Element have their own trigger (section 8). Any other block at the start runs once with empty data.
118
+ - **Run**: one trip of data through the workflow, started by the **▶ Run** button (once, now,
119
+ workflow on or off), by a start block's schedule when the workflow is **On**, or by a Run Workflow
120
+ block. Each block it passes is a **step** with a status: passed, failed, handled (error dealt with),
121
+ skipped.
122
+ - **Outputs (ports)**: most blocks have one output, `out`. If has `true` and `false`. A block whose
123
+ step setting `onError` is `"port"` gets an extra `error` output.
124
+ - **Tabs of a run**: Open Tab gives its tab a name (`main`); page blocks act on the tab with that name.
125
+ The mapping travels in the data as `$session` (do not set it by hand).
126
+
127
+ ## 2. Workflow file format
128
+
129
+ The graph format: what the editor saves and exports. Scripts (above) compile to it.
130
+
131
+ ```json
132
+ {
133
+ "format": "blockflow-workflows",
134
+ "version": 1,
135
+ "workflows": [
136
+ {
137
+ "schemaVersion": 2,
138
+ "id": "any-unique-string",
139
+ "name": "Login test",
140
+ "enabled": false,
141
+ "nodes": [
142
+ { "id": "open", "type": "open-url", "position": { "x": 0, "y": 0 },
143
+ "config": { "url": "https://example.com/login", "where": "window" } },
144
+ { "id": "form", "type": "fill-form", "position": { "x": 260, "y": 0 },
145
+ "config": {
146
+ "fields": [
147
+ { "locator": "label=Email", "value": "me@example.com" },
148
+ { "locator": "label=Password", "value": "{{secret.loginPassword}}" }
149
+ ],
150
+ "submit": "role=button[name=\"Sign in\"]"
151
+ } },
152
+ { "id": "check", "type": "assert", "position": { "x": 520, "y": 0 },
153
+ "config": { "subject": "text", "locator": "role=heading[level=1]", "operator": "contains", "expected": "Welcome" } }
154
+ ],
155
+ "edges": [
156
+ { "id": "e1", "source": "open", "target": "form" },
157
+ { "id": "e2", "source": "form", "target": "check" }
158
+ ]
159
+ }
160
+ ]
161
+ }
162
+ ```
163
+
164
+ - `id`s: any unique strings within the file (node ids unique within a workflow). Import replaces
165
+ them; Run Workflow references between workflows in the same file are kept working. A file whose
166
+ edges name a missing node id, or that repeats a node id, is refused (`edge.endpoint.missing`,
167
+ `node.id.duplicate`).
168
+ - `position`: canvas coordinates; about 260 px apart left to right reads well. Branches: ±140 px in y.
169
+ Leave `position` out of every node and import lays the workflow out.
170
+ - `step` (optional, per node): see section 7.
171
+ - A single workflow object (without the `format` wrapper) also imports.
172
+ - Import checks the whole file first and refuses it on any **error**; **warnings** import with a
173
+ notice. Errors: unknown types and keys, wrong types, invalid options, missing required settings
174
+ (including ones another setting needs, e.g. `locator` for an Assert on an element), invalid URLs and
175
+ locators, broken `{{ }}`, connections to missing blocks or from outputs a block does not have, a block
176
+ connected to itself, no start block, Run Workflow calling a workflow not in the file. Warnings:
177
+ unreachable blocks, loops, a page block without an Open Tab on every path to it, unknown secrets.
178
+ Every code is in [Repair](#repair-what-import-errors-mean).
179
+
180
+ ## 3. Data and templates
181
+
182
+ Any setting marked "supports `{{…}}`" in [`blocks.md`](blocks.md) is rendered against the incoming
183
+ data just before the block runs:
184
+
185
+ | Template | Gives |
186
+ | --- | --- |
187
+ | `{{value}}` | key `value` of the data |
188
+ | `{{$json.value}}` | same thing, n8n style |
189
+ | `{{data.items[0].title}}` | nested keys and array indexes |
190
+ | `{{secret.loginPassword}}` | a secret (section 9) |
191
+ | `{{error}}` | the error text, on the `error` output |
192
+ | `{{ price * 1.1 }}`, `{{ upper(name) }}` | an expression (below) |
193
+
194
+ Missing keys render as an empty string; objects render as JSON. The result is always a string.
195
+ Secrets are available to templates and expressions as `secret.name` but never enter the data.
196
+
197
+ ### Expressions
198
+
199
+ Used inside `{{ }}`, and **without** braces in fields that expect an expression: For Each / Filter
200
+ `list`, Transform `expression`, Save to Dataset / Download `value`. Safe: no JavaScript is executed.
201
+
202
+ | Kind | Syntax |
203
+ | --- | --- |
204
+ | values | `12`, `3.5`, `'text'`, `"text"`, `true`, `false`, `null`, `[1, 2]` |
205
+ | data | `price`, `item.title`, `rows[0].name`, `items[index]`, `$json.x` |
206
+ | math | `+ - * / %`. `+` adds when both sides read as numbers (`"1,250" + 10` → `1260`), else joins text |
207
+ | compare | `== != < <= > >=` (compare as numbers when both are numbers, else as text) |
208
+ | logic | `&& \|\| !`, `a ? b : c`, `a ?? fallback` |
209
+
210
+ Functions: `upper lower trim len number string round(x, digits) floor ceil abs min max sum avg count
211
+ join(list, sep) split(text, sep) replace(text, find, with)` (find may be `'/regex/'`) `contains
212
+ startsWith endsWith slice(x, from, to) first last keys values pluck(list, 'key') unique sort(list,
213
+ 'key'?) reverse json parseJson now() today() default(x, fallback) matches(text, '/re/i')
214
+ extract(text, '/re(group)/')`.
215
+
216
+ Examples: `sum(pluck(items, 'price'))` · `first(sort(items, 'price')).title` ·
217
+ `extract(value, '/#(\d+)/')` · `len(rows) > 0 ? 'some' : 'none'` · `default(name, 'anonymous')`.
218
+
219
+ ## 4. Elements: locators
220
+
221
+ Every "Element"/"Field" setting is a locator, Playwright style:
222
+
223
+ | Locator | Finds |
224
+ | --- | --- |
225
+ | `#save`, `form .primary`, `css=…` | CSS selector (the default) |
226
+ | `my-widget >>> button` | inside an open shadow root (web components) |
227
+ | `text=Sign in` | element whose text contains "Sign in", any case (smallest such element) |
228
+ | `text="Sign in"` | exact text (whitespace normalized) |
229
+ | `text=/sign\s?in/i` | regular expression |
230
+ | `role=button[name="Save"]` | ARIA role + accessible name (name: contains, any case) |
231
+ | `role=button[name="Save"][exact]` | exact name |
232
+ | `role=checkbox[checked]`, `role=heading[level=2]` | state / heading level |
233
+ | `role=button[pressed]`, `role=button[expanded=false]`, `role=tab[selected]`, `role=button[disabled]` | ARIA states (`aria-pressed`, `aria-expanded`, `aria-selected` or a selected `<option>`, disabled natively or by `aria-disabled`); `=false` for the opposite. An element without `aria-pressed`/`aria-expanded` matches neither. `[include-hidden]` also finds hidden elements |
234
+ | `label=Email`, `label="Email"` | form control by its `<label>`, `aria-label` or `aria-labelledby` |
235
+ | `placeholder=you@example.com` | input by placeholder |
236
+ | `testid=submit` | `data-testid`, `data-test-id`, `data-test`, `data-cy` or `data-qa` |
237
+ | `alt=Logo`, `title=Close` | by `alt` / `title` attribute |
238
+ | `xpath=//form//button`, `//form//button` | XPath |
239
+ | `#cart >> text=Remove` | the second inside the first |
240
+ | `li >> nth=0`, `li >> nth=-1` | first / last match |
241
+ | `frame=#pay >> label=Card number` | inside an iframe (same site or another site) |
242
+ | `role=listitem >> has-text=Apple` | **filter**: keep the matches so far whose text contains "Apple" (same text rules as `text=`: any case, `"exact"`, `/regex/`) |
243
+ | `li >> has-not-text=Sold out` | filter: keep those whose text does not |
244
+ | `role=row >> has=role=button[name="Edit"]` | filter: keep those with such an element inside; quote an inner locator that has steps: `has="td >> text=Paid"` |
245
+ | `li >> has-not=button` | filter: keep those without |
246
+ | `button >> visible`, `>> visible=false` | filter: keep only visible (or only hidden) matches |
247
+ | `#accept \|\| role=button[name="OK"]` | either one (all matches of both, in page order). `\|\|` binds loosest: `A >> B \|\| C` is `(A >> B) \|\| C` |
248
+
249
+ Filters narrow what the step before found, like Playwright's `locator.filter()`, so they never come first.
250
+ They combine with everything else: `role=listitem >> has-text=Banana >> role=button[name="Delete"]` is
251
+ "the Delete button in the Banana row". The picker and recorder write such a locator themselves when the
252
+ same button repeats in every row.
253
+
254
+ Common roles: `button`, `link`, `textbox`, `checkbox`, `radio`, `combobox` (a `<select>`), `heading`,
255
+ `listitem`, `row`, `cell`, `dialog`, `switch`, `tab`, `img`.
256
+
257
+ **Strict**: actions (Click, Fill, Select, Check…) fail if the locator matches more than one element,
258
+ with a message listing the matches. Add `>> nth=0` or make it more specific. Reads (Read Element,
259
+ Assert text) use the first match.
260
+
261
+ ### Getting locators from a page snapshot
262
+
263
+ A page snapshot is an outline of what is on a page, with a ready-made locator for each element that a
264
+ step could use. Two ways to get one:
265
+
266
+ - In the editor: select an **Open Tab** block and press **📸 Snapshot page**. BlockFlow opens its URL,
267
+ takes the snapshot and copies it to the clipboard. Paste it into the chat with the AI tool.
268
+ - In a workflow: the **Page Snapshot** block (`type: "page-snapshot"`) outputs `snapshot` (the text) and
269
+ `elements` (a list of `{ref, role, name, tag, locator, value?, checked?, disabled?, level?, url?}`),
270
+ for the whole page or one part (`locator`). Useful to record what a page looked like during a run.
271
+
272
+ ```text
273
+ # Page snapshot: Log in
274
+ URL: https://example.com/login
275
+ - main
276
+ - heading "Log in" [level=1] [ref=e1] locator=role=heading[name="Log in"]
277
+ - form "Login" [ref=e2] locator=role=form[name="Login"]
278
+ - textbox "Email" [required] [ref=e3] locator=label="Email"
279
+ - textbox "Password" [password] [ref=e4] locator=label="Password"
280
+ - checkbox "Remember me" [ref=e5] locator=label="Remember me"
281
+ - button "Sign in" [ref=e6] locator=role=button[name="Sign in"]
282
+ - link "Forgot password?" [url="/reset"] [ref=e7] locator=role=link[name="Forgot password?"]
283
+ ```
284
+
285
+ Each line is `role "name" [state…] [ref] locator=…`. The locator finds exactly that element (inside
286
+ frames it starts with `frame=… >> `), so a workflow can use it unchanged:
287
+ `{ "type": "fill", "config": { "locator": "label=\"Email\"", "value": "{{email}}" } }`. `[ref=…]` ids only
288
+ number the lines of one snapshot; do not use them as locators. States: `[checked]`, `[disabled]`,
289
+ `[expanded]`, `[selected]`, `[required]`, `[value="…"]` (never shown for passwords), `[options="…"]`
290
+ (selects), `[url="…"]` (links), `[level=N]` (headings). Hidden elements are left out; `[shadow]` marks a
291
+ web component's shadow root, `[frame]` an iframe whose content follows, `[cross-origin]` one that could not
292
+ be read. Long pages are cut at 1,500 lines with a note: snapshot one part with the block's `locator`.
293
+
294
+ ## 5. Waiting and timeouts
295
+
296
+ - Each action **auto-waits** until its element: exists exactly once, is visible, enabled (and
297
+ editable for Fill), has stopped moving, and is not covered by something else (a cookie banner, a
298
+ modal). A timeout tells you which of these failed ("is covered by div#overlay").
299
+ - Default timeouts: page actions 30 s, Open Tab and Navigate 45 s, Assert 10 s, Dialogs 15 s,
300
+ Scroll 120 s, Manual Step 600 s, Run Workflow 300 s, Paginate 1800 s, For Each and Repeat 3600 s
301
+ (a loop's timeout covers all its iterations), everything else 60 s (`blocks.md` lists each block's). Change per block with `step.timeoutSeconds`.
302
+ - **Assert** on the page retries until it passes or the timeout ends, like Playwright's `expect`.
303
+ - **Wait For** modes: `visible`, `hidden`, `attached`, `detached`, `enabled` (need `locator`);
304
+ `text`, `no-text` (need `text`; `locator` optional to look only inside it); `url` (needs `url`
305
+ pattern); `load`; `networkidle`; `response` (a request finishes: `url` pattern, optional `status`,
306
+ `method`; `captureBody: true` also returns `response.body`, Chromium only); `request` (the page
307
+ sends a request: `url` pattern, optional `method`; returns `request.postData`).
308
+ - URL patterns: plain text = "URL contains"; `*` = any characters except `/`, `**` = anything;
309
+ `/regex/flags`.
310
+
311
+ ## 6. Branching
312
+
313
+ ```json
314
+ "edges": [
315
+ { "source": "check", "target": "ok", "sourcePort": "true" },
316
+ { "source": "check", "target": "bad", "sourcePort": "false" }
317
+ ]
318
+ ```
319
+
320
+ **Switch** goes one of several ways. `value` (templated) is compared with each row of `cases` in
321
+ order, `{ "port": "<output name>", "operator": "…", "value": "…" }`; the first that holds sends the data
322
+ out of the output named by its `port`, none sends it out of `default`. Each case is an output: connect
323
+ with `"sourcePort": "<case name>"` (or `"default"`). Case names start with a letter or `_`, then letters,
324
+ digits, `_`, `-`; unique; not `default`, `error`, `out`, `done`, `id`, `step`, `onError`, `switch`. An
325
+ edge from a name the cases do not have is `edge.port.unknown`. In the editor, renaming a case keeps
326
+ its connections, removing it removes them.
327
+
328
+ ```json
329
+ { "id": "route", "type": "switch", "config": { "value": "{{status}}", "cases": [
330
+ { "port": "ok", "operator": "equals", "value": "200" },
331
+ { "port": "server", "operator": "matches", "value": "/^5\\d\\d$/" } ] } }
332
+ ```
333
+
334
+ **Repeat until / while** (loops, not branches, but the same conditions): Repeat's `mode` is `times`
335
+ (default: `times` rounds), `until` (run a round, then stop once `left` `operator` `right` holds; at
336
+ least one round) or `while` (check first, run while it holds; maybe none). The condition is rendered
337
+ at each check against the data the last round **ended with** (so a block on `each` can produce what
338
+ it tests, e.g. HTTP Request's `status`), with `{{iteration}}` = rounds run so far. `max` (default 100)
339
+ caps the rounds; reaching it fails the step unless `failAtMax` is `false`. For until / while, `done`
340
+ carries the data the last check saw plus `iterations`; for times, the input plus `iterations`.
341
+ Example: [`api-status-router`](examples/api-status-router.blockflow.json).
342
+
343
+ If, Switch and Repeat operators (also used by Assert): `equals`, `not-equals`, `contains`, `not-contains`,
344
+ `starts-with`, `ends-with`, `matches` (regex, write `/…/flags`), `greater`, `greater-equal`, `less`,
345
+ `less-equal` (numbers), `empty`, `not-empty`, `true`, `false` (`true`/`yes`/`on`/`1`).
346
+
347
+ A block's output goes to **every** block connected to that output, one branch after the other, each
348
+ with its own copy of the data.
349
+
350
+ ## 7. Step settings (every block)
351
+
352
+ ```json
353
+ "step": { "timeoutSeconds": 15, "retries": 2, "onError": "port", "screenshot": "always", "disabled": false, "note": "flaky on Mondays" }
354
+ ```
355
+
356
+ | Key | Meaning |
357
+ | --- | --- |
358
+ | `onError` | `stop` (default): this path stops, the run fails. `continue`: pass the input on as if it worked. `port`: send `{...input, error, errorCode, errorBlock}` out of the `error` output (`errorCode`: see [error codes](#error-codes)) (connect it with `"sourcePort": "error"`). |
359
+ | `retries` | 0 to 5 extra attempts, waiting 1 s, 2 s, 4 s… |
360
+ | `timeoutSeconds` | the step fails after this long |
361
+ | `screenshot` | `error` (default), `always`, `never`. Of the run's tab, only while that tab is showing in its window (Open Tab with `"where": "window"` is best for tests) |
362
+ | `pause` | `true`: a breakpoint. A **Debug** run pauses before this block (see [Debugging](#debugging)); a normal run ignores it |
363
+ | `trace` | `true`: record a [trace](#9-running-results-reports) of this step (pictures before and after, the element's box, URL) even when the run is not traced |
364
+ | `disabled` | skip the block, pass the data through |
365
+ | `note` | text shown on the block |
366
+
367
+ ## 8. Starting a workflow
368
+
369
+ | Start block | Starts when | On ▶ Run |
370
+ | --- | --- | --- |
371
+ | `start` (Start) | only by hand, or when called by Run Workflow; gives named starting values (a caller's values win) | yes |
372
+ | `timer` | every N seconds while On (or once) | fires once now |
373
+ | `schedule` | at set times while On: `every: "day"` + `at: "09:00"` + `days: "weekdays"` / `"mon,fri"`; `every: "hour"` + `minute`; `every: "minutes"` + `minutes` (on the clock) | fires once now |
374
+ | `page-visited` | while On, when any tab loads a page whose URL matches `url` (`when: "any"` also on SPA route changes). Tabs BlockFlow opened never trigger it. The tab becomes `main`. | uses the tab you are on |
375
+ | `context-menu` | while On, when you choose its item (`title`) in the right-click menu; gives `url`, `selection`, `link`, `src` | uses the tab you are on |
376
+ | `watch-element` | while On, when an element's text changes | reads once now |
377
+ | any other block | once when you switch the workflow On (with empty data); not again when you edit it or the browser starts | runs once |
378
+
379
+ A workflow may have several start blocks; each starts its own runs.
380
+
381
+ ## 9. Running, results, reports
382
+
383
+ - **▶ Run** (header): runs the workflow once, now. A Timer at the start fires immediately; Watch
384
+ Element reads once. **■ Stop** cancels before the next block.
385
+ - **On/Off** switch: background mode. Start blocks run on their schedules until switched off.
386
+ - After a run, blocks show ✓ / ✕ / ↪; click a block to see its **input and output** for that run.
387
+ - **Runs** tab (bottom panel) and **Reports** page (header): last 40 runs, filter, step details with
388
+ screenshots, the run of a called workflow, exports: **HTML** (self-contained, screenshots
389
+ embedded), **JUnit XML** (for CI dashboards), **JSON**.
390
+ - If the browser stops the extension's background worker during a run, the run is marked
391
+ **interrupted**.
392
+ - Chromium debugger features share one attachment per tab for the run. Chrome's debugging bar
393
+ stays visible until the run finishes (or the tab closes). Closing that bar invalidates the session;
394
+ later debugger actions fail clearly. Reports and HTML exports label runs that used CDP; JSON
395
+ includes `usedDebugger: true`. Steps run with the debugger attached also list the page's console
396
+ messages and exceptions (bounded, secrets masked; `console` in the JSON step). Workflows that do not use CDP do not request or acquire a session.
397
+ - **Trace**: **Run with trace** (header; run option `trace`), or the step setting `"trace": true` for single
398
+ steps, records for each page step a picture of its tab before and after the block, the box of the element
399
+ it acted on (drawn over the after picture), the page URL afterwards and, when the run already uses the
400
+ Chromium debugger on that tab, a network summary (request count, failed requests, slowest three; metadata
401
+ only). Reports shows a **filmstrip** of the traced steps above the step list (click a picture to jump to
402
+ the step) and before/after in each step; the HTML export embeds them; JSON has `trace` per step and
403
+ `mode: { "trace": true }` on the run. Pictures need the tab showing in its window in Chromium (Firefox
404
+ captures any tab); tracing never attaches the debugger itself and never fails a step. Steps without a tab
405
+ in their input (the Open Tab that makes it) have no trace. Trace pictures are kept apart from failure
406
+ screenshots: at most 200 per run, and the oldest runs' pictures are removed beyond 1,000 pictures or
407
+ 120 MB in total.
408
+ - <a id="debugging"></a>**Debugging**: **🐞 Debug** (header; run option `debug`) runs once and pauses before
409
+ every block with the step setting **Pause here (breakpoint)** (`"pause": true`). With **pause on error**
410
+ ticked next to it (`debug: { "pauseOnError": true }`) it also pauses when a block fails, before the
411
+ failure is handled (`onError`, retries are already used up). While paused, a banner shows the block, why
412
+ it paused, the error and the block's input, and the element of a page step is outlined on the page.
413
+ **Continue** runs on to the next breakpoint, **Step** runs this block and pauses before the next one,
414
+ **Stop** (or the header's ■ Stop) ends the run (`cancelled`, the paused block `skipped`). The pause lives
415
+ in the background worker: closing the editor does not end it, and the banner is back when the editor is
416
+ opened again. A pause nobody answers ends the run after an hour. JSON: `mode: { "debug": true }`.
417
+ - **Run from here** (a block's settings panel) runs that block, and everything after it, with the input it
418
+ had in the workflow's most recent run that reached it; nothing before it runs. It is disabled, with the
419
+ reason, when no run reached the block, or when that input was stored shortened (over 3,000 characters of JSON)
420
+ or with secret values hidden, since running with such an input would not be the same run.
421
+ JSON: `mode: { "startedAt": "<block id>" }`. The page tab in that input must still be open.
422
+ - The **JSON** export is for programs: `{ "$schema", "schemaVersion": 1, "generatedAt", "summary", "runs" }`
423
+ ([schema](report.schema.json)). Each step of a run has `nodeId`, `sourceId` (the block's `id` in the
424
+ file you imported, when it had one), `blockType`, `status`, `durationMs`, `attempts`, `input`, `output`
425
+ and, when it failed, `error`, `code`, `locator`, `url` (the page) and `matches` (for `locator.strict`,
426
+ up to 5 descriptions of the elements that matched).
427
+ - **Suites** (Suites page): a named list of saved workflows run one after the other, with one combined
428
+ report. Order them with ↑ / ↓; **Stop at the first failure** skips the rest after a workflow that did
429
+ not pass. A suite passes only when every workflow ran and passed. Downloads: **JUnit XML** (one
430
+ `<testsuite>` named after the suite, one `<testcase>` per workflow, `<failure message="[code] Block: message">`
431
+ for a failing one, `<skipped/>` for skipped ones), **HTML** (one section per workflow) and **JSON**
432
+ (`{ "$schema", "schemaVersion": 1, "generatedAt", "suite", "summary", "runs" }`,
433
+ [schema](suite-report.schema.json)). Outside tools run the same suites (or an inline one) with `suite.run`.
434
+ **↻ Re-run failed** on the last result runs only the workflows that did not pass or were skipped, in
435
+ suite order; its result replaces the last result.
436
+
437
+ ### Error codes
438
+
439
+ Every failed step has a `code`. Fix by the code, then the message:
440
+
441
+ | Code | Meaning | Fix |
442
+ | --- | --- | --- |
443
+ | `locator.not-found` | No element matches the locator (within the step timeout). | Check the locator against a page snapshot; wait for the page or the element first. |
444
+ | `locator.strict` | The locator matches more than one element where exactly one is needed. | Make it more specific (see `matches`), or add `>> nth=0`. |
445
+ | `locator.invalid` | The locator cannot be parsed (bad CSS, unknown engine, bad regex). | Fix the locator syntax. |
446
+ | `element.not-visible` | The element exists but stayed hidden. | Open whatever reveals it first (menu, tab, accordion), or wait for it. |
447
+ | `element.disabled` | The element stayed disabled. | Fill in what enables it first, or check the right element is targeted. |
448
+ | `element.not-editable` | The field is read-only. | Target an editable field. |
449
+ | `element.covered` | Another element (an overlay, a cookie banner) sits on top of it. | Close the overlay first, or use `force` on Click. |
450
+ | `element.unstable` | The element kept moving (an animation). | Wait for the animation to end. |
451
+ | `element.wrong-type` | The element cannot do this (typing into a button, selecting on a non-select…). | Use the block that fits the element, or target the real field. |
452
+ | `option.not-found` | The select has no such option (or it is disabled). | Use one of the options the message lists. |
453
+ | `timeout` | Waited too long for something other than an element (text, URL, response, popup). | Raise the step timeout, or wait for the right thing. |
454
+ | `assert.failed` | An Assert did not hold. | Fix the expectation or the steps before it. |
455
+ | `visual.mismatch` | A Screenshot with `compare` differs from its baseline by more than `maxDiffRatio` (or has another size). | Look at baseline / actual / diff in Reports; press **Accept new baseline** if the new look is right, or mask regions that change on their own. |
456
+ | `http.status` | HTTP Request got a non-2xx answer with `failOnError`. | Check the URL, method, headers and body. |
457
+ | `http.network` | HTTP Request could not reach the server. | Check the URL and the host permission. |
458
+ | `navigation.failed` | A page did not finish loading. | Check the URL; raise the timeout for slow pages. |
459
+ | `tab.missing` | No tab of that name in this run. | Put an Open Tab (with that tab name) before the step. |
460
+ | `tab.closed` | The tab was closed while the step used it. | Do not close the tab mid-run. |
461
+ | `frame.unreachable` | The element is inside a frame that could not be reached. | Check the `frame=` part of the locator. |
462
+ | `page.restricted` | The browser does not let extensions script this page. | Use a normal web page. |
463
+ | `permission.missing` | An optional permission is not granted. | Grant it on the block or in the extension settings. |
464
+ | `script.error` | Run Script code threw. | Fix the script. |
465
+ | `secrets.locked` | The secrets are encrypted and the passphrase has not been entered this session. | Open the editor, go to the Secrets page and enter your passphrase. |
466
+ | `download.failed` | A download was interrupted, or its content cannot be read (Wait for Download). | Check the link works in a normal tab; to read the file its address must still be reachable. |
467
+ | `config.invalid` | A setting is missing or invalid. | Fix the setting the message names. |
468
+ | `workflow.failed` | A workflow called by Run Workflow failed. | Fix the failing step of the called run (`childRunId`). |
469
+ | `step.failed` | Any other failure. | Read the message. |
470
+
471
+ ### Outside access: AI agents, the CLI and CI
472
+
473
+ Programs on the same computer can drive BlockFlow while **Settings → Allow outside control** is on (off by
474
+ default; asks for the `nativeMessaging` permission). They talk to a small companion, the bridge, which the
475
+ browser starts:
476
+
477
+ 1. Install the bridge once, with the extension id shown on the Settings page:
478
+ `npx blockflow-bridge install --extension-id <id>` (Chrome, Chromium, Brave, Edge and Firefox).
479
+ 2. **AI agents (MCP)**: add the server to your MCP client, e.g. Claude Code
480
+ `claude mcp add blockflow -- npx -y blockflow-mcp`. Tools: `snapshot_page` (outline of a page, for
481
+ locators), `validate_workflow` (issues with code, path and hint), `run_workflow` (inline script or saved
482
+ id; failing step, code, locator, URL and a screenshot), `get_report`, `import_workflow`, `list_workflows`,
483
+ `stop_run`, `list_suites`, `run_suite`. The loop: snapshot → write a script → validate → run → repair.
484
+ 3. **CLI and CI**: `npx blockflow-runner run <files or folders> --report junit --out
485
+ report/` starts its own Chromium with the extension in a throwaway profile (no install needed), runs
486
+ everything as one suite, writes `junit.xml` / `report.json` / `report.html`, and exits 0 (all passed),
487
+ 1 (a failure) or 2 (setup or usage error). `blockflow validate <files>` checks without running.
488
+ Secrets: `BLOCKFLOW_SECRET_LOGIN_PASSWORD` → `{{secret.LOGIN_PASSWORD}}` and `{{secret.loginPassword}}`,
489
+ or `--secret name=value`. Secrets passed this way are used for that run only and never stored.
490
+
491
+ Imported workflows are tagged "via bridge"; every outside request is listed on the Settings page.
492
+ Details: wiki [Bridge](../wiki/Bridge.md), [MCP Server](../wiki/MCP-Server.md), [CLI](../wiki/CLI.md).
493
+
494
+ ## 10. Building workflows in the editor
495
+
496
+ - **● Record**: opens a page in a new tab and turns what you do into blocks: typing (one Fill per
497
+ field; two or more fields + a click become Fill Form with that click as submit), selects,
498
+ checkboxes, clicks, Enter, page changes (Wait For URL). The on-page toolbar adds **Assert text** /
499
+ **Assert visible** for the next element you click. It also records inside iframes (locators start
500
+ with `frame=…`) and web components (open shadow roots), and follows tabs the page opens: a **Wait
501
+ for Popup** block, then the steps there with `"tab": "popup"`. Passwords are never recorded: each
502
+ password field gets its own secret named after its label or name (`{{secret.password}}`,
503
+ `{{secret.adminPassword}}`…), and the editor lists the secrets to create. In a workflow that
504
+ already has blocks, the recording continues after the selected block (or the last block of the
505
+ main path), to its right and connected to it; if the workflow already opens that site, no second
506
+ Open Tab is added and the recorded blocks use that Open Tab's tab.
507
+ - **🎯 Pick on page**: click the element; Enter confirms. Action fields get the most readable
508
+ unique locator (`role=…`, `label=…`, `testid=…`); Watch/Read Element get a structural CSS selector
509
+ (stable when the text changes). Other ways to find it are offered as one-click alternatives.
510
+ Elements inside iframes get `frame=<iframe css> >> …`, inside open shadow roots `host >>> …` when no
511
+ readable locator fits. The page: the block's own URL (Watch/Read Element), else the URL of the
512
+ nearest Open Tab before the block, else your last-used tab. Each editor keeps one picker tab and
513
+ reuses it: a block's own URL sends it to that page, an Open Tab's URL only when it shows another
514
+ site (so you can log in or go deeper there first, and the next pick stays on that page).
515
+ - **🎯 Detect fields** (Fill Form): click any field of a form; all its fields are listed with hints.
516
+ - Typing `{{` in a setting suggests names: outputs of earlier blocks, keys seen in the last run,
517
+ `secret.*`.
518
+ - **+ New ▾** → templates (the files in [`examples/`](examples)).
519
+ - **Try it** card (first run, on the canvas until closed): start the practice page with
520
+ `npm run playground` (serves `docs/manual-test` at `http://localhost:7357`), then **Create the
521
+ Try-it workflow** makes the [`playground-tour`](examples/playground-tour.blockflow.json) workflow;
522
+ press ▶ Run.
523
+ - Keys on the canvas: Ctrl/Cmd+Z undo, Ctrl/Cmd+Shift+Z or Ctrl+Y redo (each workflow keeps its own
524
+ history while you switch between them), Ctrl+C / Ctrl+V copy and paste blocks (also into another
525
+ workflow; they land where the mouse is, or 40 px further on when it has not moved), Ctrl+D
526
+ duplicate, Delete/Backspace remove.
527
+ - Messages appear as small notes in the bottom right corner; deleting asks in a dialog inside the
528
+ editor (Escape cancels).
529
+ - The step setting **Use real mouse and keyboard** is only offered on blocks that act on the page
530
+ (Click, Fill, Fill Form, Select Option, Check, Press Key, Paginate; `realInput` in
531
+ [blocks.md](blocks.md)).
532
+ - A workflow with problems cannot be switched on: its switch (header and All workflows) is greyed out
533
+ until they are fixed; **Turn all on** leaves such workflows off and names them.
534
+
535
+ ## 11. Secrets
536
+
537
+ Header → **Secrets**: name/value pairs, e.g. `loginPassword`. Use as `{{secret.loginPassword}}` in
538
+ any templated setting. Their values are replaced by `•••` in the run log, step inspector, run records
539
+ and reports, and are never part of exported workflows. They are stored unencrypted in the browser
540
+ profile's extension storage.
541
+
542
+ ## 12. Harder pages
543
+
544
+ | Situation | Use |
545
+ | --- | --- |
546
+ | A site ignores synthetic clicks/typing (checks `event.isTrusted`) | step setting `"realInput": true` on Click / Fill / Fill Form / Check / Press Key / Drag. Uses the browser's debugger (Chrome, Edge, Brave; optional permission, asked when ticked; a "debugging" bar shows while it acts). Works inside iframes too, same-site and cross-site. Also lets failed steps in background tabs get screenshots |
547
+ | Payment / login widget in an iframe | `frame=<iframe css> >> <locator>` in any locator; cross-origin frames work too. When `frame=` matches several iframes, every same-site one is searched; a cross-site one is used when they find nothing. Pick on page and Record write these locators for you |
548
+ | Web components (open shadow roots) | `text=`, `role=`, `label=`… look inside them; CSS needs `host >>> inner`. Pick on page and Record see inside them |
549
+ | "Sign in with…" popup, `target=_blank` link | Click, then **Wait for Popup** (`name: "popup"`), then blocks with `"tab": "popup"` |
550
+ | `alert` / `confirm` / `prompt` | **Dialogs** (`accept` + prompt `text`, or `dismiss`) **before** the click that opens them; `read` returns `{{dialogs}}` / `{{lastDialog}}` |
551
+ | File chooser | **Upload File** on the `<input type="file">` (hidden ones too, or its label): text you write (`source: "text"`), a file from a URL (`"url"`), or base64 data (`"data"`, e.g. `"{{body64}}"` after HTTP Request with `"responseType": "base64"`, or a `data:` URL) |
552
+ | Drop zone ("drag files here", no file input) | **Upload File** with `"target": "dropzone"` and the zone as `locator`: it gets dragenter, dragover and drop with the file in a DataTransfer. Waits (then fails with `element.wrong-type`) while nothing cancels the zone's `dragover` |
553
+ | Drag and drop: sortable lists, kanban cards, sliders | **Drag** `from` → `to` (optional `fromPosition` / `toPosition` as `"x,y"` from each element's top-left corner, `modifiers`). HTML5 drags (`draggable="true"`) get the drag events with one shared DataTransfer; anything else gets pointer/mouse moves with the button held (sliders, pointer-event sortables). `dragMode` in the output says which. With `realInput` the browser's own mouse drags (native drags too) |
554
+ | Shift+click, Ctrl+click, middle click, triple click, click at a spot | **Click** `modifiers` (`"Shift"`, `"Control+Shift"`; Alt, Control, Meta, Shift), `button` (`left`, `middle`, `right`), `clickCount`, `position` (`"x,y"` from the element's top-left corner inside its border, like Playwright). `action` stays the quick choice: `right` = right button, `double` = 2 clicks, `hover` only moves (with the modifiers held) |
555
+ | Focus or blur a field, clear it, scroll an element into view, fire an event | **Element Action** `action`: `focus`, `blur`, `clear`, `scroll-into-view`, `dispatch-event` (`eventType`; `detail` JSON: for built-in types like `click`, `keydown`, `input` the event's properties, e.g. `{"key": "Enter"}`; for any other type a CustomEvent whose `event.detail` it is). Output `defaultPrevented` |
556
+ | Wait for an API call instead of the UI | **Wait For** `mode: "response"`, `url` pattern, optional `status` (`201`, `2xx`) and `method`. A response that finished during the previous block counts. `mode: "request"` waits for the request itself (`{{request.postData}}` is what the page sent) |
557
+ | Read an API response's body | **Wait For** `mode: "response"` with `captureBody: true` → `{{response.body}}` (Chrome, Edge, Brave; debugger permission, Grant button). Only responses that **start after** the Wait For starts can be read, so it suits slow or later requests (polling, a request a timer sends); for a response that comes right after a Click, call the API with HTTP Request instead |
558
+ | "Export" button or link that downloads a file | Click, then **Wait for Download** (`url`: part of the address or file name). `{{download.filename}}`, `.size`, `.mime`, `.url`. `read: "csv"` / `"json"` / `"text"` fetches the file again from its address (extensions cannot open files on disk) → `{{rows}}` / `{{data}}` / `{{content}}`, optionally into a `dataset`. Files the page builds itself (blob: links) are read in the page, while it still has them |
559
+ | A picture of the page or one element | **Screenshot** (`area`: `visible`, `full`, `element` + `locator`; `png` or `jpeg`). Shown on the step and in the report; `{{screenshotId}}`. Chromium: full page, elements of a tab that is not showing, and any tab that is not showing need the debugger permission (Grant button); without it, an element of the showing tab is cut from the visible area. Firefox: all three work without extra permissions |
560
+ | Check the page still looks the same | **Screenshot** with `compare: true` (baseline per block, `threshold`, `maxDiffRatio`, `mask`; fails with `visual.mismatch`, see [Visual comparison](#visual-comparison-screenshots-against-a-baseline)) |
561
+ | Log in by cookie, reset state between tests | **Cookies & Storage**: `action` `get` / `set` / `delete` / `clear` on `area` `cookies` (the browser's cookie jar, HttpOnly ones too; optional "cookies" permission, Grant button; `url` = whose cookies, default the tab's page; set: `domain`, `path`, `maxAgeSeconds`, `httpOnly`, `secure`, `sameSite`) or `local` / `session` (the page's storage, by `name` = key) |
562
+ | Anything no block does | **Run Script**: async JS body, sees `data`, `return` a JSON value. Needs Chrome 135+, the userScripts permission (Grant button) and "Allow User Scripts" / developer mode for BlockFlow |
563
+ | Run the same test in CI | 🎭 **Playwright** export (sidebar row or All workflows): a `.spec.ts` for `npx playwright test`. Templates, expressions and the data blocks (Data Table, Transform, Filter, Set Variable, For Each, Repeat, If) behave as in BlockFlow, because the spec carries BlockFlow's own template/expression/CSV code. Asserts retry (`toHaveText`, `toHaveURL`, `expect.poll` for the other operators; soft → `expect.soft`); Wait For response, Dialogs, Upload File (drop zones and base64 data too), Wait for Popup, Run Script, Timer delays, Click options, Element Action and Drag (`dragTo`) map to Playwright; step timeouts, retries and error handling (`continue`, error output) are kept. Secrets become environment variables (`{{secret.loginPassword}}` → `LOGINPASSWORD`); Run Workflow calls become functions; what has no equivalent (Notify, Save to Dataset, Download) becomes a `// BlockFlow-only:` comment. Details: [wiki](../wiki/Workflows-as-Scripts.md#export-to-playwright) |
564
+
565
+ ## 13. Testing patterns
566
+
567
+ - **Test = workflow** starting with Open Tab, ending with Asserts. Run with ▶ Run; read the result in
568
+ Reports.
569
+ - **Reuse** a login (or any setup) with **Run Workflow**: the called workflow receives the caller's
570
+ data (including the tab), and its last block's data comes back. Its run appears separately, linked.
571
+ - **Soft assert** (`"soft": true`): record a failure, keep checking the rest.
572
+ - **What Assert can check** (`subject`): `text`, `input` (field value), `attribute` (`name` = the
573
+ attribute), `count`, `class` (`contains` = has the class(es), not a substring: `active` does not match
574
+ `inactive`), `css` (`name` = the property, computed value: `rgb(0, 128, 0)`, `block`),
575
+ `accessible-name`, `accessible-description` (what a screen reader announces), `url`, `title`, `value`
576
+ (a value from the data), `console-errors` (number of `console.error` calls and uncaught exceptions in
577
+ this run's tab so far; Chromium, needs `debugger`, not exported to Playwright) with an `operator`; and the yes/no ones (no operator): `visible`, `hidden`,
578
+ `checked`, `unchecked`, `enabled`, `disabled`, `focused`, `editable` (enabled, not read-only, a field),
579
+ `in-viewport` (some of it is on screen; scroll first if needed). Playwright export maps them to
580
+ `toHaveClass`/`toContainClass`, `toHaveCSS`, `toHaveAccessibleName`, `toHaveAccessibleDescription`,
581
+ `toBeFocused`, `toBeEditable`, `toBeInViewport`.
582
+ - **ARIA snapshot** (`subject: "aria-snapshot"`): checks the *structure* of the page, or of one part of it
583
+ (`locator`, optional), against a template in `expected`, like Playwright's `toMatchAriaSnapshot`. One line
584
+ per element, nested by indenting two spaces, in the [page snapshot](#getting-locators-from-a-page-snapshot)'s
585
+ form: `- role "name" [state]`, then `: text` for its text or value, or `:` and nested lines. Names are
586
+ `"exact"` (spaces collapsed) or `/regex/` (no flags); states `[level=N]`, `[checked]` (`=false`, `=mixed`),
587
+ `[disabled]`, `[expanded]` (`=false`), `[pressed]`, `[selected]`; `- text: …` is a text line; under a link,
588
+ `- /url: …`. Matching is partial: listed lines must be on the page in this order, anything else may be
589
+ there too, nested lines are looked for among the element's direct children, states that are not listed
590
+ are not checked (`- /children: equal` asks for exactly these children). Retried until the step timeout;
591
+ the failure says which template line found nothing, the closest element and the part of the page it
592
+ looked in (`assert.failed`). The template is checked on import, with the line and column of a mistake.
593
+ Lines pasted from a page snapshot work as they are (`[ref=…]` and `locator=…` are ignored; `[required]`,
594
+ `[type=…]` are checked by BlockFlow but not by Playwright). `operator` is not used.
595
+
596
+ ```text
597
+ - heading "Log in" [level=1]
598
+ - form "Login":
599
+ - textbox "Email"
600
+ - button /Sign (in|up)/
601
+ ```
602
+
603
+ Example: [`aria-login-structure`](examples/aria-login-structure.blockflow.json). Playwright export:
604
+ ``await expect(locator).toMatchAriaSnapshot(`…`)`` (the page's `body` without a locator).
605
+ - **Keys**: Press Key takes chords (`Control+Shift+K`, `Shift+Tab`, `Meta+B`; `ControlOrMeta+A` is ⌘A on
606
+ a Mac, Ctrl+A elsewhere). The modifier keys go down first, as on a keyboard, in both input modes. With
607
+ `"mode": "text"` it types `text` at the caret in one go, replacing the selection, with no key events
608
+ (like pasting; Playwright's `keyboard.insertText`). With real input and an element, it clicks the
609
+ element first, so the caret lands where the click did.
610
+ - **Expected failure path**: `step.onError: "port"` on the block that may fail, then handle the
611
+ `error` output (Notify, Stop, Log).
612
+ - **Stop** block: end a path as passed or failed with a message.
613
+ - **Manual Step**: the run waits for a person (CAPTCHA, 2FA) until they press Continue in the
614
+ notification or the editor banner.
615
+ - **Data-driven tests**: Data Table (CSV/JSON) → For Each (`each` output) → the test steps using
616
+ `{{row.email}}`. Use `step.onError: "continue"` or soft Asserts so one bad row does not stop the rest.
617
+
618
+ ### Visual comparison (screenshots against a baseline)
619
+
620
+ Screenshot with `"compare": true` checks the picture against a **baseline kept per (workflow, block)** in
621
+ the browser (IndexedDB), like Playwright's `toHaveScreenshot`:
622
+
623
+ - **First run**: no baseline yet, so this screenshot becomes it and the step passes (logged). Later runs
624
+ compare pixel by pixel. More than `maxDiffRatio` of the (unmasked) pixels differing, or another picture
625
+ size, fails the step with `visual.mismatch`.
626
+ - `threshold` (0 to 1, default `0.2`): how different one pixel's colour must be to count. Anti-aliased edge
627
+ pixels (font smoothing) are not counted. `maxDiffRatio` (0 to 1, default `0`): the share allowed, e.g.
628
+ `0.01` = 1%.
629
+ - `mask`: rows of `{"region": …}` to ignore, each an element locator (`#clock`; every match is covered) or
630
+ `"x, y, width, height"` in CSS pixels from the picture's top-left. Use it for clocks, ads, avatars.
631
+ - PNG only. Keep the page still (wait for it first) and the window size the same between runs.
632
+ - **Reports** shows the baseline, the actual picture and a diff (red: differs, yellow: anti-aliasing, blue:
633
+ masked) with **Accept new baseline** when the new look is right. `"updateBaseline": true` replaces the
634
+ baseline on every run (switch it off again). The step's output has `visual` (`status`, `diffRatio`,
635
+ `diffPixels`, `comparisonId`).
636
+ - Playwright export: `await expect(page).toHaveScreenshot("<block id>.png", { threshold, maxDiffPixelRatio,
637
+ mask })` (or on the element's locator); mask rectangles become a comment.
638
+
639
+ ```json
640
+ { "id": "home-look", "type": "screenshot", "config": { "area": "full", "compare": true, "maxDiffRatio": 0.001, "mask": [{ "region": "#clock" }] } }
641
+ ```
642
+
643
+ ### Network, device and clean state (Chromium)
644
+
645
+ Rules and overrides last for the rest of the run and are removed when it ends (passed, failed or stopped).
646
+ Only one run at a time can own a tab's routes and emulation.
647
+
648
+ - **Route** mocks, blocks or changes the tab's requests. `rules` is a JSON array; the **newest** matching
649
+ rule wins. Each rule: `url` (pattern, `**/api/**`), optional `method`, `action` (`fulfill` with
650
+ `status`/`headers`/`body`, `abort`, `continue`, `modify` the outgoing `headers`/`body`, `redirect` to
651
+ `redirectUrl`), optional `delayMs`. `backend: "auto"` uses browser rules (`declarativeNetRequest`, also
652
+ Firefox, no debugging bar) when every rule is `abort`/`redirect` without a delay, else Chromium's debugger.
653
+ `"action": "clear"` removes the tab's rules.
654
+ - **Emulate**: `device` (`iphone`, `pixel`, `ipad`, `desktop`), or `width`+`height`, `deviceScaleFactor`,
655
+ `userAgent`, `locale`, `timezone`, `latitude`+`longitude`, `colorScheme`, `reducedMotion`, `offline`.
656
+ Reload after it if the page reads these at load. `"action": "clear"` resets. Geolocation still needs the
657
+ site's own permission.
658
+ - **HAR Record** `start` … `stop`: request metadata as HAR 1.2 (at most 500 entries, `truncated` past that),
659
+ into `{{har}}`, a `dataset` or a downloaded `filename`. No bodies, cookies or auth headers; sensitive URL
660
+ query values are redacted.
661
+ - **Console**: with the debugger attached, each step records the page's console messages and uncaught
662
+ exceptions; Reports shows them under the step. Assert `console-errors` counts the errors.
663
+ - **Clear Site Data** `origins` (exact `https://site.example` origins, one per line): deletes cookies,
664
+ localStorage, IndexedDB, Cache Storage and service workers for those sites, Chromium only, permanent.
665
+ Cookies are removed for the whole registrable domain (subdomains too). Put it first for a clean start.
666
+
667
+ Example: [`mock-api-mobile`](examples/mock-api-mobile.blockflow.json).
668
+
669
+ ## 14. Scraping and data
670
+
671
+ - **One page**: `Open Tab → Extract List` with an item locator (`.product-card`) and fields
672
+ (`name`, `locator` inside the item, optional `attribute` such as `href`). Result: `{{items}}`, a list
673
+ of objects in field order; links come back absolute.
674
+ - **Many pages**: `Paginate` (Next locator) with Extract List + Save to Dataset on its `each` output,
675
+ and Download on `done`.
676
+ - **Infinite lists**: `Scroll` with `to: "end"` before Extract List.
677
+ - **Tables**: `Extract Table` (rows keyed by header text).
678
+ - **Without a tab** (static pages, faster): `HTTP Request → Extract List/Table` with
679
+ `source: "html"`, `html: "{{body}}"`, `baseUrl: "{{url}}"`.
680
+ - **Lists**: `For Each` (runs `each` per item, then `done`), `Filter` (per-item condition with
681
+ `{{item.x}}`), `Transform` (typed values from expressions), `Repeat` (N times).
682
+ - **Keeping data**: `Save to Dataset` (append/replace, kept in the browser; see the **Data** page,
683
+ which downloads CSV/JSON) and `Download` (CSV, JSON or text file into Downloads).
684
+ - **The page itself**: `Page Info` (title, meta, canonical, JSON-LD) or its localStorage /
685
+ sessionStorage / cookies. To change them (or read HttpOnly cookies): `Cookies & Storage`.
686
+ - **Files the site exports**: Click the export button → `Wait for Download` with `read: "csv"` and a
687
+ `dataset` → the rows are in the dataset (and `{{rows}}`).
688
+
689
+ ## 15. Monitoring patterns
690
+
691
+ - `Timer (repeat) → Read Element (Page URL) → If → Notify`: Read Element with a Page URL uses
692
+ BlockFlow's own background tab and reloads it each time. `{{previous}}` and `{{changed}}` compare
693
+ with the last run: `If {{value}} less {{previous}}` = "price dropped".
694
+ - `Watch Element → Notify`: fires only when the text changes.
695
+ - `Timer → HTTP Request → Assert {{status}} equals 200 (onError: port) → Notify`: uptime check.
696
+
697
+ ## 16. Examples
698
+
699
+ Each example is in both formats: `<name>.script.json` (the script, start here) and `<name>.blockflow.json`
700
+ (the graph, also the editor's templates). A test checks that both import to the same graph.
701
+
702
+ | File | Shows |
703
+ | --- | --- |
704
+ | [`login-test`](examples/login-test.blockflow.json) | Fill Form with a secret, Wait For URL with an error branch, Assert |
705
+ | [`reusable-login`](examples/reusable-login.blockflow.json) | two workflows: a reusable login and a test that calls it |
706
+ | [`price-watch`](examples/price-watch.blockflow.json) | monitoring with `{{previous}}` |
707
+ | [`api-uptime`](examples/api-uptime.blockflow.json) | HTTP Request + Assert + error output |
708
+ | [`api-status-router`](examples/api-status-router.blockflow.json) | Repeat until (retry while 5xx) + Switch on the status, branches rejoining |
709
+ | [`dark-mode-watch`](examples/dark-mode-watch.blockflow.json) | reading a class on `<html>`, `{{changed}}` |
710
+ | [`scrape-to-csv`](examples/scrape-to-csv.blockflow.json) | Paginate + Extract List + dataset + CSV download |
711
+ | [`data-driven-login`](examples/data-driven-login.blockflow.json) | Data Table + For Each + soft Assert, a secret chosen by an expression |
712
+ | [`api-to-dataset`](examples/api-to-dataset.blockflow.json) | HTTP Request + Transform + dataset history + If |
713
+ | [`mock-api-mobile`](examples/mock-api-mobile.blockflow.json) | Emulate a phone + dark mode, Route mocks a 503 and blocks analytics, Assert text and console errors |
714
+ | [`aria-login-structure`](examples/aria-login-structure.blockflow.json) | Assert `aria-snapshot`: the page's structure (exact and regex names, states, nesting), then one part of it by locator |
715
+ | [`playground-tour`](examples/playground-tour.blockflow.json) | the "Try it" workflow: Click, Fill, Select Option and Assert on `docs/manual-test/playground.html` (`npm run playground`) |
716
+
717
+ ## 17. Limits (what a browser extension cannot do, or BlockFlow does not do yet)
718
+
719
+ - Page events are synthetic (`isTrusted: false`) unless `realInput` is on (Chromium only). Real input
720
+ inside iframes assumes the page is not zoomed or CSS-transformed around the frame.
721
+ - The recorder names every popup `popup`: with two popups open at once, steps in the older one are
722
+ attributed to the newer. Iframes added after the page finished loading are not recorded (reload
723
+ or record again); a frame whose parent page does not answer BlockFlow's question about which
724
+ iframe it is (a page that swallows `message` events) records nothing.
725
+ - Closed shadow roots are not supported. Synthetic drags (without `realInput`) send pointer events to the
726
+ dragged element (as if it captured the pointer) and run synchronously, so drag code that waits for
727
+ animation frames or timers between moves may need `realInput`. Drag needs both elements in the same frame.
728
+ - Run Script needs Chrome 135+ with user scripts allowed; Firefox and older Chrome explain that.
729
+ - Response bodies (Wait For `captureBody`) need Chromium's debugger and only work for responses that
730
+ start after the Wait For starts. Wait for Download cannot open the saved file: `read` fetches its
731
+ address again (a link that makes a new file every time gives that new file; a POST form download
732
+ cannot be read). Chromium full-page and background-tab screenshots need the debugger permission.
733
+ - Route mocking, Emulate, HAR Record, console capture and Clear Site Data need Chromium (the `debugger`
734
+ or `browsingData` permission); Firefox explains that. Route with only `abort`/`redirect` rules works
735
+ everywhere. HAR replay is not built. Emulation covers the listed settings, not a full device.
736
+ - Pages browsers protect: `chrome://`, the extension stores, other extensions, PDF viewer. `file://`
737
+ only after the user enables "Allow access to file URLs".
738
+ - CAPTCHAs and 2FA are not bypassed: use Manual Step.
739
+ - Background tabs are throttled by the browser; use `"where": "window"` for tests that need
740
+ animations, lazy loading or screenshots.
741
+ - Runs stop after 1000 blocks (loop guard). Run history keeps 40 runs, the run log 300 lines and 150 screenshots;
742
+ all four are changeable in **Settings → Limits** (10–500 runs, 100–5000 log lines, 20–1000 screenshots,
743
+ 100–100000 blocks per run; raise the last one for For Each over big lists). Payloads over 3 KB are stored
744
+ as a preview.
745
+ - Firefox: grant site access in `about:addons` → BlockFlow → Permissions.
746
+
747
+ ## Repair: what import errors mean
748
+
749
+ Import reports every problem as `<level> <code> at <path>: <message> <hint>`, for example
750
+ `error config.key.unknown at /workflows/0/nodes/1/config/locater: Block "go" (click) has no setting "locater". Did you mean "locator"?`.
751
+ `path` is a JSON Pointer into the file as written: `/workflows/0/nodes/1/config/locater` is the key
752
+ `locater` in the `config` of the second node of the first workflow (`/nodes/1/...` for a bare workflow).
753
+ In a script, paths point at steps: `/steps/2/click/locater` is the `locater` setting of the third step (a
754
+ Click), `/steps/1/true/0` the first step of the second step's `true` list, `/steps/0/open` a shorthand value,
755
+ `/scripts/1/steps/…` a step of the second script in a file of several.
756
+ **Errors** refuse the whole file, **warnings** import with a notice, **info** is a note. The codes are stable.
757
+
758
+ | Code | Level | Meaning | Fix |
759
+ | --- | --- | --- | --- |
760
+ | `json.invalid` | error | Not JSON. The message gives the parser's position. | Remove trailing commas and comments, quote keys. |
761
+ | `file.shape` | error | Not a workflow file: not an object, `workflows`/`nodes`/`edges` not lists, a node without string `id`/`type`, `config`/`step` not objects, unknown `format`, schema newer than this BlockFlow. | Follow section 2. `edges: []` when there are none. |
762
+ | `file.key.unknown` | warning | A key BlockFlow does not read on the file, a workflow, a node or a connection (ignored). | Use the hinted key (`config`, not `settings`; `source`, not `from`; `sourcePort`, not `sourceHandle`). |
763
+ | `node.id.duplicate` | error | Two nodes in one workflow share an `id`. | Give each node its own id. |
764
+ | `node.type.unknown` | error | `type` is not a block. | Use the hinted type, or one from [`blocks.md`](blocks.md) (Open Tab is `open-url`). |
765
+ | `config.key.unknown` | error | A `config` key (or a column in a list setting like Fill Form's `fields`) the block does not have. | Use the hinted key; the hint lists valid keys when nothing is close. |
766
+ | `config.key.renamed` | info | An old key name (`selector` on Read/Watch Element, `next` on Paginate). It is moved on import. | Use the new name (`locator`). |
767
+ | `config.type` | error | Wrong JSON type: text as a number, `"true"` in quotes, a list setting that is not a list. | Strings in quotes, numbers and `true`/`false` without. |
768
+ | `config.required` | error | A required setting is missing or empty, or a setting another one needs (Assert on an element → `locator`; Wait For `text` mode → `text`; Upload File from a URL → `url`; Download a dataset → `dataset`; Navigate `goto` → `url`; a list row without its first column). | Fill in the setting at the path. |
769
+ | `config.enum` | error | A choice that is not one of the options. | Use the hinted value; the hint lists the options. |
770
+ | `config.value` | error | A value of the right type that is not allowed: a number out of range, a Schedule time that is not `HH:MM`. | See the setting's notes in [`blocks.md`](blocks.md). |
771
+ | `config.locator.invalid` | error | A locator that cannot work: unclosed quote or bracket, an unknown `engine=` (`rol=button`), `nth=` without a number. | Fix the syntax (section 4). Templated locators are checked when the block runs. |
772
+ | `config.url.invalid` | error | Not an http(s) URL (`javascript:`, `file:`, garbage). | A full `https://…` address, or a `{{template}}`. |
773
+ | `config.template.invalid` | error | A broken `{{ … }}`: unbalanced braces or a bad expression. | Fix the expression (section 3). |
774
+ | `config.template.unsupported` | warning | `{{ … }}` in a setting that does not render templates; the braces stay as typed. | Remove the braces. Expression settings (For Each / Filter `list`, Transform, Save to Dataset / Download `value`) take `items`, not `{{items}}`. |
775
+ | `step.key.unknown` | error | A `step` key that does not exist. | `timeoutSeconds`, `retries`, `onError`, `disabled`, `note`, `screenshot`, `realInput` (section 7). |
776
+ | `step.value` | error | A bad `step` value (`retries` above 5, `onError: "ignore"`…). | See section 7. |
777
+ | `edge.endpoint.missing` | error | A connection's `source` or `target` is not a node id in that workflow. | Use the hinted id. |
778
+ | `edge.port.unknown` | error | `sourcePort` names an output the block does not have, or `"error"` on a block without `step.onError: "port"`. | Use the hinted output (`true`/`false` on If, `each`/`done` on loops, the case names and `default` on Switch), or add `"step": {"onError": "port"}`. |
779
+ | `edge.target.no-input` | error | A connection into a block that only starts workflows (Schedule). | Remove the connection. |
780
+ | `edge.duplicate` | warning | The same connection twice. | Remove one. |
781
+ | `graph.no-start` | error | Every block has an incoming connection, so nothing starts the workflow (a warning for a workflow with no blocks). | Remove the connection into the first block. |
782
+ | `graph.cycle` | warning (error for a block connected to itself) | A connection back to an earlier block makes a loop; runs stop after 1000 blocks. | Loop with Repeat, For Each or Paginate (their `each` output) instead. |
783
+ | `graph.unreachable` | warning | A block no start block leads to; it never runs. | Connect it, or remove it. |
784
+ | `page.no-tab` | warning | A page block whose tab (`tab`, default `main`) is not opened on every path to it. | Add an Open Tab (`open-url`) with that `tab` earlier on every path, or fix `tab`. Fine for a workflow called by Run Workflow from one that opened the tab. |
785
+ | `workflow.call.missing` | error | Run Workflow's `workflow` is not the `id` of a workflow in the file or already saved. | Put the called workflow in the same file and use its `id` (not its name). |
786
+ | `secret.unknown` | warning | `{{secret.x}}` names a secret the user has not created. | Create the secret (Secrets tab) before running, or fix the name. |
787
+
788
+ Script files only:
789
+
790
+ | Code | Level | Meaning | Fix |
791
+ | --- | --- | --- | --- |
792
+ | `script.shape` | error | Not an object, no `steps` list, `format` is not `blockflow-script`, or `"scripts": []`. | Follow the script format above. |
793
+ | `script.version` | error | `version` other than `1`. | `"version": 1`. |
794
+ | `script.empty` | warning | `"steps": []`. | Add steps. |
795
+ | `step.shape` | error | A step that is not an object, has no block key or two of them, a bare value for a block without a shorthand, `step` or `onError` of the wrong type, an empty `id`. | One block key per step; settings as an object unless the block has a shorthand. |
796
+ | `step.branch.next` | error | A list under the continue port (`out`, or `done` on loops). | Put those steps after this step instead. |
797
+ | `step.onError.conflict` | error | An `onError` list on a step whose `step.onError` is `stop` or `continue`. | Drop `step.onError` (the list sets `"port"`), or the list. |
798
+
799
+ `node.type.unknown`, `node.id.duplicate` and `edge.port.unknown` (a list under a key that is not one of
800
+ the block's outputs, like `"ture"`) also apply to scripts, with step paths.