Skip to content

Latest commit

 

History

History
134 lines (114 loc) · 7.2 KB

3-engine.md

File metadata and controls

134 lines (114 loc) · 7.2 KB

Engine — execute a scenario in Chromium and record it

Issue: #3 · Phase 1 · Decisions: ADR-0003, ADR-0004, ADR-0008

Depends on #1 Depends on #2

Summary

@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.

Scope

In scope

  • packages/engine (@demoflow/engine), ESM, Node, Vitest; dependencies @demoflow/core, playwright (pinned exactly); dev dependency @demoflow/fixture so turbo builds the fixture before the tests.
  • runScenario(scenario, options): Promise<RunOutcome> — options: runDir, baseUrl, allowedOrigins, env (for valueFrom), 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 from valueFrom: { 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.

Out of scope

  • Rendering (#4), CLI and home resolution (#5), starting a dev server (devCommand is Phase 2).

Decisions

  • Run directory layout (written by the engine, read by renderers): source.webm, timeline.json, screenshots/<name>.png, scenario.json (the validated scenario with valueFrom kept 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 as runDir.
  • Real mouse movement (ADR-0004 §2): before click and hover, move to the target's centre with mouse.move(x, y, { steps }), steps = clamp(round(distance / 12), 8, 40); the timeline records pointer.from and pointer.to. The starting pointer is the viewport centre.
  • Typing is real: fill types with pressSequentially at 35 ms per character, so the recording shows typing; a masked value is typed the same way and its timeline value is ***.
  • Origin guard before the browser starts and on every navigate: the resolved URL's origin must be in allowedOrigins; otherwise stage readiness fails with origin-not-allowed and 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; execution or verification is failed (an assertion that ran and did not hold is verification; a locator that timed out is execution); the video is still closed and saved, so recording is passed.
  • rendering is left pending in the engine's result.json; the renderer updates it.

Acceptance criteria

  • bun run --filter @demoflow/engine test passes under Node on Linux in Woodpecker, using the fixture served on an ephemeral port by the test itself (never a fixed port).
  • customers.demo.json produces a playable source.webm, a timeline.json valid against @demoflow/core, and result.json with status: running overall (rendering pending), execution and verification passed.
  • Every click/hover event has pointer.from, pointer.to and a target box; the box of the "Create" button in the timeline matches boundingBox() at click time within 1 px.
  • login.demo.json with FIXTURE_PASSWORD set: the timeline value is ***, the event is masked: true, and the password string appears in no file of the run directory.
  • login.demo.json without FIXTURE_PASSWORD: readiness fails with missing-env FIXTURE_PASSWORD before the browser starts.
  • failing.demo.json: verification failed with the step index and message, steps after it absent from the timeline, video saved.
  • A scenario navigating to https://example.com with allowedOrigins: ["http://localhost:<port>"] fails readiness with origin-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 hover step of tour.demo.json.
  • Woodpecker's test step runs the engine tests on the rebuilt CI image.

Parallel plan

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.

Contention

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

Risks

  • 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 own playwright (bunx playwright install --with-deps chromium after bun install, in the pipeline), not a separately pinned one, and caches PLAYWRIGHT_BROWSERS_PATH under /ci-cache.
  • Windows path handling (medium): verified by #6, not here.