Issue: #3 · Phase 1 · Decisions: ADR-0003, ADR-0004, ADR-0008
Depends on #1 Depends on #2
@demoflow/engine takes a validated scenario and produces everything a
renderer needs: the source video, timeline.json, screenshots and a
result.json with each stage's status. It drives Chromium through
Playwright, moves the real mouse, verifies every assertion, masks secrets in
the timeline, and refuses origins outside the project's allowlist. It also
gives Woodpecker's CI image what browser tests need.
packages/engine(@demoflow/engine), ESM, Node, Vitest; dependencies@demoflow/core,playwright(pinned exactly); dev dependency@demoflow/fixtureso turbo builds the fixture before the tests.runScenario(scenario, options): Promise<RunOutcome>— options:runDir,baseUrl,allowedOrigins,env(forvalueFrom),headless(default true),observers.- Scenarios for the fixture app in
apps/fixture/demoflow/:customers.demo.json(search, create through the dialog, assert the new row),login.demo.json(password fromvalueFrom: { env: "FIXTURE_PASSWORD" }),tour.demo.json(hover, long scroll, container scroll,/slow, markers and a screenshot),failing.demo.json(asserts a text that is not there). - The CI image gains Chromium's system libraries, the Playwright Chromium build and FFmpeg.
- Rendering (#4), CLI and home resolution (#5), starting a dev server
(
devCommandis Phase 2).
- Run directory layout (written by the engine, read by renderers):
source.webm,timeline.json,screenshots/<name>.png,scenario.json(the validated scenario withvalueFromkept and no resolved values),result.json.render/is left to the renderer. - Run id:
YYYYMMDD-HHmmss-<6 lowercase base32 chars>, UTC — sortable and readable. Generated by the caller, passed asrunDir. - Real mouse movement (ADR-0004 §2): before
clickandhover, move to the target's centre withmouse.move(x, y, { steps }),steps = clamp(round(distance / 12), 8, 40); the timeline recordspointer.fromandpointer.to. The starting pointer is the viewport centre. - Typing is real:
filltypes withpressSequentiallyat 35 ms per character, so the recording shows typing; a masked value is typed the same way and its timelinevalueis***. - Origin guard before the browser starts and on every
navigate: the resolved URL's origin must be inallowedOrigins; otherwise stagereadinessfails withorigin-not-allowedand nothing is launched. - Video time base: event times are measured from the moment the page is
created (Playwright starts the video with the page), using
performance.now()deltas in the engine process. - Failure: the first failed step stops execution; later steps are not
run;
executionorverificationisfailed(an assertion that ran and did not hold isverification; a locator that timed out isexecution); the video is still closed and saved, sorecordingispassed. renderingis leftpendingin the engine'sresult.json; the renderer updates it.
-
bun run --filter @demoflow/engine testpasses under Node on Linux in Woodpecker, using the fixture served on an ephemeral port by the test itself (never a fixed port). -
customers.demo.jsonproduces a playablesource.webm, atimeline.jsonvalid against@demoflow/core, andresult.jsonwithstatus: runningoverall (rendering pending),executionandverificationpassed. - Every
click/hoverevent haspointer.from,pointer.toand a target box; the box of the "Create" button in the timeline matchesboundingBox()at click time within 1 px. -
login.demo.jsonwithFIXTURE_PASSWORDset: the timeline value is***, the event ismasked: true, and the password string appears in no file of the run directory. -
login.demo.jsonwithoutFIXTURE_PASSWORD:readinessfails withmissing-env FIXTURE_PASSWORDbefore the browser starts. -
failing.demo.json:verificationfailedwith the step index and message, steps after it absent from the timeline, video saved. - A scenario navigating to
https://example.comwithallowedOrigins: ["http://localhost:<port>"]failsreadinesswithorigin-not-allowed, and no browser process is started (asserted by an observer that records the launch). - The hover tooltip "Details" is visible in a screenshot taken right after
the
hoverstep oftour.demo.json. - Woodpecker's
teststep runs the engine tests on the rebuilt CI image.
| Slot | Owns | Touches | Depends on | Lead | Model |
|---|---|---|---|---|---|
| i3-ci-image | Chromium and FFmpeg in the CI image | deploy/ci-image/, .woodpecker/ | — | no | sonnet |
| i3-executor | the package, runScenario, locators, actions, mouse, origin guard, observer interface |
packages/engine/package.json, packages/engine/src/run.ts, packages/engine/src/index.ts, packages/engine/src/execute/, packages/engine/test/execute/, packages/engine/vitest.config.ts, packages/engine/tsconfig.json, bun.lock | i3-ci-image | yes | opus |
| i3-capture | video setup, timeline writer, screenshots, run-directory layout, result.json |
packages/engine/src/capture/, packages/engine/test/capture/, apps/fixture/demoflow/** | i3-executor | no | sonnet |
i3-executor defines EngineObserver (step started/finished, page
created, browser launched) and the RecordingOptions it passes to
browser.newContext; i3-capture implements an observer and exports it,
so it never edits run.ts or index.ts — the executor's barrel re-exports
./capture/index.js from the start, with a stub the capture slot replaces.
| Resource | Owner | Everyone else |
|---|---|---|
| packages/engine/package.json, bun.lock | i3-executor | i3-capture adds no dependency |
| packages/engine/src/index.ts | i3-executor | do not open |
| packages/engine/src/capture/index.ts | i3-capture (the executor creates the stub) | — |
| .woodpecker/pipeline.yml, deploy/ci-image/Dockerfile | i3-ci-image | do not open |
- Playwright video and event clocks drift (high). The video has no
timestamps of its own; the engine's clock starts at page creation.
Mitigation: a test clicks a button that changes the page colour and checks
with FFmpeg that the colour change is within 2 frames of the event's
endMs. If not, the spike (#4) must correct with an offset. - Chromium on the CI image (medium): the Playwright version in the image
must match
packages/engine's pin. Mitigation: the image installs browsers with the repository's ownplaywright(bunx playwright install --with-deps chromiumafterbun install, in the pipeline), not a separately pinned one, and cachesPLAYWRIGHT_BROWSERS_PATHunder/ci-cache. - Windows path handling (medium): verified by #6, not here.