Project flows & local QA templates

Flows and templates resolve from your open project, not from the @sitelensapi/mcp package install path. Canonical automation lives beside your code: .sitelens/flows/*.json and .sitelens/scenarios/*.json.

How the pieces fit

Flow — a reusable sequence of browser steps (clicks, fills, assertions, network checks). Stored as .sitelens/flows/{id}.json.
Scenario — chains one or more flows (often with parameters) for a multi-step journey. Stored as .sitelens/scenarios/{id}.json.
Profile — saved auth / session state a flow or scenario can reuse.
Recorded flow — a flow authored via Playwright Codegen (Desktop Record Flow, CLI, or MCP). After conversion it is a normal SiteLens flow — not a second-class format.

Desktop’s Automation workspace discovers and visualizes these same files. CLI and agents run them through the same contracts.

Project flows

Add JSON under your project:

.sitelens/flows/my-flow.json

Run with MCP tool sitelens_run_local_flow (up to 200 steps — assertions, network waits, screenshots):

{
  "flowId": "my-flow",
  "url": "http://127.0.0.1:3000/"
}

Optional authProfile when the flow needs a saved session. flowId maps to .sitelens/flows/{flowId}.json.

Example flow file

{
  "version": 1,
  "id": "example-homepage-smoke",
  "name": "Example — homepage smoke",
  "url": "https://example.com/",
  "viewports": ["desktop"],
  "screenshot": true,
  "exportArtifacts": true,
  "readySelector": "body",
  "steps": [
    { "type": "assertSelector", "selector": "body", "state": "visible" },
    { "type": "assertText", "text": "Example Domain" },
    { "type": "screenshot", "label": "final-state" }
  ]
}

No hand-written *.spec.ts test file required — SiteLens executes the declarative steps.

Record with Playwright Codegen

Author flows from a headed recorder — Desktop Record Flow, CLI sitelens flow codegen, or MCP sitelens_flow_codegen_* (start / status / finalize / cancel / convert). Playwright-generated behavior is converted into SiteLens flow JSON with an explicit complete / partial status — SiteLens does not silently discard constructs it cannot represent; partial saves require opt-in. After conversion, save under .sitelens/flows/ and treat it like any other flow: edit, run, and inspect with Browser Intelligence evidence.

sitelens flow codegen --flow-id login-recorded \
  --url http://localhost:3000/login \
  --browser chromium --save

Product surfaces: Desktop Record Flow, MCP Codegen.

Expected HTTP status

Assert the HTTP response you actually expect — including intentional 4xx and 5xx responses. When expect.status matches, that network assertion passes; the real status stays in evidence. This is step-level behavior and does not suppress independent policies such as failOn4xx or expectNoFailedRequests.

{
  "type": "request",
  "url": "**/api/example",
  "method": "POST",
  "expect": { "status": 500 }
}

{
  "type": "expectNetwork",
  "urlPattern": "**/api/item",
  "method": "GET",
  "expect": { "status": [400, 404] }
}

Also supported on waitForResponse. Do not combine expect.status with statusMin/statusMax (or minStatus/maxStatus). Existing range fields remain backward compatible when expect.status is omitted.

Screenshot checkpoints (evidence collection)

Add labeled screenshot steps during flows — especially for auth, forms, and multi-step investigations. PNGs land under {artifactDir}/screenshots/ and paths return in actionLog[].screenshot and summary.screenshotPaths.

{ "type": "screenshot", "label": "before-submit" }
{ "type": "screenshot", "label": "after-submit" }
{ "type": "screenshot", "label": "after-login" }
{ "type": "screenshot", "label": "final-state" }

Scaffold flows with checkpoints: sitelens flow init login-smoke --template login or --template form-submit. Legacy JSON may use { "action": "screenshot", "label": "…" }.

selectOption

Use selectOption when working with native <select> dropdowns, especially when options are hard to click visually or hidden by browser styling. Custom JavaScript dropdowns should still use click / press steps.

{
  "type": "selectOption",
  "selector": "select[name='status']",
  "value": "active"
}

Provide exactly one of value, label, or index. The selector must resolve to a native <select> element.

Tier 1 interactions

Target with exactly one of selector, testId, label, or role+name: check, uncheck, setChecked (requires checked boolean), clear, hover, and doubleClick (supports allowSubmit like click).

{ "type": "setChecked", "testId": "remember", "checked": true }
{ "type": "hover", "selector": ".menu-trigger" }

Tier 2 interactions

Safe named actions only: uploadFile (native input[type=file] + files paths), dragTo (source and target endpoint objects), focus, blur, and scrollIntoView.

{ "type": "uploadFile", "testId": "csv-upload", "files": ["/tmp/data.csv"] }
{
  "type": "dragTo",
  "source": { "selector": ".card" },
  "target": { "selector": ".drop-zone" }
}
{ "type": "scrollIntoView", "role": "button", "name": "Submit" }

Browser storage

Safe localStorage / sessionStorage steps for authenticated workflows — no arbitrary JavaScript (evaluate / js are not supported). Mutations apply to the active page (no reload). actionLog[].storage records storage type, operation, keys affected, and page URL.

{ "type": "storage.set", "storage": "session", "key": "environmentConfig", "value": "{\"env\":\"qa\"}" }
{ "type": "storage.remove", "storage": "session", "keys": ["environmentConfig", "spoofContext"] }
{ "type": "storage.clear", "storage": "local" }
{ "type": "storage.assert", "storage": "session", "key": "environmentConfig", "exists": false }

Smoke flow in repo: .sitelens/flows/storage-smoke.json.

Local QA templates (adhoc runs)

For sitelens_qa_run / sitelens_run_local_qa, pass template to apply built-in presets (console/network/screenshot defaults):

homepage-qa — console + network + screenshot
mobile-layout-qa — same defaults, mobile-oriented naming
basic-smoke — console + screenshot, lighter network checks

{
  "url": "http://localhost:3000/",
  "template": "basic-smoke",
  "viewports": ["desktop", "mobile"]
}

Ad-hoc actions / scenario steps are capped at 8 — use sitelens_run_local_flow for longer smoke paths, or Scenario Runner to chain multiple flows in a shared browser session.

Workflow verification (Scenario Runner)

For authenticated applications and multi-step user journeys, define scenarios under .sitelens/scenarios/ that chain reusable flows with saved auth profiles and parameterized test data. See the full Scenario Runner guide.

sitelens run scenario workflow-verification-scenario \\
  --profile qa-user \\
  --param baseUrl=http://localhost:3000 \\
  --param workflowId=workflow-01

Workspace resolution

MCP uses SITELENS_WORKSPACE_DIR, CURSOR_PROJECT_DIR, or process.cwd(). Call sitelens_status or run npx -y @sitelensapi/mcp sitelens doctor to see the detected flows directory.