@kkeve/suite 0.0.1 → 0.0.2

package/dist/core/global-setup.d.ts

@@ -0,0 +1,6 @@
+declare global {
+    var __keve_cdp_browser: import('@playwright/test').Browser | undefined;
+}
+export declare function getCdpBrowser(): Promise<import('@playwright/test').Browser>;
+export declare function isCdpMode(): boolean;
+export default function (): Promise<void>;

package/dist/core/global-setup.js

@@ -0,0 +1,113 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCdpBrowser = getCdpBrowser;
+exports.isCdpMode = isCdpMode;
+exports.default = default_1;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const auth_1 = require("./auth");
+async function getCdpBrowser() {
+    // 如果已有共享的 browser 对象，直接复用
+    if (globalThis.__keve_cdp_browser && globalThis.__keve_cdp_browser.isConnected()) {
+        return globalThis.__keve_cdp_browser;
+    }
+    const { chromium } = await Promise.resolve().then(() => __importStar(require('@playwright/test')));
+    let wsUrl = process.env.KEVE_CDP_WS_ENDPOINT;
+    // 如果只提供了 HTTP endpoint，自动获取 WebSocket URL
+    if (!wsUrl && process.env.KEVE_CDP_ENDPOINT) {
+        const httpUrl = process.env.KEVE_CDP_ENDPOINT.replace(/\/$/, '');
+        try {
+            const resp = await fetch(`${httpUrl}/json/version`);
+            const data = await resp.json();
+            wsUrl = data.webSocketDebuggerUrl;
+            console.log(`[keve CDP] Resolved WS endpoint: ${wsUrl}`);
+        }
+        catch (e) {
+            throw new Error(`Failed to resolve CDP WebSocket URL from ${httpUrl}: ${e.message}`);
+        }
+    }
+    if (!wsUrl)
+        throw new Error('No CDP endpoint configured');
+    const browser = await chromium.connectOverCDP(wsUrl, { timeout: 15000 });
+    console.log(`[keve CDP] Connected via ${wsUrl}`);
+    globalThis.__keve_cdp_browser = browser;
+    return browser;
+}
+function isCdpMode() {
+    return !!process.env.KEVE_CDP_WS_ENDPOINT || !!process.env.KEVE_CDP_ENDPOINT;
+}
+async function default_1() {
+    const projectRoot = path.resolve(process.cwd());
+    const storageStatePath = path.resolve(projectRoot, '.auth/storage-state.json');
+    const cdpEndpoint = process.env.KEVE_CDP_ENDPOINT || process.env.KEVE_CDP_WS_ENDPOINT;
+    if (cdpEndpoint) {
+        console.log(`[keve global-setup] CDP endpoint detected: ${cdpEndpoint}`);
+        // CDP 模式：在 global-setup 中提前连接一次，缓存 Browser 对象
+        try {
+            const browser = await getCdpBrowser();
+            const contexts = browser.contexts();
+            const pages = contexts.length > 0 ? contexts[0].pages() : [];
+            console.log(`[keve global-setup] CDP connected. contexts=${contexts.length}, pages=${pages.length}`);
+            if (pages.length > 0) {
+                console.log(`[keve global-setup] Existing tabs: ${pages.map(p => p.url()).join(', ')}`);
+            }
+        }
+        catch (e) {
+            console.warn(`[keve global-setup] CDP connection failed: ${e.message}`);
+        }
+        if (!fs.existsSync(storageStatePath)) {
+            const authDir = path.dirname(storageStatePath);
+            if (!fs.existsSync(authDir))
+                fs.mkdirSync(authDir, { recursive: true });
+            fs.writeFileSync(storageStatePath, JSON.stringify({ cookies: [], origins: [] }));
+        }
+        return;
+    }
+    console.log(`[keve global-setup] Acquiring fresh auth state...`);
+    const success = await (0, auth_1.acquireStorageState)({
+        logPrefix: '[keve global-setup]',
+    });
+    if (!success) {
+        console.warn(`[keve global-setup] Auth acquisition failed. Tests may fail due to auth issues.`);
+        if (!fs.existsSync(storageStatePath)) {
+            const authDir = path.dirname(storageStatePath);
+            if (!fs.existsSync(authDir))
+                fs.mkdirSync(authDir, { recursive: true });
+            fs.writeFileSync(storageStatePath, JSON.stringify({ cookies: [], origins: [] }));
+            console.log(`[keve global-setup] Created empty storage state → ${storageStatePath}`);
+        }
+    }
+}

