feat(testing-framework): POC — Gherkin + JS dual front-end flow-IR with reusable prompt flows

[ScriptedAlchemy]

What is this?

A POC that lets you write UI tests as plain-English Gherkin (Given / When / Then) with no step-definition code at all — the AI executes each step directly. It builds on the v2 testing-framework from #2589.

Classic Cucumber needs a JS function registered for every step. Here, the steps are the prompts:

Scenario: Checkout as admin
  When I run the "Login" flow with role "admin"
  And I remember the price of the "Trail Backpack" product as "price"
  When I add the "Trail Backpack" to the cart and open the cart
  Then the cart total equals {price}

• When steps → the Midscene UI agent acts on the page (aiAct)
• Then steps → a general agent judges a fail-closed verdict from the screenshot
• I remember ... as "price" → extracts a value into a variable table; {price} is substituted into later prompts mechanically — the model never sees a placeholder
• I run the "Login" flow → calls a reusable, parameterized prompt flow (own scope, declared args/returns, optional once-per-run memoization) — the answer to chaining prompts across complex multi-step journeys

Three interchangeable authoring styles, one engine

All three compile to the same internal flow-IR and run identically (the demo proves trace-for-trace parity). Decision rule: you probably only need style 1. Plain .feature files run end-to-end with nothing else — styles 2 and 3 are an alternative and an optional escape hatch, never requirements.

Style	For whom	What it looks like
1. Pure Gherkin	non-engineers, living docs — fully sufficient on its own	.feature files only, end to end
2. Pure JS/TS	engineering-owned suites wanting loops/types/computed args	defineFlow() / scenario() builders
3. Gherkin + overlay (optional escape hatch)	only when Gherkin is the contract AND a few scenarios need programmatic exceptions: bind-time computed values (dates/env-derived data), env-specific tweaks without forking the feature file (skip in CI, verify→soft, inserted steps)	.feature stays the source of truth; a sparse JS overlay patches anchored steps, drift caught at bind time so the prose↔JS seam can't silently rot

The example/ directory has one folder per style, each laid out as a realistic multi-file suite (shared flows reused by separate cart/checkout test modules) — see example/README.md.

Try it (no API key needed)

pnpm --filter @midscene/testing-framework demo            # offline, scripted agents, narrated walkthrough
pnpm --filter @midscene/testing-framework demo -- --live  # real browser + model via `codex login` (codex app-server)

The offline demo narrates every resolved prompt, variable capture, flow call, and verdict, then diffs the three styles against each other.

Status / validation

• 119+ unit tests (fake agents — no model/browser), package build, repo lint: all green
• Live run verified end-to-end on gpt-5.5 via Midscene's codex://app-server provider
• Design notes and open questions: packages/testing-framework/POC-GHERKIN.md

Feedback wanted

• Is the flow-call composition model (explicit args/returns, fresh scope, depth cap) the right reuse semantics?
• Which style(s) should graduate into the v2 framework proper?
• Naming: step conventions like I remember ... as "var" and I run the "X" flow with ...

[cloudflare-workers-and-pages]

Deploying midscene with    Cloudflare Pages

Latest commit:	4b1a261
Status:	✅  Deploy successful!
Preview URL:	https://e535d003.midscene.pages.dev
Branch Preview URL:	https://poc-gherkin-ai-flows.midscene.pages.dev

View logs

[ScriptedAlchemy]

Closing in favor of a fresh implementation: the POC validated the concept (AI-executed Gherkin, reusable prompt flows, three routing modes), and the follow-up design session concluded we should build it as a new standalone package — @midscene/bdd — that embeds real cucumber-js instead of extending packages/testing-framework. New PR to follow from feat/midscene-bdd. Branch kept for reference.