@trylayout/qa 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # Layout QA
 
-Layout QA is a local browser QA protocol and runner for AI-built frontends. It runs deterministic Playwright-style flows against a local or preview URL, captures the screenshot sequence, checks browser health, and writes a static HTML report.
+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.
 
 The core loop is intentionally local:
 
@@ -9,16 +9,31 @@ npx @trylayout/qa init
 npx @trylayout/qa run --target-url http://localhost:5173 --scenario happy_path --open
 ```
 
-## Why this exists
+No account, upload, hosted service, or external docs are required.
+
+Package names:
+
+- Canonical npm package: `@trylayout/qa`
+- Convenience npm alias: `layout-qa`
+- CLI binaries: `trylayout` and `layout-qa`
+
+These commands are equivalent:
+
+```bash
+npx @trylayout/qa run --target-url http://localhost:5173 --scenario happy_path --open
+npx layout-qa run --target-url http://localhost:5173 --scenario happy_path --open
+```
+
+## 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:
 
-- Wire app mocks behind a local env flag such as `VITE_LAYOUT_QA_MOCKS=1`.
-- Keep deterministic API/auth scenarios in the app repo.
+- Wire deterministic API/auth mocks behind a local env flag such as `VITE_LAYOUT_QA_MOCKS=1`.
+- Switch mock 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.
 
-Layout does not require uploading screenshots or source code. Hosted reports, PR comments, and AI review notes can be layered on later.
+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.
 
 ## Install
 
@@ -28,6 +43,12 @@ Use it directly with `npx`:
 npx @trylayout/qa run --target-url http://localhost:5173
 ```
 
+The package is also available under the unscoped alias `layout-qa` for agents and tools that infer the package name from this repository:
+
+```bash
+npx layout-qa run --target-url http://localhost:5173
+```
+
 Or install it in a project:
 
 ```bash
@@ -35,21 +56,27 @@ npm install --save-dev @trylayout/qa
 npx trylayout run --target-url http://localhost:5173
 ```
 
-The package uses Playwright. If your environment does not already have the browser binaries, run:
+The package uses Playwright. If your environment does not already have Chromium installed for Playwright, run:
 
 ```bash
 npx playwright install chromium
 ```
 
-## Commands
+## Quick Start
 
-Initialize a starter flow file:
+Create a starter flow manifest:
 
 ```bash
 npx @trylayout/qa init
 ```
 
-Run a flow:
+Start your app with whatever mock flag your project uses:
+
+```bash
+VITE_LAYOUT_QA_MOCKS=1 npm run dev
+```
+
+Run a scenario:
 
 ```bash
 npx @trylayout/qa run \
@@ -58,19 +85,6 @@ npx @trylayout/qa run \
   --open
 ```
 
-Useful options:
-
-```text
---target-url <url>     URL of the running frontend to test.
---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.
---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.
-```
-
 Each run writes:
 
 ```text
@@ -84,14 +98,34 @@ Each run writes:
 
 The process exits `0` on pass and `1` on failure, so the same command can run in CI.
 
+## Commands
+
+```text
+trylayout init [options]
+trylayout run --target-url <url> [options]
+layout-qa run --target-url <url> [options]
+```
+
+Options:
+
+```text
+--target-url <url>     URL of the running frontend to test.
+--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.
+--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.
+--force                Overwrite an existing flow file during init.
+```
+
 ## Flow Manifest
 
 Default path: `.layout/qa-flows.json`.
 
 ```json
 {
-  "$schema": "https://trylayout.com/schemas/qa-flows.v1.json",
-  "docsUrl": "https://trylayout.com/docs/qa",
   "schemaVersion": 1,
   "flows": [
     {
@@ -105,6 +139,12 @@ Default path: `.layout/qa-flows.json`.
           "type": "assert_visible_text",
           "text": "Dashboard",
           "screenshot": true
+        },
+        {
+          "id": "open_settings",
+          "type": "click",
+          "text": "Settings",
+          "screenshot": true
         }
       ]
     }
@@ -112,6 +152,27 @@ Default path: `.layout/qa-flows.json`.
 }
 ```
 
+Top-level fields:
+
+- `schemaVersion`: currently `1`.
+- `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.
+- `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.
+- `label`: optional human-readable report label.
+- `screenshot`: set `true` to capture a screenshot after the step.
+- `timeoutMs`: optional per-step timeout.
+
 Supported step types:
 
 - `goto`: navigate to `url`.
@@ -122,14 +183,36 @@ Supported step types:
 - `assert_url`: require current URL to equal `url` or contain `contains`.
 - `screenshot`: capture a screenshot checkpoint.
 
-The runner sets these before the app loads:
+Examples:
+
+```json
+{ "id": "open_settings", "type": "click", "text": "Settings" }
+```
+
+```json
+{ "id": "email", "type": "fill", "selector": "input[name='email']", "value": "layout@example.com" }
+```
+
+```json
+{ "id": "settings_url", "type": "assert_url", "contains": "/settings" }
+```
+
+## Mock Scenarios
+
+Before the app loads, the runner sets:
 
 ```js
 localStorage.setItem("layout.qa.scenario", "<scenario>");
 sessionStorage.setItem("layout.qa.runner", "1");
 ```
 
-Your app can use `layout.qa.scenario` to switch deterministic mock states. The `layout.qa.runner` flag is useful for hiding local-only QA switchers from screenshots.
+Your app can use `layout.qa.scenario` to switch deterministic mock states:
+
+- `happy_path`: normal populated data.
+- `empty`: successful responses with empty states.
+- `error`: failed or error responses that should render recovery UI.
+
+The `layout.qa.runner` flag is useful for hiding local-only QA switchers from screenshots.
 
 ## Agent Setup Prompt
 
@@ -138,24 +221,68 @@ Paste this into your coding agent inside the frontend repo:
 ```text
 Set up Layout QA for this web app.
 