package/dist/core/keve-aspect.d.ts

@@ -0,0 +1,54 @@
+/**
+ * keve-aspect — Framework-internal aspect registry for keveGoal lifecycle
+ *
+ * Three phases: before → (goal body or rescue) → after
+ * User-invisible: aspects are registered by the framework, not by test authors.
+ *
+ * Built-in aspects:
+ * - screenshot-on-enter (before, order=10) — capture screenshot before goal
+ * - react-rescue (rescue, order=0) — Re-Act loop when fn() throws
+ * - expected-check (after, order=0) — verify expected state via aiAssert
+ * - action-log-write (after, order=10) — append to action-log.jsonl
+ * - learnedActions-update (after, order=20) — update in-memory cache
+ * - screenshot-on-fail (after, order=30) — capture screenshot on failure
+ */
+export type AspectPhase = 'before' | 'rescue' | 'after';
+export interface GoalContext {
+    page: import('@playwright/test').Page;
+    step: string;
+    expected: string;
+    precondition?: string;
+    order: number;
+    testTitle: string;
+    specFilePath?: string;
+}
+export interface GoalResult {
+    success: boolean;
+    error?: Error;
+    actions?: any[];
+    finalSnapshot?: string;
+    evalResult?: {
+        achieved: boolean;
+        gap: string;
+        nextAction: string;
+        fnSource?: string;
+        screenshotPath?: string;
+        snapshotPreview?: string;
+    };
+}
+export interface AspectDefinition {
+    name: string;
+    phase: AspectPhase;
+    order: number;
+    execute: (ctx: GoalContext, result?: GoalResult, error?: Error) => Promise<GoalResult | void>;
+}
+export declare class KeveAspectRegistry {
+    private aspects;
+    register(def: AspectDefinition): void;
+    unregister(name: string): void;
+    getByPhase(phase: AspectPhase): AspectDefinition[];
+    /** Run all aspects of a phase, chaining results */
+    runPhase(phase: AspectPhase, ctx: GoalContext, result?: GoalResult, error?: Error): Promise<GoalResult | undefined>;
+}
+/** Global singleton aspect registry */
+export declare const keveAspect: KeveAspectRegistry;

package/dist/core/keve-aspect.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * keve-aspect — Framework-internal aspect registry for keveGoal lifecycle
+ *
+ * Three phases: before → (goal body or rescue) → after
+ * User-invisible: aspects are registered by the framework, not by test authors.
+ *
+ * Built-in aspects:
+ * - screenshot-on-enter (before, order=10) — capture screenshot before goal
+ * - react-rescue (rescue, order=0) — Re-Act loop when fn() throws
+ * - expected-check (after, order=0) — verify expected state via aiAssert
+ * - action-log-write (after, order=10) — append to action-log.jsonl
+ * - learnedActions-update (after, order=20) — update in-memory cache
+ * - screenshot-on-fail (after, order=30) — capture screenshot on failure
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keveAspect = exports.KeveAspectRegistry = void 0;
+class KeveAspectRegistry {
+    aspects = [];
+    register(def) {
+        this.aspects.push(def);
+    }
+    unregister(name) {
+        this.aspects = this.aspects.filter(a => a.name !== name);
+    }
+    getByPhase(phase) {
+        return this.aspects
+            .filter(a => a.phase === phase)
+            .sort((a, b) => a.order - b.order);
+    }
+    /** Run all aspects of a phase, chaining results */
+    async runPhase(phase, ctx, result, error) {
+        const aspects = this.getByPhase(phase);
+        let currentResult = result;
+        for (const aspect of aspects) {
+            try {
+                const aspectResult = await aspect.execute(ctx, currentResult, error);
+                if (aspectResult && phase === 'after') {
+                    currentResult = aspectResult;
+                }
+            }
+            catch (err) {
+                console.warn(`[keve-aspect] ${aspect.name} failed: ${err.message}`);
+                // Aspects should not throw — they are framework-internal
+            }
+        }
+        return currentResult;
+    }
+}
+exports.KeveAspectRegistry = KeveAspectRegistry;
+/** Global singleton aspect registry */
+exports.keveAspect = new KeveAspectRegistry();

