@trylayout/qa 0.1.5 → 0.2.0

package/README.md

@@ -4,7 +4,7 @@
 [![CI](https://github.com/Layout-App/layout-qa/actions/workflows/ci.yml/badge.svg)](https://github.com/Layout-App/layout-qa/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-black.svg)](LICENSE)
 
-Layout QA is a local browser QA protocol and runner for AI-built frontends. It runs deterministic flows against a local or preview URL, captures screenshots at meaningful checkpoints, checks browser health, and writes a static HTML report.
+Layout QA is a browser QA protocol and runner for frontend changes. It runs deterministic flows against a local or CI-served URL, captures screenshots at meaningful checkpoints, checks browser health, and writes a static HTML report.
 
 The core loop is intentionally local:
 
@@ -35,14 +35,14 @@ npx layout-qa run --target-url http://localhost:5173 --scenario happy_path --ope
 
 ## Why This Exists
 
-Frontend agents can move faster when they have a visual feedback loop they can run themselves. Layout gives the agent a small protocol:
+Frontend agents and developers can move faster when they have a visual feedback loop they can run themselves. Layout gives the repo a small protocol:
 
-- Wire deterministic API/auth responses behind a local env flag such as `VITE_LAYOUT_QA_MOCKS=1`.
+- Wire deterministic API/auth responses behind a QA env flag such as `LAYOUT_QA=1` or `VITE_LAYOUT_QA=1`.
 - Switch response states with `localStorage["layout.qa.scenario"]`.
-- Declare high-value browser flows in `.layout/qa-flows.json`.
-- Run the CLI locally and inspect the generated screenshots/report.
+- Declare high-value browser flows in `.layout/qa.json`.
+- Run the CLI locally or in GitHub Actions and inspect the generated screenshots/report.
 
-The goal is not to replace Playwright. The goal is to make the browser QA loop simple enough for a coding agent to set up, run, and iterate on while building a frontend branch.
+The goal is not to replace Playwright. The goal is to make the browser QA loop simple enough for a team or coding agent to run before frontend changes merge.
 
 ## Install
 
@@ -79,10 +79,10 @@ Create a starter flow manifest:
 npx @trylayout/qa init
 ```
 
-Start your app with whatever local QA flag your project uses:
+Start your app with whatever QA flag your project uses:
 
 ```bash
-VITE_LAYOUT_QA_MOCKS=1 npm run dev
+LAYOUT_QA=1 VITE_LAYOUT_QA=1 npm run dev
 ```
 
 Run a scenario:
@@ -120,42 +120,42 @@ Options:
 ```text
 --target-url <url>     URL of the running frontend to test.
 --scenario <name>      Scenario to activate. Defaults to happy_path.
---flows <path>         Flow manifest path. Defaults to .layout/qa-flows.json.
+--flows <path>         Flow manifest path. Defaults to .layout/qa.json.
 --out <path>           Artifact directory. Defaults to .layout/runs.
 --viewport <value>     Viewport preset or size. Use desktop, tablet, mobile, or WIDTHxHEIGHT. Defaults to desktop.
 --timeout <ms>         Browser run timeout. Defaults to 60000.
 --headed               Show the browser instead of running headless.
 --open                 Open the generated local HTML report after the run.
 --json                 Print machine-readable JSON.
+--upload-url <url>     Upload completed run JSON/screenshots to Layout.
+--upload-token <token> Project upload token for hosted Layout reports.
+--repo <name>          Repository full name, e.g. owner/repo.
+--branch <name>        Branch name for report metadata.
+--commit-sha <sha>     Commit SHA for report metadata.
+--pr-number <number>   Pull request number for report metadata.
+--run-source <value>   local or github_actions. Defaults from environment.
 --force                Overwrite an existing flow file during init.
 ```
 
 ## Flow Manifest
 
-Default path: `.layout/qa-flows.json`.
+Default path: `.layout/qa.json`.
 
 ```json
 {
-  "schemaVersion": 1,
+  "version": 1,
+  "baseUrl": "$LAYOUT_BASE_URL",
+  "viewports": ["desktop"],
   "flows": [
     {
       "id": "workspace_smoke",
-      "name": "Workspace smoke",
-      "startUrl": "/",
+      "label": "Workspace smoke",
       "scenarios": ["happy_path"],
       "steps": [
-        {
-          "id": "workspace_loaded",
-          "type": "assert_visible_text",
-          "text": "Dashboard",
-          "screenshot": true
-        },
-        {
-          "id": "open_settings",
-          "type": "click",
-          "text": "Settings",
-          "screenshot": true
-        }
+        {"visit": "/"},
+        {"screenshot": "Workspace loaded", "expect": {"text": ["Dashboard"]}},
+        {"click": "[data-layout-qa='open-settings']"},
+        {"screenshot": "Settings open", "expect": {"text": ["Settings"]}}
       ]
     }
   ]
@@ -164,28 +164,36 @@ Default path: `.layout/qa-flows.json`.
 
 Top-level fields:
 
-- `schemaVersion`: currently `1`.
+- `version`: currently `1`.
+- `baseUrl`: optional reference value for hosted/CI integrations. The CLI still uses `--target-url` as the source of truth.
+- `viewports`: optional default viewport labels for hosted/CI integrations.
 - `flows`: array of flow definitions.
 
 Flow fields:
 
 - `id`: stable machine-readable flow id.
-- `name`: human-readable report title.
-- `startUrl`: path or absolute URL where the flow starts.
+- `label`: human-readable report title.
 - `scenarios`: scenario names this flow can run against. Use an empty array to allow all scenarios.
 - `steps`: ordered browser steps.
 
 Step fields:
 
 - `id`: stable machine-readable step id.
-- `type`: step type.
+- `type`: explicit step type for advanced steps.
 - `label`: optional human-readable report label.
 - `screenshot`: set `true` to capture a screenshot after the step.
+- `expect`: optional assertions attached to a step.
 - `timeoutMs`: optional per-step timeout.
 - `tolerance`: optional pixel tolerance for layout assertions.
 - `minWidth`, `maxWidth`, `minHeight`, `maxHeight`: optional `assert_box` constraints.
 
-Supported step types:
+Supported shorthand steps:
+
+- `{"visit": "/path"}`: navigate to a path.
+- `{"click": "[data-layout-qa='action']"}`: click a selector. If the string does not look like a selector, it is treated as visible text.
+- `{"screenshot": "Human label"}`: capture a screenshot checkpoint.
+
+Supported explicit step types:
 
 - `goto`: navigate to `url`.
 - `click`: click by `selector` or visible `text`.
@@ -198,8 +206,25 @@ Supported step types:
 - `assert_box`: require a `selector` or visible `text` to satisfy width/height constraints.
 - `screenshot`: capture a screenshot checkpoint.
 
+Supported expectations:
+
+- `{"expect": {"text": ["Visible copy"]}}`: require visible text after the step.
+- `{"expect": {"noConsoleErrors": true}}`: require no console/page errors observed so far.
+
 Examples:
 
+```json
+{ "visit": "/checkout" }
+```
+
+```json
+{ "click": "[data-layout-qa='simulate-payment-timeout']" }
+```
+
+```json
+{ "screenshot": "Payment timeout recovery", "expect": { "text": ["Payment failed", "Try again"] } }
+```
+
 ```json
 { "id": "open_settings", "type": "click", "text": "Settings" }
 ```
@@ -249,6 +274,34 @@ Presets:
 
 The selected viewport is written to `result.json`, shown in the HTML report, and included in the run directory name.
 
+## Hosted Reports
+
+The CLI is local-first. If you have a Layout project upload token, the same run can upload screenshots and report metadata to a hosted Layout report:
+
+```bash
+npx @trylayout/qa run \
+  --target-url http://localhost:5173 \
+  --upload-url https://trylayout.com/api/v1/qa/uploads \
+  --upload-token "$LAYOUT_UPLOAD_TOKEN" \
+  --repo owner/repo \
+  --branch "$BRANCH_NAME" \
+  --commit-sha "$COMMIT_SHA"
+```
+
+Environment fallbacks:
+
+- `LAYOUT_UPLOAD_URL`
+- `LAYOUT_UPLOAD_TOKEN`
+- `LAYOUT_REPOSITORY`
+- `LAYOUT_BRANCH`
+- `LAYOUT_COMMIT_SHA`
+- `LAYOUT_PR_NUMBER`
+- `LAYOUT_RUN_SOURCE`
+
+In GitHub Actions, the CLI also reads `GITHUB_REPOSITORY`, `GITHUB_HEAD_REF`, `GITHUB_REF_NAME`, `GITHUB_SHA`, `GITHUB_REF`, and `GITHUB_EVENT_PATH` when explicit flags are not provided.
+
+If either upload flag is provided, both `--upload-url` and `--upload-token` are required. Upload failures make the CLI exit nonzero.
+
 ## Scenarios
 
 Before the app loads, the runner sets:
@@ -280,7 +333,7 @@ Rules:
 - Do not add a standalone mock server.
 - Do not require a hosted Layout service.
 - Keep all deterministic response fixtures local to this app.
-- Gate deterministic API/auth responses behind a local-only env flag such as VITE_LAYOUT_QA_MOCKS=1, NEXT_PUBLIC_LAYOUT_QA_MOCKS=1, or the framework-appropriate equivalent.
+- Gate deterministic API/auth responses behind a QA env flag such as LAYOUT_QA=1, VITE_LAYOUT_QA=1, NEXT_PUBLIC_LAYOUT_QA=1, or the framework-appropriate equivalent.
 - Use localStorage["layout.qa.scenario"] to select at least happy_path, empty, and error response states.
 - Hide any local QA switcher or debug controls when sessionStorage["layout.qa.runner"] === "1".
 
@@ -288,7 +341,7 @@ Implementation:
 - Add deterministic API fixtures for the highest-value frontend route.
 - If the app has a central auth/session abstraction, add a deterministic QA user only when the Layout QA env flag is enabled.
 - If auth is scattered or provider-SDK-only, leave a clear note in the PR/code comments and start with public or logged-out flows.
-- Add .layout/qa-flows.json with one smoke flow for the most important page.
+- Add .layout/qa.json with one smoke flow for the most important page.
 - Prefer visible text and stable selectors.
 - Add screenshot checkpoints after meaningful user-visible states.
 
@@ -317,8 +370,10 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npx playwright install chromium
-      - run: VITE_LAYOUT_QA_MOCKS=1 npm run dev -- --host 127.0.0.1 --port 5173 &
-      - run: npx @trylayout/qa run --target-url http://127.0.0.1:5173 --scenario happy_path
+      - run: LAYOUT_QA=1 VITE_LAYOUT_QA=1 npm run dev -- --host 127.0.0.1 --port 5173 &
+      - run: npx @trylayout/qa run --target-url http://127.0.0.1:5173 --scenario happy_path --run-source github_actions --upload-url https://trylayout.com/api/v1/qa/uploads --upload-token "$LAYOUT_UPLOAD_TOKEN"
+        env:
+          LAYOUT_UPLOAD_TOKEN: ${{ secrets.LAYOUT_UPLOAD_TOKEN }}
       - uses: actions/upload-artifact@v4
         if: always()
         with:

package/build/cli/layoutQa.js

@@ -6,6 +6,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
+const http_1 = require("http");
+const https_1 = require("https");
+const url_1 = require("url");
 const flows_1 = require("../flows");
 const runner_1 = require("../runner");
 const report_1 = require("../report");
@@ -21,19 +24,26 @@ Usage:
   npx layout-qa run --target-url <url> [options]
 
 Commands:
-  init                  Write a starter .layout/qa-flows.json.
+  init                  Write a starter .layout/qa.json.
   run                   Run browser QA and write a local HTML report.
 
 Options:
   --target-url <url>     URL of the running frontend to test.
   --scenario <name>      Scenario to activate. Defaults to happy_path.
-  --flows <path>         Flow manifest path. Defaults to .layout/qa-flows.json.
+  --flows <path>         Flow manifest path. Defaults to .layout/qa.json.
   --out <path>           Artifact directory. Defaults to .layout/runs.
   --viewport <value>     Viewport preset or size. Use desktop, tablet, mobile, or WIDTHxHEIGHT. Defaults to desktop.
   --timeout <ms>         Browser run timeout. Defaults to LAYOUT_QA_TEST_TIMEOUT_MS or 60000.
   --headed               Show the browser instead of running headless.
   --open                 Open the generated local HTML report after the run.
   --json                 Print machine-readable JSON.
+  --upload-url <url>     Upload completed run JSON/screenshots to Layout.
+  --upload-token <token> Project upload token for hosted Layout reports.
+  --repo <name>          Repository full name, e.g. owner/repo.
+  --branch <name>        Branch name for report metadata.
+  --commit-sha <sha>     Commit SHA for report metadata.
+  --pr-number <number>   Pull request number for report metadata.
+  --run-source <value>   local or github_actions. Defaults from environment.
   --force                Overwrite an existing flow file during init.
   --help                 Show this help.
 `);
@@ -47,10 +57,34 @@ function readFlag(args, name) {
 function hasFlag(args, name) {
     return args.includes(name);
 }
+function envValue(name) {
+    return process.env[name] || '';
+}
+async function githubEventPullRequestNumber() {
+    const eventPath = envValue('GITHUB_EVENT_PATH');
+    if (!eventPath)
+        return '';
+    const content = await promises_1.default.readFile(eventPath, 'utf8').catch(() => '');
+    if (!content)
+        return '';
+    const event = JSON.parse(content);
+    return event.pull_request?.number ? String(event.pull_request.number) : '';
+}
+function inferGithubPrNumber() {
+    const ref = envValue('GITHUB_REF');
+    const match = ref.match(/^refs\/pull\/(\d+)\//);
+    return match?.[1] || '';
+}
+function inferBranch() {
+    return envValue('GITHUB_HEAD_REF') || envValue('GITHUB_REF_NAME');
+}
 function parseArgs(args) {
     const command = args[0] && !args[0].startsWith('--') ? args[0] : 'help';
     const timeoutValue = readFlag(args, '--timeout');
     const parsedTimeoutMs = timeoutValue ? Number(timeoutValue) : undefined;
+    const rawRunSource = readFlag(args, '--run-source') ||
+        envValue('LAYOUT_RUN_SOURCE') ||
+        (envValue('GITHUB_ACTIONS') === 'true' ? 'github_actions' : 'local');
     if (timeoutValue &&
         (!Number.isFinite(parsedTimeoutMs) || Number(parsedTimeoutMs) <= 0)) {
         throw new Error('--timeout must be a positive number of milliseconds.');
@@ -61,6 +95,19 @@ function parseArgs(args) {
         scenario: readFlag(args, '--scenario') || 'happy_path',
         flowsPath: readFlag(args, '--flows'),
         outDir: readFlag(args, '--out'),
+        uploadUrl: readFlag(args, '--upload-url') || envValue('LAYOUT_UPLOAD_URL'),
+        uploadToken: readFlag(args, '--upload-token') || envValue('LAYOUT_UPLOAD_TOKEN'),
+        repo: readFlag(args, '--repo') ||
+            envValue('LAYOUT_REPOSITORY') ||
+            envValue('GITHUB_REPOSITORY'),
+        branch: readFlag(args, '--branch') || envValue('LAYOUT_BRANCH') || inferBranch(),
+        commitSha: readFlag(args, '--commit-sha') ||
+            envValue('LAYOUT_COMMIT_SHA') ||
+            envValue('GITHUB_SHA'),
+        prNumber: readFlag(args, '--pr-number') ||
+            envValue('LAYOUT_PR_NUMBER') ||
+            inferGithubPrNumber(),
+        runSource: rawRunSource === 'github_actions' ? 'github_actions' : 'local',
         viewport: (0, viewports_1.parseViewport)(readFlag(args, '--viewport')),
         timeoutMs: parsedTimeoutMs,
         headed: hasFlag(args, '--headed'),
@@ -92,6 +139,7 @@ function statusIcon(passed) {
 }
 function printHumanSummary(input) {
     const passed = (0, runner_1.isQaRunPassed)(input.result);
+    const flows = resultFlows(input.result);
     process.stdout.write(`\nLayout QA ${passed ? 'passed' : 'failed'}\n` +
         `Scenario: ${input.scenario}\n` +
         `Target: ${input.targetUrl}\n` +
@@ -99,14 +147,15 @@ function printHumanSummary(input) {
             ? (0, viewports_1.formatViewport)(input.result.viewport)
             : 'unavailable'}\n` +
         `Final URL: ${input.result.finalUrl || 'unavailable'}\n` +
-        `Flow: ${input.result.flow?.name || 'None'} (${input.result.flow?.source || 'none'})\n` +
+        `Flows: ${flows.length || 0}\n` +
         `Manifest: ${input.manifestFound ? input.manifestPath : 'not found; default smoke'}\n\n`);
     for (const check of input.result.checks) {
         process.stdout.write(`${statusIcon(check.passed)} ${check.label}${check.detail ? ` - ${check.detail}` : ''}\n`);
     }
-    if (input.result.flow?.steps.length) {
+    for (const flow of flows) {
         process.stdout.write('\nFlow steps:\n');
-        for (const step of input.result.flow.steps) {
+        process.stdout.write(`${flow.name} (${flow.source})\n`);
+        for (const step of flow.steps) {
             process.stdout.write(`${statusIcon(step.status === 'passed')} ${step.label || step.id}${step.detail ? ` - ${step.detail}` : ''}\n`);
         }
     }
@@ -126,35 +175,168 @@ function printHumanSummary(input) {
 function resultForConsole(result) {
     const clean = JSON.parse(JSON.stringify(result));
     delete clean.screenshotDataUrl;
-    const flow = clean.flow;
-    for (const step of flow?.steps || []) {
-        delete step.screenshotDataUrl;
+    const scrubFlow = (flow) => {
+        for (const step of flow?.steps || []) {
+            delete step.screenshotDataUrl;
+        }
+    };
+    scrubFlow(clean.flow);
+    const flows = clean.flows;
+    for (const flow of flows || []) {
+        scrubFlow(flow);
     }
     return clean;
 }
+function resultFlows(result) {
+    return result.flows?.length
+        ? result.flows
+        : result.flow
+            ? [result.flow]
+            : [];
+}
+function combineFlowRunResults(results) {
+    if (results.length === 1) {
+        const [result] = results;
+        return {
+            ...result,
+            flows: resultFlows(result),
+        };
+    }
+    const flows = results
+        .map(result => result.flow)
+        .filter((flow) => Boolean(flow));
+    const lastResult = results[results.length - 1];
+    const firstFailed = results.find(result => !(0, runner_1.isQaRunPassed)(result));
+    return {
+        finalUrl: lastResult.finalUrl,
+        title: lastResult.title,
+        scenarioActive: lastResult.scenarioActive,
+        controlsPresent: lastResult.controlsPresent,
+        screenshotDataUrl: lastResult.screenshotDataUrl,
+        screenshotBytes: lastResult.screenshotBytes,
+        bodyTextSample: results.map(result => result.bodyTextSample || '').join('\n\n'),
+        viewport: lastResult.viewport,
+        checks: results.flatMap(result => {
+            const flowName = result.flow?.name || 'Flow';
+            const flowId = result.flow?.id || 'flow';
+            return result.checks.map(check => ({
+                ...check,
+                id: `${flowId}_${check.id}`,
+                label: `${flowName}: ${check.label}`,
+            }));
+        }),
+        issues: results.flatMap(result => result.issues),
+        flow: flows[0],
+        flows,
+        nextAction: firstFailed?.nextAction || lastResult.nextAction,
+    };
+}
+function readFileAsDataUrl(filePath) {
+    return promises_1.default.readFile(filePath).then(buffer => {
+        const ext = path_1.default.extname(filePath).toLowerCase();
+        const mimeType = ext === '.html'
+            ? 'text/html'
+            : ext === '.json'
+                ? 'application/json'
+                : 'image/jpeg';
+        return `data:${mimeType};base64,${buffer.toString('base64')}`;
+    });
+}
+function postJson(input) {
+    const target = new url_1.URL(input.url);
+    const request = target.protocol === 'https:' ? https_1.request : http_1.request;
+    const body = JSON.stringify(input.body);
+    return new Promise((resolve, reject) => {
+        const req = request({
+            protocol: target.protocol,
+            hostname: target.hostname,
+            port: target.port,
+            path: `${target.pathname}${target.search}`,
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${input.token}`,
+                'Content-Type': 'application/json',
+                'Content-Length': Buffer.byteLength(body),
+                'User-Agent': '@trylayout/qa',
+            },
+        }, res => {
+            let responseBody = '';
+            res.setEncoding('utf8');
+            res.on('data', chunk => {
+                responseBody += chunk;
+            });
+            res.on('end', () => {
+                const parsed = responseBody
+                    ? JSON.parse(responseBody)
+                    : {};
+                if (!res.statusCode || res.statusCode >= 400) {
+                    reject(new Error(`Upload failed (${res.statusCode || 'unknown'}): ${parsed.message || parsed.error || responseBody}`));
+                    return;
+                }
+                resolve(parsed);
+            });
+        });
+        req.on('error', reject);
+        req.write(body);
+        req.end();
+    });
+}
+async function uploadRun(input) {
+    if (!input.options.uploadUrl && !input.options.uploadToken)
+        return null;
+    if (!input.options.uploadUrl || !input.options.uploadToken) {
+        throw new Error('--upload-url and --upload-token must be provided together.');
+    }
+    const prNumber = input.options.prNumber || (await githubEventPullRequestNumber());
+    const reportDataUrl = await readFileAsDataUrl(input.artifacts.reportPath);
+    return postJson({
+        url: input.options.uploadUrl,
+        token: input.options.uploadToken,
+        body: {
+            status: input.passed ? 'passed' : 'failed',
+            runSource: input.options.runSource,
+            repository: input.options.repo,
+            branch: input.options.branch,
+            commitSha: input.options.commitSha,
+            prNumber: prNumber ? Number(prNumber) : undefined,
+            scenario: input.options.scenario,
+            targetUrl: input.options.targetUrl,
+            manifestPath: input.manifestPath,
+            manifestFound: input.manifestFound,
+            result: input.result,
+            report: {
+                fileName: 'index.html',
+                dataUrl: reportDataUrl,
+            },
+        },
+    });
+}
 async function runCommand(options) {
     if (!options.targetUrl) {
         throw new Error('--target-url is required.');
     }
-    const { flow, manifestPath, manifestFound } = await (0, flows_1.loadFlow)({
+    const { flows, manifestPath, manifestFound } = await (0, flows_1.loadFlows)({
         flowsPath: options.flowsPath,
         scenario: options.scenario,
     });
-    let result;
-    try {
-        result = await (0, runner_1.runLayoutQaBrowser)({
-            targetUrl: options.targetUrl,
-            scenario: options.scenario,
-            flow,
-            timeoutMs: options.timeoutMs || (0, flows_1.getTestTimeoutMs)(),
-            headless: !options.headed,
-            viewport: options.viewport,
-        });
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        result = (0, runner_1.buildRunnerErrorResult)(message, options.viewport);
+    const results = [];
+    for (const flow of flows) {
+        try {
+            results.push(await (0, runner_1.runLayoutQaBrowser)({
+                targetUrl: options.targetUrl,
+                scenario: options.scenario,
+                flow,
+                timeoutMs: options.timeoutMs || (0, flows_1.getTestTimeoutMs)(),
+                headless: !options.headed,
+                viewport: options.viewport,
+            }));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            results.push((0, runner_1.buildRunnerErrorResult)(message, options.viewport));
+        }
     }
+    const result = combineFlowRunResults(results);
     const artifacts = await (0, report_1.writeArtifacts)({
         outDir: options.outDir,
         scenario: options.scenario,
@@ -164,6 +346,14 @@ async function runCommand(options) {
         result,
     });
     const passed = (0, runner_1.isQaRunPassed)(result);
+    const uploadResponse = await uploadRun({
+        options,
+        result,
+        artifacts,
+        manifestPath,
+        manifestFound,
+        passed,
+    });
     if (options.json) {
         process.stdout.write(`${JSON.stringify({
             status: passed ? 'passed' : 'failed',
@@ -173,6 +363,7 @@ async function runCommand(options) {
             manifestPath,
             manifestFound,
             artifacts,
+            upload: uploadResponse,
             result: resultForConsole(result),
         }, null, 2)}\n`);
     }
@@ -189,6 +380,9 @@ async function runCommand(options) {
     if (options.open) {
         await (0, report_1.openReport)(artifacts.reportPath);
     }
+    if (uploadResponse && !options.json) {
+        process.stdout.write(`Uploaded: ${String(uploadResponse.reportUrl || uploadResponse.runId)}\n`);
+    }
     process.exitCode = passed ? 0 : 1;
 }
 async function main() {

package/build/flows.d.ts

@@ -1,11 +1,13 @@
 import { LoadedQaFlow, QaFlowDefinition } from './types';
 export declare const DEFAULT_TEST_TIMEOUT_MS: number;
 export declare const SCREENSHOT_LIMIT_BYTES: number;
-export declare const FLOW_MANIFEST_PATH = ".layout/qa-flows.json";
+export declare const FLOW_MANIFEST_PATH = ".layout/qa.json";
 export declare const QA_DOCS_URL = "https://github.com/Layout-App/layout-qa#readme";
 export declare function getTestTimeoutMs(): number;
-export declare function selectFlowFromManifest(raw: unknown, scenario: string): QaFlowDefinition | null;
+export declare function selectFlowFromManifest(raw: unknown, scenario: string): QaFlowDefinition;
+export declare function selectFlowsFromManifest(raw: unknown, scenario: string): QaFlowDefinition[];
 export declare function parseFlowManifestContent(content: string, scenario: string): LoadedQaFlow | null;
+export declare function parseFlowsManifestContent(content: string, scenario: string): LoadedQaFlow[];
 export declare function defaultFlow(): LoadedQaFlow;
 export declare function resolveDefaultPath(defaultPath: string): Promise<string>;
 export declare function loadFlow(input: {
@@ -16,18 +18,32 @@ export declare function loadFlow(input: {
     manifestPath: string;
     manifestFound: boolean;
 }>;
+export declare function loadFlows(input: {
+    flowsPath: string;
+    scenario: string;
+}): Promise<{
+    flows: LoadedQaFlow[];
+    manifestPath: string;
+    manifestFound: boolean;
+}>;
 export declare function starterFlowManifest(): {
-    schemaVersion: number;
+    version: number;
+    baseUrl: string;
+    viewports: string[];
     flows: {
         id: string;
-        name: string;
-        startUrl: string;
+        label: string;
         scenarios: string[];
-        steps: {
-            id: string;
-            type: string;
-            label: string;
-            screenshot: boolean;
-        }[];
+        steps: ({
+            visit: string;
+            screenshot?: undefined;
+            expect?: undefined;
+        } | {
+            screenshot: string;
+            expect: {
+                noConsoleErrors: boolean;
+            };
+            visit?: undefined;
+        })[];
     }[];
 };

package/build/flows.js

@@ -6,16 +6,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.QA_DOCS_URL = exports.FLOW_MANIFEST_PATH = exports.SCREENSHOT_LIMIT_BYTES = exports.DEFAULT_TEST_TIMEOUT_MS = void 0;
 exports.getTestTimeoutMs = getTestTimeoutMs;
 exports.selectFlowFromManifest = selectFlowFromManifest;
+exports.selectFlowsFromManifest = selectFlowsFromManifest;
 exports.parseFlowManifestContent = parseFlowManifestContent;
+exports.parseFlowsManifestContent = parseFlowsManifestContent;
 exports.defaultFlow = defaultFlow;
 exports.resolveDefaultPath = resolveDefaultPath;
 exports.loadFlow = loadFlow;
+exports.loadFlows = loadFlows;
 exports.starterFlowManifest = starterFlowManifest;
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
 exports.DEFAULT_TEST_TIMEOUT_MS = 60 * 1000;
 exports.SCREENSHOT_LIMIT_BYTES = 300 * 1024;
-exports.FLOW_MANIFEST_PATH = '.layout/qa-flows.json';
+exports.FLOW_MANIFEST_PATH = '.layout/qa.json';
 exports.QA_DOCS_URL = 'https://github.com/Layout-App/layout-qa#readme';
 function getTestTimeoutMs() {
     const value = Number(process.env.LAYOUT_QA_TEST_TIMEOUT_MS);
@@ -40,24 +43,66 @@ function stringArray(value) {
         ? value.filter(item => typeof item === 'string')
         : [];
 }
+function expectTextArray(value) {
+    if (!isRecord(value))
+        return [];
+    const text = value.text;
+    if (typeof text === 'string')
+        return [text];
+    return stringArray(text);
+}
+function isLikelySelector(value) {
+    return /^(#|\.|\[)/.test(value) || /[#.[\]:>~+]/.test(value);
+}
+function shortcutStep(value, index) {
+    if (typeof value.visit === 'string') {
+        return {
+            type: 'goto',
+            url: value.visit.trim(),
+        };
+    }
+    if (typeof value.click === 'string') {
+        const target = value.click.trim();
+        return {
+            type: 'click',
+            ...(isLikelySelector(target) ? { selector: target } : { text: target }),
+        };
+    }
+    if (typeof value.screenshot === 'string' || value.screenshot === true) {
+        return {
+            type: 'screenshot',
+            label: typeof value.screenshot === 'string'
+                ? value.screenshot.trim()
+                : `Screenshot ${index + 1}`,
+            screenshot: true,
+        };
+    }
+    return null;
+}
 function normalizeFlowStep(value, index) {
     if (!isRecord(value))
         return null;
-    const type = stringValue(value.type).trim();
+    const shortcut = shortcutStep(value, index);
+    const type = stringValue(value.type || shortcut?.type).trim();
     if (!type)
         return null;
+    const expect = isRecord(value.expect) ? value.expect : {};
+    const clickTarget = stringValue(value.click).trim();
     return {
         id: stringValue(value.id).trim() ||
             `${type.replace(/[^a-zA-Z0-9_-]+/g, '_')}_${index + 1}`,
-        type,
-        label: stringValue(value.label || value.name).trim(),
-        text: stringValue(value.text).trim(),
-        selector: stringValue(value.selector).trim(),
+        type: type === 'visit' ? 'goto' : type,
+        label: stringValue(value.label || value.name || shortcut?.label).trim(),
+        text: stringValue(value.text || shortcut?.text).trim(),
+        expectText: expectTextArray(value.expect),
+        expectNoConsoleErrors: isRecord(expect) && expect.noConsoleErrors === true ? true : undefined,
+        selector: stringValue(value.selector || shortcut?.selector).trim() ||
+            (clickTarget && isLikelySelector(clickTarget) ? clickTarget : ''),
         value: stringValue(value.value),
-        url: stringValue(value.url || value.path).trim(),
+        url: stringValue(value.url || value.path || value.visit || shortcut?.url).trim(),
         contains: stringValue(value.contains).trim(),
         exact: booleanValue(value.exact),
-        screenshot: booleanValue(value.screenshot, type === 'screenshot'),
+        screenshot: booleanValue(value.screenshot, type === 'screenshot' || shortcut?.screenshot === true),
         timeoutMs: numberValue(value.timeoutMs),
         tolerance: numberValue(value.tolerance),
         minWidth: numberValue(value.minWidth),
@@ -78,26 +123,33 @@ function normalizeFlow(value, index) {
     const id = stringValue(value.id).trim() || `flow_${index + 1}`;
     return {
         id,
-        name: stringValue(value.name).trim() || id,
+        name: stringValue(value.label || value.name).trim() || id,
         startUrl: stringValue(value.startUrl).trim() || '/',
         scenarios: stringArray(value.scenarios),
         steps,
     };
 }
 function selectFlowFromManifest(raw, scenario) {
+    return selectFlowsFromManifest(raw, scenario)[0] || null;
+}
+function selectFlowsFromManifest(raw, scenario) {
     if (!isRecord(raw) || !Array.isArray(raw.flows))
-        return null;
+        return [];
     const flows = raw.flows
         .map((flow, index) => normalizeFlow(flow, index))
         .filter((flow) => Boolean(flow));
     if (flows.length === 0)
-        return null;
-    return (flows.find(flow => flow.scenarios.length === 0 || flow.scenarios.includes(scenario)) || flows[0]);
+        return [];
+    const selected = flows.filter(flow => flow.scenarios.length === 0 || flow.scenarios.includes(scenario));
+    return selected.length ? selected : [flows[0]];
 }
 function parseFlowManifestContent(content, scenario) {
     const flow = selectFlowFromManifest(JSON.parse(content), scenario);
     return flow ? { ...flow, source: 'manifest' } : null;
 }
+function parseFlowsManifestContent(content, scenario) {
+    return selectFlowsFromManifest(JSON.parse(content), scenario).map(flow => ({ ...flow, source: 'manifest' }));
+}
 function defaultFlow() {
     return {
         id: 'target_smoke',
@@ -139,6 +191,14 @@ async function resolveDefaultPath(defaultPath) {
     return cwdPath;
 }
 async function loadFlow(input) {
+    const loaded = await loadFlows(input);
+    return {
+        flow: loaded.flows[0],
+        manifestPath: loaded.manifestPath,
+        manifestFound: loaded.manifestFound,
+    };
+}
+async function loadFlows(input) {
     const manifestPath = input.flowsPath
         ? path_1.default.resolve(process.cwd(), input.flowsPath)
         : await resolveDefaultPath(exports.FLOW_MANIFEST_PATH);
@@ -150,33 +210,37 @@ async function loadFlow(input) {
     });
     if (!content) {
         return {
-            flow: defaultFlow(),
+            flows: [defaultFlow()],
             manifestPath,
             manifestFound: false,
         };
     }
-    const flow = parseFlowManifestContent(content, input.scenario);
+    const flows = parseFlowsManifestContent(content, input.scenario);
     return {
-        flow: flow || defaultFlow(),
+        flows: flows.length ? flows : [defaultFlow()],
         manifestPath,
-        manifestFound: Boolean(flow),
+        manifestFound: flows.length > 0,
     };
 }
 function starterFlowManifest() {
     return {
-        schemaVersion: 1,
+        version: 1,
+        baseUrl: '$LAYOUT_BASE_URL',
+        viewports: ['desktop'],
         flows: [
             {
                 id: 'smoke',
-                name: 'Smoke',
-                startUrl: '/',
+                label: 'Smoke',
                 scenarios: ['happy_path'],
                 steps: [
                     {
-                        id: 'initial_screen',
-                        type: 'screenshot',
-                        label: 'Initial screen',
-                        screenshot: true,
+                        visit: '/',
+                    },
+                    {
+                        screenshot: 'Initial screen',
+                        expect: {
+                            noConsoleErrors: true,
+                        },
                     },
                 ],
             },

package/build/report.js

@@ -19,6 +19,9 @@ function safeName(value) {
 function stepScreenshotFileName(index, stepId) {
     return `${String(index + 1).padStart(2, '0')}-${safeName(stepId)}.jpg`;
 }
+function flowStepScreenshotFileName(input) {
+    return `${safeName(input.flow.id || 'flow')}-${stepScreenshotFileName(input.stepIndex, input.stepId)}`;
+}
 async function writeDataUrl(filePath, dataUrl) {
     const match = dataUrl.match(/^data:([^;]+);base64,(.*)$/);
     if (!match)
@@ -29,8 +32,7 @@ async function writeDataUrl(filePath, dataUrl) {
 async function writeStepScreenshot(input) {
     if (!input.step.screenshotDataUrl)
         return '';
-    const fileName = stepScreenshotFileName(input.index, input.step.id);
-    const filePath = path_1.default.join(input.screenshotsDir, fileName);
+    const filePath = path_1.default.join(input.screenshotsDir, input.fileName);
     const written = await writeDataUrl(filePath, input.step.screenshotDataUrl);
     return written ? filePath : '';
 }
@@ -79,14 +81,25 @@ function renderIssueList(result) {
       </li>`)
         .join('')}</ul>`;
 }
+function resultFlows(result) {
+    return result.flows?.length
+        ? result.flows
+        : result.flow
+            ? [result.flow]
+            : [];
+}
 function renderStepList(input) {
-    const steps = input.result.flow?.steps || [];
+    const steps = input.flow.steps || [];
     if (steps.length === 0)
         return '<p class="empty">No flow steps declared.</p>';
     return steps
         .map((step, index) => {
         const screenshotHref = step.screenshotDataUrl
-            ? relativeHref(input.runDir, path_1.default.join(input.runDir, 'screenshots', stepScreenshotFileName(index, step.id)))
+            ? relativeHref(input.runDir, path_1.default.join(input.runDir, 'screenshots', flowStepScreenshotFileName({
+                flow: input.flow,
+                stepIndex: index,
+                stepId: step.id,
+            })))
             : '';
         return `<article class="step">
         <header class="step-header">
@@ -111,7 +124,12 @@ function renderReport(input) {
         ? relativeHref(input.runDir, path_1.default.join(input.runDir, 'screenshots', 'final.jpg'))
         : '';
     const resultHref = relativeHref(input.runDir, input.resultPath);
-    const flow = input.result.flow;
+    const flows = resultFlows(input.result);
+    const flowSummary = flows.length === 0
+        ? 'None'
+        : flows.length === 1
+            ? flows[0].name
+            : `${flows.length} flows`;
     const viewport = input.result.viewport;
     const failedCheckCount = input.result.checks.filter(check => !check.passed).length;
     return `<!doctype html>
@@ -283,7 +301,7 @@ function renderReport(input) {
 
     <dl class="summary">
       <div class="metric"><dt>Scenario</dt><dd>${escapeHtml(input.scenario)}</dd></div>
-      <div class="metric"><dt>Flow</dt><dd>${escapeHtml(flow?.name || 'None')}</dd></div>
+      <div class="metric"><dt>Flows</dt><dd>${escapeHtml(flowSummary)}</dd></div>
       <div class="metric"><dt>Target URL</dt><dd>${escapeHtml(input.targetUrl)}</dd></div>
       <div class="metric"><dt>Viewport</dt><dd>${escapeHtml(viewport ? (0, viewports_1.formatViewport)(viewport) : 'unavailable')}</dd></div>
       <div class="metric"><dt>Final URL</dt><dd>${escapeHtml(input.result.finalUrl || 'unavailable')}</dd></div>
@@ -294,10 +312,12 @@ function renderReport(input) {
       <ul class="stack">${renderCheckList(input.result)}</ul>
     </section>
 
-    <section>
-      <h2>${escapeHtml(flow?.name || 'Flow Steps')}</h2>
-      ${renderStepList({ runDir: input.runDir, result: input.result })}
-    </section>
+    ${flows
+        .map(flow => `<section>
+      <h2>${escapeHtml(flow.name || flow.id)}</h2>
+      ${renderStepList({ runDir: input.runDir, flow })}
+    </section>`)
+        .join('')}
 
     ${finalScreenshotHref
         ? `<section>
@@ -347,14 +367,20 @@ async function writeArtifacts(input) {
             screenshots.push(finalPath);
         }
     }
-    for (const [index, step] of (input.result.flow?.steps || []).entries()) {
-        const screenshotPath = await writeStepScreenshot({
-            screenshotsDir,
-            index,
-            step,
-        });
-        if (screenshotPath)
-            screenshots.push(screenshotPath);
+    for (const flow of resultFlows(input.result)) {
+        for (const [index, step] of flow.steps.entries()) {
+            const screenshotPath = await writeStepScreenshot({
+                screenshotsDir,
+                fileName: flowStepScreenshotFileName({
+                    flow,
+                    stepIndex: index,
+                    stepId: step.id,
+                }),
+                step,
+            });
+            if (screenshotPath)
+                screenshots.push(screenshotPath);
+        }
     }
     const resultPath = path_1.default.join(runDir, 'result.json');
     await promises_1.default.writeFile(resultPath, JSON.stringify(input.result, null, 2));

package/build/runner.js

@@ -365,6 +365,24 @@ async function caseSensitiveGoto(page, targetUrl, timeoutMs) {
 async function executeFlowStep(input) {
     const stepTimeout = input.step.timeoutMs || Math.min(input.timeoutMs, 10000);
     const exact = input.step.exact === true;
+    const withExpectations = async (detail) => {
+        const expectationDetails = [];
+        for (const text of input.step.expectText || []) {
+            await input.page
+                .getByText(text, { exact })
+                .first()
+                .waitFor({ state: 'visible', timeout: stepTimeout });
+            expectationDetails.push(`Visible text found: ${text}`);
+        }
+        if (input.step.expectNoConsoleErrors) {
+            const browserErrors = input.issues.filter(entry => ['console_error', 'page_error'].includes(entry.type));
+            if (browserErrors.length > 0) {
+                throw new Error(`Expected no console/page errors, found ${browserErrors.length}.`);
+            }
+            expectationDetails.push('No console/page errors observed.');
+        }
+        return [detail, ...expectationDetails].filter(Boolean).join(' ');
+    };
     if (input.step.type === 'goto') {
         const target = resolveTargetUrl(input.targetUrl, requireStepValue(input.step.url, 'url'));
         await caseSensitiveGoto(input.page, target, stepTimeout);
@@ -373,7 +391,7 @@ async function executeFlowStep(input) {
             .catch(() => {
             // DOM assertions after the step are the source of truth.
         });
-        return `Navigated to ${target}`;
+        return withExpectations(`Navigated to ${target}`);
     }
     if (input.step.type === 'assert_visible_text' ||
         input.step.type === 'wait_for_text') {
@@ -382,25 +400,25 @@ async function executeFlowStep(input) {
             .getByText(text, { exact })
             .first()
             .waitFor({ state: 'visible', timeout: stepTimeout });
-        return `Visible text found: ${text}`;
+        return withExpectations(`Visible text found: ${text}`);
     }
     if (input.step.type === 'click') {
         if (input.step.selector) {
             await input.page
                 .locator(input.step.selector)
                 .click({ timeout: stepTimeout });
-            return `Clicked selector: ${input.step.selector}`;
+            return withExpectations(`Clicked selector: ${input.step.selector}`);
         }
         const text = requireStepValue(input.step.text, 'text or selector');
         await input.page.getByText(text, { exact }).click({ timeout: stepTimeout });
-        return `Clicked text: ${text}`;
+        return withExpectations(`Clicked text: ${text}`);
     }
     if (input.step.type === 'fill') {
         const selector = requireStepValue(input.step.selector, 'selector');
         await input.page
             .locator(selector)
             .fill(input.step.value || '', { timeout: stepTimeout });
-        return `Filled selector: ${selector}`;
+        return withExpectations(`Filled selector: ${selector}`);
     }
     if (input.step.type === 'assert_url') {
         const currentUrl = input.page.url();
@@ -411,29 +429,29 @@ async function executeFlowStep(input) {
             currentUrl !== resolveTargetUrl(input.targetUrl, input.step.url)) {
             throw new Error(`Expected URL ${input.step.url}, got ${currentUrl}.`);
         }
-        return `URL matched: ${currentUrl}`;
+        return withExpectations(`URL matched: ${currentUrl}`);
     }
     if (input.step.type === 'assert_no_horizontal_overflow') {
-        return assertNoHorizontalOverflow(input.page, input.step.tolerance ?? 1);
+        return withExpectations(await assertNoHorizontalOverflow(input.page, input.step.tolerance ?? 1));
     }
     if (input.step.type === 'assert_in_viewport') {
-        return assertElementInViewport({
+        return withExpectations(await assertElementInViewport({
             page: input.page,
             step: input.step,
             exact,
             timeoutMs: stepTimeout,
-        });
+        }));
     }
     if (input.step.type === 'assert_box') {
-        return assertElementBox({
+        return withExpectations(await assertElementBox({
             page: input.page,
             step: input.step,
             exact,
             timeoutMs: stepTimeout,
-        });
+        }));
     }
     if (input.step.type === 'screenshot') {
-        return 'Captured screenshot checkpoint.';
+        return withExpectations('Captured screenshot checkpoint.');
     }
     throw new Error(`Unsupported flow step type: ${input.step.type}`);
 }
@@ -453,6 +471,7 @@ async function runFlow(input) {
                 step,
                 targetUrl: input.targetUrl,
                 timeoutMs: input.timeoutMs,
+                issues: input.issues,
             });
             result.url = input.page.url();
             if (step.screenshot || step.type === 'screenshot') {

package/build/types.d.ts

@@ -50,6 +50,7 @@ export type QaTestRunResult = {
     checks: QaTestRunCheck[];
     issues: QaTestRunIssue[];
     flow?: QaTestRunFlowResult;
+    flows?: QaTestRunFlowResult[];
     nextAction?: QaTestRunNextAction;
 };
 export type QaFlowStep = {
@@ -57,6 +58,8 @@ export type QaFlowStep = {
     type: string;
     label?: string;
     text?: string;
+    expectText?: string[];
+    expectNoConsoleErrors?: boolean;
     selector?: string;
     value?: string;
     url?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trylayout/qa",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Local browser QA runner and HTML reports for AI-built frontends.",
   "license": "MIT",
   "author": "Layout",