@terreno/mcp 57.20.0 → 57.22.0

package/dist/docs/versioned/next/testing/e2e/announcements.md

@@ -0,0 +1,63 @@
+# @terreno/announcements e2e tests
+
+Run the announcements smoke after a compile:
+
+```bash
+bun run compile && bun run --cwd announcements smoke
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | Pending and feed selection, audience and platform rules, acknowledgements, impressions, clicks, release import, the admin overview, and help routes through supertest (`src/tests/*.test.ts`) | `bun run --cwd announcements test` |
+| Smoke | The compiled plugin publishing an announcement and serving it to a signed-in user from a real server in a child process | `bun run --cwd announcements smoke` |
+| E2E | None yet. example-frontend has no Playwright spec for announcements | none |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`announcements/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/announcements/e2e/smoke.ts)
+runs at the `http` layer. It re-runs itself with a `serve` argument to start a child process
+that imports the compiled `@terreno/api` and `@terreno/announcements` by package name. The
+child builds a `TerrenoApp` with a passport-local user model, an inline `/health` plugin, and
+`AnnouncementsApp` with an `uploadToken`, and listens on a `freePort()` against
+`smokeMongoUri()`. The parent waits for `/health` with `spawnUntilReady`, then checks over
+real HTTP:
+
+1. `POST /announcements/import-release` with the upload token and `publish: true` returns one
+   published announcement.
+2. `POST /auth/signup` returns a token for a new, non-admin user.
+3. `GET /announcements/feed` with that token lists the announcement with its title.
+
+It prints one `✅` line per check and exits 1 on the first failure, after printing the
+server's output. The announcement is created through release import, the route release
+pipelines call, because signup never grants admin. Creating it through the admin CRUD routes
+would mean seeding an admin straight into MongoDB. Each run imports under a new release
+version, so reruns against a shared `TERRENO_TEST_MONGODB_URI` never collide.
+
+**Measured time:** 4.5–8 s in three root `bun run smoke` runs (the [guide's](../e2e.md#package-pages) figure), excluding the compile. Earlier single runs took
+21–24 s on a quiet 4-CPU container against an external replica set, and 40–100 s when parallel builds starved the CPU, excluding the compile. Most of it is loading
+the compiled packages in the child; under load, password hashing on signup alone took 17 s.
+Budget: 30 s.
+
+If the in-memory replica set times out waiting for a primary, point the smoke at a running
+replica set the way CI does:
+
+```bash
+TERRENO_TEST_MONGODB_URI="mongodb://127.0.0.1:27017/?replicaSet=rs0" bun run --cwd announcements smoke
+```
+
+## Add an e2e test
+
+- **New route, option, or visibility rule:** add a test in `announcements/src/tests/`. The
+  smoke stays one happy path; do not add edge cases to it.
+- **The publish-to-feed path changed** (for example, the import body or the feed response
+  shape): update the checks in `announcements/e2e/smoke.ts` and keep it within 30 s.
+- **A user-visible flow** (for example, the announcement modal or the changelog feed): add a
+  Playwright spec in `example-frontend/e2e/`, following
+  [Write a Playwright spec](../e2e.md#write-a-playwright-spec), against example-backend, which
+  already registers the plugin.
+
+See [the announcements reference](../../reference/announcements.md) for the plugin API and
+[the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for the smoke helpers.

package/dist/docs/versioned/next/testing/e2e/api-health.md

@@ -0,0 +1,54 @@
+# @terreno/api-health e2e tests
+
+Run the api-health smoke after a compile:
+
+```bash
+bun run compile && bun run --cwd api-health smoke
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | `HealthApp` options and branches (custom path, `enabled: false`, sync, async, failing, and throwing checks) through supertest (`src/healthApp.test.ts`) | `bun run api-health:test` |
+| Smoke | The compiled plugin answering health checks from a real server in a child process | `bun run --cwd api-health smoke` |
+| E2E | The plugin as example-backend registers it, with a MongoDB check. Client smokes that start example-backend (`spawnExampleBackend`) wait on its `/health`, and example-frontend's Playwright suite runs against that backend | `bun run frontend:e2e` |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`api-health/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/api-health/e2e/smoke.ts)
+runs at the `http` layer. It re-runs itself with a `serve` argument to start a child process
+that imports the compiled `@terreno/api-health` by package name, registers `HealthApp` on a
+plain Express app the way `TerrenoApp.register` does, and listens on a `freePort()`. It
+registers the plugin twice: once with defaults, and once at `/health/down` with a `check` that
+reports a dependency down. The parent waits for `/health` with `spawnUntilReady`, then checks
+over real HTTP:
+
+1. `GET /health` returns 200 with `{healthy: true}`.
+2. `GET /health/down` returns 503 with `healthy: false` and the check's `details`.
+
+The 503 is part of the happy path for this plugin: it is the status load balancers and Cloud
+Run probes act on. It prints one `✅` line per check and exits 1 on the first failure, after
+printing the server's output. A compiled plugin patched to always answer 200 fails check 2. A
+default route that stops answering 2xx shows up as a `spawnUntilReady` timeout, not as check 1.
+
+The smoke uses no `TerrenoApp`, so it needs no user model, MongoDB, or secrets. That also keeps
+it free of dependencies api-health does not already declare.
+
+**Measured time:** 2 s in three root `bun run smoke` runs (the [guide's](../e2e.md#package-pages) figure), excluding the compile. A single run that also loads
+`@terreno/test` cold took about 8 s on an idle machine and 11–20 s under load. Budget: 30 s.
+
+## Add an e2e test
+
+- **New option or branch:** add a unit test in `api-health/src/healthApp.test.ts`. The smoke
+  stays one happy path; do not add edge cases to it.
+- **The wire contract changed** (the status codes or the `{healthy, details}` body): update the
+  checks in `api-health/e2e/smoke.ts` and keep it within 30 s.
+- **A user-visible flow** (for example, an app screen that reports service health): add a
+  Playwright spec in `example-frontend/e2e/`, following
+  [Write a Playwright spec](../e2e.md#write-a-playwright-spec), with the plugin wired into
+  example-backend.
+
+See [the `@terreno/api-health` reference](../../reference/api-health.md) for the plugin API and
+[the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for the smoke helpers.

package/dist/docs/versioned/next/testing/e2e/api.md

@@ -0,0 +1,48 @@
+# @terreno/api e2e tests
+
+Run the api smoke after a compile:
+
+```bash
+bun run compile && bun run --cwd api smoke
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | `modelRouter`, permissions, auth, sync, and plugins through supertest against in-memory Mongo (`src/**/*.test.ts`) | `bun run api:test` (`bun run --cwd api test:coverage` adds the 95% gate) |
+| Smoke | The compiled package serving real HTTP from a child process | `bun run --cwd api smoke` |
+| E2E | api behavior seen by a user, through example-frontend's Playwright suite against example-backend | `bun run frontend:e2e` |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`api/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/api/e2e/smoke.ts) runs
+at the `http` layer. It re-runs itself with a `serve` argument to start a child process that
+imports the compiled `@terreno/api`, builds a `TerrenoApp` with a passport-local user model,
+one owner-scoped `modelRouter` model (`/widgets`), and an inline `/health` plugin, and listens
+on a `freePort()` against `smokeMongoUri()`. The parent waits for `/health` with
+`spawnUntilReady`, then checks over real HTTP:
+
+1. `GET /health` returns `{healthy: true}`.
+2. `POST /auth/signup` returns a token.
+3. `POST /widgets` with that token returns 201 and a widget owned by the new user.
+4. `GET /widgets` lists the widget.
+
+It prints one `✅` line per check and exits 1 on the first failure, after printing the
+server's output. The health route is inline because `@terreno/api-health` depends on
+`@terreno/api`.
+
+**Measured time:** 5–10 s in three root `bun run smoke` runs (the [guide's](../e2e.md#package-pages) figure), excluding the compile. Single runs took 13 s on an
+idle machine and 16–26 s under load.
+Budget: 30 s.
+
+## Add an e2e test
+
+- **New route or option behavior:** add a unit test in `api/src/`. The smoke stays one happy
+  path; do not add edge cases to it.
+- **The smoke's happy path changed** (for example, signup or the list response shape): update
+  the checks in `api/e2e/smoke.ts` and keep it within 30 s.
+- **A user-visible flow:** add a Playwright spec in `example-frontend/e2e/`, following
+  [Write a Playwright spec](../e2e.md#write-a-playwright-spec), with the route wired into
+  example-backend.

package/dist/docs/versioned/next/testing/e2e/blocks.md

@@ -0,0 +1,53 @@
+# @terreno/blocks e2e tests
+
+Run the blocks smoke after a compile:
+
+```bash
+bun run compile && bun run --cwd blocks smoke   # or, from the root: bun run smoke blocks
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | Ask and block schemas, parsing (whole and partial), lint, validation and its error codes, the prompt sections, plain text, JSON Schemas, and `runBlocksCli` in-process, against the fixtures in `src/fixtures/` and `src/asks/fixtures/` (`src/**/*.test.ts`) | `bun run blocks:test` |
+| Smoke | The compiled `terreno-blocks` binary validating documents in a real process | `bun run --cwd blocks smoke` |
+| E2E | Rendering blocks and asks in GPTChat belongs to `@terreno/ui` and example-frontend's Playwright suite (`ai-chat.spec.ts`) | `bun run frontend:e2e` |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`blocks/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/blocks/e2e/smoke.ts)
+runs at the `process` layer. It resolves `@terreno/blocks` by package name, reads the `bin`
+field of that package's `package.json`, and runs the `terreno-blocks` entry it names
+(`dist/cli.js`) with `runBin`, the way a consumer's package manager links it. It writes two
+YAML documents to a temp dir and checks:
+
+1. `terreno-blocks validate valid.yaml` exits 0 with no output. The document is a `text` block
+   and an `actions` block with a `reply` button.
+2. `terreno-blocks validate invalid.yaml` exits non-zero and prints a line naming
+   `blocks[0].markdown` and `MISSING_REQUIRED`. The document is a `text` block with no
+   `markdown`.
+
+It prints one `✅` line per check and exits 1 on the first failure, with the binary's stdout
+and stderr. A compiled CLI that stops failing on validation errors fails check 2. A `bin` entry
+that points at a missing file fails check 1. The smoke needs no Mongo, network, or server.
+
+**Measured time:** 1–2 s for the two checks and about 5 s for `bun run --cwd blocks smoke` end
+to end, excluding the compile. One root `bun run smoke blocks` run under load from parallel
+builds took 25 s. Budget: 30 s.
+
+## Add an e2e test
+
+- **New block type, field, limit, or error code:** add fixtures under `blocks/src/fixtures/`
+  and unit tests next to the code, as the
+  [block documents reference](../../reference/blocks.md) describes. The smoke stays one valid
+  and one invalid document; do not add edge cases to it.
+- **The CLI's contract changed** (a new subcommand, the output format, or the exit codes):
+  update `runBlocksCli` tests in `blocks/src/cli.test.ts`, then the checks in
+  `blocks/e2e/smoke.ts`.
+- **A user-visible rendering flow:** add a Playwright spec in `example-frontend/e2e/`, following
+  [Write a Playwright spec](../e2e.md#write-a-playwright-spec).
+
+See [the `terreno-blocks` CLI reference](../../reference/blocks.md#cli) and
+[the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for `runBin`.

package/dist/docs/versioned/next/testing/e2e/cli.md

@@ -0,0 +1,61 @@
+# @terreno/cli e2e tests
+
+Run the cli smoke after a compile:
+
+```bash
+bun run compile && bun run --cwd cli smoke   # or, from the root: bun run smoke cli
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | Argument parsing, help text, every command's handler through `runCli` with an injected `CliIo`, the generators, and the OpenAPI REST client (`src/**/*.test.ts`) | `bun run --cwd cli test` |
+| Smoke | The compiled `terreno` binary run as a child process: `--version` and one offline generator | `bun run --cwd cli smoke` |
+| E2E | Commands that need a running app (`api`, `logs`, `state`, `eval`, `navigate`, `web`, `db`) are exercised by hand against example-backend and example-frontend | none |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`cli/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/cli/e2e/smoke.ts) runs
+at the `process` layer. It reads the `bin.terreno` entry from `cli/package.json`
+(`dist/bin.js`) and runs it with `runBin()` from `@terreno/test`, from a fresh temp directory.
+It needs no network, MongoDB, or secrets. It checks:
+
+1. `dist/bin.js` starts with `#!/usr/bin/env bun`, which an installed `terreno` needs (`runBin`
+   runs the file through Bun, so the shebang is not exercised otherwise). `terreno --version`
+   exits 0 and prints the version in `cli/package.json`.
+2. `terreno --version --json` prints `{name: "@terreno/cli", version}` with the same version.
+3. `terreno generate model --name SmokeWidget --field title:String:required --out
+   models/smokeWidget.ts --json` exits 0 and reports the absolute path it wrote (`--out`
+   resolved against the working directory). The file parses as TypeScript (`Bun.Transpiler`),
+   exports `SmokeWidget`, and declares `title` as a required `String`.
+
+Each check prints one `✅` line. The smoke exits 1 on the first failure, with the command's
+output. The temp directory is removed afterwards.
+
+### MCP docs
+
+The CLI imports `@terreno/mcp`, and `@terreno/mcp` reads its bundled markdown as soon as it
+loads, so even `terreno --version` exits 1 when that markdown is missing. Only the mcp-server
+`build` script copies the markdown into `mcp-server/dist/docs`. `bun run compile` (and the
+CircleCI `smoke` job) does not. When `mcp-server/dist/docs` is missing, the smoke sets
+`TERRENO_MCP_DOCS_DIR` to `mcp-server/src/docs`, the directory `build` copies. After a full
+`bun run --cwd mcp-server build`, the smoke uses the bundled copy, as the published package
+does. The cli unit tests hit the same gap: run them after an mcp-server `build`, or with
+`TERRENO_MCP_DOCS_DIR` set the same way.
+
+**Measured time:** 3–5 s warm, excluding the compile. The first run after a compile can take
+about 10 s while Bun loads the CLI's dependency graph cold. Budget: 30 s.
+
+## Add an e2e test
+
+- **New command, flag, or generator option:** add a unit test in `cli/src/` that calls
+  `runCli` with an injected `CliIo`. The smoke stays one happy path; do not add edge cases to it.
+- **The binary's entry changed** (the `bin` path, `main`, or the `--version` contract): update
+  the checks in `cli/e2e/smoke.ts` and keep it within 30 s.
+- **A command that needs a running app:** keep it out of the smoke, which stays offline. Add a
+  case to `docs/regression/` with exact steps against example-backend and example-frontend.
+
+See [the `@terreno/cli` reference](../../reference/cli.md) for the commands and
+[the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for `runBin`.

package/dist/docs/versioned/next/testing/e2e/comms.md

@@ -0,0 +1,65 @@
+# @terreno/comms e2e tests
+
+Run the comms smoke after a compile:
+
+```bash
+bun run compile && bun run --cwd comms smoke
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | `CommsService` send, retry, hooks, and logging; each adapter against an injected client; push-token and dashboard routes; and Twilio and SendGrid webhooks, through supertest against in-memory Mongo (`src/**/*.test.ts`) | `bun run comms:test` |
+| Smoke | The compiled package sending mail from a real server and recording delivery from a signed webhook | `bun run --cwd comms smoke` |
+| E2E | The admin comms dashboard loading and its back navigation, in example-frontend's Playwright suite against example-backend (`admin-comms-back.spec.ts`) | `bun run frontend:e2e` |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`comms/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/comms/e2e/smoke.ts)
+runs at the `http` layer. It re-runs itself with a `serve` argument to start a child process
+that imports the compiled `@terreno/api` and `@terreno/comms` by package name and listens on a
+`freePort()` against `smokeMongoUri()`. The child builds a `TerrenoApp` with:
+
+- `UserModel` from `@terreno/api/testing`, with one seeded admin. Signup never grants `admin`,
+  and the dashboard needs it.
+- `CommsApp` with `SendGridMailProvider` on an in-memory client in place of `@sendgrid/mail`.
+  The client returns a SendGrid-style 202 with an `x-message-id`, so no request leaves the
+  machine and no SendGrid key is needed.
+- `WebhooksApp` with the memory idempotency store. The parent generates an ECDSA P-256 key pair
+  and passes the public key as `SENDGRID_WEBHOOK_VERIFICATION_KEY`, so `CommsApp` registers the
+  SendGrid Event Webhook route.
+- One smoke-only `modelRouter` collection action, `POST /commsSmoke/sendMail`, that calls
+  `getCommsService().sendMail()` the way app code does.
+
+The parent waits for `/health` with `spawnUntilReady`, then checks over real HTTP:
+
+1. `POST /auth/login` signs the admin in.
+2. `POST /commsSmoke/sendMail` returns an accepted send with a `loggedMessageId` and the
+   in-memory client's message id.
+3. `GET /comms/messages/:id` shows the row as a `sendgrid` mail message with status `sent`.
+4. `POST /comms/webhooks/sendgrid` with a signed `delivered` event returns 200.
+5. `GET /comms/messages/:id` shows the same row with status `delivered`.
+
+It prints one `✅` line per check and exits 1 on the first failure, after printing the
+server's output. A compiled `recordDeliveryEvent` that stops writing the status fails check 5.
+The admin email and message ids carry a per-run id, so the smoke reruns cleanly against a
+persistent `TERRENO_TEST_MONGODB_URI`.
+
+**Measured time:** about 6 s against an external replica set (`TERRENO_TEST_MONGODB_URI`) and
+17–21 s with the in-memory replica set, excluding the compile. Budget: 30 s.
+
+## Add an e2e test
+
+- **New adapter, hook, or route behavior:** add a unit test next to the code in `comms/src/`.
+  The smoke stays one happy path; do not add edge cases to it.
+- **The send-to-delivered path changed** (the `SendResult` shape, the message log, or webhook
+  intake): update the checks in `comms/e2e/smoke.ts` and keep it within 30 s.
+- **A user-visible flow** (for example, a dashboard screen): add a Playwright spec in
+  `example-frontend/e2e/`, following
+  [Write a Playwright spec](../e2e.md#write-a-playwright-spec), with the provider wired into
+  example-backend.
+
+See [the `@terreno/comms` reference](../../reference/comms.md) for the plugin API and
+[the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for the smoke helpers.

package/dist/docs/versioned/next/testing/e2e/create-terreno-app.md

@@ -0,0 +1,70 @@
+# create-terreno-app e2e tests
+
+Run the create-terreno-app smoke after a compile:
+
+```bash
+bun run compile && bun run --cwd create-terreno-app smoke   # or, from the root: bun run smoke create-terreno-app
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | Argument parsing, `--yes` defaults, the overwrite guard, and the content of every generated file, through `runCli`, `writeScaffold`, and `generateAllFiles`, plus the CLI's exit codes as a subprocess (`src/__tests__/*.test.ts`). None of them builds the generated app | `bun run --cwd create-terreno-app test:ci` |
+| Smoke | The compiled binary generates an app, and the generated backend bundles against the workspace packages | `bun run --cwd create-terreno-app smoke` |
+| E2E | none: the generated frontend and backend are not booted. Booting them needs a network `bun install` | none |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`create-terreno-app/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/create-terreno-app/e2e/smoke.ts)
+runs at the `process` layer. It never imports the package's source. It finds the compiled CLI
+through the `create-terreno-app` entry in the package's `bin`, the way `bunx` does, and runs it
+with `runBin`. Then it:
+
+1. Runs `create-terreno-app smoke-app --yes` in a new, empty temp directory. `runBin` gives the
+   CLI end-of-input on stdin, so it must finish on its flags alone: a prompt would get no answer
+   and the CLI would not print `Created <dir>`. The CLI must exit 0, print `Created <dir>`, and
+   write the backend and frontend entry files (`backend/src/index.ts`, `backend/src/server.ts`,
+   `frontend/app/_layout.tsx`, both `package.json` files, and `README.md`).
+2. Reads the runtime imports of every `backend/src/**/*.ts` file with `Bun.Transpiler`
+   (type-only imports are dropped) and checks that each package they name, other than Node
+   built-ins, is in the generated `backend/package.json` `dependencies`. Step 3 links the whole
+   monorepo `node_modules`, so the build alone would not catch an undeclared import that a
+   scaffolded app's `bun install` would leave out.
+3. Links the generated `backend/node_modules` to the monorepo's `node_modules`, and checks that
+   each `@terreno/*` dependency in the generated `backend/package.json` (`admin-backend`, `api`,
+   `api-health`) resolves to a workspace package inside the repo, not a hoisted copy under
+   `node_modules`, and that the workspace version satisfies the declared range. Nothing is
+   installed, so the smoke needs no network.
+4. Runs the generated backend's own `build` script (`bun build src/index.ts --outdir ./dist
+   --target node`) and checks that it exits 0 and writes `dist/index.js`. From the `// <path>`
+   comments Bun writes above each bundled module, it checks that the bundle holds modules from
+   each of those workspace packages' `dist/`.
+
+It prints one `✅` line per check, exits 1 on the first failure, and deletes the temp directory
+either way. The build fails when the generated backend imports a module or a package path that
+does not exist. The workspace packages compile to CommonJS, so Bun does not check named imports
+from them: a generated import of a removed `@terreno/api` export still builds. The generated
+backend's own `tsc` (`bun run compile` in a scaffolded app) catches that; the smoke skips `tsc`
+because it takes about 30 s on its own. The smoke runs the CLI and packages from `dist/`, so
+compile first: against a stale `dist/` it tests the old output.
+
+**Measured time:** 3.5–11 s on an idle container, and 15–21 s while other builds ran,
+excluding the compile. Generating and the import check take under 1 s; bundling the backend
+(about 3,300 modules) takes most of the rest. Budget: 30 s.
+
+## Add an e2e test
+
+- **New flag, default, or generated file content:** add a unit test in
+  `create-terreno-app/src/__tests__/`. The smoke stays one happy path; do not add edge cases to
+  it.
+- **The generated backend gains a `@terreno/*` dependency:** the smoke checks it with no edit,
+  because it reads the dependency list from the generated `backend/package.json`. The
+  dependency must be a workspace package.
+- **The generated backend's entry or `build` script changes:** update `EXPECTED_FILES` or the
+  build step in `create-terreno-app/e2e/smoke.ts`, and keep it within 30 s.
+
+See [the create-terreno-app reference](../../reference/create-terreno-app.md) for the CLI flags,
+[Create a Terreno app](../../how-to/create-a-terreno-app.md) for the user guide, and
+[the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for `runBin`.

package/dist/docs/versioned/next/testing/e2e/demo.md

@@ -0,0 +1,78 @@
+# Demo app e2e tests
+
+Run the demo smoke after a compile and the demo web export, with Playwright's Chromium
+installed:
+
+```bash
+bun run compile && bun run --cwd demo export && bun run --cwd demo smoke
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | Story registration, the catalog contract, preview state, and a render of every registered story with `@testing-library/react-native` (`*.test.ts(x)` in `demo/`), plus the story coverage check | `bun run --cwd demo test:ci`, then `bun run check:demo-coverage` |
+| Smoke | The static web export, served from a real port, listing the stories and rendering one story by route in Chromium | `bun run --cwd demo smoke` |
+| E2E | Maestro web flows against the same export on port 8085: the home and the Button story (`.maestro/flows/demo/`) | `bun run demo:maestro:test` |
+| Chart snapshots | Rendered chart images compared with `demo/rendered-snapshots/` | `bun run ui:charts:compare` |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`demo/e2e/smoke.spec.ts`](https://github.com/TerrenoLabs/terreno/blob/master/demo/e2e/smoke.spec.ts)
+runs at the `browser` layer. The demo ships as a static web export (`demo/dist/`), so the smoke
+tests that export the way it is deployed, not Metro. The one file has three roles.
+
+Run with Bun (`bun e2e/smoke.spec.ts`), it is the driver:
+
+1. It exits 1 at once when `demo/dist/index.html` is missing and asks for `export`. It does not
+   check that the export is newer than `ui/dist`, so rebuild the export after each compile, as
+   the command above does.
+2. It re-runs itself with a `serve` argument on a `freePort()`. That child is a static file
+   server for `dist/` that resolves a path as `serve` does without a rewrite: the exact file,
+   then `<path>.html`, then `<path>/index.html`, else 404. `spawnUntilReady` waits for
+   `/demo/Button` to answer 200.
+3. It runs the root-locked Playwright CLI on Node against this same file, passing the server URL
+   in `DEMO_SMOKE_BASE_URL`. There is no Playwright config: the demo has no other Playwright
+   suite, so the default Chromium project runs only this spec. If the package gains a
+   `playwright.config.ts`, give the smoke its own config and pass it with `--config`. Traces
+   and screenshots go to a temp dir that the driver deletes.
+
+Loaded by Playwright, the file defines one test. The export pre-renders every `testID` it
+checks into the HTML, so visibility alone would pass with a broken JS bundle. Each step also
+needs a client-side handler to respond, and a click before hydration does nothing, so the test
+retries each click with `expect(...).toPass()` instead of sleeping:
+
+1. It opens `/demo`, waits for `demo-home-screen`, and checks that the `demo-home-button` and
+   `demo-home-badge` story cards are visible. `DemoCard` names each card's press target
+   `demo-home-<lowercased name>`. It clicks `demo-home-button` until client-side navigation
+   reaches `/demo/Button`.
+2. It loads `/demo/Button` by route, waits for the story page's root `demo-preview-root` and
+   `button-variant-primary`, then clicks `button-variant-primary` until the story's `onClick`
+   logs `clicked` to the console. That button renders only in the Button page's stories.
+3. It checks that the URL is still `/demo/Button` (an unknown component redirects to `/demo`
+   once hydrated) and that the page raised no `pageerror` except React's recoverable hydration
+   errors (#418, #423, #425). The export raises #418 on every route because its pre-rendered
+   HTML differs from the first client render; React then renders on the client and the page
+   works. `demo/e2e/pageErrors.ts` holds that filter, and `demo/smokePageErrors.test.ts` tests
+   it. Any other page error fails the smoke.
+
+The driver prints one `✅` line per step and exits 1 on the first failure, after printing the
+static server's output and Playwright's report. The smoke needs Chromium
+(`bunx playwright install chromium`) but no backend, database, or secrets.
+
+**Measured time:** 7.5–8 s across three runs on a 4-CPU container, excluding the compile and
+the web export. The CircleCI `smoke` job prints each package's time on every run. Budget: 30 s.
+
+## Add an e2e test
+
+- **A story or the catalog changed:** add or update a unit test in `demo/`. The smoke stays one
+  happy path; do not add per-story checks to it.
+- **The demo home, `DemoCard` testIDs, or the story route changed:** update the testIDs and the
+  route in `demo/e2e/smoke.spec.ts` and keep it within 30 s.
+- **A user flow through a demo page:** add a Maestro flow to `.maestro/flows/demo/`. Follow
+  [Write a Maestro flow](../e2e.md#write-a-maestro-flow).
+- **A `@terreno/ui` component's behavior in a browser:** add it to the `@terreno/ui` smoke or
+  unit tests, not here.
+
+See [the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for the smoke helpers.

package/dist/docs/versioned/next/testing/e2e/example-backend.md

@@ -0,0 +1,85 @@
+# example-backend e2e tests
+
+Run the example-backend smoke after a compile:
+
+```bash
+bun run compile && bun run --cwd example-backend smoke   # or, from the root: bun run smoke example-backend
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | Routes, models, permissions, seeds, migrations, jobs, websockets, and server wiring, in-process with supertest against the in-memory Mongo from `@terreno/test` (`src/**/*.test.ts`) | `bun run --cwd example-backend test` |
+| Smoke | `src/index.ts` as a real process: boot, `/health`, and the sign-in of a user the seed script's `users` step creates | `bun run --cwd example-backend smoke` |
+| E2E | User flows through example-frontend's Playwright suite and the Maestro flows against this backend | `bun run frontend:e2e`, `bun run maestro:test` |
+| Manual regression | Cases in `docs/regression/` | none |
+
+The client smokes (rtk, syncdb, admin-frontend) also boot this backend with
+`spawnExampleBackend()`, so a backend that stops booting fails them too. This smoke is the one
+that names the backend as the cause.
+
+## The smoke
+
+[`example-backend/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/example-backend/e2e/smoke.ts)
+runs at the `http` layer. It uses its own database from `smokeMongoUri()`,
+`exampleBackendSmoke`. When `TERRENO_TEST_MONGODB_URI` points at a persistent replica set, as in
+CI and the runs below, that database outlives the run the way rtk's and syncdb's do, so later
+boots skip example-backend's first-boot work. Without it, `smokeMongoUri()` starts an in-memory
+replica set that is empty every run. Then:
+
+1. Starts `src/index.ts` as a child process with `spawnExampleBackend()` on a free port, with
+   `SEED_DEFAULTS=false` so the server does not seed users on boot. Better Auth is the
+   backend's default provider. While the server boots, the smoke process loads the seed script
+   (`src/scripts/seed-test-data.ts`), connects it to the same database, and deletes the users
+   and Better Auth accounts an earlier run left behind.
+2. Checks that `GET /health` answers 200 with `healthy: true`.
+3. Checks that `POST /api/auth/sign-in/email` for `test@example.com` answers 401. The user
+   collections are empty and boot seeding is off, so nothing but the next step can create that
+   user.
+4. Runs the seed script's `users` step in the smoke process with `runSeeds({only: ["users"]})`,
+   which is what `bun run seed --only users` runs, against the same `MONGO_URI` and
+   `BETTER_AUTH_URL` as the server. The organizations, todos, AI, and EHR demo data are skipped.
+5. Checks that `POST /api/auth/sign-in/email` now signs in `test@example.com` with its
+   published dev password and returns a session token for that user.
+6. Checks that `GET /auth/me` with `Authorization: Bearer <token>` returns `test@example.com`
+   in `data.email`. This proves the seed linked the Better Auth account to the app's `User`
+   document.
+
+The seed runs in the smoke process rather than as a second `bun` process because the seed
+script loads most of the backend's modules: a second process paid that load again, after the
+server was up. Loading it in the smoke process overlaps it with the server's boot.
+
+Each check prints one `✅` line. The smoke exits 1 on the first failure, and a failed check
+prints the backend's output. A seed step that returns without writing the user fails check 5.
+
+**Measured time:** excluding the compile, against a single-node replica set on the same 4-CPU
+container (`TERRENO_TEST_MONGODB_URI`):
+
+- 15–18 s across four runs on their own once the database exists, and 16–20 s inside three
+  root `bun run smoke` runs.
+- 27 s for the first run on an empty database. On that first boot, example-backend builds its
+  indexes, runs its migrations, and syncs its consent forms.
+- 60–98 s for the previous smoke on the same replica set. It made a new database every run and
+  ran the seed as a second process.
+
+Without `TERRENO_TEST_MONGODB_URI`, the in-memory replica set is empty every run, so two runs
+took 24 and 38 s. CI's `smoke` job sets the variable to its Mongo sidecar, which starts empty.
+Every smoke that boots example-backend uses its own database (`exampleBackendSmoke`,
+`rtkSmoke`, `syncdbSmoke`, `adminFrontendSmoke`, `exampleFrontendSmoke`), so on CI each of them
+pays the empty-database first boot (about 27 s here), not the warm times above. The CircleCI
+`smoke` job's per-package times are the ones that judge the budget. Budget: 30 s.
+
+## Add an e2e test
+
+- **New route, model, permission, or seed step:** add a unit or integration test next to it in
+  `example-backend/src/`. The smoke stays one happy path; do not add edge cases to it.
+- **The boot path, health check, seed users, or sign-in changed** (for example a new required
+  env var, a different default auth provider, or a renamed seed user): update the checks in
+  `example-backend/e2e/smoke.ts`, and `spawnExampleBackend()` in `@terreno/test` when every
+  client smoke needs the change.
+- **A user-visible flow:** add a Playwright spec in `example-frontend/e2e/`, following
+  [Write a Playwright spec](../e2e.md#write-a-playwright-spec).
+
+See [the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for `freePort()`,
+`smokeMongoUri()`, and `spawnExampleBackend()`.