@pikku/cli 0.12.89 → 0.12.91

package/skills/pikku-scenario/SKILL.md

@@ -5,12 +5,12 @@ description: >-
   test coverage. A scenario (pikkuScenario) drives the app the way users do — steps run as actors
   over the real transport against a running server — so a flow doubles as an e2e test and a
   staged/production health check. Covers scenario.do / expectEventually / expectError /
-  expectService, actors and environments in pikku.config.json, SCENARIO_ACTOR_SECRET, the
+  expectService, declared steps via pikkuScenarioStep (including browser steps driven by
+  @pikku/playwright), actors and environments in pikku.config.json, SCENARIO_ACTOR_SECRET, the
   `pikku scenario list|run` commands, live function coverage via `pikku dev --coverage`, and
   plain unit tests for pure function logic. TRIGGER when: user asks about scenarios, testing a
-  Pikku function, test coverage, end-to-end flows, or health checks. DO NOT TRIGGER when: user
-  asks about browser/UI e2e (that is @pikku/cucumber, out of scope), running an existing test
-  suite (use Bash), or CI configuration.
+  Pikku function, test coverage, end-to-end flows, browser/UI e2e, or health checks. DO NOT
+  TRIGGER when: user asks about running an existing test suite (use Bash) or CI configuration.
 installGroups: [core]
 ---
 
@@ -35,7 +35,7 @@ A scenario is a `pikkuScenario` export that drives the app **as real actors over
 Consequences that matter, and bite if ignored:
 
 - **There is no state reset.** A scenario runs against a live server. Scope what you create (unique ids, your own rows) and never assume a clean database.
-- **Every step needs an actor.** `scenario.do(...)` without `{ actor }` throws `Scenario tried to run '<rpc>' as an internal step…`. There is no bare internal-RPC step.
+- **Every effect runs as somebody, or as a declared step.** `scenario.do(...)` without `{ actor }` throws `Scenario tried to run '<rpc>' as an internal step…` — there is no bare internal-RPC step. The other way to do work is `scenario.step/given/when/then`, which runs a `pikkuScenarioStep`; its actor is optional (setup steps have none) unless it declares `browser: true`.
 - **Actors must be configured and signed in**, or the scenario cannot run.
 
 Scenarios live in `srcDirectories` like any other function — by convention `*.scenario.ts`.
