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.
- package/LICENSE +21 -0
- package/README.md +40 -2
- package/bridgeSession.mjs +163 -0
- package/format.mjs +132 -0
- package/index.d.mts +42 -0
- package/index.mjs +428 -0
- package/package.json +52 -4
- package/resources/README.md +800 -0
- package/resources/blocks.md +940 -0
- package/resources/llms.txt +25 -0
- package/resources/script.schema.json +3333 -0
- package/resources.mjs +67 -0
- package/scripts/pack.mjs +20 -0
- package/server.mjs +30 -0
|
@@ -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.
|