diff --git a/apps/cli/test/commands/render.spec.ts b/apps/cli/test/commands/render.spec.ts index acd19c53..2a0e8cef 100644 --- a/apps/cli/test/commands/render.spec.ts +++ b/apps/cli/test/commands/render.spec.ts @@ -216,7 +216,7 @@ describe('demoflow render', () => { expect(d.plans[0]?.options.formats).toEqual(['mp4', 'webm']); expect(d.plans[0]?.options.output?.fps).toBe(24); // The default end hold, as `demoflow run` recorded it (spec 365). - expect(d.plans[0]?.options.endHoldMs).toBe(2500); + expect(d.plans[0]?.options.endHoldMs).toBe(3500); expect(io.err).toContain('Rendering\n'); expect(io.out).toContain(RUN_ID); const written = await readResultFile(); diff --git a/apps/fixture/demoflow/customers-repeat.demo.json b/apps/fixture/demoflow/customers-repeat.demo.json index 020edbf9..3818518b 100644 --- a/apps/fixture/demoflow/customers-repeat.demo.json +++ b/apps/fixture/demoflow/customers-repeat.demo.json @@ -12,6 +12,7 @@ { "name": "Ken Thompson", "email": "ken@example.com" } ] }, + "pacing": { "stepDwellMs": 250, "typingDelayMs": 20 }, "steps": [ { "action": "navigate", "path": "/customers" }, { diff --git a/apps/web/src/app/docs/config/page.mdx b/apps/web/src/app/docs/config/page.mdx index 5a7802f7..8b5d56f3 100644 --- a/apps/web/src/app/docs/config/page.mdx +++ b/apps/web/src/app/docs/config/page.mdx @@ -104,7 +104,7 @@ Every `render` key is optional. These are the defaults: | `fps` | 30 | Frames per second. | | `idle.thresholdMs` | 1000 | A still stretch longer than this is shortened. | | `idle.compressToMs` | 400 | …to this long. | -| `endHoldMs` | 2500 | How long a successful video stays on screen after the last step, 0 to 10000 ms. The run records it, so a result that shows late is in the video. A failed run ends at the failure. To hold after any step, see [`hold`](/docs/scenarios#hold). | +| `endHoldMs` | 3500 | How long a successful video stays on screen after the last step, 0 to 10000 ms. The run records it, so a result that shows late is in the video. A failed run ends at the failure. To hold after any step, see [`hold`](/docs/scenarios#hold). | | `frame` | on | See below. | | `background` | `{ "preset": "ocean" }` | See below. | | `cards` | see below | Intro, scene and outro cards. | diff --git a/apps/web/src/app/docs/scenarios/page.mdx b/apps/web/src/app/docs/scenarios/page.mdx index d774690c..ff055509 100644 --- a/apps/web/src/app/docs/scenarios/page.mdx +++ b/apps/web/src/app/docs/scenarios/page.mdx @@ -82,7 +82,7 @@ Every step has an `action`. Every step may also carry a `caption`, a | `navigate` | Opens a page. | exactly one of `path` (starts with a single `/`) or `url` | | `waitFor` | Waits for an element. | `target`, `state` (`visible` by default, or `hidden`) | | `click` | Clicks an element. | `target` | -| `fill` | Types into a field. | `target`, exactly one of `value` or `valueFrom` | +| `fill` | Types into a field. | `target`, exactly one of `value` or `valueFrom`; optional `typingDelayMs` | | `select` | Picks an option of a select. | `target`, `option` | | `hover` | Moves the pointer over an element. | `target` | | `press` | Presses a key or a chord, such as `Enter` or `Control+a`. | `key`, optional `target` | @@ -129,11 +129,48 @@ steps that have a target, `waitFor` for a hidden element excepted, and on } ``` +### Pacing + +A recording plays slowly enough to follow. After each visible step +(`navigate`, `click`, `hover`, `fill`, `select`, `press`, `scroll`, +`assertVisible`, `assertText`) the video stays on the result for a moment +before the next step, and a `fill` types one character at a time. + +The top-level `pacing` object sets this for the whole scenario. Every field is +optional and has a default: + +| Field | Default | Range | What it does | +|---|---|---|---| +| `stepDwellMs` | 1000 | 0 to 10000 | Pause after each visible step. `0` turns it off. | +| `typingDelayMs` | 80 | 0 to 500 | Pause between two typed characters of a `fill`. | + +A step overrides the scenario's pacing for itself: [`hold`](#hold) (0 to 10000) +on any step replaces the dwell, and `typingDelayMs` (0 to 500) on a `fill`. A +`hold` also adds a pause after a step that has none by default, such as a +`marker`. The last step does not dwell unless it sets `hold`; the end hold +follows it. The end hold is [`render.endHoldMs`](/docs/config#render), 3500 ms +by default. + +```json +{ + "pacing": { "stepDwellMs": 700, "typingDelayMs": 60 }, + "steps": [ + { "action": "fill", "target": { "label": "Title" }, "value": "Hello", "typingDelayMs": 120 }, + { "action": "click", "target": { "role": "button", "name": "Publish" }, "hold": 2000 }, + { "action": "assertVisible", "target": { "text": "Hello" } } + ] +} +``` + +A `wait` still pauses on top of the dwell. Pacing never slows down +[setup and off-camera steps](#off-camera-steps), and a check run +(`demoflow run --check`) neither dwells nor holds the end. + ### hold -`hold` keeps the page on screen after the step, for 100 to 10000 ms. The run +`hold` keeps the page on screen after the step, for 0 to 10000 ms. The run waits that long once the step is done, and the video plays the whole hold at -real speed: the [idle trim](/docs/config#render) never shortens it. A step that +real speed: the [idle trim](/docs/config#render) never shortens it. `0` turns the dwell off. A step that fails does not hold. `hold` is refused on an off-camera step (`"record": false`). @@ -159,7 +196,7 @@ The outline is drawn where the element was when the assertion passed, so hold an element that has stopped moving. Every successful video also ends on its last frame for -[`render.endHoldMs`](/docs/config#render) (2500 ms by default), after the last +[`render.endHoldMs`](/docs/config#render) (3500 ms by default), after the last step's own `hold`. ### Scene markers diff --git a/packages/core/schemas/fragment.schema.json b/packages/core/schemas/fragment.schema.json index 3325c5d6..4a833034 100644 --- a/packages/core/schemas/fragment.schema.json +++ b/packages/core/schemas/fragment.schema.json @@ -86,9 +86,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -246,9 +246,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -393,9 +393,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -531,6 +531,12 @@ "required": ["env"], "additionalProperties": false }, + "typingDelayMs": { + "description": "Milliseconds between two typed characters of this fill; overrides pacing.typingDelayMs.", + "type": "integer", + "minimum": 0, + "maximum": 500 + }, "caption": { "type": "string", "maxLength": 120 @@ -546,9 +552,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -696,9 +702,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -835,9 +841,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -985,9 +991,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -1212,9 +1218,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -1359,9 +1365,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -1515,9 +1521,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -1569,9 +1575,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -1628,9 +1634,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -1675,9 +1681,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -1729,9 +1735,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, diff --git a/packages/core/schemas/project-config.schema.json b/packages/core/schemas/project-config.schema.json index b24af05e..0e231ee2 100644 --- a/packages/core/schemas/project-config.schema.json +++ b/packages/core/schemas/project-config.schema.json @@ -100,7 +100,7 @@ "additionalProperties": false }, "endHoldMs": { - "default": 2500, + "default": 3500, "description": "How long a successful video keeps the result on screen after the last step: the engine keeps recording and the renderer keeps the frames. 0 ends the video at the last step.", "type": "integer", "minimum": 0, diff --git a/packages/core/schemas/scenario.schema.json b/packages/core/schemas/scenario.schema.json index 4359cefb..11ebd951 100644 --- a/packages/core/schemas/scenario.schema.json +++ b/packages/core/schemas/scenario.schema.json @@ -73,6 +73,27 @@ } } }, + "pacing": { + "type": "object", + "properties": { + "stepDwellMs": { + "default": 1000, + "description": "Milliseconds the recording stays on the result of each visible step (navigate, click, hover, fill, select, press, scroll, assertVisible, assertText) before the next one. A step overrides it with hold; 0 turns it off.", + "type": "integer", + "minimum": 0, + "maximum": 10000 + }, + "typingDelayMs": { + "default": 80, + "description": "Milliseconds between two typed characters of a fill. A fill overrides it with typingDelayMs.", + "type": "integer", + "minimum": 0, + "maximum": 500 + } + }, + "additionalProperties": false, + "description": "How fast the recording plays. Every field has a default; setup and off-camera steps are not paced." + }, "setup": { "description": "Steps that run off camera before the recording starts, such as signing in: an include of a fragment, or plain steps. The recording starts in the same browser storage (cookies, localStorage), on the page setup ended on.", "minItems": 1, @@ -111,9 +132,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -263,9 +284,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -410,9 +431,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -548,6 +569,12 @@ "required": ["env"], "additionalProperties": false }, + "typingDelayMs": { + "description": "Milliseconds between two typed characters of this fill; overrides pacing.typingDelayMs.", + "type": "integer", + "minimum": 0, + "maximum": 500 + }, "caption": { "type": "string", "maxLength": 120 @@ -563,9 +590,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -713,9 +740,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -852,9 +879,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -994,9 +1021,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -1213,9 +1240,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -1360,9 +1387,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -1508,9 +1535,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -1554,9 +1581,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -1605,9 +1632,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -1652,9 +1679,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -1698,9 +1725,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -1790,9 +1817,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -1942,9 +1969,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -2089,9 +2116,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -2227,6 +2254,12 @@ "required": ["env"], "additionalProperties": false }, + "typingDelayMs": { + "description": "Milliseconds between two typed characters of this fill; overrides pacing.typingDelayMs.", + "type": "integer", + "minimum": 0, + "maximum": 500 + }, "caption": { "type": "string", "maxLength": 120 @@ -2242,9 +2275,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -2392,9 +2425,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -2531,9 +2564,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -2673,9 +2706,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -2892,9 +2925,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -3039,9 +3072,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -3187,9 +3220,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -3233,9 +3266,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -3284,9 +3317,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -3331,9 +3364,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -3377,9 +3410,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -3466,9 +3499,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -3626,9 +3659,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -3773,9 +3806,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -3911,6 +3944,12 @@ "required": ["env"], "additionalProperties": false }, + "typingDelayMs": { + "description": "Milliseconds between two typed characters of this fill; overrides pacing.typingDelayMs.", + "type": "integer", + "minimum": 0, + "maximum": 500 + }, "caption": { "type": "string", "maxLength": 120 @@ -3926,9 +3965,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -4076,9 +4115,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -4215,9 +4254,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -4365,9 +4404,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -4592,9 +4631,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -4739,9 +4778,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -4895,9 +4934,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -4949,9 +4988,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -5008,9 +5047,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -5055,9 +5094,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, @@ -5109,9 +5148,9 @@ "type": "boolean" }, "hold": { - "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.", + "description": "Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.", "type": "integer", - "minimum": 100, + "minimum": 0, "maximum": 10000 } }, diff --git a/packages/core/src/project-config.ts b/packages/core/src/project-config.ts index d6097813..d557bbee 100644 --- a/packages/core/src/project-config.ts +++ b/packages/core/src/project-config.ts @@ -203,7 +203,7 @@ export const RenderConfigSchema = z }) .prefault({}), // Kept on screen after the last step of a successful run (spec 365). - endHoldMs: z.number().int().min(0).max(10_000).default(2500).meta({ + endHoldMs: z.number().int().min(0).max(10_000).default(3500).meta({ description: 'How long a successful video keeps the result on screen after the last step: the engine keeps recording and the renderer keeps the frames. 0 ends the video at the last step.', }), diff --git a/packages/core/src/scenario.ts b/packages/core/src/scenario.ts index 7838f580..166d5633 100644 --- a/packages/core/src/scenario.ts +++ b/packages/core/src/scenario.ts @@ -5,7 +5,13 @@ import { NonEmptyStringSchema, ViewportSchema, } from './common.ts'; -import { DataKeySchema, ScenarioStepSchema, SetupStepSchema } from './step.ts'; +import { + DataKeySchema, + DwellMsSchema, + ScenarioStepSchema, + SetupStepSchema, + TypingDelayMsSchema, +} from './step.ts'; /** One item of a data list: the fields a `repeat` substitutes. */ export const DataItemSchema = z.record( @@ -39,6 +45,41 @@ export const DEFAULT_VIEWPORTS: Record< phone: { width: 412, height: 914 }, }; +/** How fast the recorded steps play when a scenario sets no `pacing` (C-203). */ +export const DEFAULT_PACING = { + stepDwellMs: 1_000, + typingDelayMs: 80, +} as const; + +/** + * How fast a recording plays (C-203): a pause after each visible step and the + * typing speed (the final frame is held by `render.endHoldMs`). Setup and off-camera steps are not + * paced. + */ +export const PacingSchema = z + .strictObject({ + stepDwellMs: DwellMsSchema.default(DEFAULT_PACING.stepDwellMs).meta({ + description: + 'Milliseconds the recording stays on the result of each visible step (navigate, click, hover, fill, select, press, scroll, assertVisible, assertText) before the next one. A step overrides it with hold; 0 turns it off.', + }), + typingDelayMs: TypingDelayMsSchema.default( + DEFAULT_PACING.typingDelayMs, + ).meta({ + description: + 'Milliseconds between two typed characters of a fill. A fill overrides it with typingDelayMs.', + }), + }) + .meta({ + description: + 'How fast the recording plays. Every field has a default; setup and off-camera steps are not paced.', + }); +export type Pacing = z.infer; + +/** The scenario's pacing with every default filled in. */ +export function resolvePacing(pacing: Partial | undefined): Pacing { + return { ...DEFAULT_PACING, ...pacing }; +} + /** A scenario file, `demoflow/**\/*.demo.json` (ADR-0003). */ export const ScenarioSchema = z .strictObject({ @@ -54,6 +95,7 @@ export const ScenarioSchema = z }), viewport: ViewportSchema.optional(), data: ScenarioDataSchema.optional(), + pacing: PacingSchema.optional(), setup: z .array(SetupStepSchema) .min(1, 'expected at least one step') diff --git a/packages/core/src/step.ts b/packages/core/src/step.ts index 2124ccc7..eb2ee5f1 100644 --- a/packages/core/src/step.ts +++ b/packages/core/src/step.ts @@ -38,14 +38,20 @@ export const RecordSchema = z.boolean().optional().meta({ 'false runs the step off camera: before the recording starts, in the same browser storage (cookies, localStorage). Only the opening steps of a scenario may be off camera; the video starts on the first recorded step.', }); +/** How long the video stays on a step's result before the next step (C-203). */ +export const DwellMsSchema = z.number().int().min(0).max(10_000); + +/** How long a `fill` waits between two typed characters (C-203). */ +export const TypingDelayMsSchema = z.number().int().min(0).max(500); + /** Fields every step may carry. */ const common = { caption: z.string().max(120).optional(), timeoutMs: z.number().int().min(100).max(60_000).default(10_000), record: RecordSchema, - hold: z.number().int().min(100).max(10_000).optional().meta({ + hold: DwellMsSchema.optional().meta({ description: - 'Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Not on an off-camera step.', + 'Milliseconds to keep the page on screen after the step, recorded and never trimmed as idle. Use it, not wait, to show a result. Overrides pacing.stepDwellMs; 0 turns the dwell off. Not on an off-camera step.', }), }; @@ -256,6 +262,10 @@ function stepSchema(mode: M) { ...zoom, value: z.string().optional(), valueFrom: z.strictObject({ env: EnvNameSchema }).optional(), + typingDelayMs: TypingDelayMsSchema.optional().meta({ + description: + 'Milliseconds between two typed characters of this fill; overrides pacing.typingDelayMs.', + }), }) .superRefine(exactlyOne(fillKeys)) .meta(exactlyOneJsonSchema(fillKeys)), diff --git a/packages/core/test/project-config.spec.ts b/packages/core/test/project-config.spec.ts index b1517484..977fcb81 100644 --- a/packages/core/test/project-config.spec.ts +++ b/packages/core/test/project-config.spec.ts @@ -16,7 +16,7 @@ describe('parseProjectConfig', () => { height: 1080, fps: 30, idle: { thresholdMs: 1000, compressToMs: 400 }, - endHoldMs: 2500, + endHoldMs: 3500, frame: { enabled: true, marginRatio: 0.06, radius: 12, shadow: true }, background: { preset: 'ocean' }, cards: { diff --git a/packages/core/test/scenario.spec.ts b/packages/core/test/scenario.spec.ts index 06506451..7d3739fc 100644 --- a/packages/core/test/scenario.spec.ts +++ b/packages/core/test/scenario.spec.ts @@ -1,5 +1,10 @@ import { describe, expect, it } from 'vitest'; -import { type Issue, parseScenario, type StepAction } from '../src/index.ts'; +import { + type Issue, + parseScenario, + resolvePacing, + type StepAction, +} from '../src/index.ts'; function scenario(...steps: unknown[]) { return { schemaVersion: 1, name: 'Demo', steps }; @@ -377,7 +382,7 @@ describe('parseScenario — every action', () => { }); }); - it.each([99, 10_001, 500.5])('rejects hold %d at steps[0].hold', (hold) => { + it.each([-1, 10_001, 500.5])('rejects hold %d at steps[0].hold', (hold) => { expect(errorsOf(scenario({ action, ...valid, hold }))).toContainEqual( expect.objectContaining({ path: 'steps[0].hold' }), ); @@ -636,3 +641,64 @@ describe('parseScenario — scenario', () => { ]); }); }); + +describe('parseScenario — pacing', () => { + const click = { action: 'click', target }; + + it('leaves pacing to the defaults when the scenario sets none', () => { + const result = parseScenario(scenario(click)); + if (!result.ok) throw new Error('expected the scenario to parse'); + expect(result.value.pacing).toBeUndefined(); + expect(resolvePacing(result.value.pacing)).toEqual({ + stepDwellMs: 1_000, + typingDelayMs: 80, + }); + }); + + it('fills in the fields a partial pacing leaves out', () => { + const result = parseScenario({ + ...scenario(click), + pacing: { stepDwellMs: 0 }, + }); + expect(result).toMatchObject({ + ok: true, + value: { + pacing: { stepDwellMs: 0, typingDelayMs: 80 }, + }, + }); + }); + + it('accepts a hold (0 turns the dwell off) on any step and a typing delay on a fill', () => { + const result = parseScenario( + scenario( + { ...click, hold: 0 }, + { action: 'marker', title: 'Intro', hold: 2_000 }, + { action: 'fill', target, value: 'Ada', typingDelayMs: 120 }, + ), + ); + expect(result).toMatchObject({ + ok: true, + value: { + steps: [{ hold: 0 }, { hold: 2_000 }, { typingDelayMs: 120 }], + }, + }); + }); + + it('rejects out-of-range and misplaced pacing', () => { + expect( + errorsOf({ ...scenario(click), pacing: { stepDwellMs: -1 } }), + ).toEqual([expect.objectContaining({ path: 'pacing.stepDwellMs' })]); + expect( + errorsOf({ ...scenario(click), pacing: { endHoldMs: 1_000 } }), + ).toEqual([expect.objectContaining({ path: 'pacing.endHoldMs' })]); + expect( + errorsOf({ ...scenario(click), pacing: { typingDelayMs: 1.5 } }), + ).toEqual([expect.objectContaining({ path: 'pacing.typingDelayMs' })]); + expect(errorsOf({ ...scenario(click), pacing: { speed: 2 } })).toEqual([ + expect.objectContaining({ path: 'pacing.speed' }), + ]); + expect(errorsOf(scenario({ ...click, typingDelayMs: 50 }))).toEqual([ + expect.objectContaining({ path: 'steps[0].typingDelayMs' }), + ]); + }); +}); diff --git a/packages/engine/src/execute/actions.ts b/packages/engine/src/execute/actions.ts index 88ddb66a..719ca6f2 100644 --- a/packages/engine/src/execute/actions.ts +++ b/packages/engine/src/execute/actions.ts @@ -1,6 +1,7 @@ import { setTimeout as sleep } from 'node:timers/promises'; import { type Box, + DEFAULT_PACING, type Locator, MASKED_VALUE, type Step, @@ -19,8 +20,8 @@ import { } from './readiness.ts'; import { waitForReady } from './ready.ts'; -/** Spec 3: the recording shows typing, one character every 35 ms. */ -export const TYPING_DELAY_MS = 35; +/** The recording shows typing, one character every 80 ms unless the scenario's pacing says otherwise (C-203). */ +export const TYPING_DELAY_MS = DEFAULT_PACING.typingDelayMs; /** A scroll waits on animation frames; this bounds one wait if the page stops producing them. */ const SCROLL_FRAME_FALLBACK_MS = 100; @@ -55,6 +56,8 @@ export interface StepContext { /** Where the real pointer is; actions that move it update it. */ pointer: Point; observers: readonly EngineObserver[]; + /** Milliseconds between two characters a `fill` types. */ + typingDelayMs: number; } /** The fields of a step's timeline event the action itself knows. */ @@ -130,7 +133,7 @@ export async function runAction( if (!masked) { await target.fill('', { timeout: step.timeoutMs }); const box = await measure(target); - await type(target, value, step.timeoutMs); + await type(target, value, step.timeoutMs, ctx.typingDelayMs); return { ...withBox(box), value }; } // #42: a failure part-way leaves typed characters on screen, so the @@ -139,7 +142,7 @@ export async function runAction( try { await target.fill('', { timeout: step.timeoutMs }); box = await measure(target); - await type(target, value, step.timeoutMs); + await type(target, value, step.timeoutMs, ctx.typingDelayMs); } catch (error) { box ??= await measure(target); throw maskedFailure(error, withBox(box)); @@ -207,10 +210,11 @@ async function type( target: PlaywrightLocator, value: string, timeoutMs: number, + delayMs: number, ): Promise { await target.pressSequentially(value, { - delay: TYPING_DELAY_MS, - timeout: timeoutMs + value.length * TYPING_DELAY_MS, + delay: delayMs, + timeout: timeoutMs + value.length * delayMs, }); } diff --git a/packages/engine/src/execute/pacing.ts b/packages/engine/src/execute/pacing.ts new file mode 100644 index 00000000..91247140 --- /dev/null +++ b/packages/engine/src/execute/pacing.ts @@ -0,0 +1,48 @@ +import type { Pacing, Step, StepAction } from '@demoflow/core'; + +/** Steps whose result the viewer sees: the default dwell follows them (C-203). */ +export const DWELL_ACTIONS: ReadonlySet = new Set([ + 'navigate', + 'click', + 'hover', + 'fill', + 'select', + 'press', + 'scroll', + 'assertVisible', + 'assertText', +]); + +/** How one step is paced. */ +export interface StepPace { + /** Held on camera after the step succeeds (the step's `hold`), before the next one starts. */ + dwellMs: number; + /** Between two characters a `fill` types. */ + typingDelayMs: number; +} + +export interface PaceMode { + /** The step is on camera: off-camera steps (setup) are never slowed down. */ + onCamera: boolean; + /** The run records a video; a check run (ADR-0021) has nothing to watch. */ + recording: boolean; + /** The last step: `render.endHoldMs` follows it instead of the default dwell. */ + last: boolean; +} + +/** + * The pace of one step (C-203). A step's own `hold` and `typingDelayMs` + * win over the scenario's pacing; off camera only an explicit typing delay + * applies, and nothing dwells. + */ +export function stepPace(step: Step, pacing: Pacing, mode: PaceMode): StepPace { + const ownTyping = step.action === 'fill' ? step.typingDelayMs : undefined; + const typingDelayMs = ownTyping ?? (mode.onCamera ? pacing.typingDelayMs : 0); + if (!mode.onCamera) return { dwellMs: 0, typingDelayMs }; + const dwellMs = + step.hold ?? + (!mode.recording || mode.last || !DWELL_ACTIONS.has(step.action) + ? 0 + : pacing.stepDwellMs); + return { dwellMs, typingDelayMs }; +} diff --git a/packages/engine/src/run.ts b/packages/engine/src/run.ts index ecf48044..8f426a51 100644 --- a/packages/engine/src/run.ts +++ b/packages/engine/src/run.ts @@ -8,6 +8,8 @@ import { type MaskedElement, type Navigation, offCameraSteps, + type Pacing, + resolvePacing, type Scenario, type Stage, type Stages, @@ -33,6 +35,7 @@ import { MarkedMasks } from './execute/marked-masks.ts'; import { MaskTracker } from './execute/mask.ts'; import { NavigationRecorder } from './execute/navigations.ts'; import type { EngineObserver, RunOutcome } from './execute/observer.ts'; +import { stepPace } from './execute/pacing.ts'; import { installPageScripts } from './execute/page-scripts.ts'; import { type Point, viewportCentre } from './execute/pointer.ts'; import { @@ -96,6 +99,7 @@ export async function runScenario( const stages = pendingStages(); const recording = recordingOptions(scenario, options.runDir); const baseUrl = scenario.baseUrl ?? options.baseUrl; + const pacing = resolvePacing(scenario.pacing); await mkdir(options.runDir, { recursive: true }); await emit('onRunStarted', { @@ -145,10 +149,14 @@ export async function runScenario( session: Session, range: { from: number; to: number; endHoldMs?: number }, events: TimelineEvent[], + onCamera: boolean, ): Promise => executeSteps({ steps, ...range, + pacing, + onCamera, + recording: record, page: session.page, clock: session.clock, baseUrl, @@ -176,7 +184,12 @@ export async function runScenario( }), }); const offEvents: TimelineEvent[] = []; - const failure = await execute(off, { from: 0, to: hidden }, offEvents); + const failure = await execute( + off, + { from: 0, to: hidden }, + offEvents, + false, + ); if (failure === undefined) { start = { storageState: await off.context.storageState(), @@ -222,6 +235,7 @@ export async function runScenario( session, { from: hidden, to: steps.length, endHoldMs: options.endHoldMs }, events, + true, ); // Before the context closes: a document's clock exchange may still be running on it. const maskedElements = await marked.list(); @@ -347,6 +361,11 @@ interface ExecuteInput { steps: readonly ExpandedStep[]; from: number; to: number; + pacing: Pacing; + /** Off-camera steps (ADR-0018) are not paced. */ + onCamera: boolean; + /** Whether the run records a video: a check run does not dwell. */ + recording: boolean; page: Page; clock: Clock; baseUrl: string | undefined; @@ -396,8 +415,14 @@ async function executeSteps(input: ExecuteInput): Promise { input.annotations.stepStarted(startMs); await emit('onStepStarted', { stepIndex, step, startMs }); + const pace = stepPace(step, input.pacing, { + onCamera: input.onCamera, + recording: input.recording, + last: stepIndex === input.to - 1, + }); const ctx = { page: input.page, + typingDelayMs: pace.typingDelayMs, stepIndex, baseUrl: input.baseUrl, guard: input.guard, @@ -458,13 +483,9 @@ async function executeSteps(input: ExecuteInput): Promise { await input.masks.track(event, step.target); } // A failed step does not hold; an off-camera one has nothing to show. - if ( - failure === undefined && - step.hold !== undefined && - step.record !== false - ) { - event.holdMs = step.hold; - const left = await hold(step.hold); + if (failure === undefined && pace.dwellMs > 0) { + event.holdMs = pace.dwellMs; + const left = await hold(pace.dwellMs); if (left !== undefined) { failure = new StepFailure('execution', originNotAllowed(left)); event.error = { message: scrub(failure.message) }; diff --git a/packages/engine/test/execute/pacing.spec.ts b/packages/engine/test/execute/pacing.spec.ts new file mode 100644 index 00000000..057ed432 --- /dev/null +++ b/packages/engine/test/execute/pacing.spec.ts @@ -0,0 +1,289 @@ +import { mkdtemp, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; +import { + resolvePacing, + type Step, + type StepInput, + StepSchema, +} from '@demoflow/core'; +import { afterAll, beforeAll, describe, expect, it } from 'vitest'; +import { stepPace } from '../../src/execute/pacing.ts'; +import { + type EngineObserver, + type RunOptions, + runScenario, +} from '../../src/index.ts'; +import { + type FixtureServer, + SIGN_IN_PATH, + startFixtureServer, +} from './fixture-server.ts'; +import { scenario } from './scenario.ts'; + +function step(input: StepInput): Step { + return StepSchema.parse(input); +} + +const onCamera = { onCamera: true, recording: true, last: false }; +const defaults = resolvePacing(undefined); + +describe('stepPace', () => { + it('dwells after a visible step and types at the default speed', () => { + expect(defaults).toEqual({ + stepDwellMs: 1_000, + typingDelayMs: 80, + }); + for (const input of [ + { action: 'navigate', path: '/' }, + { action: 'click', target: { text: 'Go' } }, + { action: 'fill', target: { label: 'Name' }, value: 'Ada' }, + { action: 'select', target: { label: 'Size' }, option: 'L' }, + { action: 'press', key: 'Enter' }, + { action: 'assertVisible', target: { text: 'Done' } }, + ] as const) { + expect(stepPace(step(input), defaults, onCamera)).toEqual({ + dwellMs: 1_000, + typingDelayMs: 80, + }); + } + }); + + it('does not dwell after a step with nothing new to see', () => { + for (const input of [ + { action: 'wait', ms: 500 }, + { action: 'marker', title: 'Scene' }, + { action: 'waitFor', target: { text: 'Done' } }, + { action: 'waitForReady', name: 'list' }, + { action: 'screenshot', name: 'shot' }, + ] as const) { + expect(stepPace(step(input), defaults, onCamera).dwellMs).toBe(0); + } + }); + + it('takes the scenario pacing, and a step overrides it', () => { + const pacing = resolvePacing({ stepDwellMs: 300, typingDelayMs: 20 }); + expect(pacing.typingDelayMs).toBe(20); + const fill = { + action: 'fill', + target: { label: 'Name' }, + value: 'Ada', + } as const; + expect(stepPace(step(fill), pacing, onCamera)).toEqual({ + dwellMs: 300, + typingDelayMs: 20, + }); + expect( + stepPace( + step({ ...fill, hold: 2_000, typingDelayMs: 150 }), + pacing, + onCamera, + ), + ).toEqual({ dwellMs: 2_000, typingDelayMs: 150 }); + // 0 turns the dwell off; a marker may ask for one. + expect(stepPace(step({ ...fill, hold: 0 }), pacing, onCamera)).toEqual({ + dwellMs: 0, + typingDelayMs: 20, + }); + expect( + stepPace( + step({ action: 'marker', title: 'Scene', hold: 800 }), + pacing, + onCamera, + ).dwellMs, + ).toBe(800); + }); + + it('leaves the default dwell off the last step: the end hold follows it', () => { + const click = step({ action: 'click', target: { text: 'Go' } }); + const last = { ...onCamera, last: true }; + expect(stepPace(click, defaults, last).dwellMs).toBe(0); + expect( + stepPace({ ...click, hold: 500 } as Step, defaults, last).dwellMs, + ).toBe(500); + }); + + it('does not slow down off-camera steps or a check run', () => { + const fill = step({ + action: 'fill', + target: { label: 'Name' }, + value: 'Ada', + hold: 2_000, + }); + expect(stepPace(fill, defaults, { ...onCamera, onCamera: false })).toEqual({ + dwellMs: 0, + typingDelayMs: 0, + }); + expect( + stepPace({ ...fill, typingDelayMs: 50 } as Step, defaults, { + ...onCamera, + onCamera: false, + }).typingDelayMs, + ).toBe(50); + // A check run adds no default dwell; a step's own hold still applies. + const plain = { ...fill, hold: undefined } as Step; + expect( + stepPace(plain, defaults, { ...onCamera, recording: false }), + ).toEqual({ dwellMs: 0, typingDelayMs: 80 }); + }); +}); + +let fixture: FixtureServer; +const runDirs: string[] = []; + +beforeAll(async () => { + fixture = await startFixtureServer(); +}); + +afterAll(async () => { + await fixture.close(); + await Promise.all( + runDirs.map((dir) => rm(dir, { recursive: true, force: true })), + ); +}); + +async function options(extra: Partial = {}): Promise { + const runDir = await mkdtemp(path.join(tmpdir(), 'demoflow-engine-')); + runDirs.push(runDir); + return { + runDir, + baseUrl: fixture.origin, + allowedOrigins: [fixture.origin], + env: {}, + ...extra, + }; +} + +/** When the last step finished and when the run did, in wall-clock ms. */ +function endWatch(): { + observer: EngineObserver; + times: { lastStepMs?: number; finishedMs?: number }; +} { + const times: { lastStepMs?: number; finishedMs?: number } = {}; + return { + times, + observer: { + onStepFinished() { + times.lastStepMs = Date.now(); + }, + onRunFinished() { + times.finishedMs = Date.now(); + }, + }, + }; +} + +const fillPassword = { + action: 'fill', + target: { label: 'Password' }, + value: 'abc', +} as const; + +describe('a paced run', () => { + it('dwells after each visible step, then holds the final frame', async () => { + const { observer, times } = endWatch(); + const outcome = await runScenario( + scenario( + [ + { action: 'navigate', path: '/login' }, + fillPassword, + { action: 'wait', ms: 200 }, + { ...fillPassword, hold: 0 }, + { action: 'marker', title: 'Done' }, + ], + { pacing: { stepDwellMs: 400, typingDelayMs: 50 } }, + ), + await options({ observers: [observer], endHoldMs: 700 }), + ); + expect(outcome.stages.execution.status).toBe('passed'); + const [navigate, fill, wait, refill, marker] = outcome.events; + expect(navigate?.holdMs).toBe(400); + expect(fill?.holdMs).toBe(400); + expect(wait?.holdMs).toBeUndefined(); + expect(refill?.holdMs).toBeUndefined(); + expect(marker?.holdMs).toBeUndefined(); + // The next step starts after the dwell, and an explicit wait adds to it. + expect( + (fill?.startMs ?? 0) - (navigate?.endMs ?? 0), + ).toBeGreaterThanOrEqual(400); + expect((refill?.startMs ?? 0) - (fill?.endMs ?? 0)).toBeGreaterThanOrEqual( + 600, + ); + // Three characters at 50 ms: two gaps between them at least. + expect((fill?.endMs ?? 0) - (fill?.startMs ?? 0)).toBeGreaterThanOrEqual( + 100, + ); + expect( + (times.finishedMs ?? 0) - (times.lastStepMs ?? 0), + ).toBeGreaterThanOrEqual(700); + }); + + it('does not slow down setup steps', async () => { + // Wall-clock ms between the end of setup step 0 and the start of step 1. + let finished0: number | undefined; + let gapMs: number | undefined; + const observer: EngineObserver = { + onStepFinished({ stepIndex }) { + if (stepIndex === 0) finished0 = Date.now(); + }, + onStepStarted({ stepIndex }) { + if (stepIndex === 1 && finished0 !== undefined) { + gapMs = Date.now() - finished0; + } + }, + }; + const outcome = await runScenario( + scenario([fillPassword], { + setup: [ + { action: 'navigate', path: SIGN_IN_PATH }, + { action: 'navigate', path: '/login' }, + ], + pacing: { stepDwellMs: 5_000 }, + }), + await options({ observers: [observer] }), + ); + expect(outcome.stages.execution.status).toBe('passed'); + expect(gapMs).toBeDefined(); + expect(gapMs ?? Infinity).toBeLessThan(2_000); + }); + + it('neither dwells nor holds in a check run', async () => { + const outcome = await runScenario( + scenario([{ action: 'navigate', path: '/login' }, fillPassword], { + pacing: { stepDwellMs: 5_000 }, + }), + await options({ record: false, endHoldMs: 0 }), + ); + expect(outcome.stages.execution.status).toBe('passed'); + expect(outcome.events.every((event) => event.holdMs === undefined)).toBe( + true, + ); + // Two 5 s dwells would take 10 s. + expect( + Date.parse(outcome.finishedAt) - Date.parse(outcome.startedAt), + ).toBeLessThan(8_000); + }); + + it('does not hold the end of a failed run', async () => { + const { observer, times } = endWatch(); + const outcome = await runScenario( + scenario( + [ + { action: 'navigate', path: '/login' }, + { + action: 'click', + target: { role: 'button', name: 'No such button' }, + timeoutMs: 300, + }, + ], + { pacing: { stepDwellMs: 0 } }, + ), + await options({ observers: [observer], endHoldMs: 5_000 }), + ); + expect(outcome.status).toBe('failed'); + expect(outcome.events.at(-1)?.holdMs).toBeUndefined(); + expect((times.finishedMs ?? 0) - (times.lastStepMs ?? 0)).toBeLessThan( + 5_000, + ); + }); +}); diff --git a/packages/engine/test/execute/scenario.ts b/packages/engine/test/execute/scenario.ts index 0cf68453..986411a9 100644 --- a/packages/engine/test/execute/scenario.ts +++ b/packages/engine/test/execute/scenario.ts @@ -5,7 +5,10 @@ import { type ScenarioStepInput, } from '@demoflow/core'; -/** An inline scenario, validated and with defaults applied. */ +/** + * An inline scenario, validated and with defaults applied. It does not dwell + * unless `pacing` says so (C-203), to keep the suite fast. + */ export function scenario( steps: ScenarioStepInput[], extra: { @@ -13,12 +16,14 @@ export function scenario( viewport?: { width: number; height: number }; data?: ScenarioInput['data']; setup?: ScenarioInput['setup']; + pacing?: ScenarioInput['pacing']; } = {}, ): Scenario { const parsed = parseScenario({ schemaVersion: 1, name: 'inline', viewport: { width: 1280, height: 720 }, + pacing: { stepDwellMs: 0 }, ...extra, steps, }); diff --git a/packages/renderer/test/plan/fixture-runs.ts b/packages/renderer/test/plan/fixture-runs.ts index f3e88124..5fd431fb 100644 --- a/packages/renderer/test/plan/fixture-runs.ts +++ b/packages/renderer/test/plan/fixture-runs.ts @@ -60,6 +60,13 @@ export async function recordFixtureRun( ); } +/** + * The pacing these runs record with unless the scenario sets its own: no + * dwell and 35 ms typing, the timing the plan tests were written against. + * Pacing itself is tested in the engine (C-203). + */ +const TEST_PACING = { stepDwellMs: 0, typingDelayMs: 35 } as const; + /** * Records a scenario given inline — validated as a scenario file is — against * the fixture, into `/`, and returns that run directory. @@ -72,7 +79,11 @@ export async function recordInlineRun( observers: readonly EngineObserver[] = [], endHoldMs = 0, ): Promise { - const parsed = parseScenario(input); + const parsed = parseScenario( + typeof input === 'object' && input !== null && !('pacing' in input) + ? { ...input, pacing: TEST_PACING } + : input, + ); if (!parsed.ok) throw new Error(JSON.stringify(parsed.errors)); const runDir = path.join(parentDir, name);