@lowdefy/docs-content 0.0.0-experimental-20260928120643 → 6.1.0

package/content/testing/config-tests.md

@@ -1,278 +0,0 @@
-# Config Tests
-
-Config tests let you test a Lowdefy app in the same language you build it in. A **journey** is a YAML file that names a page, a user to act as, and a list of steps — click this block, fill that input, wait for a request, expect this state — and `lowdefy test` runs every journey in your app and reports which passed.
-
-Journeys need no JavaScript, no Playwright setup and no separate test build. The runner boots your app's development server headless, drives each journey through the dev server's [journey route](/ai-agent-docs) (the same one the `lowdefy_run_journey` MCP tool uses), and prints a pass/fail line per journey. Because the format is declarative, an AI coding agent can write a journey for a page it just changed, run it, and read the failing step.
-
-> Config tests run against the **development server**. For tests against a production build, or tests that need custom browser code, use the Playwright based [e2e testing](/e2e-introduction) toolkit instead.
-
-## Layout
-
-Journeys live in `tests/journeys/` inside your config directory, one `.yaml` file per journey or a top-level list of journeys per file:
-
-```
-my-app/
-├── lowdefy.yaml
-├── pages/
-└── tests/
-    └── journeys/
-        ├── controls.yaml
-        └── sign-up.yaml
-```
-
-Files run in file-name order, and journeys run one at a time — each journey opens its own browser context, but they all share your app's database, so parallel journeys would interfere with one another.
-
-## A journey
-
-```yaml
-# tests/journeys/controls.yaml
-- name: member creates a control
-  pageId: controls
-  user: { roles: [admin] }
-  urlQuery: { status: open }
-  steps:
-    - click: new_control
-    - fill: { blockId: title, value: Access reviews }
-    - click: submit
-    - wait: { request: get_controls }
-    - expect: { state: { path: controls.0.title, equals: Access reviews } }
-
-- name: guest sees the empty state
-  pageId: controls
-  steps:
-    - expect: { visible: empty_state }
-```
-
-| Field      | Required | Description                                                                                                                                    |
-| ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name`     | Yes      | A short description. `--filter` matches against it, and it is printed in the results.                                                          |
-| `pageId`   | Yes      | The page to open.                                                                                                                              |
-| `user`     | No       | The user to act as, as an inline user object such as `{ sub: u1, roles: [admin] }`. Leave it out to run as the default roleless headless user. |
-| `urlQuery` | No       | An object appended to the page URL as a query string, for pages that read `_url_query`.                                                        |
-| `steps`    | Yes      | At least one step. Each step is an object with exactly one key from the step grammar below.                                                    |
-
-`user: none` injects no user at all, so the journey signs in through the app's own auth — see [Testing sign-up and sign-in](#testing-sign-up-and-sign-in).
-
-`timeout` sets how long each step may wait, in milliseconds (a whole number from 1 to 60000, default 5000). Raise it on a slow machine or CI runner rather than adding `wait: { ms }` steps.
-
-### Timeouts
-
-The journey's `timeout` (the step timeout) bounds every wait a step makes for something to happen, and a step moves on as soon as it has:
-
-| Wait                                                                       | Bound                                      |
-| -------------------------------------------------------------------------- | ------------------------------------------ |
-| A control becoming actionable for `click`, `fill`, `select`                | The step timeout.                          |
-| `expect` (`state`, `visible`, `text`, `url`, `title`) matching             | The step timeout.                          |
-| `wait: { request }` and `wait: { state }`                                  | The step timeout.                          |
-| `back` loading the previous page                                           | The step timeout.                          |
-| An email arriving for `email` or `fill.fromEmail`                          | The step timeout.                          |
-| Opening a page: the journey's page, `goto`, the first `as` for a name      | The step timeout, but at least 15 seconds. |
-| Settling after an interaction (`click`, `fill`, `select`, `press`, `back`) | The step timeout, but at most 5 seconds.   |
-| `wait: { ms }`                                                             | Exactly `ms`; the timeout does not apply.  |
-
-The settle after an interaction lets the page's own events and requests finish before the next step. It never fails a step: a page still busy after 5 seconds (an event that ends in a resend cooldown, for example) moves on, and the next step waits for what it needs itself. So raising `timeout` makes a slow journey pass without making a passing one slower.
-
-## Steps
-
-Blocks are addressed by their `blockId`. A step that does not complete within the step timeout (5 seconds, or the journey's [`timeout`](#timeouts)) fails the journey. An `expect` step waits, up to that timeout, for what it checks to become true, so a value a click leads to can arrive a moment later.
-
-| Step                                      | Meaning                                                                                                                                                     |
-| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `click: target`                           | Click the block, or the control a [target](#targets) narrows to.                                                                                            |
-| `fill: { blockId, value }`                | Type `value` into the input inside the block (or the grid cell a target names).                                                                             |
-| `fill: { blockId, fromEmail }`            | Type text read from an [email](#emails) instead of a fixed value, such as a one-time sign-in code. The actor stays on the page.                             |
-| `select: { blockId, value }`              | Open the selector block (or grid cell) and choose the option whose text is `value`. A radio, button or segmented selector's option is clicked by its label. |
-| `press: Enter`                            | Press a key or chord. `Mod` in a chord (`Mod+k`) resolves to Cmd on macOS and Ctrl elsewhere.                                                               |
-| `back: true`                              | Go back one page, like the browser's Back button. Fails when the journey has not navigated from an earlier page.                                            |
-| `goto: pageId`                            | Load a page the way a typed URL does; `{ pageId, urlQuery }` adds a query string. A protected page may redirect (to sign in), so assert where it landed.    |
-| `email: { to, subject }`                  | Open the newest [email](#emails) to `to` — with a subject containing `subject`, when given — that arrived during the journey, waiting for it if needed.     |
-| `as: name`                                | Act as [another person](#several-people), each in their own browser. The journey starts as `main`.                                                          |
-| `wait: { ms }`                            | Pause for `ms` milliseconds.                                                                                                                                |
-| `wait: { request: requestId }`            | Wait until the request has finished loading.                                                                                                                |
-| `wait: { state: path }`                   | Wait until the state value at `path` is defined.                                                                                                            |
-| `screenshot: name`                        | Capture a screenshot. Screenshots are returned to agents using the MCP tool; the CLI runner ignores them.                                                   |
-| `expect: { state: { path, equals } }`     | The page state at `path` deep-equals `equals`. A path that does not exist reads as `null`, so `equals: null` also passes for a misspelt path.               |
-| `expect: { visible: target }`             | The block, or the control a target narrows to, is visible.                                                                                                  |
-| `expect: { text: { blockId, contains } }` | The block's rendered text (or a grid row's or cell's) contains the string.                                                                                  |
-| `expect: { url: { contains } }`           | The browser URL contains the string.                                                                                                                        |
-| `expect: { title: { equals } }`           | The document title (the browser tab's text) is exactly the string; `{ contains }` checks part of it.                                                        |
-
-The full grammar, including the failure shape the route returns, is documented with the [journey tool](/ai-agent-docs). The CLI and the MCP tool share one implementation, so a journey an agent verifies interactively can be committed as-is.
-
-### Targets
-
-A `blockId` reaches a block's own control — its button, input or link. Some controls are not blocks: the Edit and Delete buttons a grid renders in every row, the OK and Cancel of a confirm dialog, the items of a dropdown menu. Wherever a step takes a `blockId`, it also takes a target object that narrows the search:
-
-| Key          | Meaning                                                                                                     |
-| ------------ | ----------------------------------------------------------------------------------------------------------- |
-| `blockId`    | The block to search inside.                                                                                 |
-| `row`        | A grid row, zero-based as displayed (`AgGrid*` blocks). Needs `blockId`.                                    |
-| `column`     | A grid cell in that row, by the column's `field` or `colId`. Needs `blockId`.                               |
-| `text`       | The interactive control whose visible text is exactly this (a button label, a tab, a menu item).            |
-| `containing` | The element whose visible text contains this: a row of a list a person picks by the name or email it shows. |
-| `nth`        | When several controls match, the zero-based one to use.                                                     |
-
-`text` on its own, with no `blockId`, searches the whole page — front-most layer first: an open dropdown menu, then an open dialog, then the page. That is how a confirm dialog's button is clicked while the grid behind its mask has a button with the same label.
-
-```yaml
-- name: member deletes a control from the grid
-  pageId: controls
-  user: { roles: [admin] }
-  steps:
-    - click: { blockId: controls_grid, row: 1, text: Delete } # the row's Delete cell button
-    - expect: { visible: { text: Are you sure? } }
-    - click: { text: Delete } # the confirm dialog's OK, not the grid's
-    - wait: { request: delete_control }
-    - expect: { text: { blockId: controls_grid, row: 1, column: title, contains: Key rotation } }
-    - click: { blockId: controls_grid, row: 0, column: actions } # the cell's first control
-    - click: { blockId: controls_grid, row: 0, column: more, nth: 0 } # an icon-only menu trigger
-    - click: { text: Archive } # the open menu's item
-```
-
-Some rows are neither a block nor a control, such as the cards of a `ListSelector`. `containing` clicks the text a person would click on, and the click reaches the row's own handler:
-
-```yaml
-- click: { blockId: members_list, containing: ada@example.test } # opens Ada's row
-```
-
-`fill`, `select` and `expect.text` always need a `blockId`; a value is typed into a block's input, never into a page-wide control. A target with a key the grammar does not know (`colum`) is rejected before the browser opens, so a typo cannot pass as a step that happened to find nothing.
-
-## Testing sign-up and sign-in
-
-A journey with `user: none` injects no user: it starts signed out, and the app's own auth decides who it is, exactly as in a real browser. Sign-up, email verification, sign-in, sign-out and organization switching all run for real, and the session cookie a sign-in sets carries through every later step.
-
-```yaml
-# tests/journeys/sign-up.yaml
-- name: a new user signs up, verifies by email and signs in
-  pageId: signup
-  user: none
-  timeout: 30000
-  steps:
-    - fill: { blockId: email, value: ada@example.test }
-    - fill: { blockId: password, value: correct-horse-battery }
-    - click: signup_button
-    - email: { to: ada@example.test, subject: Verify your email address }
-    - click: { text: Verify email address }
-    - goto: login
-    - fill: { blockId: email, value: ada@example.test }
-    - fill: { blockId: password, value: correct-horse-battery }
-    - click: login_button
-    - goto: dashboard
-    - expect: { text: { blockId: user_details, contains: ada@example.test } }
-```
-
-A journey that opens a protected page signed out lands on the sign-in page, the way a visitor would; assert where it landed with `expect: { url: ... }`.
-
-Give journeys that sign people in a `timeout` of about 30000. They load many pages, reload the app after each sign-in and wait for real emails, so on a busy machine or a CI runner the 5 second default fails them at random steps.
-
-### Emails
-
-The `email` step reads the mail the development server captured. Start the server with `LOWDEFY_DEV_SMTP_PORT` set to a free port (in the shell or the app's `.env`; the mail sink starts with the server, so restart it after adding the variable), and point the app's SMTP connection at `127.0.0.1` on that port through its secrets. The server then receives the app's mail over SMTP and keeps it instead of delivering it: every message the app sends — verification, magic link, invitation, your own `SMTPMailSend` requests — is written to `.lowdefy/mail/` in the app directory, and the directory is emptied each time the server starts. Only the development server does this, and only with the variable set; nothing in a production build captures mail.
-
-```yaml
-connections:
-  - id: email
-    type: SMTP
-    properties:
-      from: app@example.com
-      host:
-        _secret: SMTP_HOST # 127.0.0.1 for tests
-      port:
-        _number.parseInt:
-          on:
-            _secret: SMTP_PORT # the LOWDEFY_DEV_SMTP_PORT value for tests
-```
-
-`email` opens the newest matching message that arrived since the journey started, waiting up to the step timeout for one to arrive. The email is shown in the actor's tab, so `click: { text: Verify email address }` follows its button the way a person does, and `expect: { visible: { text: ... } }` checks its content. Opening the same email again (following an invitation link a second time after signing up) opens the same message. When nothing matches, the step fails with the messages that did arrive.
-
-A one-time code is typed, not clicked. `fill` with `fromEmail: { to, subject, match }` reads the same newest matching message, waiting for it the same way, and types the first match of the regular expression `match` (or its first capture group, when it has one) into the block. The actor stays on the page they are on, as a person reads the code on their phone and types it into the tab they started from. The match runs on the email's text, not its HTML markup. Anchor the pattern with `\b`, since the text can also hold the sign-in link, whose address may contain digits.
-
-```yaml
-- click: login_magic_send
-- fill:
-    blockId: otp
-    fromEmail:
-      to: ada@example.test
-      subject: Your sign-in link
-      match: '\b\d{6}\b'
-- click: login_code_verify
-```
-
-### Several people
-
-`as: invitee` switches the journey to another person with their own browser and cookies: an owner and the person they invite, or a member whose session stays open while the owner removes them. The journey starts as `main`. The first `as` for a name opens the journey's page in a new browser, as the journey's `user`; switching back returns to that person's tab as they left it.
-
-Each person also sends requests from their own client address, so auth rate limits (a few sign-in attempts per address every few seconds) count each person's attempts apart, as they would for people on different devices, instead of one budget for the whole run.
-
-### The database
-
-Journeys perform real sign-ups, so they need a database that starts empty and is never a real one. Run them against a fresh test database each time: a sign-up journey run a second time finds its address already registered, and no verification email is sent. Give each journey its own addresses, so journeys in one run do not collide.
-
-Keep journeys that write, like these, out of `tests/journeys/` when your everyday `lowdefy test` runs against a shared database. Put them in their own directory, such as `tests/auth-journeys/`, and run them only from a script that starts the test database, the mail sink and the server they need:
-
-```
-lowdefy test --journeys-directory tests/auth-journeys --url http://localhost:3290
-```
-
-A plain `lowdefy test`, and the `lowdefy_run_tests` agent tool, never read that directory.
-
-## Running
-
-```
-pnpx lowdefy@5 test
-```
-
-With no options, `lowdefy test` prepares `.lowdefy/dev` exactly as `lowdefy dev` does, starts the development server on a free port without opening a browser, runs every journey, prints the results and stops the server.
-
-```
-PASS  member creates a control  (5 steps, 1840ms)
-FAIL  guest sees the empty state
-      file: /my-app/tests/journeys/controls.yaml
-      step 0: { expect: { visible: empty_state } }
-      expected: block "empty_state" to be visible
-      actual:   Timeout 5000ms exceeded.
-1 passed, 1 failed of 2 journeys
-```
-
-A failing journey stops at its first failing step and prints the step's index, the step itself, and the `expected` and `actual` values. Steps after the failure are not run.
-
-### Options
-
-- `--filter <name>`: Only run journeys whose `name` contains the string (case-insensitive). `lowdefy test --filter control` runs every journey with "control" in its name.
-- `--journeys-directory <path>`: Read journeys from this directory instead of `tests/journeys/`, for journeys that need a server set up for them, such as [auth journeys](#the-database). A relative path is resolved from the current directory. The run fails when the directory holds no journeys.
-- `--url <url>`: Run against a development server that is already running instead of starting one, for example `lowdefy test --url http://localhost:3000` while `lowdefy dev` is open in another terminal. This is the fastest way to iterate on a journey.
-- `--port <port>`: The port to start the development server on. If it is in use the next free port is taken. The default is `3000`.
-- `--config-directory`, `--dev-directory`, `--ref-resolver`, `--log-level`, `--disable-telemetry`: As for [`lowdefy dev`](/cli#dev).
-
-### Exit codes
-
-| Exit code | Meaning                                                                                                                                           |
-| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `0`       | Every journey passed, or `tests/journeys/` has no journeys (a note is printed).                                                                   |
-| `1`       | At least one journey failed, a journey file was invalid, an explicit `--filter` matched no journey, or a `--journeys-directory` held no journeys. |
-
-A journey file that is not valid YAML, or does not match the journey format (a missing `name`, a step with two keys, an unknown step key) is reported as a failed journey with the validation message and the file path. It never aborts the run, so one broken file cannot hide the results of the others.
-
-## Continuous integration
-
-`lowdefy test` needs only Node.js, pnpm and a Chromium the dev server can launch. A GitHub Actions job looks like:
-
-```yaml
-name: Config tests
-on: [push, pull_request]
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-      - run: pnpx playwright install --with-deps chromium
-      - run: pnpx lowdefy@5 test
-        env:
-          LOWDEFY_DISABLE_TELEMETRY: true
-```
-
-Set the same environment variables (`.env` values, connection secrets) the app needs in dev, and make sure the database the journeys write to is a test database — journeys perform real actions against real requests.

package/content/tutorial/tutorial-requests-api.md

@@ -1,155 +0,0 @@
-# 5. API / HTTP requests
-
-If you have been following along, you can continue with your current config. Else, you can find the config from the previous section [here](https://github.com/lowdefy/lowdefy-example-tutorial/tree/main/04-interactive-pages).
-
-We will now add a `AxiosHttp` [connection and request](/connections-and-requests) to get the list of products that tickets can be logged for from an external API endpoint.
-
-## Configuring the AxiosHttp Connection and Request
-
-We want to add a [`Selector`](/Selector) block to our form that will allow the user to select which product they are logging a ticket about, from a preset list of options. This list of preset product options will be obtained from the [DummyJSON](https://dummyjson.com/) API.
-
-For this, we will make use of an [`AxiosHttp`](/AxiosHttp) connection as described in the following steps:
-
-#### 5.1. Adding a new connection to the app
-
-In your `lowdefy.yaml` file, add the following:
-
-##### `lowdefy.yaml`
-
-```yaml
-name: lowdefy-project-template
-version: 6.0.0
-
-################ -------- Copy from here -------- ################
-connections:
-  - id: dummy_api
-    type: AxiosHttp
-    properties:
-      baseURL: https://dummyjson.com/
-################ ------- Copy to here ----------- ################
-
-menus:
-  # ...
-```
-
-#### 5.2. Adding a request to the page
-
-In your `new-ticket.yaml` file, add the following request:
-
-##### `pages/new-ticket.yaml`
-
-```yaml
-id: new-ticket
-type: PageHeaderMenu
-################ -------- Copy from here -------- ################
-requests:
-  - id: get_products
-    type: AxiosHttp
-    connectionId: dummy_api
-    properties:
-      url: /products
-################ ------- Copy to here ----------- ################
-
-properties:
-  title: New ticket # The title in the browser tab.
-layout:
-  justify: center # Center the contents of the page
-blocks:
-  # ...
-```
-
-#### 5.3. Triggering the request on page load
-
-In your `new-ticket.yaml` file, add an onMount event that calls `get_products` request:
-
-##### `pages/new-ticket.yaml`
-
-```yaml
-requests:
-  - id: get_products
-    type: AxiosHttp
-    connectionId: dummy_api
-    properties:
-      url: /products
-
-################ -------- Copy from here -------- ################
-events:
-  onMount:
-    - id: fetch_products
-      type: Request
-      params: get_products
-################ ------- Copy to here ----------- ################
-
-properties:
-  title: New ticket # The title in the browser tab.
-layout:
-  justify: center # Center the contents of the page
-blocks:
-  # ...
-```
-
-#### 5.4. Using the request response as selector options
-
-In your `new-ticket.yaml` file, add the a Selector block and populate it with the results from the `get_products` request. We will make use of [`_array.map`](/_array#map_title) operator to get the product titles from the response obtained from the request. This is done as follows:
-
-##### `pages/new-ticket.yaml`
-
-```yaml
-id: new-ticket
-    # ...
-blocks:
-  - id: content_card
-    # ...
-    blocks:
-      - id: page_heading
-        type: Title
-        properties:
-          content: Log a ticket # Change the title on the page.
-          level: 3 # Make the title a little smaller (an html `<h3>`).
-      - id: ticket_title
-        type: TextInput
-        properties:
-          title: Title
-      - id: ticket_type
-        type: ButtonSelector
-        properties:
-          title: Ticket type
-          options: # Set the allowed options
-            - Suggestion
-            - Complaint
-            - Question
-
-################ ------- Copy from here -------- ################
-      - id: product
-        type: Selector
-        required: true
-        properties:
-          title: Product
-          options:
-            # Map over API response to create an array of product titles
-            _array.map:
-              # use dot notation to access value in response object properties
-              - _request: get_products.data.products
-              - _function:
-                  __args: 0.title
-################ ------- Copy to here -------- ################
-
-      - id: ticket_description
-        type: TextArea
-        properties:
-          title: Description
-```
-
-### What happened
-
-We defined the [`AxiosHttp`](/AxiosHttp) connection to be used to obtain the list of products that tickets can be created for.
-
-We also defined an [`AxiosHttp`](/AxiosHttp) request, to fetch the products data when the page is mounted. To do this, we used the onMount event to execute the Request action to make the API call.
-
-We then mapped the request response to the product selector options by using the [_request](/_request) and [_array.map](/_array#map_title) operators.
-
-> You can find the final configuration files for this section [here](https://github.com/lowdefy/lowdefy-example-tutorial/tree/main/05-requests-api).
-
-### Up next
-
-Next we will save the form data to a SQLite database file.