/playwright-storybook-flows

name: playwright-storybook-flows
description: >-
  Specialization of playwright-harness for AUTHORING and REPRODUCING flows. A
  flow is a sequence of steps a human or an agent can take inside an
  application to demonstrate a specific feature; it is written as a Storybook
  docs page in a conventional location, where a human reads it as a manual
  walkthrough (issue reproduction, QA) and an agent driving Playwright reads it
  as an executable rubric (integration testing). Use when the task is "record a
  flow", "author a flow doc", "write repro steps as a flow", "reproduce the
  flow in Storybook", or "turn a manual walkthrough into something an agent can
  re-drive". Read playwright-harness FIRST for all browser execution; this
  skill never re-documents Playwright.

Storybook Flows: specialization of playwright-harness

**Read `playwright-harness` first.** This skill contains no Playwright instruction and never will: all browser execution, screenshots, waits, and assertions belong to `playwright-harness`. When a flow's evidence needs to land on a PR, that is `prove-work-on-github`; when a captured image needs shrinking, that is `asset-optimization`. This skill points to those seams and documents exactly one thing: **how to record human/machine shared steps for running a flow.**

> **Status: being authored.** Definitions, step properties, the visualization > spec, and the storage convention are locked; the authoring and reproduction > loops are still being dictated and validated. Nothing in here is > project-specific: the target Storybook is always parameterized > (`STORYBOOK_URL`), and flow locations are conventions, not paths into any one > repo.

What a flow is

A **flow** is a sequence of steps that a human or an agent can take inside an application to demonstrate a specific feature.

The same document serves both readers. A human reads it as a walkthrough; an agent reads it as an executable rubric and reproduces it later on its own. If either reader would need a second document, the flow is miswritten.

Flows earn their keep in two situations:

• **Issue reproduction.** An issue arrives whose reproduction requires a series

of steps; the flow illustrates and preserves those steps.

• **Integration testing.** A series of steps worth testing repeatedly is

encapsulated as a flow, and an agent drives it.

Self-containment (the transportability rule)

Flows do not reference other flows. Every flow is internally consistent, internally self-contained, and therefore transportable.

During authorship it is fine for a flow to be *described* in terms of another flow ("log in, then..."); the referenced steps are then **inlined** into the new flow. If a detailed authentication flow exists and a new flow begins with "log in", the authentication steps are copied into the new flow, not linked. Assume the person or agent executing a flow has no knowledge of any other flow.

The single exception is a **precondition** (below): required starting state may name another flow; steps never do.

Preconditions (required starting state)

A flow may require a certain state to have already taken place before step 1, in the manner of a Cucumber scenario outline: "if you are already logged in, then perform the flow."

**In this context only, a flow may reference another flow** as the way to reach the required state. The precondition names the state and the flow that establishes it; it is not a step, and it is not inlined. Steps inside the flow body still never reference other flows.

The final state

Every flow ends in **success** or **failure**, and every flow must define its final success state. Completing all steps in sequence, including the last one, with no problems and no errors thrown, is success. Without a defined success state neither an integration test nor a QA tester can know the flow completed; with one, the flow is a pass/fail instrument.

Steps

A flow consists of steps. A step is complete only when it has all of the following properties:

1. **A number.** Steps are numbered and execute in sequence. 2. **A title.** Short and succinct: "Log in", "Click button". 3. **A description.** A short account of the action being taken. 4. **A route.** The route the step takes place on, as a clickable link (described below). 5. **A visualization.** The most important property, described below.

Routes and the base URL

Flows take place inside a web application, so every flow is on some route, and the flow records it. The route appears at the flow level as well, beyond the scenario outline, not only on individual steps.

Routes are recorded as **clickable links**, and they resolve against a configured base:

• **A configuration sits at the root of the flows folder** and declares the

default base URL for flows, pointing at the QA server or the development server. There must be a default test root URL for flows.

• **Routes in flow documents are authored relative to that base.** If the

configuration says the default flow base is `www.my-qa-server.com/testers`, every route described while authoring is relative to it, and the rendered links point into that server.

• **Runners substitute the base.** When an agent runs a flow locally, it

replaces the base URL and drives the same relative routes against the local server.

• **A flow may override the base.** If a flow is authored against a specific

environment (reproducing something that happens in production, say), the author states that during authoring; the override is written into the flow document itself and all of its clickable links resolve against the override instead of the default.

<!-- stub: the concrete shape of the flows-root configuration file gets locked during first real authoring, then recorded here. -->

The visualization

A visualization is, ideally, an **actual inline component**: the real component rendered in the flow document, not a description of it. Flows are MDX files in Storybook,