package/dist/core/keve-decorators.d.ts

@@ -0,0 +1,51 @@
+/**
+ * keve-decorators — @keveModel + @keveScene 装饰器
+ *
+ * 使用 TC39 Stage 3 装饰器 API (Playwright 1.58+ 默认支持)
+ *
+ * 执行顺序（TC39 Stage 3 规范）：
+ * 1. Method decorator 函数调用 → 注册 addInitializer
+ * 2. Class decorator 函数调用 → 注册 addInitializer
+ * 3. Method addInitializers 执行 → @keveScene 注册场景到 WeakMap
+ * 4. Class addInitializer 执行 → @keveModel 读取 WeakMap 并调用 test.describe
+ *
+ * 两层装饰器 + 函数调用：
+ *   Model (模块) → test.describe → @keveModel
+ *   Scene (场景) → test → @keveScene (fn.toString() 捕获完整脚本)
+ *   Goal  (步骤) → 步骤元数据 → keveGoal() 函数调用（在方法体内）
+ */
+import { type KeveGoalMeta } from './keve-registry';
+/** Called by keve-test.ts to register the extended test instance */
+export declare function setKeveTest(t: any): void;
+/** Get the current keve test instance (extended with fixtures) */
+export declare function getKeveTest(): any;
+export type { KeveGoalMeta, KeveEvalMeta, ErrorCategory } from './keve-registry';
+export interface KeveSceneMeta {
+    id: string;
+    description: string;
+    title: string;
+    code: string;
+    goals: KeveGoalMeta[];
+    fn: Function;
+}
+/**
+ * @keveModel(name) — Class decorator (模块层)
+ * Uses context.addInitializer to defer test.describe() registration
+ * until AFTER all @keveScene addInitializers have run.
+ */
+export declare function keveModel(id: string, description: string): <T extends {
+    new (...args: any[]): {};
+}>(ctor: T, context: ClassDecoratorContext) => T;
+/**
+ * @keveScene(title) — Method decorator (场景层, static methods only)
+ * Captures fn.toString() as the complete scene script.
+ * Wraps fn with try-catch-finally to classify errors and decide skipAI.
+ * Registers scene metadata to both WeakMap and global Map.
+ *
+ * The wrapper preserves the original function's destructuring signature by
+ * extracting the parameter text from fn.toString() and constructing a wrapper
+ * via new Function(), so Playwright can correctly resolve fixture dependencies.
+ */
+export declare function keveScene(id: string, description: string): (fn: Function, context: ClassMethodDecoratorContext) => Function;
+/** 获取 Model 下注册的所有 Scene */
+export declare function getModelScenes(ctor: Function): KeveSceneMeta[] | null;

