Acceptance‑Test‑Driven Demo Handoff: One‑Page Spec to Guarantee Playable, Billable Demos

Treat the handoff spec as executable intent, not narrative. The page contains three minimal, precise artifacts: (1) 3–6 Playwright acceptance tests that describe user journeys (including a microcheckout path), (2) an OpenAPI fragment that defines the API endpoints the demo will call and the mock responses you expect, and (3) a Figma frame called the “demo slice” with annotated interactive states. Contractors implement until those tests pass and the Figma slice is visually matched.

This format forces alignment because each artifact answers a different question: Playwright answers “does the flow work end‑to‑end?”, OpenAPI answers “what data looks like and what errors look like?”, and Figma answers “what the UI must look and behave like.” When combined on one page, they eliminate vague acceptance criteria and let you verify both UX and billing behavior programmatically.

Write acceptance tests before a line of front‑end code. Each test should be short, deterministic, and focused on the business outcome you care about for the demo: landing → product selection → microcheckout (test both success and safe‑failure flows). Use Playwright’s test runner and fixtures to target the exact DOM selectors you’ve exported from the Figma demo slice or from your component naming convention.

Keep tests stable by mocking slow or external dependencies via the OpenAPI stub described on the same page. Tests should assert two things: the demo is playable (flows complete without JS errors) and the demo demonstrates the correct billing contract (microcheckout returns the expected pricing/receipt fields). When these tests are the acceptance gate, contractors must make the demo pass to claim “done.”

Include an OpenAPI fragment on the spec page that defines only the endpoints the demo touches (price lookup, cart, create‑intent, confirm, webhooks). The fragment should include example requests and full example responses for success, validation error, and a simulated declined payment. A mock server can be generated directly from the fragment so the Playwright tests always hit the same deterministic responses.

This makes the demo safe to demo publicly and lets contractors implement “billing” without touching production payment systems. The OpenAPI stub is the single source of truth for what the front end expects from pricing and receipt fields and how to handle edge cases—so the delivered demo behaves identically to your billing contract assumptions.

Prepare a single Figma frame labeled Demo Slice. It should contain the minimal screens/states the Playwright tests will exercise and include annotated component names and the exact copy used in the demo. Use Dev Mode or equivalent to mark what is “Ready for Dev” and export a tiny assets bundle. This slice is the visual truth that developers reference while implementing the DOM structure and ARIA attributes Playwright will assert.

Because designers and contractors share the same tiny canonical slice, visual regressions are easy to spot. When the Playwright tests and OpenAPI mock pass but the rendered UI diverges from the Figma slice, the spec is still failing—so visual fidelity becomes part of acceptance instead of a post‑hoc talk.

Embed the one‑page spec in your project brief (AppWispr customers often use a single spec page in their tasks). Require contractors to: (a) wire the front end to the generated OpenAPI mock, (b) implement the UI to match the Figma demo slice, and (c) deliver green Playwright runs for the specified scenarios. Acceptance is the green test run plus a recording of a manual smoke check and a short note describing how webhooks or receipts are stubbed.

This workflow reduces multiple revision cycles. Because acceptance is automated, you can approve implementations the moment tests pass and the demo’s microcheckout returns the expected receipt fields—preventing accidental billing exposure and saving time for founders and product teams.