MCP guides · SiteLens QA

Scenario Runner & workflow verification

Most browser QA tools stop at a page. Real applications require setup. Scenario Runner chains reusable flows in one shared browser session—saved auth profiles, parameterized test data, and multi-step workflow verification for authenticated applications.

Flows vs scenarios

Flow

A single QA flow targeting one page or a short step sequence. Lives under .sitelens/flows/{flowId}.json. Run with sitelens_run_local_flow.

Scenario

Setup and orchestration of one or more flows in a shared session. Lives under .sitelens/scenarios/{scenarioId}.json. Run with sitelens_run_local_scenario or sitelens run scenario.

Scenario Runner chain

Chain reusable flows together using one browser session:

1
Login

Reuse a saved auth profile (profile) or run a login setup flow.

2
Initialize state

Select test data, toggle features, or seed application state.

3
Open workflow

Navigate to the route or feature under test.

4
Perform actions

Click, fill, and interact across multi-step journeys.

5
Verify outcome

Assert UI state, capture labeled screenshot checkpoints, and export artifacts.

Project layout

your-app-repo/
  .sitelens/
    flows/
      auth-login-setup.json
      select-test-data.json
      feature-toggle.json
      verify-admin-panel.json
    scenarios/
      workflow-verification-scenario.json
      login-then-smoke-scenario.json

Auth profiles live under ~/.sitelens/profiles/ and ~/.sitelens/auth/—not in the repo. See login-once auth.

Example scenario

{
  "version": 1,
  "id": "workflow-verification-scenario",
  "name": "Workflow Verification Scenario",
  "profile": "qa-user",
  "params": {
    "baseUrl": "http://localhost:3000",
    "workflowId": "workflow-01"
  },
  "viewports": ["desktop"],
  "screenshot": true,
  "flows": [
    {
      "flow": "select-test-data",
      "with": { "url": "{{baseUrl}}/admin/data?select={{workflowId}}" }
    },
    {
      "flow": "feature-toggle",
      "with": { "url": "{{baseUrl}}/admin/features?workflow={{workflowId}}&flag=preview" }
    },
    {
      "flow": "verify-admin-panel",
      "with": { "url": "{{baseUrl}}/admin/dashboard" }
    }
  ]
}

Screenshot checkpoints

Example flows under .sitelens/flows/ include labeled screenshot steps for evidence collection — e.g. before-submit, after-submit, after-login, final-state. Each flow in a scenario exports its own artifact folder; read actionLog[].screenshot.path and screenshotPaths from the combined JSON output. 

{ "type": "screenshot", "label": "after-login" }

Agents: keep exportArtifacts: true on flows during investigations; avoid --no-screenshot unless disk output must be skipped.

Run scenarios

CLI

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

MCP (Cursor)

{
  "scenarioId": "workflow-verification-scenario",
  "profile": "qa-user",
  "params": {
    "baseUrl": "http://localhost:3000",
    "workflowId": "workflow-01"
  }
}

Tool: sitelens_run_local_scenario. Requires SITELENS_MODE=local (default).

Parameterized flows

Pass IDs, URLs, environment values, and test data via params and --param flags. Reference placeholders as {{baseUrl}}, {{workflowId}}, etc. in flow with blocks—no need to rewrite flows per environment.

Shared browser sessions

Cookies, local storage, session state, and authentication persist across every flow in a scenario. Login once, run setup flows, then verify—without restarting the browser between steps.

Built for real applications

Related