@uzulla/voreux 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 uzulla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# Voreux
+
+Voreux は、**Stagehand + Vitest** ベースの E2E テストフレームワークです。
+
+AI に「クリックして」「入力して」と指示するだけで、Web ブラウザ操作を自動化するテストを書けます。
+
+## 特徴
+
+- **AI ファースト**: LLM に自然な指示語でブラウザ操作をさせる
+- **自己修復**: 要素が見つからなくなっても自動でリトライ
+- **スクリーンショット比較**: ビジュアルリグレッションも検出
+- **録画対応**: テスト実行の様子を動画出力
+
+## インストール
+
+```bash
+npm install @uzulla/voreux
+# または
+pnpm add @uzulla/voreux
+```
+
+**必須環境**
+
+- Node.js >= 22.x
+- pnpm >= 10.x（推奨）または npm
+- Windows ユーザーは **WSL2** が必要です
+
+## クイックスタート
+
+```bash
+# プロジェクトの雛形を生成
+npx @uzulla/voreux init my-e2e
+cd my-e2e
+
+# 依存をインストール
+pnpm install
+
+# OPENAI_API_KEY を設定
+cp .env.example .env
+# .env の OPENAI_API_KEY を実際のキーに置き換える
+
+# テストを実行
+pnpm test
+```
+
+## 最初のテストを書く
+
+```ts
+import { defineScenarioSuite } from "@uzulla/voreux";
+
+const steps = [
+  {
+    name: "load page",
+    selfHeal: false,
+    run: async (ctx) => {
+      await ctx.page.goto("https://example.com/");
+    },
+  },
+];
+
+defineScenarioSuite({
+  suiteName: "example",
+  originUrl: "https://example.com/",
+  steps,
+});
+```
+
+## 設定
+
+### 環境変数
+
+| 変数 | 既定値 | 説明 |
+|---|---|---|
+| `OPENAI_API_KEY` | **必須** | OpenAI API キー |
+| `SELF_HEAL` | `0` | `1` で自己修復を有効化 |
+| `STAGEHAND_MODEL` | `openai/gpt-4o` | 使用するモデル |
+| `E2E_HEADLESS` | `false` | `1` でヘッドレス実行 |
+
+## ライセンス
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+import { spawnSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { parseArgs } from "util";
+const PKG_VERSION = JSON.parse(fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf-8")).version;
+const HELP_TEXT = `Voreux — Stagehand + Vitest E2E testing framework
+
+Usage:
+  voreux init [dir] [--force]  Scaffold a project (default: skips existing files)
+  voreux test [pattern]         Run vitest tests (default: all)
+  voreux --help                Show this help
+  voreux --version             Show version
+
+Options:
+  --force, -f   Overwrite existing files during init
+
+Examples:
+  voreux init my-e2e
+  voreux init my-e2e --force   (overwrites any existing files)
+  cd my-e2e
+  # add OPENAI_API_KEY to .env
+  voreux test
+
+For more details, see: https://github.com/uzulla/voreux`;
+const INIT_TEMPLATE_FILES = {
+    "package.json": JSON.stringify({
+        name: "my-voreux-project",
+        version: "0.1.0",
+        type: "module",
+        private: true,
+        scripts: {
+            test: "vitest run",
+            "test:self-heal": "cross-env SELF_HEAL=1 vitest run",
+            build: "tsc --noEmit",
+        },
+        dependencies: {
+            "@uzulla/voreux": `^${PKG_VERSION}`,
+            zod: "^3.25.76",
+        },
+        devDependencies: {
+            "@types/node": "^25.2.1",
+            "cross-env": "^10.1.0",
+            typescript: "^5.9.3",
+            vitest: "^4.0.18",
+        },
+    }, null, 2),
+    "vitest.config.ts": `import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    pool: "forks",
+    poolOptions: {
+      forks: {
+        singleFork: true,
+      },
+    },
+  },
+});
+`,
+    ".env.example": `OPENAI_API_KEY=sk-...`,
+    ".gitignore": `node_modules
+.env
+screenshots
+recordings
+baselines
+*.png
+*.mp4
+`,
+    "tsconfig.json": JSON.stringify({
+        compilerOptions: {
+            target: "ES2022",
+            module: "NodeNext",
+            moduleResolution: "NodeNext",
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+        },
+    }, null, 2),
+    "tests/example.test.ts": `import { defineScenarioSuite } from "@uzulla/voreux";
+
+const steps = [
+  {
+    name: "load page",
+    selfHeal: false,
+    run: async (ctx) => {
+      await ctx.page.goto("https://example.com/");
+    },
+  },
+];
+
+defineScenarioSuite({
+  suiteName: "example",
+  originUrl: "https://example.com/",
+  steps,
+});
+`,
+};
+async function cmdInit(targetDir, force) {
+    const resolved = targetDir ? path.resolve(targetDir) : process.cwd();
+    if (fs.existsSync(resolved) && !fs.statSync(resolved).isDirectory()) {
+        console.error(`voreux init: ${resolved} is a file, not a directory.`);
+        process.exit(1);
+    }
+    if (!fs.existsSync(resolved)) {
+        fs.mkdirSync(resolved, { recursive: true });
+        console.log(`Created directory: ${resolved}`);
+    }
+    for (const [relativePath, content] of Object.entries(INIT_TEMPLATE_FILES)) {
+        const filePath = path.join(resolved, relativePath);
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        if (fs.existsSync(filePath)) {
+            if (force) {
+                fs.writeFileSync(filePath, content, "utf-8");
+                console.log(`Overwritten: ${relativePath}`);
+            }
+            else {
+                console.log(`Skipped (exists): ${relativePath}`);
+            }
+        }
+        else {
+            fs.writeFileSync(filePath, content, "utf-8");
+            console.log(`Created: ${relativePath}`);
+        }
+    }
+    console.log(`\nScaffold complete! Next steps:\n` +
+        `  cd ${resolved}\n` +
+        `  pnpm install\n` +
+        `  cp .env.example .env\n` +
+        `  # add OPENAI_API_KEY to .env\n` +
+        `  pnpm test\n`);
+}
+async function cmdTest(pattern) {
+    const args = ["vitest", "run"];
+    if (pattern) {
+        args.push(pattern);
+    }
+    console.log(`Running vitest...`);
+    const result = spawnSync("pnpm", args, {
+        cwd: process.cwd(),
+        stdio: "inherit",
+        shell: false,
+    });
+    if (result.status !== 0) {
+        process.exit(result.status ?? 1);
+    }
+}
+async function main() {
+    const { values, positionals } = parseArgs({
+        options: {
+            force: { type: "boolean", short: "f" },
+            help: { type: "boolean", short: "h" },
+            version: { type: "boolean", short: "v" },
+        },
+        allowPositionals: true,
+    });
+    if (values.help) {
+        console.log(HELP_TEXT);
+        return;
+    }
+    if (values.version) {
+        console.log(`voreux ${PKG_VERSION}`);
+        return;
+    }
+    const [command, ...rest] = positionals;
+    switch (command) {
+        case "init":
+            await cmdInit(rest[0], values.force ?? false);
+            break;
+        case "test":
+            await cmdTest(rest[0]);
+            break;
+        case undefined:
+            console.log(HELP_TEXT);
+            break;
+        default:
+            console.error(`Unknown command: ${command}`);
+            console.log(`Run 'voreux --help' for usage.`);
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error("voreux: fatal error:", err);
+    process.exit(1);
+});

package/dist/config.d.ts

@@ -0,0 +1,35 @@
+export interface E2EFrameworkConfig {
+    stagehand: {
+        model: string;
+        cacheDir: string;
+    };
+    paths: {
+        screenshotsDir: string;
+        recordingsDir: string;
+        baselinesDir: string;
+    };
+    browser: {
+        headless: boolean;
+        viewport: {
+            width: number;
+            height: number;
+        };
+    };
+    videoRecording: {
+        frameIntervalMs: number;
+        injectFrameCount: number;
+    };
+    navigation: {
+        timeoutMs: number;
+        pollIntervalMs: number;
+    };
+    visualRegression: {
+        mismatchThreshold: number;
+    };
+}
+/**
+ * フレームワーク共通設定。
+ * 環境変数でオーバーライド可能にして、各プロジェクトで再利用しやすくする。
+ */
+export declare const frameworkConfig: E2EFrameworkConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,KAAK,EAAE;QACL,cAAc,EAAE,MAAM,CAAC;QACvB,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,OAAO,EAAE;QACP,QAAQ,EAAE,OAAO,CAAC;QAClB,QAAQ,EAAE;YACR,KAAK,EAAE,MAAM,CAAC;YACd,MAAM,EAAE,MAAM,CAAC;SAChB,CAAC;KACH,CAAC;IACF,cAAc,EAAE;QACd,eAAe,EAAE,MAAM,CAAC;QACxB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,UAAU,EAAE;QACV,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,gBAAgB,EAAE;QAChB,iBAAiB,EAAE,MAAM,CAAC;KAC3B,CAAC;CACH;AAwBD;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,kBAmC7B,CAAC"}

package/dist/config.js

@@ -0,0 +1,55 @@
+const toInt = (value, fallback) => {
+    if (!value)
+        return fallback;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) ? parsed : fallback;
+};
+const toFloat = (value, fallback) => {
+    if (!value)
+        return fallback;
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+};
+const toBool = (value, fallback) => {
+    if (!value)
+        return fallback;
+    if (value === "1" || value.toLowerCase() === "true")
+        return true;
+    if (value === "0" || value.toLowerCase() === "false")
+        return false;
+    return fallback;
+};
+const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+/**
+ * フレームワーク共通設定。
+ * 環境変数でオーバーライド可能にして、各プロジェクトで再利用しやすくする。
+ */
+export const frameworkConfig = {
+    stagehand: {
+        model: process.env.STAGEHAND_MODEL ?? "openai/gpt-4o",
+        cacheDir: process.env.STAGEHAND_CACHE_DIR ?? ".cache/stagehand-e2e",
+    },
+    paths: {
+        screenshotsDir: process.env.E2E_SCREENSHOTS_DIR ?? "screenshots",
+        recordingsDir: process.env.E2E_RECORDINGS_DIR ?? "recordings",
+        baselinesDir: process.env.E2E_BASELINES_DIR ?? "baselines",
+    },
+    browser: {
+        headless: toBool(process.env.E2E_HEADLESS, false),
+        viewport: {
+            width: toInt(process.env.E2E_VIEWPORT_WIDTH, 1280),
+            height: toInt(process.env.E2E_VIEWPORT_HEIGHT, 720),
+        },
+    },
+    videoRecording: {
+        frameIntervalMs: Math.max(1, toInt(process.env.E2E_FRAME_INTERVAL_MS, 500)),
+        injectFrameCount: Math.max(1, toInt(process.env.E2E_INJECT_FRAME_COUNT, 3)),
+    },
+    navigation: {
+        timeoutMs: Math.max(1, toInt(process.env.E2E_NAV_TIMEOUT_MS, 10000)),
+        pollIntervalMs: Math.max(1, toInt(process.env.E2E_NAV_POLL_INTERVAL_MS, 300)),
+    },
+    visualRegression: {
+        mismatchThreshold: clamp(toFloat(process.env.E2E_VISUAL_DIFF_THRESHOLD, 0.1), 0, 1),
+    },
+};

package/dist/context.d.ts

@@ -0,0 +1,32 @@
+import type { Stagehand } from "@browserbasehq/stagehand";
+import type { Recorder } from "./recording.js";
+import type { ScreenshotFn } from "./screenshot.js";
+export declare const SCREENSHOT_DIR: string;
+export declare const RECORDING_DIR: string;
+export declare const FRAMES_DIR: string;
+export declare const BASELINES_DIR: string;
+export declare const VISUAL_DIFF_THRESHOLD: number;
+export declare class VisualRegressionError extends Error {
+    diffPath: string;
+    mismatchRatio: number;
+    constructor(diffPath: string, mismatchRatio: number);
+}
+export interface TestContext {
+    stagehand: Stagehand;
+    page: any;
+    screenshot: ScreenshotFn;
+    recorder: Recorder;
+    originUrl: string;
+    /** act() 実行 → 新タブ or 同一タブ遷移を待って結果ページを返す */
+    actAndWaitForNav: (instruction: string, urlPattern: string) => Promise<any>;
+    /** ビューポートのスクリーンショットをベースラインと比較し、差異超過なら throw */
+    assertNoVisualRegression: (baselineName: string) => Promise<void>;
+    /** 現在のスクリーンショットをベースラインとして保存 */
+    saveCurrentBaseline: (baselineName: string) => void;
+    /** observe() 結果を一括ハイライト → screenshot → 録画フレーム注入 → ハイライト除去 */
+    highlightObserved: (actions: any[], screenshotName: string) => Promise<void>;
+    /** observe() で要素を探し、単一ハイライト → screenshot → 録画フレーム注入 → ハイライト除去 */
+    highlightTarget: (instruction: string, screenshotName: string) => Promise<void>;
+}
+export declare function createTestContext(stagehand: Stagehand, page: any, recorder: Recorder, screenshotFn: ScreenshotFn, originUrl: string): TestContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAQ1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAOpD,eAAO,MAAM,cAAc,QAE1B,CAAC;AACF,eAAO,MAAM,aAAa,QAAoD,CAAC;AAC/E,eAAO,MAAM,UAAU,QAAqC,CAAC;AAC7D,eAAO,MAAM,aAAa,QAAmD,CAAC;AAE9E,eAAO,MAAM,qBAAqB,QACkB,CAAC;AAMrD,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;gBACV,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM;CAQpD;AAMD,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,SAAS,CAAC;IACrB,IAAI,EAAE,GAAG,CAAC;IACV,UAAU,EAAE,YAAY,CAAC;IACzB,QAAQ,EAAE,QAAQ,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAElB,2CAA2C;IAC3C,gBAAgB,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IAE5E,+CAA+C;IAC/C,wBAAwB,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAElE,+BAA+B;IAC/B,mBAAmB,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,CAAC;IAEpD,6DAA6D;IAC7D,iBAAiB,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE,cAAc,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7E,iEAAiE;IACjE,eAAe,EAAE,CACf,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,GAAG,EACT,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,YAAY,EAC1B,SAAS,EAAE,MAAM,GAChB,WAAW,CA4Gb"}

package/dist/context.js

@@ -0,0 +1,112 @@
+import path from "path";
+import { frameworkConfig } from "./config.js";
+import { highlightElement, highlightElements, removeHighlights, } from "./highlight.js";
+import { compareWithBaseline, saveBaseline } from "./screenshot.js";
+// ----------------------------------------------------------------
+// 定数
+// ----------------------------------------------------------------
+export const SCREENSHOT_DIR = path.resolve(frameworkConfig.paths.screenshotsDir);
+export const RECORDING_DIR = path.resolve(frameworkConfig.paths.recordingsDir);
+export const FRAMES_DIR = path.join(RECORDING_DIR, "frames");
+export const BASELINES_DIR = path.resolve(frameworkConfig.paths.baselinesDir);
+export const VISUAL_DIFF_THRESHOLD = frameworkConfig.visualRegression.mismatchThreshold;
+// ----------------------------------------------------------------
+// VisualRegressionError
+// ----------------------------------------------------------------
+export class VisualRegressionError extends Error {
+    diffPath;
+    mismatchRatio;
+    constructor(diffPath, mismatchRatio) {
+        super(`Visual regression detected (${(mismatchRatio * 100).toFixed(1)}% mismatch). Diff: ${diffPath}`);
+        this.name = "VisualRegressionError";
+        this.diffPath = diffPath;
+        this.mismatchRatio = mismatchRatio;
+    }
+}
+export function createTestContext(stagehand, page, recorder, screenshotFn, originUrl) {
+    let lastComparisonSsPath = null;
+    const ctx = {
+        stagehand,
+        page,
+        recorder,
+        originUrl,
+        screenshot: screenshotFn,
+        async actAndWaitForNav(instruction, urlPattern) {
+            const initialPages = new Set(stagehand.context.pages());
+            await stagehand.act(instruction);
+            // 新タブ or 同一タブ遷移で URL が urlPattern にマッチするまでポーリング
+            const deadline = Date.now() + frameworkConfig.navigation.timeoutMs;
+            let resultPage = null;
+            while (Date.now() < deadline) {
+                // 新しく開いたページのみチェック
+                const newPages = stagehand.context
+                    .pages()
+                    .filter((p) => !initialPages.has(p));
+                const matchedPage = newPages.find((p) => p.url().includes(urlPattern));
+                if (matchedPage) {
+                    resultPage = matchedPage;
+                    break;
+                }
+                // 同一タブ遷移チェック
+                if (page.url().includes(urlPattern)) {
+                    resultPage = page;
+                    break;
+                }
+                await new Promise((r) => setTimeout(r, frameworkConfig.navigation.pollIntervalMs));
+            }
+            if (!resultPage) {
+                throw new Error(`Navigation failed: no page matching "${urlPattern}" found`);
+            }
+            if (resultPage !== page) {
+                await resultPage.waitForLoadState("domcontentloaded").catch(() => { });
+            }
+            return resultPage;
+        },
+        async assertNoVisualRegression(baselineName) {
+            const ssPath = path.join(SCREENSHOT_DIR, `${baselineName}.png`);
+            await page.screenshot({ path: ssPath });
+            lastComparisonSsPath = ssPath;
+            const diffPath = path.join(SCREENSHOT_DIR, `${baselineName}-diff.png`);
+            const comparison = compareWithBaseline(ssPath, baselineName, {
+                baselinesDir: BASELINES_DIR,
+                diffPath,
+            });
+            if (!comparison.skipped &&
+                comparison.mismatchRatio > VISUAL_DIFF_THRESHOLD) {
+                throw new VisualRegressionError(diffPath, comparison.mismatchRatio);
+            }
+        },
+        saveCurrentBaseline(baselineName) {
+            if (lastComparisonSsPath) {
+                saveBaseline(lastComparisonSsPath, baselineName, BASELINES_DIR);
+            }
+        },
+        async highlightObserved(actions, screenshotName) {
+            await highlightElements(page, actions);
+            try {
+                await screenshotFn(screenshotName);
+                await recorder.injectFrames(frameworkConfig.videoRecording.injectFrameCount);
+            }
+            finally {
+                await removeHighlights(page);
+            }
+        },
+        async highlightTarget(instruction, screenshotName) {
+            const targets = await stagehand.observe(instruction);
+            if (targets.length > 0) {
+                await highlightElement(page, targets[0].selector, {
+                    showCursor: true,
+                    label: "Click target",
+                });
+                try {
+                    await screenshotFn(screenshotName);
+                    await recorder.injectFrames(frameworkConfig.videoRecording.injectFrameCount);
+                }
+                finally {
+                    await removeHighlights(page);
+                }
+            }
+        },
+    };
+    return ctx;
+}

package/dist/highlight.d.ts

@@ -0,0 +1,31 @@
+/**
+ * DOM ベースのハイライト・カーソル可視化ヘルパー。
+ * page.evaluate() でオーバーレイを注入し、page.screenshot() に反映させる。
+ */
+interface HighlightElementOpts {
+    showCursor?: boolean;
+    label?: string;
+    overlayColor?: string;
+    borderColor?: string;
+}
+/**
+ * 単一要素をハイライト + オプションでカーソル表示。
+ * act() のクリック対象の可視化用。
+ */
+export declare function highlightElement(page: any, selector: string, opts?: HighlightElementOpts): Promise<void>;
+interface ObservedAction {
+    selector: string;
+    description: string;
+    [key: string]: any;
+}
+/**
+ * 複数要素をナンバリング付きでハイライト。
+ * observe() 結果の可視化用。
+ */
+export declare function highlightElements(page: any, actions: ObservedAction[]): Promise<void>;
+/**
+ * 注入したハイライトオーバーレイを除去する。
+ */
+export declare function removeHighlights(page: any): Promise<void>;
+export {};
+//# sourceMappingURL=highlight.d.ts.map

package/dist/highlight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"highlight.d.ts","sourceRoot":"","sources":["../src/highlight.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAmBH,UAAU,oBAAoB;IAC5B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,GAAG,EACT,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAmHf;AAED,UAAU,cAAc;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,GAAG,EACT,OAAO,EAAE,cAAc,EAAE,GACxB,OAAO,CAAC,IAAI,CAAC,CA8Gf;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAK/D"}

package/dist/highlight.js

@@ -0,0 +1,225 @@
+/**
+ * DOM ベースのハイライト・カーソル可視化ヘルパー。
+ * page.evaluate() でオーバーレイを注入し、page.screenshot() に反映させる。
+ */
+const HIGHLIGHT_CONTAINER_ID = "__stagehand_highlight_container__";
+const COLOR_PALETTE = [
+    { bg: "rgba(255, 152, 0, 0.25)", border: "rgba(255, 152, 0, 0.8)" },
+    { bg: "rgba(33, 150, 243, 0.25)", border: "rgba(33, 150, 243, 0.8)" },
+    { bg: "rgba(156, 39, 176, 0.25)", border: "rgba(156, 39, 176, 0.8)" },
+    { bg: "rgba(0, 150, 136, 0.25)", border: "rgba(0, 150, 136, 0.8)" },
+    { bg: "rgba(244, 67, 54, 0.25)", border: "rgba(244, 67, 54, 0.8)" },
+    { bg: "rgba(76, 175, 80, 0.25)", border: "rgba(76, 175, 80, 0.8)" },
+    { bg: "rgba(255, 235, 59, 0.30)", border: "rgba(255, 193, 7, 0.8)" },
+    { bg: "rgba(121, 85, 72, 0.25)", border: "rgba(121, 85, 72, 0.8)" },
+];
+const CURSOR_SVG = `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <path d="M5 3l14 8-6.5 2L9 19.5z" fill="#222" stroke="#fff" stroke-width="1.5"/>
+</svg>`;
+/**
+ * 単一要素をハイライト + オプションでカーソル表示。
+ * act() のクリック対象の可視化用。
+ */
+export async function highlightElement(page, selector, opts = {}) {
+    const { showCursor = false, label = "", overlayColor = "rgba(255, 152, 0, 0.3)", borderColor = "rgba(255, 152, 0, 0.8)", } = opts;
+    await page.evaluate(({ selector, overlayColor, borderColor, showCursor, label, cursorSvg, containerId, }) => {
+        let el = null;
+        try {
+            if (selector.startsWith("xpath=")) {
+                const xpath = selector.slice("xpath=".length);
+                const node = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue;
+                if (node instanceof Element) {
+                    el = node;
+                }
+            }
+            else {
+                el = document.querySelector(selector);
+            }
+        }
+        catch {
+            return;
+        }
+        if (!el)
+            return;
+        el.scrollIntoView?.({
+            block: "center",
+            behavior: "instant",
+        });
+        const rect = el.getBoundingClientRect();
+        const scrollX = window.scrollX;
+        const scrollY = window.scrollY;
+        // Ensure container
+        let container = document.getElementById(containerId);
+        if (!container) {
+            container = document.createElement("div");
+            container.id = containerId;
+            container.style.position = "absolute";
+            container.style.top = "0";
+            container.style.left = "0";
+            container.style.width = `${document.documentElement.scrollWidth}px`;
+            container.style.height = `${document.documentElement.scrollHeight}px`;
+            container.style.pointerEvents = "none";
+            container.style.zIndex = "2147483647";
+            document.documentElement.appendChild(container);
+        }
+        // Overlay box
+        const overlay = document.createElement("div");
+        overlay.style.position = "absolute";
+        overlay.style.left = `${rect.left + scrollX - 3}px`;
+        overlay.style.top = `${rect.top + scrollY - 3}px`;
+        overlay.style.width = `${rect.width + 6}px`;
+        overlay.style.height = `${rect.height + 6}px`;
+        overlay.style.background = overlayColor;
+        overlay.style.border = `3px solid ${borderColor}`;
+        overlay.style.borderRadius = "4px";
+        overlay.style.boxSizing = "border-box";
+        container.appendChild(overlay);
+        // Label badge
+        if (label) {
+            const badge = document.createElement("div");
+            badge.textContent = label;
+            badge.style.position = "absolute";
+            badge.style.left = `${rect.left + scrollX - 3}px`;
+            badge.style.top = `${rect.top + scrollY - 22}px`;
+            badge.style.background = borderColor;
+            badge.style.color = "#fff";
+            badge.style.fontSize = "11px";
+            badge.style.fontFamily = "Arial, sans-serif";
+            badge.style.fontWeight = "bold";
+            badge.style.padding = "2px 6px";
+            badge.style.borderRadius = "3px 3px 0 0";
+            badge.style.whiteSpace = "nowrap";
+            container.appendChild(badge);
+        }
+        // Cursor SVG
+        if (showCursor) {
+            const cursor = document.createElement("div");
+            cursor.innerHTML = cursorSvg;
+            cursor.style.position = "absolute";
+            cursor.style.left = `${rect.left + scrollX + rect.width / 2}px`;
+            cursor.style.top = `${rect.top + scrollY + rect.height / 2}px`;
+            container.appendChild(cursor);
+        }
+    }, {
+        selector,
+        overlayColor,
+        borderColor,
+        showCursor,
+        label,
+        cursorSvg: CURSOR_SVG,
+        containerId: HIGHLIGHT_CONTAINER_ID,
+    });
+}
+/**
+ * 複数要素をナンバリング付きでハイライト。
+ * observe() 結果の可視化用。
+ */
+export async function highlightElements(page, actions) {
+    await page.evaluate(({ actions, palette, containerId }) => {
+        // Ensure container
+        let container = document.getElementById(containerId);
+        if (!container) {
+            container = document.createElement("div");
+            container.id = containerId;
+            container.style.position = "absolute";
+            container.style.top = "0";
+            container.style.left = "0";
+            container.style.width = `${document.documentElement.scrollWidth}px`;
+            container.style.height = `${document.documentElement.scrollHeight}px`;
+            container.style.pointerEvents = "none";
+            container.style.zIndex = "2147483647";
+            document.documentElement.appendChild(container);
+        }
+        for (let i = 0; i < actions.length; i++) {
+            const action = actions[i];
+            const color = palette[i % palette.length];
+            let el = null;
+            try {
+                if (action.selector.startsWith("xpath=")) {
+                    const xpath = action.selector.slice("xpath=".length);
+                    const node = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue;
+                    if (node instanceof Element) {
+                        el = node;
+                    }
+                }
+                else {
+                    el = document.querySelector(action.selector);
+                }
+            }
+            catch {
+                continue;
+            }
+            if (!el)
+                continue;
+            const rect = el.getBoundingClientRect();
+            const scrollX = window.scrollX;
+            const scrollY = window.scrollY;
+            // Overlay box
+            const overlay = document.createElement("div");
+            overlay.style.position = "absolute";
+            overlay.style.left = `${rect.left + scrollX - 2}px`;
+            overlay.style.top = `${rect.top + scrollY - 2}px`;
+            overlay.style.width = `${rect.width + 4}px`;
+            overlay.style.height = `${rect.height + 4}px`;
+            overlay.style.background = color.bg;
+            overlay.style.border = `2px solid ${color.border}`;
+            overlay.style.borderRadius = "3px";
+            overlay.style.boxSizing = "border-box";
+            container.appendChild(overlay);
+            // Number badge
+            const badge = document.createElement("div");
+            badge.textContent = String(i + 1);
+            badge.style.position = "absolute";
+            badge.style.left = `${rect.left + scrollX - 2}px`;
+            badge.style.top = `${rect.top + scrollY - 20}px`;
+            badge.style.background = color.border;
+            badge.style.color = "#fff";
+            badge.style.fontSize = "11px";
+            badge.style.fontFamily = "Arial, sans-serif";
+            badge.style.fontWeight = "bold";
+            badge.style.padding = "1px 5px";
+            badge.style.borderRadius = "3px 3px 0 0";
+            badge.style.whiteSpace = "nowrap";
+            badge.style.maxWidth = "200px";
+            badge.style.overflow = "hidden";
+            badge.style.textOverflow = "ellipsis";
+            container.appendChild(badge);
+            // Description tooltip (below the element)
+            if (action.description) {
+                const tip = document.createElement("div");
+                tip.textContent = `${i + 1}. ${action.description}`;
+                tip.style.position = "absolute";
+                tip.style.left = `${rect.left + scrollX - 2}px`;
+                tip.style.top = `${rect.top + scrollY + rect.height + 4}px`;
+                tip.style.background = "rgba(0,0,0,0.75)";
+                tip.style.color = "#fff";
+                tip.style.fontSize = "10px";
+                tip.style.fontFamily = "Arial, sans-serif";
+                tip.style.padding = "2px 5px";
+                tip.style.borderRadius = "2px";
+                tip.style.whiteSpace = "nowrap";
+                tip.style.maxWidth = "300px";
+                tip.style.overflow = "hidden";
+                tip.style.textOverflow = "ellipsis";
+                container.appendChild(tip);
+            }
+        }
+    }, {
+        actions: actions.map((a) => ({
+            selector: a.selector,
+            description: a.description,
+        })),
+        palette: COLOR_PALETTE,
+        containerId: HIGHLIGHT_CONTAINER_ID,
+    });
+}
+/**
+ * 注入したハイライトオーバーレイを除去する。
+ */
+export async function removeHighlights(page) {
+    await page.evaluate((containerId) => {
+        const c = document.getElementById(containerId);
+        if (c)
+            c.remove();
+    }, HIGHLIGHT_CONTAINER_ID);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { ScenarioStep, ScenarioSuiteOptions } from "./scenario.js";
+export { defineScenarioSuite } from "./scenario.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { defineScenarioSuite } from "./scenario.js";

package/dist/recording.d.ts

@@ -0,0 +1,23 @@
+export interface Recorder {
+    stop: () => Promise<number>;
+    /** 現在のページ状態をフレームとして即座に n 枚書き込む */
+    injectFrames: (n?: number) => Promise<void>;
+}
+/**
+ * ffmpeg コマンドが利用可能かを確認する。
+ * 結果はプロセス内でキャッシュされる。
+ */
+export declare function hasFfmpegCommand(): boolean;
+/** ffmpeg 未インストール時用の no-op recorder */
+export declare function createNoopRecorder(): Recorder;
+/**
+ * ページのフレームキャプチャを開始する。
+ * 返り値の stop() を呼ぶとキャプチャを終了し、撮影したフレーム数を返す。
+ */
+export declare function startRecording(page: any, framesDir: string, intervalMs?: number): Recorder;
+/**
+ * フレーム画像群を ffmpeg で MP4 動画に変換する。
+ * 成功時は動画パスを返し、失敗時は null を返す。
+ */
+export declare function framesToVideo(framesDir: string, outputDir: string, fps: number): string | null;
+//# sourceMappingURL=recording.d.ts.map

package/dist/recording.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recording.d.ts","sourceRoot":"","sources":["../src/recording.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5B,kCAAkC;IAClC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAW1C;AAED,uCAAuC;AACvC,wBAAgB,kBAAkB,IAAI,QAAQ,CAK7C;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,GAAG,EACT,SAAS,EAAE,MAAM,EACjB,UAAU,SAAM,GACf,QAAQ,CA8CV;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,IAAI,CAcf"}

package/dist/recording.js

@@ -0,0 +1,89 @@
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+let ffmpegAvailableCache;
+/**
+ * ffmpeg コマンドが利用可能かを確認する。
+ * 結果はプロセス内でキャッシュされる。
+ */
+export function hasFfmpegCommand() {
+    if (ffmpegAvailableCache !== undefined)
+        return ffmpegAvailableCache;
+    try {
+        execSync("ffmpeg -version", { stdio: "ignore" });
+        ffmpegAvailableCache = true;
+    }
+    catch {
+        ffmpegAvailableCache = false;
+    }
+    return ffmpegAvailableCache;
+}
+/** ffmpeg 未インストール時用の no-op recorder */
+export function createNoopRecorder() {
+    return {
+        stop: async () => 0,
+        injectFrames: async () => { },
+    };
+}
+/**
+ * ページのフレームキャプチャを開始する。
+ * 返り値の stop() を呼ぶとキャプチャを終了し、撮影したフレーム数を返す。
+ */
+export function startRecording(page, framesDir, intervalMs = 500) {
+    let frameIndex = 0;
+    let stopped = false;
+    let injecting = false;
+    const capture = async () => {
+        while (!stopped) {
+            if (!injecting) {
+                try {
+                    const filePath = path.join(framesDir, `frame-${String(frameIndex).padStart(5, "0")}.png`);
+                    await page.screenshot({ path: filePath });
+                    frameIndex++;
+                }
+                catch {
+                    // ブラウザが閉じられた等の場合は無視
+                }
+            }
+            await new Promise((r) => setTimeout(r, intervalMs));
+        }
+    };
+    const promise = capture();
+    return {
+        injectFrames: async (n = 3) => {
+            injecting = true;
+            try {
+                for (let i = 0; i < n; i++) {
+                    const filePath = path.join(framesDir, `frame-${String(frameIndex).padStart(5, "0")}.png`);
+                    await page.screenshot({ path: filePath });
+                    frameIndex++;
+                }
+            }
+            catch { }
+            injecting = false;
+        },
+        stop: async () => {
+            stopped = true;
+            await promise;
+            return frameIndex;
+        },
+    };
+}
+/**
+ * フレーム画像群を ffmpeg で MP4 動画に変換する。
+ * 成功時は動画パスを返し、失敗時は null を返す。
+ */
+export function framesToVideo(framesDir, outputDir, fps) {
+    const outputPath = path.join(outputDir, "test-recording.mp4");
+    const pattern = path.join(framesDir, "frame-%05d.png");
+    try {
+        execSync(`ffmpeg -y -framerate ${fps} -i "${pattern}" -c:v libx264 -pix_fmt yuv420p "${outputPath}" 2>/dev/null`);
+        // フレーム画像を削除
+        fs.rmSync(framesDir, { recursive: true });
+        return outputPath;
+    }
+    catch {
+        console.error("  ffmpeg conversion failed. Raw frames kept in:", framesDir);
+        return null;
+    }
+}

package/dist/scenario.d.ts

@@ -0,0 +1,18 @@
+import type { TestContext } from "./context.js";
+export interface ScenarioStep {
+    name: string;
+    run: (ctx: TestContext) => Promise<void>;
+    /** false を指定すると self-heal をスキップ（既定は適用） */
+    selfHeal?: boolean;
+}
+export interface ScenarioSuiteOptions {
+    suiteName: string;
+    originUrl: string;
+    steps: ScenarioStep[];
+}
+/**
+ * E2E シナリオ実行の共通ライフサイクルを提供する。
+ * 利用者は steps を並べるだけでシナリオを定義できる。
+ */
+export declare function defineScenarioSuite({ suiteName, originUrl, steps, }: ScenarioSuiteOptions): void;
+//# sourceMappingURL=scenario.d.ts.map

package/dist/scenario.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario.d.ts","sourceRoot":"","sources":["../src/scenario.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAKhD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,SAAS,EACT,SAAS,EACT,KAAK,GACN,EAAE,oBAAoB,GAAG,IAAI,CA8C7B"}

package/dist/scenario.js

@@ -0,0 +1,49 @@
+import { afterAll, afterEach, beforeAll, describe, test } from "vitest";
+import { withSelfHeal } from "./self-heal.js";
+import { closeStagehand, initStagehand } from "./stagehand.js";
+/**
+ * E2E シナリオ実行の共通ライフサイクルを提供する。
+ * 利用者は steps を並べるだけでシナリオを定義できる。
+ */
+export function defineScenarioSuite({ suiteName, originUrl, steps, }) {
+    describe(suiteName, () => {
+        let _ctx;
+        let _recorder;
+        const getCtx = () => {
+            if (!_ctx)
+                throw new Error("ctx not initialized");
+            return _ctx;
+        };
+        beforeAll(async () => {
+            ({ ctx: _ctx, recorder: _recorder } = await initStagehand(originUrl));
+        });
+        afterAll(async () => {
+            if (_ctx && _recorder) {
+                await closeStagehand(_ctx, _recorder).catch((e) => console.error("closeStagehand error:", e));
+            }
+        });
+        afterEach(async (testCtx) => {
+            if (_ctx && testCtx.task.result?.state === "fail") {
+                const name = `error-${testCtx.task.name.replace(/\s+/g, "-")}`;
+                try {
+                    await _ctx.screenshot(name);
+                }
+                catch (err) {
+                    console.warn(`Failed to capture error screenshot "${name}":`, err);
+                }
+            }
+        });
+        for (const step of steps) {
+            test(step.name, async () => {
+                const ctx = getCtx();
+                if (step.selfHeal === false) {
+                    await step.run(ctx);
+                    return;
+                }
+                await withSelfHeal(ctx, async () => {
+                    await step.run(ctx);
+                });
+            });
+        }
+    });
+}

package/dist/screenshot.d.ts

@@ -0,0 +1,23 @@
+export type ScreenshotFn = (name: string, targetPage?: any) => Promise<string>;
+/**
+ * スクリーンショット撮影ヘルパーを生成する。
+ * 返り値の関数は名前を受け取ってスクリーンショットを保存し、ファイルパスを返す。
+ */
+export declare function createScreenshotHelper(page: any, dir: string): ScreenshotFn;
+/**
+ * 2枚の PNG スクリーンショットを比較し、差異の割合と diff 画像を返す。
+ * ベースラインが存在しない場合は比較をスキップ。
+ */
+export declare function compareWithBaseline(currentPath: string, baselineName: string, opts: {
+    baselinesDir: string;
+    diffPath: string;
+}): {
+    mismatchRatio: number;
+    diffSaved: boolean;
+    skipped: boolean;
+};
+/**
+ * 現在のスクリーンショットをベースラインとして保存する。
+ */
+export declare function saveBaseline(screenshotPath: string, baselineName: string, baselinesDir: string): string;
+//# sourceMappingURL=screenshot.d.ts.map

package/dist/screenshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../src/screenshot.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE/E;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CAU3E;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CA6BjE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,GACnB,MAAM,CAOR"}

package/dist/screenshot.js

@@ -0,0 +1,53 @@
+import fs from "fs";
+import path from "path";
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+/**
+ * スクリーンショット撮影ヘルパーを生成する。
+ * 返り値の関数は名前を受け取ってスクリーンショットを保存し、ファイルパスを返す。
+ */
+export function createScreenshotHelper(page, dir) {
+    return async (name, targetPage = page) => {
+        const filePath = path.join(dir, `${name}.png`);
+        try {
+            await targetPage.screenshot({ path: filePath, fullPage: true });
+        }
+        catch {
+            await targetPage.screenshot({ path: filePath });
+        }
+        return filePath;
+    };
+}
+/**
+ * 2枚の PNG スクリーンショットを比較し、差異の割合と diff 画像を返す。
+ * ベースラインが存在しない場合は比較をスキップ。
+ */
+export function compareWithBaseline(currentPath, baselineName, opts) {
+    const baselinePath = path.join(opts.baselinesDir, `${baselineName}.png`);
+    if (!fs.existsSync(baselinePath)) {
+        return { mismatchRatio: 0, diffSaved: false, skipped: true };
+    }
+    const img1 = PNG.sync.read(fs.readFileSync(currentPath));
+    const img2 = PNG.sync.read(fs.readFileSync(baselinePath));
+    // サイズが異なる場合は大幅な変化とみなす
+    if (img1.width !== img2.width || img1.height !== img2.height) {
+        return { mismatchRatio: 1, diffSaved: false, skipped: false };
+    }
+    const { width, height } = img1;
+    const diff = new PNG({ width, height });
+    const numDiffPixels = pixelmatch(img1.data, img2.data, diff.data, width, height, { threshold: 0.1 });
+    const mismatchRatio = numDiffPixels / (width * height);
+    fs.writeFileSync(opts.diffPath, PNG.sync.write(diff));
+    return { mismatchRatio, diffSaved: true, skipped: false };
+}
+/**
+ * 現在のスクリーンショットをベースラインとして保存する。
+ */
+export function saveBaseline(screenshotPath, baselineName, baselinesDir) {
+    if (!fs.existsSync(baselinesDir)) {
+        fs.mkdirSync(baselinesDir, { recursive: true });
+    }
+    const dest = path.join(baselinesDir, `${baselineName}.png`);
+    fs.copyFileSync(screenshotPath, dest);
+    return dest;
+}

package/dist/self-heal.d.ts

@@ -0,0 +1,9 @@
+import type { TestContext } from "./context.js";
+/**
+ * テスト本体をセルフヒール付きで実行するラッパー。
+ *
+ * SELF_HEAL=1 かつエラーが VisualRegressionError でない場合、
+ * performSelfHeal() で回復を試み fn() を再実行する。
+ */
+export declare function withSelfHeal(ctx: TestContext, fn: () => Promise<void>): Promise<void>;
+//# sourceMappingURL=self-heal.d.ts.map

package/dist/self-heal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-heal.d.ts","sourceRoot":"","sources":["../src/self-heal.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAgChD;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,WAAW,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GACtB,OAAO,CAAC,IAAI,CAAC,CAaf"}

package/dist/self-heal.js

@@ -0,0 +1,51 @@
+import fs from "fs";
+import path from "path";
+import { frameworkConfig } from "./config.js";
+import { VisualRegressionError } from "./context.js";
+/**
+ * セルフヒール回復処理:
+ * 1. 余分なタブを閉じる
+ * 2. Stagehand キャッシュを削除して LLM に再推論させる
+ * 3. テスト対象ページをリロードしてクリーンな状態に戻す
+ */
+async function performSelfHeal(ctx) {
+    // 余分なタブを閉じる
+    const extraPages = ctx.stagehand.context
+        .pages()
+        .filter((p) => p !== ctx.page);
+    for (const ep of extraPages) {
+        try {
+            await ep.close();
+        }
+        catch { }
+    }
+    // キャッシュを削除
+    const cacheDir = path.resolve(frameworkConfig.stagehand.cacheDir);
+    if (fs.existsSync(cacheDir)) {
+        fs.rmSync(cacheDir, { recursive: true });
+        fs.mkdirSync(cacheDir, { recursive: true });
+    }
+    // ページを再読み込み
+    await ctx.page.goto(ctx.originUrl);
+    await ctx.page.waitForLoadState("networkidle");
+}
+/**
+ * テスト本体をセルフヒール付きで実行するラッパー。
+ *
+ * SELF_HEAL=1 かつエラーが VisualRegressionError でない場合、
+ * performSelfHeal() で回復を試み fn() を再実行する。
+ */
+export async function withSelfHeal(ctx, fn) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        if (err instanceof VisualRegressionError)
+            throw err;
+        if (process.env.SELF_HEAL !== "1")
+            throw err;
+        console.log("  [self-heal] Test failed, performing recovery and retrying...");
+        await performSelfHeal(ctx);
+        await fn();
+    }
+}

