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,940 @@
1
+ # Block reference
2
+
3
+ <!-- Generated by scripts/guide.ts from src/core/blocks. Do not edit by hand: run `npm run guide:sync`. -->
4
+
5
+ 53 blocks. Every block also accepts the common `step` settings (see README.md in this folder).
6
+
7
+ - **Start**: [Start](#%EF%B8%8F-start--start) `start` · [Timer](#-timer--timer) `timer` · [Schedule](#-schedule--schedule) `schedule` · [Page Visited](#-page-visited--page-visited) `page-visited` · [Context Menu](#-context-menu--context-menu) `context-menu` · [Watch Element](#-watch-element--watch-element) `watch-element`
8
+ - **Tabs**: [Open Tab](#-open-tab--open-url) `open-url` · [Navigate](#-navigate--navigate) `navigate` · [Wait for Popup](#-wait-for-popup--wait-for-popup) `wait-for-popup` · [Wait for Download](#-wait-for-download--wait-for-download) `wait-for-download` · [Cookies & Storage](#-cookies--storage--cookies-storage) `cookies-storage` · [Route](#-route--route) `route` · [HAR Record](#-har-record--har-record) `har-record` · [Emulate](#-emulate--emulate) `emulate` · [Clear Site Data](#-clear-site-data--clear-site-data) `clear-site-data` · [Close Tab](#%EF%B8%8F-close-tab--close-tab) `close-tab`
9
+ - **Page actions**: [Click](#-click--click) `click` · [Fill](#%EF%B8%8F-fill--fill) `fill` · [Fill Form](#-fill-form--fill-form) `fill-form` · [Select Option](#-select-option--select-option) `select-option` · [Check](#%EF%B8%8F-check--check) `check` · [Press Key](#-press-key--press-key) `press-key` · [Drag](#-drag--drag) `drag` · [Element Action](#%EF%B8%8F-element-action--element-action) `element-action` · [Upload File](#-upload-file--upload-file) `upload-file` · [Scroll](#%EF%B8%8F-scroll--scroll) `scroll` · [Dialogs](#-dialogs--dialogs) `dialogs` · [Wait For](#-wait-for--wait-for) `wait-for` · [Run Script](#-run-script--run-script) `run-script`
10
+ - **Read & scrape**: [Read Element](#-read-element--read-element) `read-element` · [Extract List](#-extract-list--extract-list) `extract-list` · [Extract Table](#-extract-table--extract-table) `extract-table` · [Paginate](#-paginate--paginate) `paginate` · [Page Info](#%E2%84%B9%EF%B8%8F-page-info--page-info) `page-info` · [Page Snapshot](#-page-snapshot--page-snapshot) `page-snapshot` · [Screenshot](#-screenshot--screenshot) `screenshot`
11
+ - **Test**: [Assert](#-assert--assert) `assert` · [Manual Step](#-manual-step--manual-step) `manual-step` · [Stop](#-stop--stop) `stop`
12
+ - **Logic & loops**: [If](#-if--if) `if` · [Switch](#-switch--switch) `switch` · [For Each](#-for-each--for-each) `for-each` · [Repeat](#-repeat--repeat) `repeat` · [Run Workflow](#-run-workflow--run-workflow) `run-workflow`
13
+ - **Data**: [Set Variable](#%EF%B8%8F-set-variable--set-variable) `set-variable` · [Transform](#-transform--transform) `transform` · [Filter](#-filter--filter) `filter` · [Data Table](#%EF%B8%8F-data-table--data-table) `data-table` · [Save to Dataset](#-save-to-dataset--save-dataset) `save-dataset` · [Download](#%EF%B8%8F-download--download) `download`
14
+ - **Send & log**: [Notify](#-notify--notify) `notify` · [HTTP Request](#-http-request--http-request) `http-request` · [Log](#-log--log) `log`
15
+
16
+ ## ▶️ Start — `start`
17
+
18
+ Start here when you press Run, with some starting values (also defaults for Run Workflow).
19
+
20
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
21
+ - Default timeout: 60s
22
+ - Can start a workflow: yes (has its own schedule/trigger)
23
+
24
+ | Setting (`config` key) | Type | Default | Notes |
25
+ | --- | --- | --- | --- |
26
+ | `inputs` (Starting values) | list of rows {name, value} | `[]` | |
27
+
28
+ Adds to the data: `(your names)` (One key per starting value.)
29
+
30
+ ## ⏱ Timer — `timer`
31
+
32
+ Start the flow on a schedule, or delay it when placed after another block.
33
+
34
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
35
+ - Default timeout: 660s
36
+ - Can start a workflow: yes (has its own schedule/trigger)
37
+
38
+ | Setting (`config` key) | Type | Default | Notes |
39
+ | --- | --- | --- | --- |
40
+ | `seconds` (Seconds) | number | `60` | Under 30 seconds the extension keeps its background worker awake to fire on time (Chromium). 30 seconds or more uses browser alarms. After another block: waits up to 600 s inside the run; longer delays continue as a new run. |
41
+ | `repeat` (Repeat) | boolean | `true` | Only used when this block starts the flow. After another block it always fires once. |
42
+
43
+ Adds to the data: `tick` (How many times the timer has fired (when it starts the flow).); `firedAt` (ISO time the timer fired.)
44
+
45
+ ## 📅 Schedule — `schedule`
46
+
47
+ Start the flow at set times: daily at 09:00, on weekdays, every hour, every N minutes.
48
+
49
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
50
+ - Default timeout: 60s
51
+ - Can start a workflow: yes (has its own schedule/trigger)
52
+
53
+ | Setting (`config` key) | Type | Default | Notes |
54
+ | --- | --- | --- | --- |
55
+ | `every` (Every) | one of `day`, `hour`, `minutes` | `"day"` | |
56
+ | `at` (At (HH:MM)) | text | `"09:00"` | For "day". Local time of this computer. |
57
+ | `days` (Days) | text | `"weekdays"` | For "day": every day, weekdays, weekends, or names: mon, wed, fri. |
58
+ | `minute` (Minute) | number | `0` | For "hour": minutes past the hour. |
59
+ | `minutes` (Minutes) | number | `15` | For "N minutes". Runs on the clock (:00, :15, :30…). |
60
+
61
+ Adds to the data: `firedAt` (When it fired.); `scheduledFor` (The time it was planned for.)
62
+
63
+ ## 🌍 Page Visited — `page-visited`
64
+
65
+ Start when you open a matching page (in any tab). That tab becomes "main".
66
+
67
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
68
+ - Default timeout: 60s
69
+ - Can start a workflow: yes (has its own schedule/trigger)
70
+
71
+ | Setting (`config` key) | Type | Default | Notes |
72
+ | --- | --- | --- | --- |
73
+ | `url` (Page URL pattern) | text | `""` | required. Plain text = the URL contains it; * any part between slashes; ** anything; /…/ regex. |
74
+ | `when` (When) | one of `load`, `any` | `"load"` | |
75
+
76
+ Adds to the data: `url` (The page address.); `title` (The page title.); `tabId` (The tab.)
77
+
78
+ ## 🖱 Context Menu — `context-menu`
79
+
80
+ Add an item to the right-click menu that starts the flow on that page.
81
+
82
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
83
+ - Default timeout: 60s
84
+ - Can start a workflow: yes (has its own schedule/trigger)
85
+
86
+ | Setting (`config` key) | Type | Default | Notes |
87
+ | --- | --- | --- | --- |
88
+ | `title` (Menu item) | text | `"Run my workflow"` | required |
89
+ | `contexts` (Show it when right-clicking) | one of `all`, `page`, `selection`, `link`, `image` | `"all"` | |
90
+
91
+ Adds to the data: `url` (The page address.); `selection` (Selected text, if any.); `link` (The link right-clicked, if any.); `src` (The image right-clicked, if any.)
92
+
93
+ ## 👁 Watch Element — `watch-element`
94
+
95
+ Fire when the text of a part of a web page changes.
96
+
97
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
98
+ - Default timeout: 60s
99
+ - Can start a workflow: yes (has its own schedule/trigger)
100
+
101
+ | Setting (`config` key) | Type | Default | Notes |
102
+ | --- | --- | --- | --- |
103
+ | `locator` (Element) | locator | `""` | required |
104
+ | `url` (Page URL) | url | `""` | required, supports `{{…}}` |
105
+ | `intervalSeconds` (Check every (seconds)) | number | `60` | Only used when this block starts the flow. After a Timer, the Timer decides. Under 30 seconds keeps the background worker awake. |
106
+ | `reload` (Reload page before checking) | boolean | `true` | Needed to see server-side changes. Turn off for pages that update themselves. |
107
+ | `emitOnFirstRead` (Fire on the first read too) | boolean | `false` | Off = the first read just records the starting value. |
108
+
109
+ Adds to the data: `value` (The new text of the element.); `previous` (The text before the change (null on the first read).); `url` (The page that was watched.); `locator` (The element locator (also as `selector`, its name before v0.3).); `changedAt` (ISO time the change was noticed.)
110
+
111
+ ## 🔗 Open Tab — `open-url`
112
+
113
+ Open a web page, and remember the tab for the next blocks.
114
+
115
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
116
+ - Default timeout: 45s
117
+ - Can start a workflow: yes (runs once with empty data)
118
+
119
+ | Setting (`config` key) | Type | Default | Notes |
120
+ | --- | --- | --- | --- |
121
+ | `url` (URL) | url | `""` | required, supports `{{…}}`. Use {{name}} to insert a value from the previous block. |
122
+ | `where` (Open in) | one of `new`, `workflow`, `window`, `current` | `"new"` | |
123
+ | `tab` (Tab name) | text | `"main"` | Later blocks find the tab by this name. Use another name (e.g. "admin") for a second tab. |
124
+ | `active` (Switch to it) | boolean | `true` | Off = open quietly in the background. |
125
+ | `waitUntil` (Continue when) | one of `load`, `networkidle`, `none` | `"load"` | |
126
+
127
+ Adds to the data: `url` (The URL that was opened.); `tabId` (Id of the tab it was opened in.)
128
+
129
+ ## 🧭 Navigate — `navigate`
130
+
131
+ Go to a URL, back, forward, or reload, in a tab of this run.
132
+
133
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
134
+ - Default timeout: 45s
135
+ - Can start a workflow: yes (runs once with empty data)
136
+
137
+ | Setting (`config` key) | Type | Default | Notes |
138
+ | --- | --- | --- | --- |
139
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
140
+ | `action` (Action) | one of `goto`, `back`, `forward`, `reload` | `"goto"` | |
141
+ | `url` (URL) | text | `""` | supports `{{…}}` |
142
+ | `waitUntil` (Continue when) | one of `load`, `networkidle`, `none` | `"load"` | |
143
+
144
+ Adds to the data: `url` (The URL after navigating.)
145
+
146
+ ## 🪟 Wait for Popup — `wait-for-popup`
147
+
148
+ Catch a new tab or window the page opened, and name it for the next blocks.
149
+
150
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
151
+ - Default timeout: 30s
152
+ - Can start a workflow: yes (runs once with empty data)
153
+
154
+ | Setting (`config` key) | Type | Default | Notes |
155
+ | --- | --- | --- | --- |
156
+ | `tab` (Opened by tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
157
+ | `name` (Call the new tab) | text | `"popup"` | required |
158
+ | `waitUntil` (Continue when) | one of `load`, `networkidle`, `none` | `"load"` | |
159
+
160
+ Adds to the data: `popupUrl` (The address of the new tab.); `popupTabId` (Its tab id.)
161
+
162
+ ## 📥 Wait for Download — `wait-for-download`
163
+
164
+ Wait until the page downloads a file (an export, a report) and get its name, size and type. Can read CSV / JSON / text files.
165
+
166
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
167
+ - Default timeout: 60s
168
+ - Can start a workflow: yes (runs once with empty data)
169
+
170
+ | Setting (`config` key) | Type | Default | Notes |
171
+ | --- | --- | --- | --- |
172
+ | `url` (URL or file name (optional)) | text | `""` | supports `{{…}}`. Empty = the first download. Plain text: the address or file name contains it; * and /regex/ as in Wait For. |
173
+ | `read` (Read the file) | one of `none`, `text`, `csv`, `json` | `"none"` | Extensions cannot open files on disk, so the file is fetched again from its address (with the site's cookies). Fine for exports; a link that makes a new file each time gives that new file. |
174
+ | `dataset` (Save rows to dataset (optional)) | text | `""` | supports `{{…}}`. CSV rows, or a JSON list, replace this dataset. |
175
+ | `tab` (Tab) | text | `"main"` | The tab that starts the download. Needed only to read files the page made itself (blob: addresses). |
176
+
177
+ Adds to the data: `download` ({filename, url, path, size, mime, downloadId} of the finished download.); `content` (With "as text": the file content.); `rows` (With "as CSV": one object per row, by header.); `data` (With "as JSON": the parsed value.); `datasetSize` (With a dataset: its rows afterwards.)
178
+
179
+ ## 🍪 Cookies & Storage — `cookies-storage`
180
+
181
+ Read, set, delete or clear a site's cookies, or the page's localStorage / sessionStorage.
182
+
183
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
184
+ - Default timeout: 30s
185
+ - Can start a workflow: yes (runs once with empty data)
186
+
187
+ | Setting (`config` key) | Type | Default | Notes |
188
+ | --- | --- | --- | --- |
189
+ | `action` (Do) | one of `get`, `set`, `delete`, `clear` | `"get"` | |
190
+ | `area` (In) | one of `cookies`, `local`, `session` | `"cookies"` | |
191
+ | `name` (Name / key) | text | `""` | supports `{{…}}`. Needed to set or delete. For get: empty = all of them. |
192
+ | `value` (Value) | text | `""` | supports `{{…}}`. For set. |
193
+ | `url` (Site (cookies, optional)) | text | `""` | supports `{{…}}`. Whose cookies. Empty = the page open in the tab. |
194
+ | `domain` (Domain (set, optional)) | text | `""` | supports `{{…}}`. With a leading dot the cookie is also sent to subdomains. |
195
+ | `path` (Path (set, optional)) | text | `""` | |
196
+ | `maxAgeSeconds` (Expires in seconds (set)) | number | `0` | 0 = a session cookie, gone when the browser closes. |
197
+ | `httpOnly` (HttpOnly (set)) | boolean | `false` | |
198
+ | `secure` (Secure (set)) | boolean | `false` | |
199
+ | `sameSite` (SameSite (set)) | one of ``, `Lax`, `Strict`, `None` | `""` | |
200
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
201
+
202
+ Adds to the data: `value` (get with a name: the value (null when missing). get without: an object of name → value. set: the value.); `cookies` (Cookies, get/set: the full cookies [{name, value, domain, path, expires, httpOnly, secure, sameSite}].); `deleted` (delete / clear: how many were removed.)
203
+
204
+ ## 🚦 Route — `route`
205
+
206
+ Mock, block or modify page requests for this run. Newest matching rule wins; clear removes the tab’s rules.
207
+
208
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
209
+ - Default timeout: 30s
210
+ - Can start a workflow: yes (runs once with empty data)
211
+
212
+ | Setting (`config` key) | Type | Default | Notes |
213
+ | --- | --- | --- | --- |
214
+ | `action` (Do) | one of `add`, `clear` | `"add"` | |
215
+ | `backend` (Use) | one of `auto`, `cdp`, `dnr` | `"auto"` | |
216
+ | `rules` (Rules (JSON)) | text | `"[]"` | supports `{{…}}`. An array: url pattern, optional method, action, optional status/headers/body/redirectUrl/delayMs. Last matching rule wins. CDP modify changes the outgoing request; browser rules support abort/redirect without delays. |
217
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
218
+
219
+ Adds to the data: `route` (Installed rule count and backend ({rules, backend}). Cleared routes report zero rules.)
220
+
221
+ ## 📡 HAR Record — `har-record`
222
+
223
+ Start or stop recording network metadata as HAR 1.2. Chromium only; bodies, cookies and headers are excluded.
224
+
225
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
226
+ - Default timeout: 60s
227
+ - Can start a workflow: yes (runs once with empty data)
228
+
229
+ | Setting (`config` key) | Type | Default | Notes |
230
+ | --- | --- | --- | --- |
231
+ | `action` (Do) | one of `start`, `stop` | `"start"` | |
232
+ | `dataset` (Save entries to dataset (stop, optional)) | text | `""` | supports `{{…}}`. Replaces this dataset with the HAR entries. |
233
+ | `filename` (Download HAR file (stop, optional)) | text | `""` | supports `{{…}}`. Leave blank to return the HAR without downloading it. |
234
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
235
+
236
+ Adds to the data: `recording` (Whether recording is active.); `har` (On stop: HAR 1.2 log, metadata only (at most 500 entries).); `truncated` (True when more requests occurred than the recording limit.); `datasetSize` (Entries written when a dataset was supplied.)
237
+
238
+ ## 📱 Emulate — `emulate`
239
+
240
+ Chromium only: change viewport/device, locale, timezone, location, media preferences or offline state until this run ends. Location still needs the site’s permission.
241
+
242
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
243
+ - Default timeout: 60s
244
+ - Can start a workflow: yes (runs once with empty data)
245
+
246
+ | Setting (`config` key) | Type | Default | Notes |
247
+ | --- | --- | --- | --- |
248
+ | `action` (Do) | one of `set`, `clear` | `"set"` | |
249
+ | `device` (Device preset) | one of ``, `iphone`, `pixel`, `ipad`, `desktop` | `""` | |
250
+ | `width` (Viewport width) | number | `0` | 0 uses the preset/default. Supply width and height together. |
251
+ | `height` (Viewport height) | number | `0` | |
252
+ | `deviceScaleFactor` (Device scale factor) | number | `0` | 0 uses the preset/default. |
253
+ | `userAgent` (User agent) | text | `""` | supports `{{…}}`. Optional override of the preset user agent. Changes may need a later Navigate/reload. |
254
+ | `locale` (Locale) | text | `""` | supports `{{…}}`. Intl locale and language override; reload for page code that reads language at startup. |
255
+ | `timezone` (Timezone) | text | `""` | supports `{{…}}` |
256
+ | `latitude` (Latitude) | text | `""` | supports `{{…}}` |
257
+ | `longitude` (Longitude) | text | `""` | supports `{{…}}`. Both coordinates required. This does not grant the site geolocation permission. |
258
+ | `accuracy` (Location accuracy (metres)) | number | `1` | |
259
+ | `colorScheme` (Color scheme) | one of ``, `light`, `dark` | `""` | |
260
+ | `reducedMotion` (Reduced motion) | one of ``, `reduce`, `no-preference` | `""` | |
261
+ | `offline` (Offline) | boolean | `false` | Blocks network requests from this tab. Cleared automatically at run end. |
262
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
263
+
264
+ Adds to the data: `emulated` (Environment options applied to the tab.)
265
+
266
+ ## 🧹 Clear Site Data — `clear-site-data`
267
+
268
+ Chromium only: delete cookies, local storage, IndexedDB, Cache Storage and service workers for listed sites. Cookie deletion affects the whole registrable domain, including its subdomains.
269
+
270
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
271
+ - Default timeout: 60s
272
+ - Can start a workflow: yes (runs once with empty data)
273
+
274
+ | Setting (`config` key) | Type | Default | Notes |
275
+ | --- | --- | --- | --- |
276
+ | `origins` (Site origins to clear) | text | `""` | required, supports `{{…}}`. Explicit HTTP(S) origins only, separated by newlines or commas. Deletion is permanent. Cookies are cleared for each whole registrable domain, including subdomains; other storage is filtered by origin. Never clears history, downloads, passwords or extension data. |
277
+
278
+ Adds to the data: `clearedOrigins` (The exact origins whose site data was cleared (cookies use registrable-domain scope).)
279
+
280
+ ## ✖️ Close Tab — `close-tab`
281
+
282
+ Close a tab this run opened.
283
+
284
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
285
+ - Default timeout: 60s
286
+ - Can start a workflow: yes (runs once with empty data)
287
+
288
+ | Setting (`config` key) | Type | Default | Notes |
289
+ | --- | --- | --- | --- |
290
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
291
+
292
+ Adds to the data: `(same data)` (The input, passed on.)
293
+
294
+ ## 👆 Click — `click`
295
+
296
+ Click (or double-click, right-click, hover) an element, with any button, modifier keys and position. Waits until it can be clicked.
297
+
298
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
299
+ - Default timeout: 30s
300
+ - Can start a workflow: yes (runs once with empty data)
301
+ - Step setting `realInput` ("Use real mouse and keyboard") applies to this block
302
+
303
+ | Setting (`config` key) | Type | Default | Notes |
304
+ | --- | --- | --- | --- |
305
+ | `locator` (Element) | locator | `""` | required, supports `{{…}}`. CSS, or text=…, role=…[name="…"], label=…, placeholder=…, testid=…, A >> B, >> nth=0. Or press 🎯 Pick. |
306
+ | `action` (Action) | one of `click`, `double`, `right`, `hover` | `"click"` | |
307
+ | `button` (Mouse button) | one of `left`, `middle`, `right` | `"left"` | For "click". Right-click always uses the right button. |
308
+ | `modifiers` (Keys held) | text | `""` | Modifier keys held during the click: Alt, Control, Meta, Shift (joined with + or commas). Empty = none. |
309
+ | `position` (Position) | text | `""` | Where to click: x,y in pixels from the element’s top-left corner. Empty = its center. |
310
+ | `clickCount` (Click count) | number | `1` | Presses in a row (3 = triple click, selects a paragraph). Double-click means at least 2. |
311
+ | `force` (Skip the checks) | boolean | `false` | Click even if the element looks hidden, disabled or covered. Only for stubborn pages. |
312
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
313
+
314
+ Adds to the data: `(same data)` (The input, passed on.)
315
+
316
+ ## ⌨️ Fill — `fill`
317
+
318
+ Type a value into a text field. Works with React, Vue and Angular forms.
319
+
320
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
321
+ - Default timeout: 30s
322
+ - Can start a workflow: yes (runs once with empty data)
323
+ - Step setting `realInput` ("Use real mouse and keyboard") applies to this block
324
+
325
+ | Setting (`config` key) | Type | Default | Notes |
326
+ | --- | --- | --- | --- |
327
+ | `locator` (Field) | locator | `""` | required, supports `{{…}}`. CSS, or text=…, role=…[name="…"], label=…, placeholder=…, testid=…, A >> B, >> nth=0. Or press 🎯 Pick. |
328
+ | `value` (Value) | text | `""` | supports `{{…}}` |
329
+ | `mode` (How) | one of `fill`, `type` | `"fill"` | |
330
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
331
+
332
+ Adds to the data: `(same data)` (The input, passed on.)
333
+
334
+ ## 📋 Fill Form — `fill-form`
335
+
336
+ Fill several fields at once: text, selects, checkboxes. Optionally click submit.
337
+
338
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
339
+ - Default timeout: 30s
340
+ - Can start a workflow: yes (runs once with empty data)
341
+ - Step setting `realInput` ("Use real mouse and keyboard") applies to this block
342
+
343
+ | Setting (`config` key) | Type | Default | Notes |
344
+ | --- | --- | --- | --- |
345
+ | `fields` (Fields) | list of rows {locator, value} | `[]` | required. Empty values are skipped. Selects take the option text or value; checkboxes take true or false. |
346
+ | `submit` (Then click (optional)) | locator | `""` | supports `{{…}}`. CSS, or text=…, role=…[name="…"], label=…, placeholder=…, testid=…, A >> B, >> nth=0. Or press 🎯 Pick. |
347
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
348
+
349
+ Adds to the data: `(same data)` (The input, passed on.)
350
+
351
+ ## 🔽 Select Option — `select-option`
352
+
353
+ Choose an option in a dropdown (<select>), by its text or value.
354
+
355
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
356
+ - Default timeout: 30s
357
+ - Can start a workflow: yes (runs once with empty data)
358
+ - Step setting `realInput` ("Use real mouse and keyboard") applies to this block
359
+
360
+ | Setting (`config` key) | Type | Default | Notes |
361
+ | --- | --- | --- | --- |
362
+ | `locator` (Dropdown) | locator | `""` | required, supports `{{…}}`. CSS, or text=…, role=…[name="…"], label=…, placeholder=…, testid=…, A >> B, >> nth=0. Or press 🎯 Pick. |
363
+ | `value` (Option) | text | `""` | required, supports `{{…}}`. Several for a multi-select: separate with \| |
364
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
365
+
366
+ Adds to the data: `selected` (Values of the selected options.)
367
+
368
+ ## ☑️ Check — `check`
369
+
370
+ Tick or untick a checkbox, radio button or switch. Does nothing if it already is.
371
+
372
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
373
+ - Default timeout: 30s
374
+ - Can start a workflow: yes (runs once with empty data)
375
+ - Step setting `realInput` ("Use real mouse and keyboard") applies to this block
376
+
377
+ | Setting (`config` key) | Type | Default | Notes |
378
+ | --- | --- | --- | --- |
379
+ | `locator` (Checkbox) | locator | `""` | required, supports `{{…}}`. CSS, or text=…, role=…[name="…"], label=…, placeholder=…, testid=…, A >> B, >> nth=0. Or press 🎯 Pick. |
380
+ | `state` (Make it) | one of `check`, `uncheck` | `"check"` | |
381
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
382
+
383
+ Adds to the data: `(same data)` (The input, passed on.)
384
+
385
+ ## ⏎ Press Key — `press-key`
386
+
387
+ Press a key or shortcut (Enter, Tab, Escape, Control+A…), or insert text at the caret.
388
+
389
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
390
+ - Default timeout: 30s
391
+ - Can start a workflow: yes (runs once with empty data)
392
+ - Step setting `realInput` ("Use real mouse and keyboard") applies to this block
393
+
394
+ | Setting (`config` key) | Type | Default | Notes |
395
+ | --- | --- | --- | --- |
396
+ | `mode` (Do) | one of `key`, `text` | `"key"` | |
397
+ | `key` (Key) | text | `"Enter"` | Key names as on the keyboard: Enter, Tab, Escape, Backspace, ArrowDown, a, Control+A, Shift+Tab, Control+Shift+K. ControlOrMeta+A is ⌘A on a Mac, Ctrl+A elsewhere. |
398
+ | `text` (Text) | text | `""` | supports `{{…}}`. For "insert text": typed at the caret in one go, like pasting. |
399
+ | `locator` (On element (optional)) | locator | `""` | supports `{{…}}`. Focus this element first. Empty = whatever has focus. |
400
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
401
+
402
+ Adds to the data: `(same data)` (The input, passed on.)
403
+
404
+ ## ✋ Drag — `drag`
405
+
406
+ Drag an element onto another one: sortable lists, kanban cards, sliders, drop targets.
407
+
408
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
409
+ - Default timeout: 30s
410
+ - Can start a workflow: yes (runs once with empty data)
411
+ - Step setting `realInput` ("Use real mouse and keyboard") applies to this block
412
+
413
+ | Setting (`config` key) | Type | Default | Notes |
414
+ | --- | --- | --- | --- |
415
+ | `from` (Drag this) | locator | `""` | required, supports `{{…}}`. The element to pick up (a card, a list item, a slider handle). |
416
+ | `to` (Drop on) | locator | `""` | required, supports `{{…}}`. The element to drop it on (another item, a column, a spot on the slider track). |
417
+ | `fromPosition` (Grab at) | text | `""` | x,y in pixels from the top-left corner of "Drag this". Empty = its center. |
418
+ | `toPosition` (Drop at) | text | `""` | x,y in pixels from the top-left corner of "Drop on". Empty = its center. |
419
+ | `modifiers` (Keys held) | text | `""` | Modifier keys held during the drag: Alt, Control, Meta, Shift. |
420
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
421
+
422
+ Adds to the data: `(same data)` (The input, passed on.); `dragMode` ("html5" (drag events) or "pointer" (pointer/mouse moves): how the page took the drag.)
423
+
424
+ ## 🎛️ Element Action — `element-action`
425
+
426
+ Focus, blur, clear, scroll into view, or dispatch an event (click, input, a custom event) on an element.
427
+
428
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
429
+ - Default timeout: 30s
430
+ - Can start a workflow: yes (runs once with empty data)
431
+
432
+ | Setting (`config` key) | Type | Default | Notes |
433
+ | --- | --- | --- | --- |
434
+ | `locator` (Element) | locator | `""` | required, supports `{{…}}`. CSS, or text=…, role=…[name="…"], label=…, placeholder=…, testid=…, A >> B, >> nth=0. Or press 🎯 Pick. |
435
+ | `action` (Action) | one of `focus`, `blur`, `clear`, `scroll-into-view`, `dispatch-event` | `"focus"` | |
436
+ | `eventType` (Event type) | text | `""` | For "dispatch an event". Bubbles, cancelable and composed. |
437
+ | `detail` (Detail (JSON)) | text | `""` | supports `{{…}}`. For "dispatch an event". Built-in types (click, keydown, input, focus, drag…): the event’s properties. Other types are a CustomEvent and this is its event.detail. |
438
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
439
+
440
+ Adds to the data: `(same data)` (The input, passed on.); `defaultPrevented` (For "dispatch an event": true when the page cancelled the event.)
441
+
442
+ ## 📎 Upload File — `upload-file`
443
+
444
+ Choose a file for a file input or drop it on a drop zone, without the file dialog: text you write, a file from a URL, or base64 data.
445
+
446
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
447
+ - Default timeout: 30s
448
+ - Can start a workflow: yes (runs once with empty data)
449
+
450
+ | Setting (`config` key) | Type | Default | Notes |
451
+ | --- | --- | --- | --- |
452
+ | `locator` (File input or drop zone) | locator | `"input[type=file]"` | required, supports `{{…}}`. The <input type="file"> (hidden ones work too) or its label; with "drop zone", the area files are dropped on. |
453
+ | `target` (Put it) | one of `input`, `dropzone` | `"input"` | |
454
+ | `source` (File) | one of `text`, `url`, `data` | `"text"` | |
455
+ | `content` (Content) | text | `""` | supports `{{…}}`. For "text". |
456
+ | `url` (URL) | text | `""` | supports `{{…}}`. For "download". |
457
+ | `data` (Data) | text | `""` | supports `{{…}}`. For "base64 data": base64 or a data: URL, usually {{body64}} from HTTP Request with "Response as: base64". |
458
+ | `filename` (File name) | text | `"upload.txt"` | supports `{{…}}`. Empty with a URL = the name in the URL. |
459
+ | `mime` (Type) | text | `"text/plain"` | supports `{{…}}`. For "text" and "base64 data" ({{mime}} after HTTP Request; a data: URL brings its own). With a URL the server says. |
460
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
461
+
462
+ Adds to the data: `uploaded` (The file name.)
463
+
464
+ ## 🖱️ Scroll — `scroll`
465
+
466
+ Scroll to the bottom, top or an element; or keep scrolling until no more content loads.
467
+
468
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
469
+ - Default timeout: 120s
470
+ - Can start a workflow: yes (runs once with empty data)
471
+
472
+ | Setting (`config` key) | Type | Default | Notes |
473
+ | --- | --- | --- | --- |
474
+ | `to` (Scroll) | one of `end`, `bottom`, `top`, `element` | `"end"` | |
475
+ | `locator` (Element) | locator | `""` | supports `{{…}}`. Only for "to an element". |
476
+ | `maxScrolls` (At most (scrolls)) | number | `20` | |
477
+ | `pauseMs` (Wait between scrolls (ms)) | number | `1000` | |
478
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
479
+
480
+ Adds to the data: `scrolls` (How many times it scrolled.)
481
+
482
+ ## 💬 Dialogs — `dialogs`
483
+
484
+ Answer alert / confirm / prompt boxes automatically, or read what they said.
485
+
486
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
487
+ - Default timeout: 15s
488
+ - Can start a workflow: yes (runs once with empty data)
489
+
490
+ | Setting (`config` key) | Type | Default | Notes |
491
+ | --- | --- | --- | --- |
492
+ | `action` (From now on) | one of `accept`, `dismiss`, `read` | `"accept"` | |
493
+ | `text` (Text for prompts) | text | `""` | supports `{{…}}` |
494
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
495
+
496
+ Adds to the data: `dialogs` (Dialogs shown in this page so far: {type, message}.); `lastDialog` (The message of the latest one.)
497
+
498
+ ## ⏳ Wait For — `wait-for`
499
+
500
+ Wait until an element appears or goes, some text shows, the URL changes, or the page settles.
501
+
502
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
503
+ - Default timeout: 30s
504
+ - Can start a workflow: yes (runs once with empty data)
505
+
506
+ | Setting (`config` key) | Type | Default | Notes |
507
+ | --- | --- | --- | --- |
508
+ | `mode` (Wait until) | one of `visible`, `hidden`, `attached`, `detached`, `enabled`, `text`, `no-text`, `url`, `load`, `networkidle`, `response`, `request` | `"visible"` | |
509
+ | `locator` (Element) | locator | `""` | supports `{{…}}`. For the element modes. For text: only look inside this element (optional). |
510
+ | `text` (Text) | text | `""` | supports `{{…}}` |
511
+ | `url` (URL pattern) | text | `""` | supports `{{…}}`. Plain text: the URL contains it. * matches any part between slashes, ** anything. /…/ is a regular expression. Also the request address for the network modes. |
512
+ | `status` (Status (optional)) | text | `""` | For "a network request finishes". |
513
+ | `method` (Method (optional)) | text | `""` | For the network modes. Empty = any. |
514
+ | `captureBody` (Capture the response body) | boolean | `false` | For "a network request finishes". Chrome, Edge, Brave only (debugger permission). Only responses that start after this block starts can be read, so it suits slow or later requests. |
515
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
516
+
517
+ Adds to the data: `url` (The tab's URL when the wait ended.); `response` (For "a network request finishes": {url, status, method}, plus body (or bodyBase64) with "Capture the response body".); `request` (For "the page sends a request": {url, method, type, postData}.)
518
+
519
+ ## 🧑‍💻 Run Script — `run-script`
520
+
521
+ Run your own JavaScript in the page; its return value is saved. Chrome 135+.
522
+
523
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
524
+ - Default timeout: 30s
525
+ - Can start a workflow: yes (runs once with empty data)
526
+
527
+ | Setting (`config` key) | Type | Default | Notes |
528
+ | --- | --- | --- | --- |
529
+ | `code` (JavaScript) | text | `"return document.querySelectorAll('a').length;"` | required. An async function body: use await, read `data`, and `return` a JSON value. |
530
+ | `into` (Save the result as) | text | `"result"` | |
531
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
532
+
533
+ Adds to the data: `result` (What the code returned (or the name you chose).)
534
+
535
+ ## 🔎 Read Element — `read-element`
536
+
537
+ Read a value from a page: text, attribute, class, whether it exists, or how many.
538
+
539
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
540
+ - Default timeout: 60s
541
+ - Can start a workflow: yes (runs once with empty data)
542
+
543
+ | Setting (`config` key) | Type | Default | Notes |
544
+ | --- | --- | --- | --- |
545
+ | `locator` (Element) | locator | `""` | required, supports `{{…}}` |
546
+ | `url` (Page URL) | url | `""` | supports `{{…}}`. BlockFlow opens it in its own background tab. Leave empty to read the run's tab instead (see Tab). |
547
+ | `tab` (Tab) | text | `""` | Used when Page URL is empty: read from this tab of the run (from Open Tab), as it is now, without reloading. |
548
+ | `read` (Read) | one of `text`, `value`, `attribute`, `has-class`, `exists`, `count` | `"text"` | |
549
+ | `name` (Attribute / class name) | text | `""` | Only for "an attribute" and "has a class". |
550
+ | `reload` (Reload page before reading) | boolean | `true` | |
551
+
552
+ Adds to the data: `value` (What was read ("true"/"false" for class and exists).); `previous` (The value from the last run (empty on the first run).); `changed` (True when value differs from previous (false on the first run).); `count` (How many elements matched the locator.); `url` (The page that was read.); `locator` (The locator that was read (also as `selector`, its name before v0.3).)
553
+
554
+ ## 🧺 Extract List — `extract-list`
555
+
556
+ Scrape repeated items (cards, results, rows) into a list of objects.
557
+
558
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
559
+ - Default timeout: 30s
560
+ - Can start a workflow: yes (runs once with empty data)
561
+
562
+ | Setting (`config` key) | Type | Default | Notes |
563
+ | --- | --- | --- | --- |
564
+ | `locator` (Each item) | locator | `""` | required, supports `{{…}}`. CSS, or text=…, role=…[name="…"], label=…, placeholder=…, testid=…, A >> B, >> nth=0. Or press 🎯 Pick. |
565
+ | `fields` (Fields) | list of rows {name, locator, attribute} | `[]` | No fields = each item's text as {text}. Links (href, src) come back as full URLs. |
566
+ | `limit` (At most (0 = all)) | number | `0` | |
567
+ | `into` (Save the list as) | text | `"items"` | |
568
+ | `source` (From) | one of `tab`, `html` | `"tab"` | |
569
+ | `html` (HTML) | text | `"{{body}}"` | supports `{{…}}`. Only for "HTML in the data". |
570
+ | `baseUrl` (Page address) | text | `""` | supports `{{…}}`. Makes relative links absolute (HTML mode). |
571
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
572
+
573
+ Adds to the data: `items` (The list (or the name you chose).); `count` (How many items.)
574
+
575
+ ## 📊 Extract Table — `extract-table`
576
+
577
+ Read an HTML table into a list of rows, keyed by its column headers.
578
+
579
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
580
+ - Default timeout: 30s
581
+ - Can start a workflow: yes (runs once with empty data)
582
+
583
+ | Setting (`config` key) | Type | Default | Notes |
584
+ | --- | --- | --- | --- |
585
+ | `locator` (Table) | locator | `"table"` | required, supports `{{…}}`. CSS, or text=…, role=…[name="…"], label=…, placeholder=…, testid=…, A >> B, >> nth=0. Or press 🎯 Pick. |
586
+ | `into` (Save the rows as) | text | `"rows"` | |
587
+ | `source` (From) | one of `tab`, `html` | `"tab"` | |
588
+ | `html` (HTML) | text | `"{{body}}"` | supports `{{…}}`. Only for "HTML in the data". |
589
+ | `baseUrl` (Page address) | text | `""` | supports `{{…}}`. Makes relative links absolute (HTML mode). |
590
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
591
+
592
+ Adds to the data: `rows` (One object per row (or the name you chose).); `count` (How many rows.)
593
+
594
+ ## 📄 Paginate — `paginate`
595
+
596
+ Run "each" on every page of a paged list, clicking Next in between.
597
+
598
+ - Outputs (ports): `each`, `done` (plus `error` when step.onError is "port")
599
+ - Default timeout: 1800s
600
+ - Can start a workflow: yes (runs once with empty data)
601
+ - Step setting `realInput` ("Use real mouse and keyboard") applies to this block
602
+
603
+ | Setting (`config` key) | Type | Default | Notes |
604
+ | --- | --- | --- | --- |
605
+ | `locator` (Next button) | locator | `"role=link[name=\"Next\"]"` | required, supports `{{…}}`. CSS, or text=…, role=…[name="…"], label=…, placeholder=…, testid=…, A >> B, >> nth=0. Or press 🎯 Pick. |
606
+ | `maxPages` (At most (pages)) | number | `10` | |
607
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
608
+
609
+ Adds to the data: `page` (On "each": the page number, from 1.); `pages` (On "done": how many pages were visited.)
610
+
611
+ ## ℹ️ Page Info — `page-info`
612
+
613
+ Read the page itself: title, meta tags, JSON-LD, or its localStorage / cookies.
614
+
615
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
616
+ - Default timeout: 30s
617
+ - Can start a workflow: yes (runs once with empty data)
618
+
619
+ | Setting (`config` key) | Type | Default | Notes |
620
+ | --- | --- | --- | --- |
621
+ | `area` (Read) | one of `page`, `local`, `session`, `cookies` | `"page"` | |
622
+ | `key` (Key (optional)) | text | `""` | supports `{{…}}`. Storage and cookies: one key. Empty = all of them. |
623
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
624
+
625
+ Adds to the data: `page` (For "page": url, title, description, canonical, lang, meta, jsonLd, links.); `value` (For storage and cookies: the value (or an object of all of them).)
626
+
627
+ ## 📸 Page Snapshot — `page-snapshot`
628
+
629
+ Outline of what is on the page (roles, names, a locator for each element), to write steps from or keep with the run.
630
+
631
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
632
+ - Default timeout: 30s
633
+ - Can start a workflow: yes (runs once with empty data)
634
+
635
+ | Setting (`config` key) | Type | Default | Notes |
636
+ | --- | --- | --- | --- |
637
+ | `locator` (Part of the page (optional)) | locator | `""` | supports `{{…}}`. Only this element and what is inside it. Empty = the whole page. |
638
+ | `maxLines` (At most (lines)) | number | `1500` | Long pages are cut here, with a note. |
639
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
640
+
641
+ Adds to the data: `snapshot` (The outline: one element per line, e.g. - button "Sign in" [ref=e3] locator=role=button[name="Sign in"].); `elements` (The same elements as a list of {ref, role, name, tag, locator, value?, checked?, disabled?, level?, url?}.)
642
+
643
+ ## 📷 Screenshot — `screenshot`
644
+
645
+ Take a picture of what the tab shows, the whole page, or one element. Shown on the step and in the report.
646
+
647
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
648
+ - Default timeout: 30s
649
+ - Can start a workflow: yes (runs once with empty data)
650
+
651
+ | Setting (`config` key) | Type | Default | Notes |
652
+ | --- | --- | --- | --- |
653
+ | `area` (Take) | one of `visible`, `full`, `element` | `"visible"` | |
654
+ | `locator` (Element) | locator | `""` | supports `{{…}}`. For "one element". It is scrolled into view first. |
655
+ | `format` (Format) | one of `png`, `jpeg` | `"png"` | |
656
+ | `quality` (JPEG quality) | number | `80` | |
657
+ | `compare` (Compare with the baseline) | boolean | `false` | Visual check: the first run keeps the picture as this block's baseline; later runs fail (visual.mismatch) when it looks different. PNG only. |
658
+ | `threshold` (Colour threshold) | number | `0.2` | How different a pixel's colour must be to count, 0 to 1 (0.2 like Playwright; 0 = any change). |
659
+ | `maxDiffRatio` (Allowed difference) | number | `0` | Share of pixels that may differ, 0 to 1 (0.01 = 1%). 0 = none. |
660
+ | `mask` (Ignore regions) | list of rows {region} | `[]` | Parts that change on their own (a clock, an ad): an element locator, or "x, y, width, height" in CSS pixels from the picture's top-left. |
661
+ | `updateBaseline` (Update the baseline) | boolean | `false` | Save this run's picture as the new baseline and pass (like Playwright's --update-snapshots). Switch it off again after. |
662
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
663
+
664
+ Adds to the data: `screenshotId` (Id of the stored picture (shown on the step and in the report).); `screenshot` ({id, width, height, area}: the size in pixels.); `visual` (With compare: {status (baseline-saved, baseline-updated, match), diffRatio, diffPixels, comparisonId}. A mismatch fails the step with visual.mismatch.)
665
+
666
+ ## ✅ Assert — `assert`
667
+
668
+ Check that something is true. Fails the run (or just records it, if soft) when it is not.
669
+
670
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
671
+ - Default timeout: 10s
672
+ - Can start a workflow: yes (runs once with empty data)
673
+
674
+ | Setting (`config` key) | Type | Default | Notes |
675
+ | --- | --- | --- | --- |
676
+ | `subject` (Check) | one of `text`, `input`, `attribute`, `count`, `visible`, `hidden`, `checked`, `unchecked`, `enabled`, `disabled`, `focused`, `editable`, `in-viewport`, `class`, `css`, `accessible-name`, `accessible-description`, `aria-snapshot`, `url`, `title`, `console-errors`, `value` | `"text"` | |
677
+ | `locator` (Element) | locator | `""` | supports `{{…}}`. For element checks. For "ARIA snapshot": the part of the page (empty = the whole page). |
678
+ | `name` (Attribute or CSS property) | text | `""` | The attribute name for "attribute of an element", the CSS property (color, display…) for "CSS value". |
679
+ | `value` (Value) | text | `""` | supports `{{…}}`. Only for "a value from the data". |
680
+ | `operator` (Must) | one of `equals`, `not-equals`, `contains`, `not-contains`, `starts-with`, `ends-with`, `matches`, `greater`, `greater-equal`, `less`, `less-equal`, `empty`, `not-empty`, `true`, `false` | `"contains"` | Not used by the yes/no checks (visible, checked…). |
681
+ | `expected` (Expected) | text | `""` | supports `{{…}}`. For "ARIA snapshot": a template, one line per element, nested by indenting: - heading "Welcome" [level=1], - button /Sign (in\|up)/, - listitem: Apples. |
682
+ | `message` (Message when it fails) | text | `""` | supports `{{…}}` |
683
+ | `soft` (Soft: record the failure but keep going) | boolean | `false` | |
684
+ | `tab` (Tab) | text | `"main"` | The name an Open Tab block gave the tab earlier in this run. Usually "main". |
685
+
686
+ Adds to the data: `actual` (What was found.)
687
+
688
+ ## ✋ Manual Step — `manual-step`
689
+
690
+ Pause until you press Continue: solve a CAPTCHA, type a 2FA code, take a look.
691
+
692
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
693
+ - Default timeout: 600s
694
+ - Can start a workflow: yes (runs once with empty data)
695
+
696
+ | Setting (`config` key) | Type | Default | Notes |
697
+ | --- | --- | --- | --- |
698
+ | `message` (What to do) | text | `"Solve the CAPTCHA in the open tab, then press Continue."` | required, supports `{{…}}` |
699
+
700
+ Adds to the data: `(same data)` (The input, passed on after you continue.)
701
+
702
+ ## ⏹ Stop — `stop`
703
+
704
+ End this path here: as passed, or as failed with a message.
705
+
706
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
707
+ - Default timeout: 60s
708
+ - Can start a workflow: yes (runs once with empty data)
709
+
710
+ | Setting (`config` key) | Type | Default | Notes |
711
+ | --- | --- | --- | --- |
712
+ | `outcome` (End as) | one of `fail`, `pass` | `"fail"` | |
713
+ | `message` (Message) | text | `""` | supports `{{…}}` |
714
+
715
+ Adds to the data: nothing
716
+
717
+ ## 🔀 If — `if`
718
+
719
+ Go one way when a condition is true, another when it is false.
720
+
721
+ - Outputs (ports): `true`, `false` (plus `error` when step.onError is "port")
722
+ - Default timeout: 60s
723
+ - Can start a workflow: yes (runs once with empty data)
724
+
725
+ | Setting (`config` key) | Type | Default | Notes |
726
+ | --- | --- | --- | --- |
727
+ | `left` (Value) | text | `"{{value}}"` | supports `{{…}}` |
728
+ | `operator` (Condition) | one of `equals`, `not-equals`, `contains`, `not-contains`, `starts-with`, `ends-with`, `matches`, `greater`, `greater-equal`, `less`, `less-equal`, `empty`, `not-empty`, `true`, `false` | `"equals"` | |
729
+ | `right` (Compare to) | text | `""` | supports `{{…}}`. Ignored by "is empty", "is true" and similar. For a pattern, write /text/i. |
730
+
731
+ Adds to the data: `(same data)` (The input, unchanged, out of "true" or "false".)
732
+
733
+ ## 🚦 Switch — `switch`
734
+
735
+ Go one of several ways: the first case that matches the value picks the output, else "default".
736
+
737
+ - Outputs (ports): set by its settings; with the defaults `first`, `second`, `default` (plus `error` when step.onError is "port")
738
+ - Default timeout: 60s
739
+ - Can start a workflow: yes (runs once with empty data)
740
+
741
+ | Setting (`config` key) | Type | Default | Notes |
742
+ | --- | --- | --- | --- |
743
+ | `value` (Value) | text | `"{{value}}"` | supports `{{…}}`. What the cases look at. |
744
+ | `cases` (Cases (first match wins)) | list of rows {port, operator, value} | `[{"port":"first","operator":"equals","value":"1"},{"port":"second","operator":"equals","value":"2"}]` | required. Each case is an output named after it (letters, digits, "_" and "-"; not "default", "error", "out" or "done"). No match goes to "default". For a pattern, write /text/i. |
745
+
746
+ Adds to the data: `(same data)` (The input, unchanged, out of the matching case or "default".)
747
+
748
+ ## 🔁 For Each — `for-each`
749
+
750
+ Repeat the blocks on "each" for every item of a list, then continue from "done".
751
+
752
+ - Outputs (ports): `each`, `done` (plus `error` when step.onError is "port")
753
+ - Default timeout: 3600s
754
+ - Can start a workflow: yes (runs once with empty data)
755
+
756
+ | Setting (`config` key) | Type | Default | Notes |
757
+ | --- | --- | --- | --- |
758
+ | `list` (List) | text | `"items"` | required. Where the list is in the data, e.g. items or data.results (an expression, no {{ }}). |
759
+ | `as` (Call each item) | text | `"item"` | |
760
+
761
+ Adds to the data: `item` (On "each": the current item (or the name you chose).); `index` (On "each": its position, from 0.); `total` (On "each": how many items there are.); `count` (On "done": how many items were processed.)
762
+
763
+ ## 🔂 Repeat — `repeat`
764
+
765
+ Run the blocks on "each" a number of times, or until / while a condition holds, then continue from "done".
766
+
767
+ - Outputs (ports): `each`, `done` (plus `error` when step.onError is "port")
768
+ - Default timeout: 3600s
769
+ - Can start a workflow: yes (runs once with empty data)
770
+
771
+ | Setting (`config` key) | Type | Default | Notes |
772
+ | --- | --- | --- | --- |
773
+ | `mode` (Repeat) | one of `times`, `until`, `while` | `"times"` | |
774
+ | `times` (Times) | number | `3` | For "a number of times". |
775
+ | `left` (Value) | text | `"{{iteration}}"` | supports `{{…}}` per item. Until / while: rendered at every check against the data the last time ended with ({{iteration}} = times run so far). |
776
+ | `operator` (Condition) | one of `equals`, `not-equals`, `contains`, `not-contains`, `starts-with`, `ends-with`, `matches`, `greater`, `greater-equal`, `less`, `less-equal`, `empty`, `not-empty`, `true`, `false` | `"equals"` | |
777
+ | `right` (Compare to) | text | `""` | supports `{{…}}` per item |
778
+ | `max` (At most (times)) | number | `100` | Until / while: a safety limit. |
779
+ | `failAtMax` (Fail when the limit is reached) | boolean | `true` | Off: continue from "done" instead. |
780
+
781
+ Adds to the data: `iteration` (On "each": 1, 2, 3…); `iterations` (On "done": how many times it ran. Until / while: "done" also carries the data the last round ended with.)
782
+
783
+ ## 🧩 Run Workflow — `run-workflow`
784
+
785
+ Run another workflow with this data, and continue with what it returns.
786
+
787
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
788
+ - Default timeout: 300s
789
+ - Can start a workflow: yes (runs once with empty data)
790
+
791
+ | Setting (`config` key) | Type | Default | Notes |
792
+ | --- | --- | --- | --- |
793
+ | `workflow` (Workflow) | workflow id | `""` | required. Its start blocks receive this data. It does not need to be On. |
794
+
795
+ Adds to the data: `(its data)` (Whatever the called workflow's last block produced.)
796
+
797
+ ## 🏷️ Set Variable — `set-variable`
798
+
799
+ Add a value to the data flowing through.
800
+
801
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
802
+ - Default timeout: 60s
803
+ - Can start a workflow: yes (runs once with empty data)
804
+
805
+ | Setting (`config` key) | Type | Default | Notes |
806
+ | --- | --- | --- | --- |
807
+ | `name` (Name) | text | `""` | required |
808
+ | `value` (Value) | text | `""` | supports `{{…}}` |
809
+
810
+ Adds to the data: `name` (Whatever you named it.)
811
+
812
+ ## 🧮 Transform — `transform`
813
+
814
+ Compute new values with expressions: math, text, lists (sum, sort, pluck…).
815
+
816
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
817
+ - Default timeout: 60s
818
+ - Can start a workflow: yes (runs once with empty data)
819
+
820
+ | Setting (`config` key) | Type | Default | Notes |
821
+ | --- | --- | --- | --- |
822
+ | `values` (Values) | list of rows {name, expression} | `[{"name":"total","expression":"sum(pluck(items, 'price'))"}]` | required. Expressions without {{ }}. See docs/guide for the functions. |
823
+
824
+ Adds to the data: `(your names)` (One key per row.)
825
+
826
+ ## 🧹 Filter — `filter`
827
+
828
+ Keep only the list items that match a condition.
829
+
830
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
831
+ - Default timeout: 60s
832
+ - Can start a workflow: yes (runs once with empty data)
833
+
834
+ | Setting (`config` key) | Type | Default | Notes |
835
+ | --- | --- | --- | --- |
836
+ | `list` (List) | text | `"items"` | required. Where the list is in the data, e.g. items or data.results (an expression, no {{ }}). |
837
+ | `left` (Value (per item)) | text | `"{{item.price}}"` | supports `{{…}}` per item. Rendered for each item: {{item.…}} is the item, other {{…}} the data. |
838
+ | `operator` (Condition) | one of `equals`, `not-equals`, `contains`, `not-contains`, `starts-with`, `ends-with`, `matches`, `greater`, `greater-equal`, `less`, `less-equal`, `empty`, `not-empty`, `true`, `false` | `"less"` | |
839
+ | `right` (Compare to) | text | `"50"` | supports `{{…}}` per item |
840
+ | `into` (Save as (empty = replace the list)) | text | `""` | |
841
+
842
+ Adds to the data: `(list)` (The kept items, under the list's name or "Save as".)
843
+
844
+ ## 🗂️ Data Table — `data-table`
845
+
846
+ Rows of data you paste in (CSV or JSON), e.g. logins to test one by one.
847
+
848
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
849
+ - Default timeout: 60s
850
+ - Can start a workflow: yes (runs once with empty data)
851
+
852
+ | Setting (`config` key) | Type | Default | Notes |
853
+ | --- | --- | --- | --- |
854
+ | `text` (Data) | text | `"email,password\nfirst@example.com,one\nsecond@example.com,two"` | required. CSV with a header row (comma, semicolon or tab), or a JSON list. |
855
+ | `into` (Save the rows as) | text | `"rows"` | |
856
+
857
+ Adds to the data: `rows` (The rows (or the name you chose).); `count` (How many rows.)
858
+
859
+ ## 💾 Save to Dataset — `save-dataset`
860
+
861
+ Add rows to a named dataset kept in the browser. See and download it on the Data page.
862
+
863
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
864
+ - Default timeout: 60s
865
+ - Can start a workflow: yes (runs once with empty data)
866
+
867
+ | Setting (`config` key) | Type | Default | Notes |
868
+ | --- | --- | --- | --- |
869
+ | `dataset` (Dataset) | text | `"scraped"` | required, supports `{{…}}` |
870
+ | `value` (What to save) | text | `"items"` | required. An expression: a list adds one row per item, anything else one row. E.g. items, or item inside a For Each. Build objects with Transform first. |
871
+ | `mode` (Mode) | one of `append`, `replace` | `"append"` | |
872
+
873
+ Adds to the data: `datasetSize` (Rows in the dataset afterwards.)
874
+
875
+ ## ⬇️ Download — `download`
876
+
877
+ Save a list or a dataset to a CSV or JSON file in Downloads.
878
+
879
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
880
+ - Default timeout: 60s
881
+ - Can start a workflow: yes (runs once with empty data)
882
+
883
+ | Setting (`config` key) | Type | Default | Notes |
884
+ | --- | --- | --- | --- |
885
+ | `from` (Save) | one of `value`, `dataset` | `"value"` | |
886
+ | `value` (Value) | text | `"items"` | An expression, for "a value from the data". |
887
+ | `dataset` (Dataset) | text | `""` | supports `{{…}}` |
888
+ | `format` (Format) | one of `csv`, `json`, `text` | `"csv"` | |
889
+ | `filename` (File name) | text | `"blockflow-{{ today() }}.csv"` | required, supports `{{…}}` |
890
+
891
+ Adds to the data: `file` (The file name used.)
892
+
893
+ ## 🔔 Notify — `notify`
894
+
895
+ Show a desktop notification.
896
+
897
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
898
+ - Default timeout: 60s
899
+ - Can start a workflow: yes (runs once with empty data)
900
+
901
+ | Setting (`config` key) | Type | Default | Notes |
902
+ | --- | --- | --- | --- |
903
+ | `title` (Title) | text | `"BlockFlow"` | required, supports `{{…}}` |
904
+ | `message` (Message) | text | `""` | supports `{{…}}` |
905
+
906
+ Adds to the data: `notified` (Always true once the notification was shown.)
907
+
908
+ ## 🌐 HTTP Request — `http-request`
909
+
910
+ Call an API or webhook and use the response.
911
+
912
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
913
+ - Default timeout: 60s
914
+ - Can start a workflow: yes (runs once with empty data)
915
+
916
+ | Setting (`config` key) | Type | Default | Notes |
917
+ | --- | --- | --- | --- |
918
+ | `url` (URL) | url | `""` | required, supports `{{…}}` |
919
+ | `method` (Method) | one of `GET`, `POST`, `PUT`, `PATCH`, `DELETE` | `"GET"` | |
920
+ | `headers` (Headers) | text | `""` | supports `{{…}}`. One per line, as Name: value |
921
+ | `body` (Body) | text | `""` | supports `{{…}}`. Sent for POST, PUT, PATCH and DELETE. |
922
+ | `failOnError` (Stop the flow on HTTP errors (4xx, 5xx)) | boolean | `true` | |
923
+ | `responseType` (Response as) | one of `text`, `base64` | `"text"` | |
924
+
925
+ Adds to the data: `url` (The URL that was called (handy as the base for Extract from HTML).); `status` (HTTP status code.); `ok` (True for 2xx responses.); `body` (Response text.); `data` (Parsed JSON, when the body is JSON.); `body64` (With "Response as: base64": the body, base64 (empty `body`). Upload File takes it as source "data".); `mime` (With "Response as: base64": the response's Content-Type without parameters (Upload File "Type": {{mime}}).)
926
+
927
+ ## 📝 Log — `log`
928
+
929
+ Write a line to the run log, e.g. a value you want to see.
930
+
931
+ - Outputs (ports): `out` (plus `error` when step.onError is "port")
932
+ - Default timeout: 60s
933
+ - Can start a workflow: yes (runs once with empty data)
934
+
935
+ | Setting (`config` key) | Type | Default | Notes |
936
+ | --- | --- | --- | --- |
937
+ | `message` (Message) | text | `"{{value}}"` | required, supports `{{…}}` |
938
+ | `level` (Level) | one of `info`, `warn`, `error`, `debug` | `"info"` | |
939
+
940
+ Adds to the data: `(same data)` (The input, passed on.)