@trylayout/qa 0.1.2 → 0.1.3

package/README.md

@@ -7,6 +7,7 @@ The core loop is intentionally local:
 ```bash
 npx @trylayout/qa init
 npx @trylayout/qa run --target-url http://localhost:5173 --scenario happy_path --open
+npx @trylayout/qa run --target-url http://localhost:5173 --scenario happy_path --viewport 390x844 --open
 ```
 
 No account, upload, hosted service, or external docs are required.
@@ -88,7 +89,7 @@ npx @trylayout/qa run \
 Each run writes:
 
 ```text
-.layout/runs/<timestamp-scenario>/
+.layout/runs/<timestamp-scenario-viewport>/
   index.html
   result.json
   screenshots/
@@ -113,6 +114,7 @@ Options:
 --scenario <name>      Mock scenario to activate. Defaults to happy_path.
 --flows <path>         Flow manifest path. Defaults to .layout/qa-flows.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.
@@ -172,6 +174,8 @@ Step fields:
 - `label`: optional human-readable report label.
 - `screenshot`: set `true` to capture a screenshot after the step.
 - `timeoutMs`: optional per-step timeout.
+- `tolerance`: optional pixel tolerance for layout assertions.
+- `minWidth`, `maxWidth`, `minHeight`, `maxHeight`: optional `assert_box` constraints.
 
 Supported step types:
 
@@ -181,6 +185,9 @@ Supported step types:
 - `assert_visible_text`: require visible `text`.
 - `wait_for_text`: alias for a visible text wait.
 - `assert_url`: require current URL to equal `url` or contain `contains`.
+- `assert_no_horizontal_overflow`: require the page not to overflow the viewport horizontally.
+- `assert_in_viewport`: require a `selector` or visible `text` to have a nonzero box intersecting the viewport.
+- `assert_box`: require a `selector` or visible `text` to satisfy width/height constraints.
 - `screenshot`: capture a screenshot checkpoint.
 
 Examples:
@@ -197,6 +204,43 @@ Examples:
 { "id": "settings_url", "type": "assert_url", "contains": "/settings" }
 ```
 
+```json
+{ "id": "no_overflow", "type": "assert_no_horizontal_overflow" }
+```
+
+```json
+{ "id": "main_visible", "type": "assert_in_viewport", "selector": "main" }
+```
+
+```json
+{
+  "id": "primary_cta_size",
+  "type": "assert_box",
+  "selector": "[data-qa='primary-cta']",
+  "minWidth": 120,
+  "maxHeight": 56
+}
+```
+
+## Viewports
+
+The runner defaults to the desktop viewport, `1280x900`. Use `--viewport` to run the same flow at a preset or exact size:
+
+```bash
+npx @trylayout/qa run --target-url http://localhost:5173 --viewport desktop
+npx @trylayout/qa run --target-url http://localhost:5173 --viewport tablet
+npx @trylayout/qa run --target-url http://localhost:5173 --viewport mobile
+npx @trylayout/qa run --target-url http://localhost:5173 --viewport 390x844
+```
+
+Presets:
+
+- `desktop`: `1280x900`
+- `tablet`: `768x1024`
+- `mobile`: `390x844`
+
+The selected viewport is written to `result.json`, shown in the HTML report, and included in the run directory name.
+
 ## Mock Scenarios
 
 Before the app loads, the runner sets:
@@ -281,6 +325,8 @@ This package is intentionally small:
 - It does run Playwright against an already-running frontend.
 - It does write local screenshots and an HTML report.
 - It does support deterministic scenario switching.
+- It does support explicit viewport sizing.
+- It does support lightweight layout assertions.
 - It does not build or host your app.
 - It does not upload results.
 - It does not perform AI review by itself.

package/build/cli/layoutQa.js

@@ -9,6 +9,7 @@ const path_1 = __importDefault(require("path"));
 const flows_1 = require("../flows");
 const runner_1 = require("../runner");
 const report_1 = require("../report");
