@lowdefy/docs-content 0.0.0-experimental-20260910082708 → 6.0.0

package/content/testing/config-tests.md

@@ -1,164 +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.                                                    |
-
-## Steps
-
-Blocks are addressed by their `blockId`. Every step has a 5 second timeout by default; a step that does not complete in time fails the journey.
-
-| 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).                           |
-| `select: { blockId, value }`              | Open the selector block (or grid cell) and choose the option whose text is `value`.                       |
-| `press: Enter`                            | Press a key or chord. `Mod` in a chord (`Mod+k`) resolves to Cmd on macOS and Ctrl elsewhere.             |
-| `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`.                                                            |
-| `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.                                                                      |
-
-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). |
-| `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
-```
-
-`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.
-
-## 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.
-- `--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, or an explicit `--filter` matched no journey. |
-
-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/hazards.json

@@ -1,44 +0,0 @@
-[
-  {
-    "id": "state-in-request-properties",
-    "appliesTo": { "kinds": ["requests"] },
-    "message": "_state in request properties is always undefined — a request is evaluated on the server with an empty state. Pass the value in the payload and read it with _payload.",
-    "see": "concepts/connections-and-requests"
-  },
-  {
-    "id": "visible-false-prunes-state",
-    "appliesTo": { "kinds": ["blocks"] },
-    "message": "visible: false removes the block and its state. Style it hidden (for example style: { display: none }) to keep the value.",
-    "see": "concepts/lowdefy-schema"
-  },
-  {
-    "id": "link-same-page-no-onmount",
-    "appliesTo": { "types": ["Link"] },
-    "message": "A Link to the page already open does not remount it, so onMount does not fire again. Trigger the reload chain from the same action list.",
-    "see": "actions/link"
-  },
-  {
-    "id": "ref-njk-renders-at-build",
-    "appliesTo": { "types": ["_ref"] },
-    "message": "A _ref to a .njk file renders at build, so _state, _request and _user are undefined inside it. Use _nunjucks over a .txt file for a template that needs runtime values.",
-    "see": "operators/_ref"
-  },
-  {
-    "id": "ref-js-imported-as-module",
-    "appliesTo": { "types": ["_ref"] },
-    "message": "A _ref to a .js file imports it as a module rather than reading it as text. Name the file .js.txt to read its source.",
-    "see": "operators/_ref"
-  },
-  {
-    "id": "tenant-wall-lookup",
-    "appliesTo": { "kinds": ["requests"], "when": "connectionTenantNotNone" },
-    "message": "This request runs over a tenant-walled connection. The wall injects { $match: { <tenant field> } } into the top-level pipeline and into every $lookup / $unionWith sub-pipeline, so a lookup into a collection with no tenant field returns [] with no error. Run the request over the shared connection and pass tenant facts in the payload instead.",
-    "see": "concepts/connections-and-requests"
-  },
-  {
-    "id": "reject-not-caught",
-    "appliesTo": { "types": [":reject"] },
-    "message": ":reject is the routine's reply, not an exception. A :catch never runs for it, :finally does, and :throw is the caught path.",
-    "see": "controls/reject"
-  }
-]