package/dist/core/keve-decorators.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * keve-decorators — @keveModel + @keveScene 装饰器
+ *
+ * 使用 TC39 Stage 3 装饰器 API (Playwright 1.58+ 默认支持)
+ *
+ * 执行顺序（TC39 Stage 3 规范）：
+ * 1. Method decorator 函数调用 → 注册 addInitializer
+ * 2. Class decorator 函数调用 → 注册 addInitializer
+ * 3. Method addInitializers 执行 → @keveScene 注册场景到 WeakMap
+ * 4. Class addInitializer 执行 → @keveModel 读取 WeakMap 并调用 test.describe
+ *
+ * 两层装饰器 + 函数调用：
+ *   Model (模块) → test.describe → @keveModel
+ *   Scene (场景) → test → @keveScene (fn.toString() 捕获完整脚本)
+ *   Goal  (步骤) → 步骤元数据 → keveGoal() 函数调用（在方法体内）
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setKeveTest = setKeveTest;
+exports.getKeveTest = getKeveTest;
+exports.keveModel = keveModel;
+exports.keveScene = keveScene;
+exports.getModelScenes = getModelScenes;
+const test_1 = require("@playwright/test");
+const keve_registry_1 = require("./keve-registry");
+// ─── Configurable test reference ────────────────────────────────────
+// keveModel needs to call test.describe / test — but it must use the EXTENDED test
+// (with keveGoal/keveAssert fixtures), not the base @playwright/test.
+// keve-test.ts calls setKeveTest() after creating the extended test.
+let _keveTest = test_1.test;
+/** Called by keve-test.ts to register the extended test instance */
+function setKeveTest(t) { _keveTest = t; }
+/** Get the current keve test instance (extended with fixtures) */
+function getKeveTest() { return _keveTest; }
+// ─── Internal Registry (WeakMap per Model constructor) ─────────────
+/** Model → Scene 列表：每个 @keveModel 类下注册的 @keveScene 列表 */
+const modelScenesMap = new WeakMap();
+// ─── Error Classification ──────────────────────────────────────────
+// Error classification moved to keve-report.ts onTestEnd — 
+// onTestEnd has access to result.error and result.status, which is more reliable
+// than try-catch in the decorator (async rejections, test-level timeouts can bypass decorator catch).
+// ─── TC39 Stage 3 Decorators ──────────────────────────────────────
+/**
+ * @keveModel(name) — Class decorator (模块层)
+ * Uses context.addInitializer to defer test.describe() registration
+ * until AFTER all @keveScene addInitializers have run.
+ */
+function keveModel(id, description) {
+    return (ctor, context) => {
+        context.addInitializer(function () {
+            const ctor = this;
+            const scenes = modelScenesMap.get(ctor) || [];
+            _keveTest.describe(`${id}: ${description}`, () => {
+                for (const scene of scenes) {
+                    _keveTest(scene.title, scene.fn);
+                }
+            });
+        });
+        return ctor;
+    };
+}
+/**
+ * @keveScene(title) — Method decorator (场景层, static methods only)
+ * Captures fn.toString() as the complete scene script.
+ * Wraps fn with try-catch-finally to classify errors and decide skipAI.
+ * Registers scene metadata to both WeakMap and global Map.
+ *
+ * The wrapper preserves the original function's destructuring signature by
+ * extracting the parameter text from fn.toString() and constructing a wrapper
+ * via new Function(), so Playwright can correctly resolve fixture dependencies.
+ */
+function keveScene(id, description) {
+    return (fn, context) => {
+        const code = fn.toString(); // Capture original code BEFORE wrapping
+        const title = `${id}: ${description}`;
+        // Register the original function directly — Playwright resolves fixture dependencies
+        // by parsing fn.toString() / AST. Wrapping with new Function() breaks this resolution.
+        // Error classification is handled in onTestEnd (keve-report.ts), not here.
+        context.addInitializer(function () {
+            const ctor = this;
+            if (!modelScenesMap.has(ctor))
+                modelScenesMap.set(ctor, []);
+            const scene = { id, description, title, code, goals: [], fn };
+            modelScenesMap.get(ctor).push(scene);
+            // Register to global maps for Reporter access
+            keve_registry_1.sceneCodeMap.set(title, code); // Stores ORIGINAL code, not wrapped
+        });
+        return fn; // Return original function unchanged — preserves fixture parameter signature
+    };
+}
+// ─── Utility ───────────────────────────────────────────────────────
+/** 获取 Model 下注册的所有 Scene */
+function getModelScenes(ctor) {
+    return modelScenesMap.get(ctor) || null;
+}