package/dist/stagehand.d.ts

@@ -0,0 +1,16 @@
+import { type TestContext } from "./context.js";
+import { type Recorder } from "./recording.js";
+/**
+ * Stagehand を初期化し、テスト実行に必要な環境を準備する。
+ * beforeAll() から呼び出す。
+ */
+export declare function initStagehand(originUrl: string): Promise<{
+    ctx: TestContext;
+    recorder: Recorder;
+}>;
+/**
+ * 録画を停止し、ブラウザを閉じ、動画を生成する。
+ * afterAll() から呼び出す。
+ */
+export declare function closeStagehand(ctx: TestContext, recorder: Recorder): Promise<void>;
+//# sourceMappingURL=stagehand.d.ts.map

package/dist/stagehand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stagehand.d.ts","sourceRoot":"","sources":["../src/stagehand.ts"],"names":[],"mappings":"AAGA,OAAO,EAKL,KAAK,WAAW,EACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAIL,KAAK,QAAQ,EAEd,MAAM,gBAAgB,CAAC;AAGxB;;;GAGG;AACH,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9D,GAAG,EAAE,WAAW,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;CACpB,CAAC,CA2CD;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/stagehand.js

@@ -0,0 +1,55 @@
+import { Stagehand } from "@browserbasehq/stagehand";
+import fs from "fs";
+import { frameworkConfig } from "./config.js";
+import { createTestContext, FRAMES_DIR, RECORDING_DIR, SCREENSHOT_DIR, } from "./context.js";
+import { createNoopRecorder, framesToVideo, hasFfmpegCommand, startRecording, } from "./recording.js";
+import { createScreenshotHelper } from "./screenshot.js";
+/**
+ * Stagehand を初期化し、テスト実行に必要な環境を準備する。
+ * beforeAll() から呼び出す。
+ */
+export async function initStagehand(originUrl) {
+    // 出力ディレクトリを準備（前回分をクリア）
+    for (const dir of [SCREENSHOT_DIR, RECORDING_DIR]) {
+        if (fs.existsSync(dir))
+            fs.rmSync(dir, { recursive: true });
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    const ffmpegAvailable = hasFfmpegCommand();
+    if (ffmpegAvailable) {
+        fs.mkdirSync(FRAMES_DIR, { recursive: true });
+    }
+    else {
+        console.info("ffmpeg not found: skip frame capture and video conversion");
+    }
+    const stagehand = new Stagehand({
+        env: "LOCAL",
+        model: frameworkConfig.stagehand.model,
+        cacheDir: frameworkConfig.stagehand.cacheDir,
+        localBrowserLaunchOptions: {
+            headless: frameworkConfig.browser.headless,
+            viewport: frameworkConfig.browser.viewport,
+        },
+    });
+    await stagehand.init();
+    const page = stagehand.context.pages()[0];
+    const screenshotFn = createScreenshotHelper(page, SCREENSHOT_DIR);
+    const recorder = ffmpegAvailable
+        ? startRecording(page, FRAMES_DIR, frameworkConfig.videoRecording.frameIntervalMs)
+        : createNoopRecorder();
+    const ctx = createTestContext(stagehand, page, recorder, screenshotFn, originUrl);
+    return { ctx, recorder };
+}
+/**
+ * 録画を停止し、ブラウザを閉じ、動画を生成する。
+ * afterAll() から呼び出す。
+ */
+export async function closeStagehand(ctx, recorder) {
+    const totalFrames = await recorder.stop();
+    await ctx.stagehand.close();
+    if (totalFrames > 0) {
+        const safeInterval = Math.max(frameworkConfig.videoRecording.frameIntervalMs, 1);
+        const fps = Math.round(1000 / safeInterval);
+        framesToVideo(FRAMES_DIR, RECORDING_DIR, fps);
+    }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@uzulla/voreux",
+  "version": "0.1.0",
+  "description": "Voreux: Stagehand + Vitest ベースの E2E テストフレームワーク",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "voreux": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@browserbasehq/stagehand": "^3.0.8",
+    "pixelmatch": "^7.1.0",
+    "pngjs": "^7.0.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.1",
+    "@types/pngjs": "^6.0.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}