+const viewports_1 = require("../viewports");
 function printHelp() {
     process.stdout.write(`Layout QA CLI
 
@@ -28,6 +29,7 @@ Options:
   --scenario <name>      Mock scenario to activate. Defaults to happy_path.
   --flows <path>         Flow manifest path. Defaults to .layout/qa-flows.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.
@@ -59,6 +61,7 @@ function parseArgs(args) {
         scenario: readFlag(args, '--scenario') || 'happy_path',
         flowsPath: readFlag(args, '--flows'),
         outDir: readFlag(args, '--out'),
+        viewport: (0, viewports_1.parseViewport)(readFlag(args, '--viewport')),
         timeoutMs: parsedTimeoutMs,
         headed: hasFlag(args, '--headed'),
         json: hasFlag(args, '--json'),
@@ -92,6 +95,9 @@ function printHumanSummary(input) {
     process.stdout.write(`\nLayout QA ${passed ? 'passed' : 'failed'}\n` +
         `Scenario: ${input.scenario}\n` +
         `Target: ${input.targetUrl}\n` +
+        `Viewport: ${input.result.viewport
+            ? (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` +
         `Manifest: ${input.manifestFound ? input.manifestPath : 'not found; default smoke'}\n\n`);
@@ -142,11 +148,12 @@ async function runCommand(options) {
             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);
+        result = (0, runner_1.buildRunnerErrorResult)(message, options.viewport);
     }
     const artifacts = await (0, report_1.writeArtifacts)({
         outDir: options.outDir,
@@ -162,6 +169,7 @@ async function runCommand(options) {
             status: passed ? 'passed' : 'failed',
             scenario: options.scenario,
             targetUrl: options.targetUrl,
+            viewport: options.viewport,
             manifestPath,
             manifestFound,
             artifacts,

package/build/flows.js

@@ -59,6 +59,11 @@ function normalizeFlowStep(value, index) {
         exact: booleanValue(value.exact),
         screenshot: booleanValue(value.screenshot, type === 'screenshot'),
         timeoutMs: numberValue(value.timeoutMs),
+        tolerance: numberValue(value.tolerance),
+        minWidth: numberValue(value.minWidth),
+        maxWidth: numberValue(value.maxWidth),
+        minHeight: numberValue(value.minHeight),
+        maxHeight: numberValue(value.maxHeight),
     };
 }
 function normalizeFlow(value, index) {

package/build/index.d.ts

@@ -2,3 +2,4 @@ export * from './flows';
 export * from './report';
 export * from './runner';
 export * from './types';
+export * from './viewports';

package/build/index.js

@@ -18,3 +18,4 @@ __exportStar(require("./flows"), exports);
 __exportStar(require("./report"), exports);
 __exportStar(require("./runner"), exports);
 __exportStar(require("./types"), exports);
+__exportStar(require("./viewports"), exports);

package/build/report.js

@@ -12,6 +12,7 @@ const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const flows_1 = require("./flows");
 const runner_1 = require("./runner");
+const viewports_1 = require("./viewports");
 function safeName(value) {
     return value.replace(/[^a-zA-Z0-9_-]+/g, '_').replace(/^_+|_+$/g, '');
 }
@@ -111,6 +112,7 @@ function renderReport(input) {
         : '';
     const resultHref = relativeHref(input.runDir, input.resultPath);
     const flow = input.result.flow;
+    const viewport = input.result.viewport;
     const failedCheckCount = input.result.checks.filter(check => !check.passed).length;
     return `<!doctype html>
 <html lang="en">
@@ -150,7 +152,7 @@ function renderReport(input) {
     section { margin-top: 28px; }
     a { color: inherit; }
     .eyebrow { color: var(--muted); font-size: .78rem; font-weight: 650; text-transform: uppercase; letter-spacing: .04em; }
-    .summary { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 12px; margin-top: 24px; }
+    .summary { display: grid; grid-template-columns: repeat(5, minmax(0, 1fr)); gap: 12px; margin-top: 24px; }
     .metric, .panel, .step, .issue {
       border: 1px solid var(--line);
       background: var(--panel);
@@ -215,6 +217,7 @@ function renderReport(input) {
       <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>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>
     </dl>
 
@@ -265,7 +268,8 @@ async function writeArtifacts(input) {
         ? path_1.default.resolve(process.cwd(), input.outDir)
         : await (0, flows_1.resolveDefaultPath)('.layout/runs');
     const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-    const runDir = path_1.default.join(outRoot, `${stamp}-${safeName(input.scenario)}`);
+    const viewportId = input.result.viewport?.id || 'viewport_unknown';
+    const runDir = path_1.default.join(outRoot, `${stamp}-${safeName(input.scenario)}-${safeName(viewportId)}`);
     const screenshotsDir = path_1.default.join(runDir, 'screenshots');
     await promises_1.default.mkdir(screenshotsDir, { recursive: true });
     const screenshots = [];

package/build/runner.d.ts

@@ -1,10 +1,11 @@
-import { LoadedQaFlow, QaTestRunCheck, QaTestRunFlowResult, QaTestRunIssue, QaTestRunNextAction, QaTestRunResult } from './types';
+import { LoadedQaFlow, QaTestRunCheck, QaTestRunFlowResult, QaTestRunIssue, QaTestRunNextAction, QaTestRunResult, QaViewport } from './types';
 export declare function runLayoutQaBrowser(input: {
     targetUrl: string;
     scenario: string;
     flow: LoadedQaFlow;
     timeoutMs?: number;
     headless?: boolean;
+    viewport?: QaViewport;
 }): Promise<{
     finalUrl: string;
     title: string;
@@ -13,10 +14,11 @@ export declare function runLayoutQaBrowser(input: {
     screenshotDataUrl: string | undefined;
     screenshotBytes: number;
     bodyTextSample: string;
+    viewport: QaViewport;
     checks: QaTestRunCheck[];
     issues: QaTestRunIssue[];
     flow: QaTestRunFlowResult;
     nextAction: QaTestRunNextAction;
 }>;
-export declare function buildRunnerErrorResult(message: string): QaTestRunResult;
+export declare function buildRunnerErrorResult(message: string, viewport?: QaViewport): QaTestRunResult;
 export declare function isQaRunPassed(result: QaTestRunResult): boolean;

package/build/runner.js

@@ -38,6 +38,7 @@ exports.buildRunnerErrorResult = buildRunnerErrorResult;
 exports.isQaRunPassed = isQaRunPassed;
 const url_1 = require("url");
 const flows_1 = require("./flows");
+const viewports_1 = require("./viewports");
 function truncate(value, maxLength = 1000) {
     return value.length <= maxLength ? value : `${value.slice(0, maxLength)}...`;
 }
@@ -230,6 +231,131 @@ function requireStepValue(value, field) {
     }
     return value;
 }
+function stepLocator(page, step, exact, requiredField) {
+    if (step.selector) {
+        return page.locator(step.selector).first();
+    }
+    const text = requireStepValue(step.text, requiredField);
+    return page.getByText(text, { exact }).first();
+}
+function formatBox(box) {
+    return `${Math.round(box.width)}x${Math.round(box.height)} at ${Math.round(box.x)},${Math.round(box.y)}`;
+}
+async function assertNoHorizontalOverflow(page, tolerance = 1) {
+    const result = (await page.evaluate(checkTolerance => {
+        function elementLabel(element) {
+            const tagName = element.tagName.toLowerCase();
+            const testId = element.getAttribute('data-testid') ||
+                element.getAttribute('data-qa') ||
+                '';
+            if (testId)
+                return `${tagName}[data-qa/testid="${testId}"]`;
+            if (element.id)
+                return `${tagName}#${element.id}`;
+            const className = Array.from(element.classList).slice(0, 3).join('.');
+            return className ? `${tagName}.${className}` : tagName;
+        }
+        const root = document.documentElement;
+        const body = document.body;
+        const viewportWidth = window.innerWidth;
+        const scrollWidth = Math.max(root?.scrollWidth || 0, body?.scrollWidth || 0);
+        const overflowPx = Math.max(0, scrollWidth - viewportWidth);
+        const offenders = Array.from(document.body?.querySelectorAll('*') || [])
+            .map(element => {
+            const rect = element.getBoundingClientRect();
+            if (rect.width <= 0 || rect.height <= 0)
+                return null;
+            const rightOverflow = Math.max(0, rect.right - viewportWidth);
+            const leftOverflow = Math.max(0, -rect.left);
+            const elementOverflowPx = Math.max(rightOverflow, leftOverflow);
+            if (elementOverflowPx <= checkTolerance)
+                return null;
+            return {
+                label: elementLabel(element),
+                x: Math.round(rect.x),
+                width: Math.round(rect.width),
+                right: Math.round(rect.right),
+                overflowPx: Math.round(elementOverflowPx),
+            };
+        })
+            .filter((entry) => Boolean(entry))
+            .sort((a, b) => b.overflowPx - a.overflowPx)
+            .slice(0, 5);
+        return {
+            viewportWidth,
+            scrollWidth,
+            overflowPx,
+            offenders,
+        };
+    }, tolerance));
+    if (result.overflowPx > tolerance) {
+        const offenderDetail = result.offenders.length
+            ? ` Offenders: ${result.offenders
+                .map(offender => `${offender.label} overflowed ${offender.overflowPx}px (x=${offender.x}, width=${offender.width}, right=${offender.right})`)
+                .join('; ')}.`
+            : '';
+        throw new Error(`Horizontal overflow detected: document width ${result.scrollWidth}px exceeds viewport ${result.viewportWidth}px by ${result.overflowPx}px.${offenderDetail}`);
+    }
+    return `No horizontal overflow: document width ${result.scrollWidth}px, viewport ${result.viewportWidth}px.`;
+}
+async function assertElementInViewport(input) {
+    const locator = stepLocator(input.page, input.step, input.exact, 'selector or text');
+    await locator.waitFor({ state: 'visible', timeout: input.timeoutMs });
+    const box = await locator.boundingBox();
+    if (!box || box.width <= 0 || box.height <= 0) {
+        throw new Error('Expected element to have a visible nonzero layout box.');
+    }
+    const viewport = input.page.viewportSize();
+    if (!viewport) {
+        throw new Error('Could not read the current browser viewport size.');
+    }
+    const tolerance = input.step.tolerance ?? 1;
+    const right = box.x + box.width;
+    const bottom = box.y + box.height;
+    const visibleWidth = Math.min(right, viewport.width) - Math.max(box.x, 0);
+    const visibleHeight = Math.min(bottom, viewport.height) - Math.max(box.y, 0);
+    if (visibleWidth <= tolerance || visibleHeight <= tolerance) {
+        throw new Error(`Expected element to intersect viewport ${viewport.width}x${viewport.height}, got box ${formatBox(box)}.`);
+    }
+    return `Element intersects viewport ${viewport.width}x${viewport.height}: ${formatBox(box)}.`;
+}
+function definedBoxConstraints(step) {
+    return [
+        ['minWidth', step.minWidth],
+        ['maxWidth', step.maxWidth],
+        ['minHeight', step.minHeight],
+        ['maxHeight', step.maxHeight],
+    ];
+}
+async function assertElementBox(input) {
+    const constraints = definedBoxConstraints(input.step).filter(([, value]) => value !== undefined);
+    if (constraints.length === 0) {
+        throw new Error('assert_box requires at least one of minWidth, maxWidth, minHeight, or maxHeight.');
+    }
+    const locator = stepLocator(input.page, input.step, input.exact, 'selector or text');
+    await locator.waitFor({ state: 'visible', timeout: input.timeoutMs });
+    const box = await locator.boundingBox();
+    if (!box || box.width <= 0 || box.height <= 0) {
+        throw new Error('Expected element to have a visible nonzero layout box.');
+    }
+    const failures = [];
+    if (input.step.minWidth !== undefined && box.width < input.step.minWidth) {
+        failures.push(`width ${Math.round(box.width)}px is below minWidth ${input.step.minWidth}px`);
+    }
+    if (input.step.maxWidth !== undefined && box.width > input.step.maxWidth) {
+        failures.push(`width ${Math.round(box.width)}px is above maxWidth ${input.step.maxWidth}px`);
+    }
+    if (input.step.minHeight !== undefined && box.height < input.step.minHeight) {
+        failures.push(`height ${Math.round(box.height)}px is below minHeight ${input.step.minHeight}px`);
+    }
+    if (input.step.maxHeight !== undefined && box.height > input.step.maxHeight) {
+        failures.push(`height ${Math.round(box.height)}px is above maxHeight ${input.step.maxHeight}px`);
+    }
+    if (failures.length > 0) {
+        throw new Error(`Element box ${formatBox(box)} failed constraints: ${failures.join('; ')}.`);
+    }
+    return `Element box matched constraints: ${formatBox(box)}.`;
+}
 async function caseSensitiveGoto(page, targetUrl, timeoutMs) {
     return page.goto(targetUrl, {
         waitUntil: 'domcontentloaded',
@@ -287,6 +413,25 @@ async function executeFlowStep(input) {
         }
         return `URL matched: ${currentUrl}`;
     }
+    if (input.step.type === 'assert_no_horizontal_overflow') {
+        return assertNoHorizontalOverflow(input.page, input.step.tolerance ?? 1);
+    }
+    if (input.step.type === 'assert_in_viewport') {
+        return assertElementInViewport({
+            page: input.page,
+            step: input.step,
+            exact,
+            timeoutMs: stepTimeout,
+        });
+    }
+    if (input.step.type === 'assert_box') {
+        return assertElementBox({
+            page: input.page,
+            step: input.step,
+            exact,
+            timeoutMs: stepTimeout,
+        });
+    }
     if (input.step.type === 'screenshot') {
         return 'Captured screenshot checkpoint.';
     }
@@ -345,13 +490,14 @@ async function runFlow(input) {
 }
 async function runLayoutQaBrowser(input) {
     const timeoutMs = input.timeoutMs || flows_1.DEFAULT_TEST_TIMEOUT_MS;
+    const viewport = input.viewport || viewports_1.DEFAULT_VIEWPORT;
     const issues = [];
     const { chromium } = await Promise.resolve().then(() => __importStar(require('playwright')));
     const browser = await chromium.launch({ headless: input.headless !== false });
     try {
         const context = await browser.newContext({
             ignoreHTTPSErrors: true,
-            viewport: { width: 1280, height: 900 },
+            viewport: { width: viewport.width, height: viewport.height },
         });
         await context.addInitScript({
             content: `
@@ -444,6 +590,7 @@ async function runLayoutQaBrowser(input) {
             screenshotDataUrl,
             screenshotBytes: screenshot.byteLength,
             bodyTextSample: pageState.bodyTextSample,
+            viewport,
             checks,
             issues: issues.slice(0, 20),
             flow: flowResult,
@@ -464,8 +611,9 @@ async function runLayoutQaBrowser(input) {
         });
     }
 }
-function buildRunnerErrorResult(message) {
+function buildRunnerErrorResult(message, viewport = viewports_1.DEFAULT_VIEWPORT) {
     return {
+        viewport,
         checks: [
             {
                 id: 'runner_error',
@@ -489,6 +637,7 @@ function buildRunnerErrorResult(message) {
                 'Confirm the target URL is reachable by the runner.',
                 'Confirm the app is served with the Layout mock env flag enabled.',
                 'Retry after the target loads consistently in a browser.',
+                `Viewport used for this run: ${(0, viewports_1.formatViewport)(viewport)}.`,
             ],
         },
     };

package/build/types.d.ts

@@ -27,6 +27,11 @@ export type QaTestRunFlowStepResult = {
     screenshotDataUrl?: string;
     screenshotBytes?: number;
 };
+export type QaViewport = {
+    id: string;
+    width: number;
+    height: number;
+};
 export type QaTestRunFlowResult = {
     id: string;
     name: string;
@@ -41,6 +46,7 @@ export type QaTestRunResult = {
     screenshotDataUrl?: string;
     screenshotBytes?: number;
     bodyTextSample?: string;
+    viewport?: QaViewport;
     checks: QaTestRunCheck[];
     issues: QaTestRunIssue[];
     flow?: QaTestRunFlowResult;
@@ -58,6 +64,11 @@ export type QaFlowStep = {
     exact?: boolean;
     screenshot?: boolean;
     timeoutMs?: number;
+    tolerance?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
 };
 export type QaFlowDefinition = {
     id: string;

package/build/viewports.d.ts

@@ -0,0 +1,5 @@
+import { QaViewport } from './types';
+export declare const DEFAULT_VIEWPORT: QaViewport;
+export declare const VIEWPORT_PRESETS: Record<string, QaViewport>;
+export declare function parseViewport(value?: string): QaViewport;
+export declare function formatViewport(viewport: QaViewport): string;

package/build/viewports.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VIEWPORT_PRESETS = exports.DEFAULT_VIEWPORT = void 0;
+exports.parseViewport = parseViewport;
+exports.formatViewport = formatViewport;
+exports.DEFAULT_VIEWPORT = {
+    id: 'desktop',
+    width: 1280,
+    height: 900,
+};
+exports.VIEWPORT_PRESETS = {
+    desktop: exports.DEFAULT_VIEWPORT,
+    tablet: {
+        id: 'tablet',
+        width: 768,
+        height: 1024,
+    },
+    mobile: {
+        id: 'mobile',
+        width: 390,
+        height: 844,
+    },
+};
+function cloneViewport(viewport) {
+    return { ...viewport };
+}
+function parseViewport(value) {
+    const raw = (value || '').trim().toLowerCase();
+    if (!raw)
+        return cloneViewport(exports.DEFAULT_VIEWPORT);
+    const preset = exports.VIEWPORT_PRESETS[raw];
+    if (preset)
+        return cloneViewport(preset);
+    const match = raw.match(/^(\d{2,5})x(\d{2,5})$/);
+    if (!match) {
+        throw new Error(`Unsupported viewport "${value}". Use desktop, tablet, mobile, or WIDTHxHEIGHT.`);
+    }
+    const width = Number(match[1]);
+    const height = Number(match[2]);
+    if (!Number.isInteger(width) ||
+        !Number.isInteger(height) ||
+        width <= 0 ||
+        height <= 0) {
+        throw new Error(`Viewport "${value}" must use positive integer dimensions.`);
+    }
+    return {
+        id: `${width}x${height}`,
+        width,
+        height,
+    };
+}
+function formatViewport(viewport) {
+    return `${viewport.id} (${viewport.width}x${viewport.height})`;
+}

package/package.json

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