-Docs: https://trylayout.com/docs/qa
-Flow schema: https://trylayout.com/schemas/qa-flows.v1.json
-
-Add deterministic mock API/auth states behind a local-only env flag such as VITE_LAYOUT_QA_MOCKS=1. Use the scenario key localStorage["layout.qa.scenario"] with at least happy_path, empty, and error states. Keep mocks inside the app test/dev setup; do not add a standalone mock server.
-
-Add .layout/qa-flows.json with one smoke flow for the highest-value page and screenshot checkpoints after meaningful user-visible states. Prefer visible text and stable selectors. Hide any local QA scenario switcher when sessionStorage["layout.qa.runner"] === "1".
-
-Then run:
+Goal:
+Create a local-only browser QA loop that an agent can run while changing frontend code.
+
+Rules:
+- Do not add a standalone mock server.
+- Do not require a hosted Layout service.
+- Keep all mock data local to this app.
+- Gate mocks behind a local-only env flag such as VITE_LAYOUT_QA_MOCKS=1, NEXT_PUBLIC_LAYOUT_QA_MOCKS=1, or the framework-appropriate equivalent.
+- Use localStorage["layout.qa.scenario"] to select at least happy_path, empty, and error mock states.
+- Hide any local QA switcher or debug controls when sessionStorage["layout.qa.runner"] === "1".
+
+Implementation:
+- Add deterministic API fixtures for the highest-value frontend route.
+- If the app has a central auth/session abstraction, add a deterministic mock 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.
+- Prefer visible text and stable selectors.
+- Add screenshot checkpoints after meaningful user-visible states.
+
+Run:
 npx @trylayout/qa run --target-url <local app url> --scenario happy_path --open
+npx @trylayout/qa run --target-url <local app url> --scenario empty --open
+npx @trylayout/qa run --target-url <local app url> --scenario error --open
 ```
 
-## npm Publishing
+## CI Example
+
+```yaml
+name: Layout QA
+
+on:
+  pull_request:
+
+jobs:
+  qa:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          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
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: layout-qa-report
+          path: .layout/runs
+```
 
-This repo is configured for a public scoped npm package:
+## Current Scope
 
-```bash
-npm login
-npm publish --access public
-```
+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 not build or host your app.
+- It does not upload results.
+- It does not perform AI review by itself.
 
-If the `@trylayout` npm scope does not exist yet, create it in npm first, then rerun publish from this repo.
+Those hosted/reporting layers can be added later without changing the local protocol.

package/build/cli/layoutQa.js

@@ -15,7 +15,9 @@ function printHelp() {
 Usage:
   trylayout init [options]
   trylayout run --target-url <url> [options]
+  layout-qa run --target-url <url> [options]
   npx @trylayout/qa run --target-url <url> [options]
+  npx layout-qa run --target-url <url> [options]
 
 Commands:
   init                  Write a starter .layout/qa-flows.json.

package/build/flows.d.ts

@@ -2,7 +2,7 @@ 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 QA_DOCS_URL = "https://trylayout.com/docs/qa";
+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 parseFlowManifestContent(content: string, scenario: string): LoadedQaFlow | null;
@@ -17,8 +17,6 @@ export declare function loadFlow(input: {
     manifestFound: boolean;
 }>;
 export declare function starterFlowManifest(): {
-    $schema: string;
-    docsUrl: string;
     schemaVersion: number;
     flows: {
         id: string;

package/build/flows.js

@@ -16,7 +16,7 @@ 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.QA_DOCS_URL = 'https://trylayout.com/docs/qa';
+exports.QA_DOCS_URL = 'https://github.com/Layout-App/layout-qa#readme';
 function getTestTimeoutMs() {
     const value = Number(process.env.LAYOUT_QA_TEST_TIMEOUT_MS);
     return Number.isFinite(value) && value > 0 ? value : exports.DEFAULT_TEST_TIMEOUT_MS;
@@ -159,8 +159,6 @@ async function loadFlow(input) {
 }
 function starterFlowManifest() {
     return {
-        $schema: 'https://trylayout.com/schemas/qa-flows.v1.json',
-        docsUrl: exports.QA_DOCS_URL,
         schemaVersion: 1,
         flows: [
             {

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@trylayout/qa",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Local browser QA runner and HTML reports for AI-built frontends.",
   "license": "MIT",
   "author": "Layout",
-  "homepage": "https://trylayout.com/docs/qa",
+  "homepage": "https://github.com/Layout-App/layout-qa#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Layout-App/layout-qa.git"
@@ -21,6 +21,7 @@
     "ai-agents"
   ],
   "bin": {
+    "layout-qa": "build/cli/layoutQa.js",
     "trylayout": "build/cli/layoutQa.js"
   },
   "files": [