@lowdefy/docs-content 6.1.0 → 7.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/README.md +1 -0
- package/content/actions/downloadcsv.md +1 -1
- package/content/actions/emailotpsend.md +58 -0
- package/content/actions/emailotpverify.md +79 -0
- package/content/actions/getlocalstorage.md +43 -0
- package/content/actions/link.md +47 -1
- package/content/actions/login.md +25 -5
- package/content/actions/logout.md +7 -5
- package/content/actions/magiclinkverify.md +117 -0
- package/content/actions/pdfmake.md +2 -2
- package/content/actions/posthogalias.md +29 -0
- package/content/actions/posthogcapture.md +49 -0
- package/content/actions/posthogcapturepageleave.md +38 -0
- package/content/actions/posthogfeatureflag.md +50 -0
- package/content/actions/posthoggroup.md +37 -0
- package/content/actions/posthogidentify.md +54 -0
- package/content/actions/posthoginit.md +96 -0
- package/content/actions/posthogoptin.md +29 -0
- package/content/actions/posthogoptout.md +29 -0
- package/content/actions/posthogpageview.md +37 -0
- package/content/actions/posthogreloadfeatureflags.md +47 -0
- package/content/actions/posthogreset.md +28 -0
- package/content/actions/posthogsetpersonproperties.md +36 -0
- package/content/actions/removelocalstorage.md +28 -0
- package/content/actions/resetvalidation.md +5 -3
- package/content/actions/setdarkmode.md +3 -3
- package/content/actions/setglobal.md +2 -0
- package/content/actions/setlocale.md +1 -1
- package/content/actions/setlocalstorage.md +34 -0
- package/content/actions/setstate.md +2 -0
- package/content/actions/validate.md +7 -4
- package/content/adapter-reference/mongodbauthadapter.md +46 -0
- package/content/agents/agent-endpoint-tools.md +24 -0
- package/content/agents/agent-properties.md +13 -3
- package/content/agents/agent-server-hooks.md +1 -1
- package/content/agents/agentchat.md +43 -7
- package/content/agents/agentconversations.md +42 -8
- package/content/agents/agents-introduction.md +107 -0
- package/content/callback-reference/auth0logoutcallback.md +54 -0
- package/content/concepts/ai-agent-docs.md +455 -106
- package/content/concepts/blocks.md +150 -0
- package/content/concepts/connections-and-requests.md +402 -0
- package/content/concepts/custom-html.md +42 -0
- package/content/concepts/custom-styling.md +50 -5
- package/content/concepts/dynamic-page-content.md +309 -0
- package/content/concepts/events-and-actions.md +154 -2
- package/content/concepts/four-primitives.md +31 -0
- package/content/concepts/html-attributes.md +293 -0
- package/content/concepts/i18n.md +8 -3
- package/content/concepts/keyboard-shortcuts.md +2 -2
- package/content/concepts/layout-overview.md +1 -1
- package/content/concepts/logger.md +99 -0
- package/content/concepts/lowdefy-api.md +1319 -0
- package/content/concepts/lowdefy-schema.md +136 -3
- package/content/concepts/menus.md +8 -7
- package/content/concepts/module-authoring.md +76 -5
- package/content/concepts/modules.md +3 -1
- package/content/concepts/notifications.md +180 -0
- package/content/concepts/operators.md +7 -0
- package/content/concepts/page-and-app-state.md +252 -0
- package/content/concepts/page-paths.md +209 -0
- package/content/concepts/theming.md +582 -0
- package/content/connections/aigateway.md +375 -0
- package/content/connections/anthropic.md +169 -2
- package/content/connections/awss3.md +178 -2
- package/content/connections/axioshttp.md +181 -0
- package/content/connections/google.md +169 -2
- package/content/connections/mongodb.md +1014 -3
- package/content/connections/openai-connection.md +169 -2
- package/content/connections/sendgridmail.md +2 -0
- package/content/connections/smtp.md +3 -1
- package/content/connections/treg.md +329 -0
- package/content/container-blocks/affix.md +47 -7
- package/content/container-blocks/alert.md +76 -24
- package/content/container-blocks/badge.md +100 -24
- package/content/container-blocks/box.md +9 -9
- package/content/container-blocks/card.md +132 -27
- package/content/container-blocks/carousel.md +60 -7
- package/content/container-blocks/collapse.md +153 -9
- package/content/container-blocks/configprovider.md +35 -13
- package/content/container-blocks/confirmmodal.md +69 -23
- package/content/container-blocks/content.md +62 -98
- package/content/container-blocks/descriptions.md +45 -4
- package/content/container-blocks/drawer.md +139 -28
- package/content/container-blocks/dropdownmenu.md +119 -31
- package/content/container-blocks/flex.md +40 -62
- package/content/container-blocks/footer.md +15 -11
- package/content/container-blocks/googlemapsheatmap.md +1 -1
- package/content/container-blocks/googlemapsscript.md +2 -2
- package/content/container-blocks/header.md +71 -36
- package/content/container-blocks/label.md +34 -7
- package/content/container-blocks/layout.md +52 -34
- package/content/container-blocks/masonry.md +17 -71
- package/content/container-blocks/mobilemenu.md +131 -88
- package/content/container-blocks/modal.md +161 -26
- package/content/container-blocks/pageheadermenu.md +138 -31
- package/content/container-blocks/pagesidebarlayout.md +230 -27
- package/content/container-blocks/pagesidermenu.md +153 -43
- package/content/container-blocks/popover.md +34 -31
- package/content/container-blocks/result.md +32 -21
- package/content/container-blocks/sider.md +85 -122
- package/content/container-blocks/span.md +7 -7
- package/content/container-blocks/spinner.md +3 -3
- package/content/container-blocks/splitter.md +150 -68
- package/content/container-blocks/tabs.md +64 -12
- package/content/container-blocks/tooltip.md +22 -46
- package/content/container-blocks/watermark.md +22 -4
- package/content/controls/parallel_for.md +21 -2
- package/content/controls/reject.md +24 -3
- package/content/controls/return.md +17 -1
- package/content/controls/throw.md +1 -0
- package/content/controls/try.md +4 -2
- package/content/controls/while.md +46 -0
- package/content/deployment/deployment-environments.md +10 -7
- package/content/deployment/docker.md +22 -7
- package/content/deployment/node-server.md +4 -0
- package/content/deployment/vercel.md +17 -6
- package/content/display-blocks/aggrid.md +33 -16
- package/content/display-blocks/anchor.md +16 -15
- package/content/display-blocks/avatar.md +57 -37
- package/content/display-blocks/breadcrumb.md +70 -21
- package/content/display-blocks/button.md +93 -19
- package/content/display-blocks/calendar.md +12 -0
- package/content/display-blocks/clickablehtml.md +239 -0
- package/content/display-blocks/dangeroushtml.md +1 -1
- package/content/display-blocks/difflist.md +1 -1
- package/content/display-blocks/difftimeline.md +1 -1
- package/content/display-blocks/divider.md +64 -3
- package/content/display-blocks/dropdownbutton.md +81 -30
- package/content/display-blocks/echart.md +35 -1
- package/content/display-blocks/eventlog.md +363 -0
- package/content/display-blocks/floatbutton.md +129 -42
- package/content/display-blocks/html.md +61 -1
- package/content/display-blocks/icon.md +250 -67
- package/content/display-blocks/img.md +2 -2
- package/content/display-blocks/menu.md +146 -73
- package/content/display-blocks/message.md +38 -124
- package/content/display-blocks/notification.md +94 -222
- package/content/display-blocks/paragraph.md +59 -9
- package/content/display-blocks/pollingtimer.md +263 -0
- package/content/display-blocks/progress.md +96 -17
- package/content/display-blocks/qrcode.md +19 -4
- package/content/display-blocks/s3download.md +1 -1
- package/content/display-blocks/search.md +19 -9
- package/content/display-blocks/skeletonbutton.md +1 -0
- package/content/display-blocks/skeletoninput.md +1 -0
- package/content/display-blocks/statistic.md +75 -17
- package/content/display-blocks/steps.md +58 -25
- package/content/display-blocks/table.md +2527 -0
- package/content/display-blocks/tablelight.md +621 -0
- package/content/display-blocks/tag.md +102 -17
- package/content/display-blocks/title.md +50 -11
- package/content/display-blocks/tour.md +33 -23
- package/content/input-blocks/autocomplete.md +81 -9
- package/content/input-blocks/buttonselector.md +45 -8
- package/content/input-blocks/captcha.md +40 -0
- package/content/input-blocks/checkboxselector.md +97 -7
- package/content/input-blocks/checkboxswitch.md +33 -3
- package/content/input-blocks/colorselector.md +63 -14
- package/content/input-blocks/daterangeselector.md +165 -45
- package/content/input-blocks/dateselector.md +139 -41
- package/content/input-blocks/datetimeselector.md +158 -49
- package/content/input-blocks/inputgallery.md +3 -3
- package/content/input-blocks/intentinput.md +207 -0
- package/content/input-blocks/monthselector.md +120 -52
- package/content/input-blocks/multipleselector.md +150 -39
- package/content/input-blocks/numberinput.md +98 -12
- package/content/input-blocks/pagination.md +70 -14
- package/content/input-blocks/paragraphinput.md +51 -37
- package/content/input-blocks/passwordinput.md +60 -6
- package/content/input-blocks/phonenumberinput.md +59 -26
- package/content/input-blocks/placesautocomplete.md +319 -0
- package/content/input-blocks/radioselector.md +83 -7
- package/content/input-blocks/ratingslider.md +57 -26
- package/content/input-blocks/s3uploadbutton.md +24 -24
- package/content/input-blocks/s3uploaddragger.md +3 -3
- package/content/input-blocks/s3uploadphoto.md +5 -5
- package/content/input-blocks/segmentedselector.md +72 -32
- package/content/input-blocks/selector.md +109 -21
- package/content/input-blocks/switch.md +65 -17
- package/content/input-blocks/tableinput.md +445 -0
- package/content/input-blocks/tagmultipleselector.md +114 -0
- package/content/input-blocks/tagselector.md +114 -0
- package/content/input-blocks/textarea.md +32 -3
- package/content/input-blocks/textinput.md +70 -29
- package/content/input-blocks/tiptapinput.md +1 -1
- package/content/input-blocks/tiptapmentioninput.md +2 -2
- package/content/input-blocks/titleinput.md +39 -12
- package/content/input-blocks/treeinput.md +49 -25
- package/content/input-blocks/treemultipleselector.md +127 -10
- package/content/input-blocks/treeselector.md +97 -9
- package/content/input-blocks/upload.md +64 -15
- package/content/input-blocks/uploaddragger.md +17 -1
- package/content/input-blocks/uploadphoto.md +18 -1
- package/content/input-blocks/weekselector.md +120 -55
- package/content/learn/introduction.md +27 -0
- package/content/learn/quickstart.md +53 -0
- package/content/learn/showcase.md +8 -0
- package/content/list-blocks/controlledlist.md +24 -15
- package/content/list-blocks/list.md +11 -11
- package/content/list-blocks/masonrylist.md +7 -34
- package/content/migration/auth-upgrade.md +337 -0
- package/content/migration/upgrade-guide.md +1 -0
- package/content/migration/v3-to-v4.md +417 -0
- package/content/migration/v6-to-v7.md +620 -0
- package/content/operators/_agent.md +155 -0
- package/content/operators/_app.md +2 -1
- package/content/operators/_array.md +122 -1
- package/content/operators/_build.md +1 -0
- package/content/operators/_credential.md +57 -0
- package/content/operators/_cron.md +292 -0
- package/content/operators/_date.md +2 -0
- package/content/operators/_error.md +24 -1
- package/content/operators/_get.md +6 -6
- package/content/operators/_hmac.md +78 -0
- package/content/operators/_js.md +2 -1
- package/content/operators/_location.md +1 -1
- package/content/operators/_media.md +13 -0
- package/content/operators/_module.md +56 -2
- package/content/operators/_operator.md +17 -3
- package/content/operators/_path_params.md +82 -0
- package/content/operators/_ref.md +258 -0
- package/content/operators/_request.md +1 -1
- package/content/operators/_request_details.md +6 -0
- package/content/operators/_type.md +14 -3
- package/content/operators/_url_query.md +2 -0
- package/content/operators/_user.md +3 -3
- package/content/plugins/plugins-actions.md +10 -0
- package/content/plugins/plugins-connections.md +25 -0
- package/content/plugins/plugins-dev.md +66 -0
- package/content/plugins/plugins-icon-sets.md +267 -0
- package/content/plugins/plugins-introduction.md +27 -1
- package/content/plugins/plugins.md +19 -0
- package/content/plugins/posthog.md +359 -0
- package/content/provider-reference/auth-js-providers.md +107 -0
- package/content/provider-reference/openidconnectprovider.md +44 -0
- package/content/recipes/recipes.md +16 -0
- package/content/reference/actions-reference.md +31 -0
- package/content/reference/blocks-reference.md +35 -0
- package/content/reference/cli.md +403 -0
- package/content/reference/connections-reference.md +23 -0
- package/content/reference/operators-reference.md +47 -0
- package/content/reference/reference.md +16 -0
- package/content/reference/schema-reference.md +12 -0
- package/content/testing/config-tests.md +677 -0
- package/content/testing/e2e-configuration.md +31 -1
- package/content/testing/e2e-getting-started.md +1 -1
- package/content/testing/e2e-introduction.md +1 -1
- package/content/testing/e2e-writing-tests.md +12 -1
- package/content/testing/explore-pull-request.md +136 -0
- package/content/testing/journey-data-sets.md +326 -0
- package/content/tutorial/tutorial-actions-operators.md +2 -2
- package/content/tutorial/tutorial-add-blocks.md +2 -2
- package/content/tutorial/tutorial-create-page.md +48 -2
- package/content/tutorial/tutorial-display-data-page.md +3 -3
- package/content/tutorial/tutorial-requests-api.md +155 -0
- package/content/tutorial/tutorial-requests-sql.md +153 -0
- package/content/tutorial/tutorial-start.md +66 -1
- package/content/user-authentication/auth-configuration.md +267 -0
- package/content/user-authentication/auth-providers.md +24 -0
- package/content/user-authentication/auth-steps.md +141 -0
- package/content/user-authentication/login-and-logout.md +160 -8
- package/content/user-authentication/mcp-oauth.md +424 -0
- package/content/user-authentication/organizations.md +246 -0
- package/content/user-authentication/protected-pages-apis.md +97 -0
- package/content/user-authentication/roles.md +49 -0
- package/content/user-authentication/two-factor.md +229 -0
- package/content/user-authentication/user-object.md +58 -0
- package/content/user-authentication/users-introduction.md +8 -0
- package/content/websockets/websocket-publish.md +105 -0
- package/content/websockets/websocket-subscriptions.md +136 -0
- package/content/websockets/websockets-introduction.md +101 -0
- package/hazards.json +56 -0
- package/index.json +3458 -14
- package/package.json +10 -1
- package/scripts/extractAgentDocs.js +41 -30
- package/scripts/hashDocSources.js +38 -0
- package/scripts/isRedirectPage.js +26 -0
- package/scripts/recordSourceHashes.js +97 -0
- package/scripts/resolvePageSections.js +42 -0
- package/scripts/sectionKind.js +27 -0
- package/content/concepts/cli.md +0 -223
- package/content/other/introduction.md +0 -39
- package/content/other/next-auth-providers.md +0 -3
- /package/content/{other → actions}/updatesession.md +0 -0
|
@@ -14,7 +14,7 @@ export default createConfig();
|
|
|
14
14
|
|
|
15
15
|
This will:
|
|
16
16
|
- Look for your Lowdefy app in the current directory
|
|
17
|
-
- Build and start on port 3000
|
|
17
|
+
- Build and start the app's e2e server on port 3000, and stop it when the run ends
|
|
18
18
|
- Run tests from the `e2e/` directory matching `**/*.spec.js`
|
|
19
19
|
- Take screenshots only on failure
|
|
20
20
|
|
|
@@ -42,6 +42,26 @@ export default createConfig({
|
|
|
42
42
|
});
|
|
43
43
|
```
|
|
44
44
|
|
|
45
|
+
## Reusing a running server
|
|
46
|
+
|
|
47
|
+
By default a server already listening on the configured port fails the run, so a server left behind by an earlier run never serves an old build to new tests. To skip the build while you iterate, start the server once with `pnpm e2e:server` in another terminal and run the tests with `LOWDEFY_E2E_REUSE_SERVER=true pnpm e2e`. Before any test runs, the config asks a reused server which build it serves. Any other server on the port, such as `lowdefy dev`, a production build, or the e2e server of another app or git worktree, stops the run with an error that names the port, instead of the tests running against it. Stop that server, or give each app or worktree its own `port`, or set `LOWDEFY_E2E_PORT` to move one run.
|
|
48
|
+
|
|
49
|
+
The server Playwright starts stops when the Playwright run stops, however the run ends (including a killed or timed-out run).
|
|
50
|
+
|
|
51
|
+
## Starting a server outside Playwright
|
|
52
|
+
|
|
53
|
+
Other test runners (a vitest or Jest `globalSetup`) and scripts can start the app's e2e server with `startServer`. The server stops when the process that started it exits, however it exits.
|
|
54
|
+
|
|
55
|
+
```javascript
|
|
56
|
+
import startServer from '@lowdefy/e2e-utils/startServer';
|
|
57
|
+
|
|
58
|
+
const server = await startServer({ appDir: './', port: 3191 });
|
|
59
|
+
// ... run tests against server.url
|
|
60
|
+
await server.stop();
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
`startServer` runs `lowdefy build --server e2e` first unless `build: false` is passed, fails at once if the port is already in use, and takes extra environment variables for the server as `env`. A harness that starts `lowdefy start` itself should pass its own process id as `--exit-with-pid` (or set `LOWDEFY_EXIT_WITH_PID`), so the server never outlives it.
|
|
64
|
+
|
|
45
65
|
## Multi-app configuration
|
|
46
66
|
|
|
47
67
|
If your project has multiple Lowdefy apps (for example, in a monorepo), use `createMultiAppConfig`:
|
|
@@ -81,14 +101,24 @@ export default {
|
|
|
81
101
|
};
|
|
82
102
|
```
|
|
83
103
|
|
|
104
|
+
Keep `globalSetup` from the base configuration (spreading `base` does), since it runs the server check. To add your own global setup, pass both: `globalSetup: [base.globalSetup, './global-setup.js']`.
|
|
105
|
+
|
|
84
106
|
## Environment variables
|
|
85
107
|
|
|
108
|
+
These variables change a run:
|
|
109
|
+
|
|
110
|
+
| Variable | Purpose |
|
|
111
|
+
|----------|---------|
|
|
112
|
+
| `LOWDEFY_E2E_PORT` | Run on this port instead of the configured `port` (one app per config) |
|
|
113
|
+
| `LOWDEFY_E2E_REUSE_SERVER` | Set to `true` to reuse a server already running on the port |
|
|
114
|
+
|
|
86
115
|
The configuration sets these environment variables automatically:
|
|
87
116
|
|
|
88
117
|
| Variable | Purpose |
|
|
89
118
|
|----------|---------|
|
|
90
119
|
| `LOWDEFY_BUILD_DIR` | Absolute path to build artifacts — used by test fixtures to generate the block manifest |
|
|
91
120
|
| `LOWDEFY_E2E_MOCKS_FILE` | Absolute path to `mocks.yaml` — used by test fixtures to load static mocks |
|
|
121
|
+
| `LOWDEFY_E2E_SERVERS` | Port and build directory of each app server — used by the global setup to check a reused server |
|
|
92
122
|
|
|
93
123
|
## Assertion timeouts
|
|
94
124
|
|
|
@@ -40,7 +40,7 @@ Run tests with the Playwright UI (useful for debugging):
|
|
|
40
40
|
pnpm e2e:ui
|
|
41
41
|
```
|
|
42
42
|
|
|
43
|
-
> The first run will take longer because Playwright needs to build and start your Lowdefy app.
|
|
43
|
+
> The first run will take longer because Playwright needs to build and start your Lowdefy app. To skip the build on later runs, keep the server running with `pnpm e2e:server` and run `LOWDEFY_E2E_REUSE_SERVER=true pnpm e2e`. Without that variable, or if another server holds the port, such as `lowdefy dev`, the run stops with an error that names the port.
|
|
44
44
|
|
|
45
45
|
## Your first test
|
|
46
46
|
|
|
@@ -24,7 +24,7 @@ The e2e server build exposes internal state on `window.lowdefy`, so your tests c
|
|
|
24
24
|
|
|
25
25
|
## Prerequisites
|
|
26
26
|
|
|
27
|
-
- **Node.js
|
|
27
|
+
- **Node.js 24+**
|
|
28
28
|
- A working Lowdefy app (your app must build successfully)
|
|
29
29
|
- **Playwright** (installed automatically during setup)
|
|
30
30
|
|
|
@@ -17,6 +17,17 @@ await ldf.block('next_btn').do.click();
|
|
|
17
17
|
await ldf.waitForPage('/next-page');
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
+
A page whose [`path`](/page-paths) has placeholders has one instance per set of values. `goto` and `waitForPage` also take a target object, and build the URL from the page's path:
|
|
21
|
+
|
|
22
|
+
```javascript
|
|
23
|
+
await ldf.goto({ pageId: 'ticket', pathParams: { space: 'support', ticket_id: '1234' } });
|
|
24
|
+
|
|
25
|
+
await ldf.block('next_btn').do.click();
|
|
26
|
+
await ldf.waitForPage({ pageId: 'ticket', pathParams: { space: 'support', ticket_id: '1235' } });
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
The target is `{ pageId, pathParams, urlQuery }`: `pathParams` gives one string per placeholder, and `urlQuery` adds a query string. The URL includes the app's `basePath`, so the same target works in an app served under one. A missing placeholder value is an error that names it. Block, state, request and validation helpers always read the page instance on screen, so after `waitForPage` they read the new instance and not the one before it.
|
|
30
|
+
|
|
20
31
|
You can also access the current page ID and the raw Playwright page object:
|
|
21
32
|
|
|
22
33
|
```javascript
|
|
@@ -154,7 +165,7 @@ const data = await ldf.request('fetch_users').response();
|
|
|
154
165
|
|
|
155
166
|
## URL
|
|
156
167
|
|
|
157
|
-
Use `ldf.url()` and `ldf.urlQuery('key')` for URL assertions.
|
|
168
|
+
Use `ldf.url()` and `ldf.urlQuery('key')` for URL assertions. The URL of a page with a [`path`](/page-paths) holds the values of its placeholders, so assert it with `ldf.url()`; there is no separate accessor for them.
|
|
158
169
|
|
|
159
170
|
### Assert the current URL
|
|
160
171
|
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# Exploring a Pull Request
|
|
2
|
+
|
|
3
|
+
Your coding agent explores a pull request before it merges, and what it leaves behind is more of your suite. For each page the pull request changed, and each role that can open it, the agent looks at the page, reads its config and lists the goal of every path a user can take there. These are not only edge cases and problems, but also behaviour no journey documents yet. It writes one [journey](/config-tests) per goal and proves each one with `lowdefy test --repeat 3`:
|
|
4
|
+
|
|
5
|
+
- A journey that passes joins the suite in `tests/journeys/`.
|
|
6
|
+
- A journey that fails, with an [app error](/config-tests#app-errors) or because its goal is not met, is a **finding**. The agent reports it with that journey, which fails under `lowdefy test` until the bug is fixed and is the regression test after.
|
|
7
|
+
|
|
8
|
+
The agent never reports a finding without a journey that fails with it. What it thinks looks broken, or looks fine, is not a finding.
|
|
9
|
+
|
|
10
|
+
Exploring runs on pull requests only, with a person there to read the findings. It never runs nightly or in CI. The journeys it adds are what your app runs on its own schedule.
|
|
11
|
+
|
|
12
|
+
## With a coding agent
|
|
13
|
+
|
|
14
|
+
`lowdefy agent-setup` installs the `journeys-from-pr` skill. Ask your agent to explore a pull request, and it:
|
|
15
|
+
|
|
16
|
+
1. Reads the pull request with `gh pr view`, and works in a checkout at its head (it makes a worktree if this one is not).
|
|
17
|
+
2. Starts that checkout's dev server and runs `lowdefy journeys scope --base <the pull request's base branch> --json`.
|
|
18
|
+
3. For each page and role in the scope, takes a screenshot of the page and reads its config as one of the data set users that role allows, then writes down the goals.
|
|
19
|
+
4. Writes a journey per goal on a [journey data set](/journey-data-sets), with `name` and a `description` stating the goal, and runs each with `lowdefy test --repeat 3 <file>`.
|
|
20
|
+
5. Keeps the journeys that pass, and reports the ones that fail as findings, each with its journey file and failure. It asks you before it posts anything on the pull request.
|
|
21
|
+
|
|
22
|
+
**A bug bash** is the same skill given a goal sentence instead of a pull request, such as "try to break the invoice form with odd input". The agent takes the pages from the sentence, or from the pages you name, and explores them the same way.
|
|
23
|
+
|
|
24
|
+
## Journeys carry their goal
|
|
25
|
+
|
|
26
|
+
A journey's `name` is at most 100 characters. An optional `description`, at most 60 words, says what the journey proves. `lowdefy test` checks both, and does not print the description: it is for the people and agents who read the suite.
|
|
27
|
+
|
|
28
|
+
```yaml
|
|
29
|
+
# tests/journeys/invoices/send-reminder.yaml
|
|
30
|
+
name: a member sends a payment reminder for an overdue invoice
|
|
31
|
+
description: An overdue invoice shows a reminder button to members. Sending it records the reminder on the invoice and shows when it was sent.
|
|
32
|
+
pageId: invoice
|
|
33
|
+
data: invoices
|
|
34
|
+
user: member
|
|
35
|
+
pathParams:
|
|
36
|
+
invoiceId: inv-overdue
|
|
37
|
+
steps:
|
|
38
|
+
- click: send_reminder_button
|
|
39
|
+
- wait: { request: send_reminder }
|
|
40
|
+
- expect: { text: { blockId: reminder_sent, contains: 'Reminder sent' } }
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Clicks a data set journey refuses
|
|
44
|
+
|
|
45
|
+
Journeys on a data set never reach a real service. A click on a block whose events reach a connection whose type declares nothing, or declares `meta.dataSet: 'external'` but has no request resolvers, fails at that step and names the block and the connection's declaration. Requests of other `external` connection types are sunk: recorded and answered with `null`. A click that runs an auth action such as `Logout` fails at that step and names the action; a click that skips it does not. Connections that declare `redirect` or `walled`, such as `MongoDBCollection`, can be clicked. See [Clicks a data set journey refuses](/journey-data-sets#clicks-a-data-set-journey-refuses).
|
|
46
|
+
|
|
47
|
+
## lowdefy journeys scope
|
|
48
|
+
|
|
49
|
+
`lowdefy journeys scope` prints what a change touched: the pages, why each is in scope, and who can open it.
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
# The changes since the merge base with the pull request's base branch
|
|
53
|
+
lowdefy journeys scope --base origin/main
|
|
54
|
+
|
|
55
|
+
# As JSON, for an agent
|
|
56
|
+
lowdefy journeys scope --base origin/main --json
|
|
57
|
+
|
|
58
|
+
# Every page of the app, for a bug bash with no pull request
|
|
59
|
+
lowdefy journeys scope
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
| Option | Description |
|
|
63
|
+
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
64
|
+
| `--base <ref>` | Compare with the merge base of this branch or commit and `HEAD`. Without it, every page of the head is listed, with the reason `head`. |
|
|
65
|
+
| `--json` | Print the scope as JSON instead of the summary. |
|
|
66
|
+
| `--config-directory` | The app directory. Default is the current working directory. |
|
|
67
|
+
| `--dev-directory` | The installed dev server, whose builder builds both revisions. Default is `<config-directory>/.lowdefy/dev`. |
|
|
68
|
+
| `--ref-resolver <path>` | A `_ref` resolver function for both builds. |
|
|
69
|
+
|
|
70
|
+
The command needs no running dev server and no data set. It builds with the installed dev server, where the full builder and your plugins live, and installs it first when the app has none, without starting it.
|
|
71
|
+
|
|
72
|
+
### What is in scope
|
|
73
|
+
|
|
74
|
+
The scope builds the config twice in full: once at the base (the merge base with `--base`), once at the head (your working tree, uncommitted changes included). Both builds use the head's installed Lowdefy, so a version bump does not show up as a change. It strips the build's location markers before comparing, so moving a block down a file changes nothing.
|
|
75
|
+
|
|
76
|
+
A page is in scope when:
|
|
77
|
+
|
|
78
|
+
- its own config changed, or it is new (reason `page`);
|
|
79
|
+
- one of its requests changed, was added or was removed (`request:<requestId>`);
|
|
80
|
+
- it calls an endpoint, directly or through endpoints that call endpoints, whose config changed (`endpoint:<endpointId>`);
|
|
81
|
+
- a request or endpoint it reaches uses a connection whose config changed (`connection:<connectionId>`);
|
|
82
|
+
- it subscribes to a websocket source whose config changed (`websocket:<websocketId>`).
|
|
83
|
+
|
|
84
|
+
A change in a file that pages `_ref` shows on every page that refs it, with the reason `page`, and each changed block's `source` names that file and line.
|
|
85
|
+
|
|
86
|
+
A change to an **app-wide** artifact (app events, menus, global, app, config, i18n, theme, auth, dynamic policies or tenant targets) can affect any page. It adds the three pages most production sessions start on (from `.lowdefy/test/coverage.json`, see [Coverage](/config-tests#coverage)), or the home page, with the reason `app-wide`.
|
|
87
|
+
|
|
88
|
+
Removed pages are listed, not put in scope. Changes the diff cannot see (plugin code, notification or agent artifacts) are listed as "changed but not compared". The base is built with the plugins the head installs, so a plugin whose version changed is listed: its type changes are not in the diff. If the base cannot be built (for example, it lists a plugin the head no longer installs), every page is in scope (`base-not-built`) and the scope says why.
|
|
89
|
+
|
|
90
|
+
### Who can open each page
|
|
91
|
+
|
|
92
|
+
Each page in scope carries `roles`, read from the head build's page auth:
|
|
93
|
+
|
|
94
|
+
- `access`: `public`, `signed-in` (any signed-in user) or `roles` (a user holding one of `roles`);
|
|
95
|
+
- `users`: the users of every data set under `tests/data/` that the page admits, as `{ dataSet, user, roles }`. A journey on the page names one of them as its `user`.
|
|
96
|
+
|
|
97
|
+
### JSON output
|
|
98
|
+
|
|
99
|
+
```json
|
|
100
|
+
{
|
|
101
|
+
"base": "1f643731f…",
|
|
102
|
+
"head": "8741420c9…",
|
|
103
|
+
"dirty": false,
|
|
104
|
+
"pages": [
|
|
105
|
+
{
|
|
106
|
+
"pageId": "invoice",
|
|
107
|
+
"reasons": ["page", "request:send_reminder"],
|
|
108
|
+
"authChanged": false,
|
|
109
|
+
"blocks": [
|
|
110
|
+
{
|
|
111
|
+
"blockId": "send_reminder_button",
|
|
112
|
+
"type": "Button",
|
|
113
|
+
"change": "added",
|
|
114
|
+
"label": "Send reminder",
|
|
115
|
+
"source": "pages/invoice.yaml:42"
|
|
116
|
+
}
|
|
117
|
+
],
|
|
118
|
+
"roles": {
|
|
119
|
+
"access": "roles",
|
|
120
|
+
"roles": ["member"],
|
|
121
|
+
"users": [{ "dataSet": "invoices", "user": "member", "roles": ["member"] }]
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
],
|
|
125
|
+
"appWide": [],
|
|
126
|
+
"uncompared": [],
|
|
127
|
+
"plugins": { "missingFromHead": [], "versionChanged": [] },
|
|
128
|
+
"removedPages": []
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
`blocks` lists each block the change added, changed or removed, with its type, label and source. `authChanged` is true when the page's auth differs from the base.
|
|
133
|
+
|
|
134
|
+
### Caching
|
|
135
|
+
|
|
136
|
+
Base checkouts and clean builds are cached under `.lowdefy/scope/`, keyed by commit and by the installed Lowdefy version, and removed after 14 days unused. A dirty head is built for each run and the build is removed afterwards. The scope writes nothing else.
|
|
@@ -0,0 +1,326 @@
|
|
|
1
|
+
# Journey Data Sets
|
|
2
|
+
|
|
3
|
+
A **data set** gives [config test journeys](/config-tests) a database of their own. You declare test data, and the people journeys act as, in `tests/data/<name>.yaml`. Everything a data set loads is committed, so every machine runs a journey on the same data. A journey that names the data set with `data:` runs against a fresh in-memory MongoDB database loaded with that data. Journeys on a data set may write freely: every run starts from the same data, and the developer's own database is never touched.
|
|
4
|
+
|
|
5
|
+
```yaml
|
|
6
|
+
- name: member assigns an open ticket to a teammate
|
|
7
|
+
pageId: tickets
|
|
8
|
+
data: tickets
|
|
9
|
+
user: member
|
|
10
|
+
steps:
|
|
11
|
+
- click: { blockId: tickets_grid, containing: t-empty-title, column: assignee }
|
|
12
|
+
- select: { blockId: assignee, value: Grace Hopper }
|
|
13
|
+
- as: outsider
|
|
14
|
+
- goto: tickets
|
|
15
|
+
- expect: { text: { blockId: tickets_grid, contains: No tickets } }
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Without `data:`, a journey runs exactly as before, against whatever database the app's connections point at.
|
|
19
|
+
|
|
20
|
+
## Data set files
|
|
21
|
+
|
|
22
|
+
A data set is a plain YAML file in `tests/data/` under the config directory. The file name is the data set's name: lowercase letters, digits, `-` and `_`.
|
|
23
|
+
|
|
24
|
+
```yaml
|
|
25
|
+
# tests/data/tickets.yaml
|
|
26
|
+
fixtures: # committed documents, keyed by connection id
|
|
27
|
+
tickets:
|
|
28
|
+
- { _id: t-empty-title, organizationId: org_a, title: '', status: open }
|
|
29
|
+
organizations:
|
|
30
|
+
- { _id: org_a, name: Acme Test Co }
|
|
31
|
+
generate: # optional: seeded background documents, the same on every machine
|
|
32
|
+
seed: 7
|
|
33
|
+
tickets:
|
|
34
|
+
count: 200
|
|
35
|
+
fields:
|
|
36
|
+
organizationId: org_b
|
|
37
|
+
title: { text: { words: [3, 8] } }
|
|
38
|
+
status: { oneOf: [open, pending, closed], weights: [3, 1, 6] }
|
|
39
|
+
indexes: # optional, keyed by connection id, in the listIndexes() shape
|
|
40
|
+
tickets:
|
|
41
|
+
- { key: { organizationId: 1, number: 1 }, unique: true }
|
|
42
|
+
users: # the people journeys act as
|
|
43
|
+
owner: { id: u_1, roles: [admin], organizationId: org_a }
|
|
44
|
+
member: { id: u_2, roles: [member], organizationId: org_a }
|
|
45
|
+
outsider: { id: u_9, roles: [admin], organizationId: org_b }
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
A data set can be as small as one organization and its owner:
|
|
49
|
+
|
|
50
|
+
```yaml
|
|
51
|
+
# tests/data/empty-org.yaml
|
|
52
|
+
fixtures:
|
|
53
|
+
organizations: [{ _id: org_new, name: New Co }]
|
|
54
|
+
users:
|
|
55
|
+
owner: { id: u_new, roles: [admin], organizationId: org_new }
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
| Key | Description |
|
|
59
|
+
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
60
|
+
| `extends` | Data sets to load first, by name, e.g. `[base]`. See [Extending a data set](#extending-a-data-set). |
|
|
61
|
+
| `fixtures` | Documents to load, keyed by connection id. Dates use the serializer's `{ "~d": "2026-01-02T00:00:00.000Z" }` marker and ObjectIds use `{ _oid: '<hex>' }`. A fixture with an `_id` replaces any earlier document with that `_id`; one without is inserted. |
|
|
62
|
+
| `generate` | Documents made from a small spec with a fixed seed, keyed by connection id like `fixtures`. See [Generated documents](#generated-documents). |
|
|
63
|
+
| `users` | The people journeys act as, keyed by name. Each is an inline user object, the shape a journey's inline `user:` takes. They are injected callers and carry no credentials: `password` is refused. |
|
|
64
|
+
| `indexes` | Indexes to create, keyed by connection id, in the shape MongoDB's `listIndexes()` returns: `key`, an optional `name`, and any other option (`unique`, `sparse`, `partialFilterExpression`, `collation`, `weights`, …), passed to `createIndexes` as given. `v` and `ns` are refused. Two connections that load one collection merge their indexes. |
|
|
65
|
+
|
|
66
|
+
## Extending a data set
|
|
67
|
+
|
|
68
|
+
A data set can load other data sets first with `extends`, so a set that is "the base tenant plus a second tenant" does not copy the base tenant's rows:
|
|
69
|
+
|
|
70
|
+
```yaml
|
|
71
|
+
# tests/data/two-orgs.yaml
|
|
72
|
+
extends: [base]
|
|
73
|
+
fixtures:
|
|
74
|
+
organizations:
|
|
75
|
+
- { _id: org_b, name: Beta Test Co }
|
|
76
|
+
users:
|
|
77
|
+
outsider: { id: u_9, roles: [admin], organizationId: org_b }
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
- **Order.** Each extended set loads first, in the order `extends` lists them, then this file. An extended set can extend others; a set reached twice loads once, at its first place. A cycle is refused.
|
|
81
|
+
- **Fixtures and indexes** add up per connection. The usual rules then apply across files: a later fixture with an `_id` replaces an earlier one, and a later index with the same `key` replaces an earlier one.
|
|
82
|
+
- **Users** with the same name: the later file's user replaces the earlier one.
|
|
83
|
+
- **`generate` stays per file.** Only the named data set's own `generate` runs. Its `ref` fields and `_id` checks see every fixture, including the extended sets' fixtures.
|
|
84
|
+
- `lowdefy data list`, the `lowdefy journeys` commands and journey runs all read the merged data set.
|
|
85
|
+
|
|
86
|
+
## Generated documents
|
|
87
|
+
|
|
88
|
+
`generate` gives a data set volume and realistic neighbours without copying a real database: a list page with 400 invoices, a search over many customers, a report over months of dates. A `seed` makes the output identical on every machine and every run; change it to get a different, equally fixed set.
|
|
89
|
+
|
|
90
|
+
```yaml
|
|
91
|
+
generate:
|
|
92
|
+
seed: 7
|
|
93
|
+
customers_db:
|
|
94
|
+
count: 50
|
|
95
|
+
fields:
|
|
96
|
+
name: { company: true }
|
|
97
|
+
invoices_db:
|
|
98
|
+
count: 400
|
|
99
|
+
fields:
|
|
100
|
+
_id: { sequence: { prefix: inv-, start: 1 } }
|
|
101
|
+
status: { oneOf: [draft, sent, paid], weights: [1, 2, 5] }
|
|
102
|
+
amount: { number: { min: 10, max: 5000, decimals: 2 } }
|
|
103
|
+
issued: { date: { from: 2026-01-01, to: 2026-09-30 } }
|
|
104
|
+
note: { text: { words: [3, 12] } }
|
|
105
|
+
contact: { name: true }
|
|
106
|
+
email: { email: true }
|
|
107
|
+
customerId: { ref: customers_db }
|
|
108
|
+
currency: ZAR
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Each key under `generate` other than `seed` is a connection id, with `count` (how many documents) and `fields` (how to make each field). A field's value is one of these kinds:
|
|
112
|
+
|
|
113
|
+
| Kind | Example | Makes |
|
|
114
|
+
| ---------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
115
|
+
| a literal | `currency: ZAR` | The value as written, in every document. A string, number, boolean, `null`, list, or a `~d` date or `_oid` marker. Write any other object as `{ literal: { ... } }`. |
|
|
116
|
+
| `oneOf` | `{ oneOf: [draft, sent, paid], weights: [1, 2, 5] }` | One of the values. `weights` is optional, one number per value; without it each value is equally likely. |
|
|
117
|
+
| `number` | `{ number: { min: 10, max: 5000, decimals: 2 } }` | A number from `min` to `max`, rounded to `decimals` places (default `0`, whole numbers). |
|
|
118
|
+
| `date` | `{ date: { from: 2026-01-01, to: 2026-09-30 } }` | A date between `from` and `to`, loaded as a date, as a fixture's `~d` marker is. Each bound is a UTC date (`2026-01-31`) or a date-time with its offset (`2026-01-31T09:00:00Z`). |
|
|
119
|
+
| `text` | `{ text: { words: [3, 12] } }` | A sentence of that many words from a small built-in word list. |
|
|
120
|
+
| `name` | `{ name: true }` | A person's name, such as `Grace Okafor`, from small built-in lists. |
|
|
121
|
+
| `email` | `{ email: true }` | An address at a reserved example domain, such as `maya.chen@example.org`, so it can never reach a real inbox. |
|
|
122
|
+
| `company` | `{ company: true }` | A made-up company name, such as `Harbor Logistics Ltd`. |
|
|
123
|
+
| `sequence` | `{ sequence: { prefix: inv-, start: 1 } }` | `inv-1`, `inv-2`, …, one per document. Without `prefix` it makes numbers; `sequence: true` counts from 1. |
|
|
124
|
+
| `ref` | `{ ref: customers_db }` | The `_id` of a document of another connection, from its fixtures or its generated documents. Connections are generated in the order their refs need; a cycle is refused. |
|
|
125
|
+
|
|
126
|
+
- **`_id`.** A document's `_id` is `<connection id>-1`, `<connection id>-2`, … unless `fields` sets it. A generated `_id` that is also a fixture's `_id`, or that is generated twice, is refused, also across connections that name one collection.
|
|
127
|
+
- **Stable.** Each field has its own seeded sequence, so adding a field or a connection leaves every other field's values as they were.
|
|
128
|
+
- **Size advice.** A connection that loads more than 1,000 documents (fixtures and generated together) gets a warning saying it is not advised. Every journey on the data set loads that many documents, so keep the count to what a page needs. It is never refused.
|
|
129
|
+
- **No dependency.** The lists are small and built in; nothing is downloaded.
|
|
130
|
+
|
|
131
|
+
Rules, checked before any browser opens:
|
|
132
|
+
|
|
133
|
+
- **Plain YAML.** No `_ref` and no operators: a data set is test input, not app config. Share rows between data sets with `extends`.
|
|
134
|
+
- **Connections.** Every connection id in `fixtures`, `generate` and `indexes` must be a `MongoDBCollection` connection whose `collection` is a literal string, and whose `databaseName` is a literal string or not set. Two connections that name one collection load into it together.
|
|
135
|
+
- **One database.** Under a data set every redirected connection reads one database. Two connections that name the same collection in different databases (a different `databaseName` or `databaseUri` secret) would share one collection. When the data set names either of them, the journey is refused. When it names neither, the result carries a warning. A connection whose `collection` is computed per request cannot be checked.
|
|
136
|
+
- **Indexes first.** Each collection's indexes are created before any document is loaded, so a fixture or generated document that breaks a unique index fails the load and names the document, the index and the duplicate key. A TTL index is loaded as a plain index, so old fixture dates are never deleted mid-run.
|
|
137
|
+
|
|
138
|
+
## Named users and `as`
|
|
139
|
+
|
|
140
|
+
`user:` takes two more forms on a data set journey: the name of one of the data set's users, or a list of them.
|
|
141
|
+
|
|
142
|
+
| `user` | The journey acts as |
|
|
143
|
+
| ---------------- | -------------------------------------------------------------------------------------------------------- |
|
|
144
|
+
| left out | the default roleless headless user |
|
|
145
|
+
| an object | that inline user |
|
|
146
|
+
| `none` | nobody: the journey signs in through the app (refused on a data set while auth is configured, see below) |
|
|
147
|
+
| any other string | that data set user, e.g. `user: member` |
|
|
148
|
+
| a list of names | each of those data set users in turn, e.g. `user: [admin, member]` (see below) |
|
|
149
|
+
|
|
150
|
+
`as: <name>` switches to another person with their own browser. When the name is a user of the journey's data set, that actor acts as that user. Any other name opens as the journey's `user`, as before. So a two-person journey (`owner` invites, `outsider` must not see the tenant's rows) needs no sign-in at all.
|
|
151
|
+
|
|
152
|
+
A user name with no `data:`, or a name the data set does not declare, fails before a browser opens.
|
|
153
|
+
|
|
154
|
+
## One journey, several users
|
|
155
|
+
|
|
156
|
+
When several roles are promised the same flow, list their users rather than copying the journey once per role:
|
|
157
|
+
|
|
158
|
+
```yaml
|
|
159
|
+
name: edits a ticket
|
|
160
|
+
pageId: ticket
|
|
161
|
+
data: tickets
|
|
162
|
+
user: [admin, member]
|
|
163
|
+
steps:
|
|
164
|
+
- click: edit_button
|
|
165
|
+
# ...
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
`lowdefy test` and `lowdefy_run_tests` run the journey once as each user, each in a fresh database of its own, and report each run on its own line as `<name> [<user>]`:
|
|
169
|
+
|
|
170
|
+
```
|
|
171
|
+
PASS edits a ticket [admin] (6 steps, 2310ms)
|
|
172
|
+
FAIL edits a ticket [member]
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
`--filter` matches that name, so `lowdefy test --filter "[member]"` runs only the member's run, and a full-suite recording and coverage see each user's run apart. `--repeat` repeats each run. Lints read the journey once.
|
|
176
|
+
|
|
177
|
+
- A list holds data set user names only, needs `data:`, and names each user once. `none` and inline user objects stay single values.
|
|
178
|
+
- `as:` steps work as before: the journey's first actor, `main`, is the run's user, and any other `as:` name that is a data set user opens as that user.
|
|
179
|
+
- A role that must be refused (it lands on `/404`, or the feature is hidden) expects a different outcome, so it is a journey of its own, not another user in the list.
|
|
180
|
+
|
|
181
|
+
## The fixture rule
|
|
182
|
+
|
|
183
|
+
Generated documents are background: they give a page volume, realistic shapes and neighbouring records. A journey depends only on values written for it:
|
|
184
|
+
|
|
185
|
+
- Every value a journey types, selects, clicks by text, puts in `urlQuery` or `pathParams` (the values of a [page path](/page-paths)'s placeholders) or asserts comes from the data set's `fixtures` or `users`, or is UI text from the app's config (labels, titles, options). A generated value is the same on every machine, but it changes when the spec or the seed does, and nobody reading the journey can see where it came from.
|
|
186
|
+
- Target grid rows with `containing: <fixture value>`, never a bare `row: N`. A state path with an array index, such as `locations.0.path`, has the same problem: assert it only on a list the fixtures own outright, or assert by text.
|
|
187
|
+
- Keep generated documents away from the fixture tenant. Let the fixtures own one organization completely, and generate other organizations' rows around it.
|
|
188
|
+
|
|
189
|
+
Fixture records are test data written for the journey: never rows copied with credentials, tokens or external ids intact.
|
|
190
|
+
|
|
191
|
+
## What `lowdefy test` prints
|
|
192
|
+
|
|
193
|
+
`lowdefy test` prints each data set once per run, as `data tickets: 203 documents`, and the warnings its load returned (size advice, connections that share a collection). `lowdefy data list` prints each data set in `tests/data/` with the documents it loads and the users it names.
|
|
194
|
+
|
|
195
|
+
## How a journey reaches its database
|
|
196
|
+
|
|
197
|
+
A data set journey runs on the running dev server, beside your own browser tabs:
|
|
198
|
+
|
|
199
|
+
1. The dev server starts one in-memory MongoDB replica set the first time a data set journey runs, on a free port from 49152 up so it never holds a port one of your apps needs. It stops, and its files are removed, when the dev server stops; if it dies, the journey that finds it fails and the next one starts a new store. The first run downloads the MongoDB binary once (`Downloading MongoDB <version> for journey data sets (once).`). Set `MONGOMS_VERSION` to match your cluster's MongoDB version.
|
|
200
|
+
2. Each journey run gets a fresh database on it, loaded with the indexes, then the generated documents, then the fixtures. Runs never see each other's writes, so an agent's journey can run alongside `lowdefy test`.
|
|
201
|
+
3. Every browser the journey opens carries a cookie that only the dev server's own headless browser can produce. Requests with it read the run's database. Your own tabs carry no such cookie and keep using your real database on the same server.
|
|
202
|
+
4. When the journey ends, its browsers close, the dev server waits up to 30 seconds for background work the journey started (detached `CallApi` calls, background endpoint work), and then drops the database.
|
|
203
|
+
|
|
204
|
+
**What is redirected:** every connection read under a data set journey goes through one check, for requests, endpoint routines, background and detached endpoint calls, websocket change stream sources, and module connections alike. The check reads the connection type's `meta.dataSet` declaration:
|
|
205
|
+
|
|
206
|
+
- `redirect`: the run's database URI and name are merged over the connection's `properties`, whether or not the data set lists the connection. Core `MongoDBCollection` declares it.
|
|
207
|
+
- `walled`: the type holds no database address and reaches MongoDB only through the walled client, by naming walled `MongoDBCollection` connections. Its connection passes unchanged, and each walled connection it names is read through the same check, so it takes the run's database as any `redirect` connection does. Plugin types declare it; no core type does.
|
|
208
|
+
- `external`: the type reaches an outside service, not your app's data. Under a data set journey every request of the type is sunk: it is recorded and answers `null`, and nothing is sent (see [Requests to outside services are sunk](#requests-to-outside-services-are-sunk)). Core `AxiosHttp`, `SendGridMail`, `SMTP`, `Stripe`, `AIGateway`, `Anthropic`, `OpenAI`, `Google`, `Mcp`, `TregConnection`, `AwsS3Bucket`, `AzureBlobContainer` and `GoogleCloudStorageBucket` declare it.
|
|
209
|
+
- No declaration: the journey fails with `Connection "<id>" (type <type>) cannot run under data set "<name>": its type does not say how to redirect it.` Core `Knex`, `Redis`, `Elasticsearch`, `GoogleSheet` and `TestConnection` refuse, and so does any plugin type that has not declared.
|
|
210
|
+
|
|
211
|
+
A `redirect` connection whose whole `properties` is an operator (a top-level key starting with `_`, such as `_if` or `_ref` evaluated at runtime) also refuses, because the check cannot see what it evaluates to. Operators inside the properties are fine: `databaseUri: { _secret: MONGODB_URI }` is replaced by the run's URI before any operator runs.
|
|
212
|
+
|
|
213
|
+
The browsers a data set journey opens stay on one host of the dev server. A request to the dev server's port on another host (`127.0.0.1` when the journey opened `localhost`, `[::1]`, a LAN address) would carry no data set cookie, so it is stopped in the browser and the step fails with `Journey left its origin <origin> for <url>; a data set journey must stay on one host of the dev server.` Requests to other ports and other sites are untouched.
|
|
214
|
+
|
|
215
|
+
**What is not redirected:**
|
|
216
|
+
|
|
217
|
+
- Connection types declared `external` (HTTP APIs, email, payments, AI providers, MCP, object storage) are never given the run's database. Their requests are sunk, as described below. What does not go through a request resolver still reaches the real service: an agent calling its model provider through its connection is not sunk, and an `external` type with no request resolvers (such as `Mcp`) is refused by the click rails.
|
|
218
|
+
- Code that reads a database URI from anywhere but its connection's `properties`, such as a secret or environment variable read directly. A plugin type that declares `redirect` and does this breaks its declaration.
|
|
219
|
+
- The auth engine. Data set journeys never reach it: their requests carry injected users, and `/api/auth/*` answers 404 for them.
|
|
220
|
+
- Atlas Search (`$search`, `$vectorSearch`): pages whose requests use it fail on the in-memory database, which has no search engine.
|
|
221
|
+
|
|
222
|
+
### Plugin connection types
|
|
223
|
+
|
|
224
|
+
A plugin connection type runs under a data set journey only when it declares `meta.dataSet` on its connection export:
|
|
225
|
+
|
|
226
|
+
```js
|
|
227
|
+
export default {
|
|
228
|
+
schema,
|
|
229
|
+
meta: { dataSet: 'redirect' },
|
|
230
|
+
requests: { MyStoreFind, MyStoreInsert },
|
|
231
|
+
};
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Declare `redirect` only when the type takes its database from `properties.databaseUri` and `properties.databaseName` and nothing else. It must honour `databaseName`, as `MongoDBCollection` does, and key any client it keeps between requests by the URI it is given, never by connection id alone: a client cached by connection id keeps the database it first opened, which can be your real one.
|
|
235
|
+
|
|
236
|
+
Declare `walled` when the type holds no database URI and reaches MongoDB only through the walled client: its requests call the resolver's `walled(connectionId)` argument and pass what it returns to `getWalledCollection` from `@lowdefy/connection-mongodb/walled`. The walled connections it names follow the data set on their own, so its writes land in the run's database:
|
|
237
|
+
|
|
238
|
+
```js
|
|
239
|
+
// connection export
|
|
240
|
+
export default {
|
|
241
|
+
schema,
|
|
242
|
+
meta: { tenant: false, dataSet: 'walled' },
|
|
243
|
+
requests: { AcceptMatch },
|
|
244
|
+
};
|
|
245
|
+
|
|
246
|
+
// request resolver
|
|
247
|
+
import { getWalledCollection } from '@lowdefy/connection-mongodb/walled';
|
|
248
|
+
|
|
249
|
+
async function AcceptMatch({ connection, request, walled }) {
|
|
250
|
+
const matches = getWalledCollection(await walled(connection.mongoConnectionId));
|
|
251
|
+
return matches.updateOne({ _id: request.matchId }, { $set: { accepted: true } });
|
|
252
|
+
}
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
A type that also calls an outside service declares `external` instead, and its requests are sunk under a data set journey. Declare `external` only for a type that reaches an outside service and holds none of your app's data. Leave it undeclared for any other data store: data set journeys that use it are refused rather than run against your real data.
|
|
256
|
+
|
|
257
|
+
A `walled` type can have some request types that reach an outside service, such as one that downloads files or calls an AI provider. Declare `meta.dataSet: 'external'` on those request resolvers. Under a data set journey only those requests are sunk; the type's other requests run for real against the run's database:
|
|
258
|
+
|
|
259
|
+
```js
|
|
260
|
+
// request resolver
|
|
261
|
+
async function GenerateAnswers({ connection, request, walled }) {
|
|
262
|
+
// calls an AI gateway
|
|
263
|
+
}
|
|
264
|
+
GenerateAnswers.meta = { checkRead: true, dataSet: 'external' };
|
|
265
|
+
|
|
266
|
+
// connection export
|
|
267
|
+
export default {
|
|
268
|
+
schema,
|
|
269
|
+
meta: { tenant: false, dataSet: 'walled' },
|
|
270
|
+
requests: { AcceptMatch, GenerateAnswers },
|
|
271
|
+
};
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
The sunk request is recorded in `sunk` like any other, with its `connectionType` and `requestType`. A request-level `external` is honoured on any connection type that has request resolvers, not only `walled` ones.
|
|
275
|
+
|
|
276
|
+
The dev server cannot check a `walled` or `external` declaration, since a connection's properties are evaluated later and may read secrets. It is your promise as the plugin author.
|
|
277
|
+
|
|
278
|
+
## Clicks a data set journey refuses
|
|
279
|
+
|
|
280
|
+
A data set journey fails two kinds of click, so that it never reaches a real service and never fails for a reason that is not the app's. A click on a connection the data set cannot run is refused before it acts, naming the block and why; a click that runs an auth action fails once it has run:
|
|
281
|
+
|
|
282
|
+
- A click on a block whose events reach a connection, through a `Request` action or a `CallAPI` into an endpoint routine, whose type declares nothing, declares `external` but has no request resolvers, or that has no connection artifact. Connections whose type declares `redirect` or `walled` (such as `MongoDBCollection`) run against the run's database, and connections whose type declares `external` have their requests sunk, so both can be clicked. The message names the declaration, so you know what to change:
|
|
283
|
+
|
|
284
|
+
- No declaration: `Block "export_rows" reaches connection "warehouse" (Knex, no dataSet declaration), which a data set cannot redirect, so a data-set journey cannot click it.`
|
|
285
|
+
- No artifact: `Block "sync" reaches connection "legacy" (no connection artifact), which a data set cannot redirect, so a data-set journey cannot click it.`
|
|
286
|
+
- `external` with no request resolvers: `Block "connect" reaches connection "tools" (Mcp, dataSet: external), which reaches a real service, so a data-set journey cannot click it.`
|
|
287
|
+
|
|
288
|
+
The rails read the declaration only. A `redirect` connection whose `properties` the check above refuses passes the rails, and the step fails with that check's message when the request runs.
|
|
289
|
+
|
|
290
|
+
- A click that runs an action that calls the auth engine (`Logout`, `Login`, `ChangePassword` and the other auth actions). Data set users are injected and have no auth session, so these fail every time. Unlike the connection check, this one is made while the click runs: the step fails only if the action executes, and the message names the block and the action (`Block "logout_button" ran the auth action Logout, which a data-set journey cannot run: ...`). A click whose auth action is skipped works, so you can test the paths that stop before it: a `Validate` that throws on an empty form, an endpoint that refuses a duplicate, an action with a `skip:` condition that is true.
|
|
291
|
+
|
|
292
|
+
The block is the one the click lands on: the target's block, or for a `text` or `containing` target, the nearest block around the element it matched. Request and endpoint ids computed by operators are not followed by the connection check. Journeys without `data:` click anything. Cover such controls with a journey that runs off data sets, against a test database.
|
|
293
|
+
|
|
294
|
+
## Requests to outside services are sunk
|
|
295
|
+
|
|
296
|
+
Under a data set journey, every request of a connection type that declares `meta.dataSet: 'external'`, and every request type that declares `meta.dataSet: 'external'` on its own resolver, is replaced by a sink, in the dev server process that would have sent it. The request is still validated, read-checked and write-checked as for real, then recorded and answered with `null`; the service (mail, HTTP, payments, an AI provider, object storage) never sees it. Because the sink sits where the request runs, it holds for a branch of an endpoint the click does not take, a connection id an operator computes, and detached or background endpoint calls alike, which a check on the config could not promise.
|
|
297
|
+
|
|
298
|
+
A run that sank requests returns them, in the order they ran, as `sunk` beside its result:
|
|
299
|
+
|
|
300
|
+
```yaml
|
|
301
|
+
sunk:
|
|
302
|
+
- connectionId: notifications-email
|
|
303
|
+
connectionType: SMTP
|
|
304
|
+
requestType: SMTPMailSend
|
|
305
|
+
requestId: send
|
|
306
|
+
pageId: evidence/review
|
|
307
|
+
endpointId: null
|
|
308
|
+
request: { to: owner@example.test, subject: ... }
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
`request` is the request's evaluated properties with the app's secrets scrubbed. The connection's own properties, which hold its credentials, are never recorded.
|
|
312
|
+
|
|
313
|
+
A routine that reads a sunk request's response gets `null`, so a step that needs the response (an order id from a payment API) reads nothing: give such a branch a journey off data sets, or an endpoint that tolerates a missing response.
|
|
314
|
+
|
|
315
|
+
One request is not sunk: an `SMTP` request whose connection points at the dev server's mail capture (`LOWDEFY_DEV_SMTP_PORT`, on `127.0.0.1`, `localhost` or `::1`), so the `email` step keeps reading the mail a journey sends there. Nothing leaves the machine.
|
|
316
|
+
|
|
317
|
+
## Auth journeys stay on their harness
|
|
318
|
+
|
|
319
|
+
Data set users are injected callers. A journey that signs up or signs in through the app's own auth is an auth journey, and stays off data sets: run it against a test database as described under [The database](/config-tests#the-database). Two combinations are refused rather than run silently wrong:
|
|
320
|
+
|
|
321
|
+
- `user: none` on a data set journey while auth is configured. A signed-out actor's sign-in would write sessions to the app's real auth database while its requests read the data set.
|
|
322
|
+
- Any data set journey while `auth.dev.mockUser` (or `LOWDEFY_DEV_USER`) is active. The mock user wins over the injected user, so the journey would act as someone outside the data set.
|
|
323
|
+
|
|
324
|
+
## Agents
|
|
325
|
+
|
|
326
|
+
The `lowdefy_run_journey` MCP tool takes `data` and the name and list forms of `user`, the same as the journey file, and returns the data set the journey ran on with its result. With a list it runs once as each user and returns `{ passed, runs: [{ user, ... }] }`, `passed` only when every run passed. `lowdefy_run_tests` and `lowdefy test --url` run data set journeys like any other, because the dev server they target does the loading.
|
|
@@ -29,7 +29,7 @@ blocks:
|
|
|
29
29
|
properties:
|
|
30
30
|
title: Reset
|
|
31
31
|
block: true
|
|
32
|
-
icon:
|
|
32
|
+
icon: Eraser
|
|
33
33
|
################ -------- Copy from here -------- ################
|
|
34
34
|
events:
|
|
35
35
|
onClick:
|
|
@@ -92,7 +92,7 @@ blocks:
|
|
|
92
92
|
block: true
|
|
93
93
|
color: primary
|
|
94
94
|
variant: solid
|
|
95
|
-
icon:
|
|
95
|
+
icon: save
|
|
96
96
|
################ -------- Copy from here -------- ################
|
|
97
97
|
events:
|
|
98
98
|
onClick:
|
|
@@ -50,7 +50,7 @@ blocks:
|
|
|
50
50
|
title: Reset
|
|
51
51
|
block: true # Make the button fill all the space available to it
|
|
52
52
|
type: default # Make the button a plain button
|
|
53
|
-
icon:
|
|
53
|
+
icon: Eraser
|
|
54
54
|
- id: submit_button
|
|
55
55
|
type: Button
|
|
56
56
|
layout:
|
|
@@ -59,7 +59,7 @@ blocks:
|
|
|
59
59
|
title: Submit
|
|
60
60
|
block: true
|
|
61
61
|
type: primary # Make the button a primary button with color
|
|
62
|
-
icon:
|
|
62
|
+
icon: save
|
|
63
63
|
################ -------- Copy to here ---------- ################
|
|
64
64
|
```
|
|
65
65
|
|