package/dist/core/keve-registry.d.ts

@@ -0,0 +1,38 @@
+/**
+ * keve-registry — Global scene metadata registry
+ *
+ * Shared between keve-decorators (writes) and keve-report (reads).
+ * This module has NO dependency on @playwright/test, so the Reporter
+ * can import it without pulling Playwright into the report build.
+ */
+export interface KeveGoalMeta {
+    precondition?: string;
+    step: string;
+    expected: string;
+    order: number;
+}
+/** 错误分类类型 */
+export type ErrorCategory = 'script' | 'env' | 'assert' | 'visual' | 'text-mismatch' | 'react-fail' | 'pass' | 'unknown';
+/** 场景执行后的评估元数据，由 @keveScene 装饰器写入，Reporter 读取 */
+export interface KeveEvalMeta {
+    /** 错误分类 */
+    errorCategory: ErrorCategory;
+    /** 是否跳过 AI 评估（脚本错误时为 true） */
+    skipAI: boolean;
+    /** 原始错误信息（可选，未截断） */
+    errorMessage?: string;
+}
+/**
+ * 场景代码映射: scene title → scene code (fn.toString())
+ * Reporter 通过 sceneCodeMap.get(title) 获取场景脚本
+ */
+export declare const sceneCodeMap: Map<string, string>;
+/**
+ * 场景目标映射: scene title → goal metadata array
+ */
+export declare const sceneGoalsMap: Map<string, KeveGoalMeta[]>;
+/**
+ * 场景评估元数据映射: scene title → KeveEvalMeta
+ * @keveScene 装饰器在执行后写入分类结果，Reporter 在 onTestEnd 中读取
+ */
+export declare const sceneEvalMetaMap: Map<string, KeveEvalMeta>;

package/dist/core/keve-registry.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * keve-registry — Global scene metadata registry
+ *
+ * Shared between keve-decorators (writes) and keve-report (reads).
+ * This module has NO dependency on @playwright/test, so the Reporter
+ * can import it without pulling Playwright into the report build.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sceneEvalMetaMap = exports.sceneGoalsMap = exports.sceneCodeMap = void 0;
+// ─── Global Registry ──────────────────────────────────────────────
+/**
+ * 场景代码映射: scene title → scene code (fn.toString())
+ * Reporter 通过 sceneCodeMap.get(title) 获取场景脚本
+ */
+exports.sceneCodeMap = new Map();
+/**
+ * 场景目标映射: scene title → goal metadata array
+ */
+exports.sceneGoalsMap = new Map();
+/**
+ * 场景评估元数据映射: scene title → KeveEvalMeta
+ * @keveScene 装饰器在执行后写入分类结果，Reporter 在 onTestEnd 中读取
+ */
+exports.sceneEvalMetaMap = new Map();

package/dist/core/keve-report.d.ts

@@ -0,0 +1,27 @@
+/**
+ * keve-report: Playwright Reporter that collects test execution data
+ *
+ * After EACH test completes (onTestEnd), records test result metadata
+ * including step results, error category, AI exploration steps, and diagnostics.
+ * Results are appended to confidence-data.jsonl (one line per test).
+ *
+ * After ALL tests complete (onEnd), generates report-data.json directly,
+ * eliminating the need for a separate `keve report` command.
+ *
+ * Usage in playwright config:
+ *   reporter: [
+ *     ['list'],
+ *     ['@ks-data/keve-suite/keve-report'],
+ *   ]
+ */
+import type { Reporter, TestCase, TestResult, FullResult, FullConfig, Suite } from '@playwright/test/reporter';
+declare class KeveReporter implements Reporter {
+    private outputPath;
+    private resultDir;
+    onBegin(config: FullConfig, suite: Suite): void;
+    private static CONFIDENCE_MAP;
+    onTestEnd(test: TestCase, result: TestResult): Promise<void>;
+    onEnd(result: FullResult): Promise<void>;
+    private appendRecord;
+}
+export default KeveReporter;