@@ -84,24 +84,167 @@ A scenario takes the same config fields as a workflow (`title`, `description`, `
 
 ### The scenario API
 
-| Call | Purpose |
-| --- | --- |
-| `scenario.do(step, rpc, data, { actor })` | Run an RPC as that actor. The step name is what appears in the run output. |
+| Call                                                                                 | Purpose                                                                                                              |
+| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `scenario.do(step, rpc, data, { actor })`                                            | Run an RPC as that actor. The step name is what appears in the run output.                                           |
 | `scenario.expectEventually(step, rpc, data, predicate, { actor, within, interval })` | Poll until `predicate(out)` passes or `within` elapses. For anything asynchronous — queues, workers, eventual state. |
-| `scenario.expectError(step, rpc, data, { actor, matches })` | Assert the call **fails**. For fault injection and negative paths. |
-| `scenario.expectService(step, 'service.method', { actor, calledWith })` | Assert a stubbed service was called. Requires the server to run with `--test`. |
+| `scenario.expectError(step, rpc, data, { actor, matches })`                          | Assert the call **fails**. For fault injection and negative paths.                                                   |
+| `scenario.expectService(step, 'service.method', { actor, calledWith })`              | Assert a stubbed service was called. Requires the server to run with `--test`.                                       |
+| `scenario.step(step, stepName, data, { actor })`                                     | Run a declared `pikkuScenarioStep`. `given`/`when`/`then` are the same call with a keyword in the rendered prose.    |
 
 `expectEventually` is **scenario-only**. Calling it from a `pikkuWorkflowFunc` is a critical inspector error (`PKU675`) pointing you at `pikkuScenario`.
 
-Prefer `expectEventually` over sleeping. There is no `beforeEach`/`afterEach` — a scenario is a plain async function.
+Prefer `expectEventually` over sleeping.
+
+### Setup and teardown (`before` / `after`)
+
+A scenario config takes `before` and `after`. Both have the **same signature as `func`** — `(services, data, wire)` — with the return value discarded:
+
+```typescript
+const resetsCredentials = async (_services, _data, { actors }) => {
+  await actors!.admin!.invoke('resetCredentials', {})
+}
+
+export const credentialScenario = pikkuScenario({
+  title: 'A credential is loaded on first use',
+  tags: ['scenario', 'credential'],
+  before: resetsCredentials,
+  after: removesInstalledAddon,
+  func: async (services, data, { scenario, actors }) => { /* … */ },
+})
+```
+
+| Rule                                                                                                     |
+| -------------------------------------------------------------------------------------------------------- |
+| `before` throwing skips the body and fails the run — but `after` still runs.                             |
+| `after` always runs, in a `finally`, whether the scenario passed or failed.                              |
+| `after` throwing fails a run that would otherwise have passed.                                           |
+| `after` throwing on an already-failed run attaches as the `cause` and never replaces the original error. |
+| Neither runs when the run is suspended or waiting — teardown only fires at a terminal outcome.           |
+| Hooks are **not** ladder rows. The runner records nothing for them; a failure is labelled by phase.      |
+
+A hook reaches the app the same way the body does: through `wire.actors`. If you want cleanup to be *visible* on the ladder, make it an ordinary `scenario.then(...)` instead.
+
+Hooks are scenario-only. A `before`/`after` on a `pikkuWorkflowFunc` never runs — a workflow is durable and resumable, so a callback that reran on every replay would have no honest meaning.
+
+### Grouping scenarios (`pikkuFeature`)
+
+`pikkuFeature` groups scenarios the way gherkin's `Feature:` groups `Scenario:`. Scenarios are referenced by **imported identifier**, so a renamed or deleted scenario is a compile error rather than a silent skip:
+
+```typescript
+import { pikkuFeature } from '#pikku/workflow/pikku-workflow-types.gen.js'
+import {
+  credentialLazyLoadScenario,
+  credentialRoundTripScenario,
+} from './credential.scenario.js'
+
+export const credentialFeature = pikkuFeature({
+  name: 'Credential API',
+  description: 'Credentials resolve lazily and are scoped per user',
+  tags: ['credential'],
+  before: startsMockOAuthServer,
+  after: stopsMockOAuthServer,
+  scenarios: [
+    credentialLazyLoadScenario,
+    ...['stripe', 'google', 'hmac-key'].map((name) => ({
+      scenario: credentialRoundTripScenario,
+      data: { name },
+    })),
+  ],
+})
+```
+
+| Rule                                                                                                                                     |
+| ---------------------------------------------------------------------------------------------------------------------------------------- |
+| The **export identifier is the feature's id**; `name` is the human-readable label. Both must be exported or the build fails.              |
+| A `{ scenario, data }` entry is gherkin's `Examples:` — one run per entry. `data` is typed against that scenario's input.                 |
+| Feature hooks run **once around the whole group** (`before → a → b → c → after`), _not_ per scenario. `after` runs in a `finally`.         |
+| There is deliberately **no `Background:`**. Per-scenario setup is the scenario's own `before`, referencing a shared function.             |
+| A scenario's effective tags are its own **plus** the feature's, so `--tags credential` selects through the feature.                       |
+| A scenario need not belong to a feature — one with no input still runs standalone.                                                        |
+| Membership is resolved by **object identity** at runtime, which is why a loop works and why a scenario built inline in a feature is an error. |
+
+The **feature is the run unit**: `--flows` on a scenario whose every feature entry carries `data` errors and names the features containing it, because the feature is what supplies that data. Use `--features` for those. A scenario referenced bare anywhere, or in no feature at all, still runs standalone.
+
+### Declared steps (`pikkuScenarioStep`)
+
+`scenario.do` can only name an RPC. A **step** is a named, typed unit of scenario behaviour whose body is an ordinary pikku function — so it can call several RPCs as its actor, assert, or drive a browser.
+
+```typescript
+import { pikkuScenarioStep } from '#pikku/workflow/pikku-workflow-types.gen.js'
+import { requireActor } from '@pikku/core/workflow'
+
+export const buysAnApple = pikkuScenarioStep<
+  { qty: number },
+  { orderId: string }
+>({
+  name: 'buysAnApple',
+  description: 'buys an apple',
+  template: 'buys {qty} apples',
+  func: async (_services, { qty }, { scenarioStep }) => {
+    return await requireActor(scenarioStep).invoke('placeOrder', { qty })
+  },
+})
+```
+
+```typescript
+await scenario.given(
+  'buys an apple',
+  'buysAnApple',
+  { qty: 1 },
+  { actor: actors.shopper }
+)
+// reporter renders: Given the shopper buys 1 apples   ✓  412ms
+```
+
+Rules that bite:
+
+- **The step is referenced by its typed string name, not by importing the const** — exactly like `workflow.do`. The name is the step's `pikkuFuncId` and is checked against the generated step map. A non-literal target is a critical error (`PKU678`).
+- **Steps are not RPCs.** They are deliberately never network-callable — a browser-driving step must not be.
+- **`actor.invoke` is typed over the exposed RPC map**, so the name and the payload are checked and the result comes back narrowed — no cast. `actor.invokeRaw(name, data, { headers })` is the same call reporting `{ status, ok, body }` instead of throwing; use it whenever the refusal *is* the assertion.
+- **`actor` and `env` are optional on the wire**, because a pure assertion step needs neither. Narrow them with `requireActor(scenarioStep)` and `requireScenarioEnv(scenarioStep)` from `@pikku/core/workflow` rather than a local guard — both name the step and say what to pass. `env` is `{ apiUrl, appUrl? }` from the environment the run targets, and is how a raw-HTTP step learns the target's URL: a step runs in the CLI process, where there is no `variables` service and `process.env` is not the answer.
+- **Steps default to `retries: 0`**, unlike ordinary workflow steps. Retrying a failed assertion is wrong; pass `retries` explicitly if a step is genuinely flaky-by-nature.
+- **Step results are persisted**, so return JSON-serialisable data — never a `Locator` or a client object.
+- **`description` documents the step; `template` is what the report renders.** `template`'s `{placeholders}` are filled from the input the step was called with, so one step reads differently for each call — `sees {state} addon {packageName}` reports as "sees available addon @pikku/addon-stripe". Reflect every input field in the template, and type the values so they read as words (`state?: 'installed' | 'available'`, not `installed?: boolean`). A placeholder with no value renders as nothing and the whitespace collapses.
+- Prose precedence is `options.description` → the step's `template` → the step's own `description` → the positional step name. Repeated names get `#1`, `#2` ordinals, so a `for` loop over a data set is how you write a Scenario Outline. A loop-generated step name is not statically known, so it is matched back to its declaration by step function instead — which works as long as that function's call sites agree on their phase, actor and prose. Two call sites that disagree make the loop step report under its bare runtime name.
+
+### Browser steps
+
+A step declaring `browser: true` gets `wire.browser` — a session bound to **its actor**, signed in through the same `signInPath` + `SCENARIO_ACTOR_SECRET` path the HTTP actors use, so the browser and the RPC calls are one identity. Calling such a step without an actor is a critical error (`PKU677`).
+
+```typescript
+export const opensTheCart = pikkuScenarioStep<
+  { path: string },
+  { url: string },
+  true
+>({
+  name: 'opensTheCart',
+  description: 'opens the cart',
+  browser: true,
+  func: async (_services, { path }, { browser }) => {
+    await browser.goto(path)
+    return { url: browser.page.url() }
+  },
+})
+```
+
+- Install `@pikku/playwright` and `@playwright/test`, and import `@pikku/playwright` once (`import type {} from '@pikku/playwright'`) so `browser.page` is a typed Playwright `Page`. Without it you still get the structural `goto`/`screenshot` handle.
+- The environment needs an `appUrl` beside its `apiUrl`. `pikku scenario run` fails fast before running anything if a browser scenario has no `appUrl` or the driver is not installed.
+- `pikku scenario run <env> --no-browser` **skips** scenarios containing browser steps and reports them as skipped — it does not fail them. That is how a machine with no browser stays green.
+- Playwright auto-waits; do not wrap `page.click` in `expectEventually`.
 
 ## Configuration
 
-Actors and environments live in `pikku.config.json`:
+Personas, actors and environments live in `pikku.config.json`:
 
 ```json
 {
   "scenarios": {
+    "personas": {
+      "shopper": { "description": "Buys things here", "primary": true },
+      "support": { "description": "Answers for the shop", "proficiency": "power" },
+      "reminders": { "description": "The shop chasing abandoned carts", "kind": "system" }
+    },
     "actors": {
       "shopper": {
         "email": "shopper@actors.local",
@@ -109,7 +252,7 @@ Actors and environments live in `pikku.config.json`:
         "jobTitle": "First-time buyer",
         "personality": "Impatient shopper who abandons slow checkouts"
       },
-      "support": { "email": "support@actors.local", "name": "Support" }
+      "shopperB": { "persona": "shopper", "email": "shopper-b@actors.local" }
     },
     "environments": {
       "local": {
@@ -121,23 +264,37 @@ Actors and environments live in `pikku.config.json`:
 }
 ```
 
+### Personas and actors
+
+A **persona** is a kind of person; an **actor** is one body that signs in as one. Above, `support` is declared only as a persona — its actor is materialised (`support@actors.local`), so `actors.support` works without an `actors` entry. Write an actor by hand only when you need something the materialised one wouldn't have:
+
+- a **real email or personality** for it, like `shopper`;
+- a **second body of the same persona**, like `shopperB` — which is what tenant isolation, peer sharing, and "another member's row" scenarios are made of. Two actors of one persona must be two different users, so **two actors sharing an email is an error**.
+
+A persona holds only what is true of that kind of person for the app's whole lifetime — `description`, `primary` (whose experience the product is), `kind`, `proficiency`. What someone is trying to get done, and the circumstances they are doing it in, belong to the **scenario**, not to them.
+
+`kind: "system"` is the app acting on its own — a schedule, a cleanup, a send. It gets **no actor**: there is nobody to sign in. Give it one by hand only if it genuinely has a service account.
+
+An actor with no `persona` is its own persona, so a project that never declares any keeps working unchanged.
+
 - `environments.<name>.apiUrl` is required. `signInPath` defaults to `/auth/sign-in/actor`, `rpcPath` to `/rpc`.
 - **`SCENARIO_ACTOR_SECRET` is an environment variable and never goes in `pikku.config.json`.** It signs actors in. `pikku scenario run` throws without it; a server auto-building actors warns and runs without them.
 
 ## Running
 
 ```bash
-pikku scenario list                       # name [tags] + description; takes no options
+pikku scenario list                       # features with their scenarios indented, then ungrouped scenarios
 SCENARIO_ACTOR_SECRET=… pikku scenario run local
 SCENARIO_ACTOR_SECRET=… pikku scenario run local --flows orderSupportScenario
+SCENARIO_ACTOR_SECRET=… pikku scenario run local --features credentialFeature
 SCENARIO_ACTOR_SECRET=… pikku scenario run local --tags smoke,scenario
 ```
 
-`run` takes the environment as a **required positional** — the key from `scenarios.environments`. `--flows`/`-f` filters by scenario name, `--tags`/`-t` by tag (match-any).
+`run` takes the environment as a **required positional** — the key from `scenarios.environments`. `--flows`/`-f` filters by scenario name, `--features` by feature id, `--tags`/`-t` by tag (match-any). Every filter narrows the same plan, so narrowing a feature to two of its five scenarios still runs the feature's hooks exactly once around those two.
 
-Output is `PASS <name> (<ms>) → <output>` / `FAIL <name> (<ms>): <error>`, then `N/M scenarios passed against '<env>'`.
+Output is `PASS <name> (<ms>) → <output>` / `FAIL <name> (<ms>): <error>`, then `N/M scenarios passed against '<env>'`. A scenario inside a feature is named `<Feature> › <scenario> <data>`.
 
-**Exit code is 1** if any scenario fails *or* if no scenario matched the filter — a typo'd `--flows` is a hard error, not a silent zero-run pass. It throws outright on an unknown environment, an unknown flow name, or a missing `SCENARIO_ACTOR_SECRET`.
+**Exit code is 1** if any scenario fails _or_ if no scenario matched the filter — a typo'd `--flows` is a hard error, not a silent zero-run pass. It throws outright on an unknown environment, an unknown flow name, or a missing `SCENARIO_ACTOR_SECRET`.
 
 ## Coverage
 
@@ -160,7 +317,15 @@ SCENARIO_ACTOR_SECRET=… pikku scenario run local --coverage
 The run resets coverage before each scenario and snapshots after, writing **`<outDir>/coverage/scenario-coverage.json`**:
 
 ```jsonc
-{ "generatedAt": "…", "environment": "local", "scenarios": { "<name>": { /* FunctionCoverageReport */ } } }
+{
+  "generatedAt": "…",
+  "environment": "local",
+  "scenarios": {
+    "<name>": {
+      /* FunctionCoverageReport */
+    },
+  },
+}
 ```
 
 Coverage is best-effort: it disables itself with a warning if the server is not collecting or the first actor cannot invoke, and it needs at least one configured actor. If you get no coverage, check those first.
@@ -184,7 +349,9 @@ import assert from 'node:assert'
 
 describe('createTodo', () => {
   test('creates a todo', async () => {
-    const services = { todoStore: { add: async (title: string) => ({ id: '1', title }) } }
+    const services = {
+      todoStore: { add: async (title: string) => ({ id: '1', title }) },
+    }
     const result = await createTodo.func(services as any, { title: 'Buy milk' })
     assert.equal(result.title, 'Buy milk')
   })
@@ -199,16 +366,16 @@ Services are plain objects — a Pikku function is pure business logic, so a moc
 
 ## Red flags
 
-| Smell | Why it's wrong |
-| --- | --- |
-| `pikku tests …` | Removed in #865. Use `pikku scenario`. |
-| `.feature` files / Gherkin for function tests | Scenarios are TypeScript, not Gherkin. The in-process cucumber function world was deleted. |
-| `scenario.do(...)` with no `{ actor }` | Throws. Every step runs as somebody. |
-| A scenario per function | Scenarios are user flows. One flow covers many functions; that is the point. |
-| Assuming a clean database | There is no state reset — it may be a staging server. Scope what you create. |
-| `sleep()` before asserting | Use `expectEventually`. |
-| `expectEventually` in a `pikkuWorkflowFunc` | `PKU675` — scenario-only. |
-| Coverage silently 0 | Server not run with `--coverage`, `verboseMeta` off, `scaffold.scenarios` unset, or no actors configured. |
+| Smell                                         | Why it's wrong                                                                                            |
+| --------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `pikku tests …`                               | Removed in #865. Use `pikku scenario`.                                                                    |
+| `.feature` files / Gherkin for function tests | Scenarios are TypeScript, not Gherkin. The in-process cucumber function world was deleted.                |
+| `scenario.do(...)` with no `{ actor }`        | Throws. Every step runs as somebody.                                                                      |
+| A scenario per function                       | Scenarios are user flows. One flow covers many functions; that is the point.                              |
+| Assuming a clean database                     | There is no state reset — it may be a staging server. Scope what you create.                              |
+| `sleep()` before asserting                    | Use `expectEventually`.                                                                                   |
+| `expectEventually` in a `pikkuWorkflowFunc`   | `PKU675` — scenario-only.                                                                                 |
+| Coverage silently 0                           | Server not run with `--coverage`, `verboseMeta` off, `scaffold.scenarios` unset, or no actors configured. |
 
 `@pikku/cucumber` is a **browser/e2e** harness (`Actor`, `BrowserWorld`, `PersonaData`, `DbUtils`) — out of scope here.