Project flows & local QA templates

Flows and templates resolve from your open project, not from the @sitelensapi/mcp package install path.

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.

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.