@be-link/smart-test 1.0.1-beta.0

package/README.md

@@ -0,0 +1,289 @@
+# @be-link/smart-test
+
+> AI-powered visual testing for Playwright - 基于 AI 视觉模型的 Playwright 测试工具
+
+使用 AI 视觉识别能力，让你的 E2E 测试更智能、更可靠。
+
+## ✨ 特性
+
+- 🤖 **AI 视觉检查**：基于通义千问等视觉模型，智能检查页面是否符合预期
+- 🎯 **零侵入设计**：与 Playwright 无缝集成，无需修改现有测试代码
+- 🔧 **灵活配置**：支持全局配置和单次调用配置
+- 📸 **自动截图**：自动保存测试截图，方便排查问题
+- 🚫 **优雅降级**：无 API Key 时自动跳过，不影响其他测试
+- 📦 **TypeScript**：完整的类型定义支持
+
+## 📦 安装
+
+```bash
+# 使用 pnpm
+pnpm add -D @be-link/smart-test
+
+# 使用 npm
+npm install -D @be-link/smart-test
+
+# 使用 yarn
+yarn add -D @be-link/smart-test
+```
+
+## 🚀 快速开始
+
+### 1. 配置 API Key
+
+在项目根目录创建 `.env` 文件：
+
+```bash
+AI_API_KEY=sk-your-api-key-here
+```
+
+### 2. 初始化配置
+
+在 `playwright.config.ts` 中配置：
+
+```typescript
+import { defineConfig } from '@playwright/test';
+import { configure } from '@be-link/smart-test';
+
+// 初始化 AI 配置
+configure({
+  apiKey: process.env.AI_API_KEY,
+  screenshotDir: './test-results/ai-screenshots',
+});
+
+export default defineConfig({
+  // ... 其他 Playwright 配置
+});
+```
+
+### 3. 在测试中使用
+
+```typescript
+import { test, expect } from '@playwright/test';
+import { aiReviewScreenshot } from '@be-link/smart-test';
+
+test.describe('优惠券页面', () => {
+  test('AI 检查页面布局', async ({ page }) => {
+    await page.goto('/coupon');
+
+    // 使用 AI 检查页面
+    const result = await aiReviewScreenshot(page, '页面应该显示优惠券列表，包含标题、优惠券卡片和底部按钮');
+
+    // 处理结果
+    if (result.skipped) {
+      test.skip(); // 无 API Key 时跳过
+    }
+
+    expect(result.ok, result.issues?.join(', ')).toBeTruthy();
+  });
+});
+```
+
+## 📖 API 文档
+
+### `configure(config)`
+
+配置全局设置。
+
+```typescript
+import { configure } from '@be-link/smart-test';
+
+configure({
+  apiKey: 'sk-xxx', // AI API 密钥
+  baseURL: 'https://...', // AI 服务地址（可选）
+  model: 'qwen3-vl-plus', // AI 模型（可选）
+  screenshotDir: './screenshots', // 截图保存目录（可选）
+  saveScreenshots: true, // 是否保存截图（可选）
+  timeout: 30000, // 超时时间（可选）
+});
+```
+
+### `aiReviewScreenshot(page, options)`
+
+使用 AI 检查页面截图。
+
+**参数：**
+
+- `page: Page` - Playwright Page 对象
+- `options: string | AiCheckOptions` - 检查选项
+
+**返回值：** `Promise<AiCheckResult>`
+
+```typescript
+interface AiCheckResult {
+  ok: boolean; // 检查是否通过
+  issues?: string[]; // 问题列表
+  skipped?: boolean; // 是否跳过
+  reason?: string; // 跳过原因
+  screenshotPath?: string; // 截图路径
+  rawResponse?: string; // AI 原始响应
+}
+```
+
+## 🎨 使用示例
+
+### 基础用法
+
+```typescript
+// 简单字符串描述
+const result = await aiReviewScreenshot(page, '页面应该显示登录表单');
+```
+
+### 带配置的用法
+
+```typescript
+// 带配置对象
+const result = await aiReviewScreenshot(page, {
+  expected: '页面应该显示商品列表',
+  model: 'gpt-4-vision-preview', // 使用其他模型
+  saveScreenshots: false, // 不保存截图
+  screenshotPrefix: 'product', // 自定义截图前缀
+});
+```
+
+### 完整测试示例
+
+```typescript
+import { test, expect } from '@playwright/test';
+import { aiReviewScreenshot } from '@be-link/smart-test';
+
+test.describe('商品页面测试', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/products');
+    await page.waitForLoadState('networkidle');
+  });
+
+  test('检查页面布局', async ({ page }) => {
+    const result = await aiReviewScreenshot(page, {
+      expected: '页面顶部应有搜索框，中间显示商品网格布局，底部有分页器',
+      fullPage: true,
+    });
+
+    if (result.skipped) {
+      console.log('跳过原因:', result.reason);
+      test.skip();
+    }
+
+    if (!result.ok && result.issues) {
+      console.warn('发现的问题:', result.issues);
+    }
+
+    expect(result.ok, `AI 检查失败: ${result.issues?.join(', ')}`).toBeTruthy();
+  });
+
+  test('检查响应式布局', async ({ page }) => {
+    // 切换到移动端视图
+    await page.setViewportSize({ width: 375, height: 667 });
+
+    const result = await aiReviewScreenshot(page, '移动端布局：商品应该以单列显示，每个卡片占满宽度');
+
+    if (!result.skipped) {
+      expect(result.ok).toBeTruthy();
+    }
+  });
+});
+```
+
+### 批量检查多个元素
+
+```typescript
+test('检查多个区域', async ({ page }) => {
+  const checks = [
+    { selector: '.header', expected: '顶部导航栏应显示 logo 和菜单' },
+    { selector: '.main-content', expected: '主内容区应显示文章列表' },
+    { selector: '.sidebar', expected: '侧边栏应显示热门标签' },
+  ];
+
+  for (const check of checks) {
+    const element = await page.locator(check.selector);
+    const screenshot = await element.screenshot();
+
+    // 这里可以扩展为单独检查某个元素的功能
+    // 当前版本检查整页，后续可以增强
+  }
+});
+```
+
+## 🔧 高级配置
+
+### 支持多种 AI 模型
+
+```typescript
+// 使用通义千问（默认）
+configure({
+  apiKey: process.env.QWEN_API_KEY,
+  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+  model: 'qwen3-vl-plus',
+});
+
+// 使用 OpenAI GPT-4 Vision
+configure({
+  apiKey: process.env.OPENAI_API_KEY,
+  baseURL: 'https://api.openai.com/v1',
+  model: 'gpt-4-vision-preview',
+});
+```
+
+### 自定义截图存储
+
+```typescript
+configure({
+  screenshotDir: './custom-screenshots',
+  saveScreenshots: true,
+});
+
+// 单次调用自定义
+const result = await aiReviewScreenshot(page, {
+  expected: '...',
+  screenshotPrefix: 'my-feature',
+  screenshotDir: './feature-screenshots',
+});
+```
+
+### 在 CI 环境中使用
+
+```typescript
+// 在 CI 中可能不需要保存截图，减少存储开销
+configure({
+  apiKey: process.env.AI_API_KEY,
+  saveScreenshots: process.env.CI !== 'true',
+});
+```
+
+## 🤔 常见问题
+
+### Q: 没有配置 API Key 会怎样？
+
+A: 测试会自动跳过 AI 检查，返回 `skipped: true`，不会影响其他测试的执行。
+
+### Q: 支持哪些 AI 模型？
+
+A: 理论上支持所有兼容 OpenAI Chat Completions API 的视觉模型，包括：
+
+- 通义千问 (qwen3-vl-plus) - 默认
+- OpenAI GPT-4 Vision
+- 其他兼容的模型服务
+
+### Q: 截图保存在哪里？
+
+A: 默认保存在 `./test-results/ai-screenshots/` 目录，可以通过 `screenshotDir` 配置修改。
+
+### Q: 如何查看 AI 的原始响应？
+
+A: 检查结果中的 `rawResponse` 字段包含了 AI 的原始响应内容。
+
+```typescript
+const result = await aiReviewScreenshot(page, '...');
+console.log('AI 原始响应:', result.rawResponse);
+```
+
+## 📝 License
+
+MIT
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 📮 联系方式
+
+如有问题，请在 [GitHub Issues](https://github.com/snowmountain-top/be-link/issues) 中提出。

package/dist/core/ai-assistant.d.ts

@@ -0,0 +1,30 @@
+import type { Page } from '@playwright/test';
+import type { AiCheckOptions, AiCheckResult } from './types';
+/**
+ * 使用 AI 视觉模型检查页面截图是否符合预期
+ *
+ * @param page - Playwright Page 对象
+ * @param options - 检查选项（字符串或配置对象）
+ * @returns 检查结果
+ *
+ * @example
+ * ```typescript
+ * // 简单使用
+ * const result = await aiReviewScreenshot(page, '页面应该显示优惠券列表');
+ *
+ * // 带配置使用
+ * const result = await aiReviewScreenshot(page, {
+ *   expected: '页面应该显示优惠券列表',
+ *   model: 'gpt-4-vision-preview',
+ *   saveScreenshots: false,
+ * });
+ *
+ * // 处理结果
+ * if (result.skipped) {
+ *   test.skip();
+ * }
+ * expect(result.ok, result.issues?.join(', ')).toBeTruthy();
+ * ```
+ */
+export declare function aiReviewScreenshot(page: Page, options: string | AiCheckOptions): Promise<AiCheckResult>;
+//# sourceMappingURL=ai-assistant.d.ts.map

package/dist/core/ai-assistant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-assistant.d.ts","sourceRoot":"","sources":["../../src/core/ai-assistant.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAkB,MAAM,SAAS,CAAC;AAI7E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CA2E7G"}

package/dist/core/config.d.ts

@@ -0,0 +1,36 @@
+import type { AiVisionConfig } from './types';
+/**
+ * 配置 AI 视觉检查的全局设置
+ *
+ * @param config - 配置选项
+ *
+ * @example
+ * ```typescript
+ * import { configure } from '@be-link/smart-test';
+ *
+ * configure({
+ *   apiKey: process.env.AI_API_KEY,
+ *   model: 'qwen3-vl-plus',
+ *   screenshotDir: './screenshots',
+ * });
+ * ```
+ */
+export declare function configure(config: Partial<AiVisionConfig>): void;
+/**
+ * 获取当前的全局配置
+ *
+ * @returns 当前配置
+ */
+export declare function getConfig(): Required<AiVisionConfig>;
+/**
+ * 重置配置为默认值
+ */
+export declare function resetConfig(): void;
+/**
+ * 合并全局配置和局部配置
+ *
+ * @param localConfig - 局部配置（会覆盖全局配置）
+ * @returns 合并后的配置
+ */
+export declare function mergeConfig(localConfig?: Partial<AiVisionConfig>): Required<AiVisionConfig>;
+//# sourceMappingURL=config.d.ts.map

package/dist/core/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAmB9C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI,CAK/D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,QAAQ,CAAC,cAAc,CAAC,CAEpD;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAElC;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,WAAW,GAAE,OAAO,CAAC,cAAc,CAAM,GAAG,QAAQ,CAAC,cAAc,CAAC,CAK/F"}

package/dist/core/types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * AI 视觉检查配置
+ */
+export interface AiVisionConfig {
+    /**
+     * AI API 密钥
+     */
+    apiKey?: string;
+    /**
+     * AI 服务的 base URL
+     * @default 'https://dashscope.aliyuncs.com/compatible-mode/v1'
+     */
+    baseURL?: string;
+    /**
+     * 使用的 AI 模型
+     * @default 'qwen3-vl-plus'
+     */
+    model?: string;
+    /**
+     * 截图保存目录
+     * @default './test-results/ai-screenshots'
+     */
+    screenshotDir?: string;
+    /**
+     * 是否保存截图到文件
+     * @default true
+     */
+    saveScreenshots?: boolean;
+    /**
+     * AI 请求超时时间（毫秒）
+     * @default 30000
+     */
+    timeout?: number;
+}
+/**
+ * AI 检查结果
+ */
+export interface AiCheckResult {
+    /**
+     * 检查是否通过
+     */
+    ok: boolean;
+    /**
+     * 检查发现的问题列表
+     */
+    issues?: string[];
+    /**
+     * 是否跳过了检查（例如：无 API key）
+     */
+    skipped?: boolean;
+    /**
+     * 跳过的原因
+     */
+    reason?: string;
+    /**
+     * 截图保存的路径（如果启用了保存）
+     */
+    screenshotPath?: string;
+    /**
+     * AI 原始响应内容
+     */
+    rawResponse?: string;
+}
+/**
+ * AI 检查选项（单次调用）
+ */
+export interface AiCheckOptions extends Partial<AiVisionConfig> {
+    /**
+     * 期望的页面描述或检查条件
+     */
+    expected: string;
+    /**
+     * 是否截取完整页面
+     * @default true
+     */
+    fullPage?: boolean;
+    /**
+     * 自定义截图文件名前缀
+     * @default 'ai-review'
+     */
+    screenshotPrefix?: string;
+}
+/**
+ * AI 响应的 JSON 格式
+ */
+export interface AiResponseJson {
+    /**
+     * 检查是否通过
+     */
+    pass: boolean;
+    /**
+     * 发现的问题列表
+     */
+    issues?: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,EAAE,EAAE,OAAO,CAAC;IAEZ;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,OAAO,CAAC,cAAc,CAAC;IAC7D;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,IAAI,EAAE,OAAO,CAAC;IAEd;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @be-link/smart-test
+ *
+ * AI-powered visual testing for Playwright
+ * 基于 AI 视觉模型的 Playwright 测试工具
+ */
+export { aiReviewScreenshot } from './core/ai-assistant';
+export { configure, getConfig, resetConfig } from './core/config';
+export type { AiVisionConfig, AiCheckResult, AiCheckOptions, AiResponseJson } from './core/types';
+//# 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;;;;;GAKG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAGlE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.esm.js

@@ -0,0 +1,247 @@
+import { OpenAI } from 'openai';
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * 默认配置
+ */
+const DEFAULT_CONFIG = {
+    apiKey: '',
+    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+    model: 'qwen3-vl-plus',
+    screenshotDir: './test-results/ai-screenshots',
+    saveScreenshots: true,
+    timeout: 30000,
+};
+/**
+ * 全局配置
+ */
+let globalConfig = { ...DEFAULT_CONFIG };
+/**
+ * 配置 AI 视觉检查的全局设置
+ *
+ * @param config - 配置选项
+ *
+ * @example
+ * ```typescript
+ * import { configure } from '@be-link/smart-test';
+ *
+ * configure({
+ *   apiKey: process.env.AI_API_KEY,
+ *   model: 'qwen3-vl-plus',
+ *   screenshotDir: './screenshots',
+ * });
+ * ```
+ */
+function configure(config) {
+    globalConfig = {
+        ...globalConfig,
+        ...config,
+    };
+}
+/**
+ * 获取当前的全局配置
+ *
+ * @returns 当前配置
+ */
+function getConfig() {
+    return { ...globalConfig };
+}
+/**
+ * 重置配置为默认值
+ */
+function resetConfig() {
+    globalConfig = { ...DEFAULT_CONFIG };
+}
+/**
+ * 合并全局配置和局部配置
+ *
+ * @param localConfig - 局部配置（会覆盖全局配置）
+ * @returns 合并后的配置
+ */
+function mergeConfig(localConfig = {}) {
+    return {
+        ...globalConfig,
+        ...localConfig,
+    };
+}
+
+/**
+ * 保存截图到文件
+ *
+ * @param screenshot - 截图 Buffer
+ * @param dir - 保存目录
+ * @param prefix - 文件名前缀
+ * @returns 截图文件的绝对路径
+ */
+async function saveScreenshot(screenshot, dir, prefix = 'ai-review') {
+    // 确保目录存在
+    await fs.promises.mkdir(dir, { recursive: true });
+    // 生成文件名（使用时间戳避免冲突）
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const filename = `${prefix}-${timestamp}.png`;
+    const screenshotPath = path.resolve(dir, filename);
+    // 写入文件
+    await fs.promises.writeFile(screenshotPath, screenshot);
+    return screenshotPath;
+}
+/**
+ * 将截图转换为 base64 编码
+ *
+ * @param screenshot - 截图 Buffer
+ * @returns base64 编码的字符串
+ */
+function screenshotToBase64(screenshot) {
+    return screenshot.toString('base64');
+}
+
+/**
+ * 使用 AI 视觉模型检查页面截图是否符合预期
+ *
+ * @param page - Playwright Page 对象
+ * @param options - 检查选项（字符串或配置对象）
+ * @returns 检查结果
+ *
+ * @example
+ * ```typescript
+ * // 简单使用
+ * const result = await aiReviewScreenshot(page, '页面应该显示优惠券列表');
+ *
+ * // 带配置使用
+ * const result = await aiReviewScreenshot(page, {
+ *   expected: '页面应该显示优惠券列表',
+ *   model: 'gpt-4-vision-preview',
+ *   saveScreenshots: false,
+ * });
+ *
+ * // 处理结果
+ * if (result.skipped) {
+ *   test.skip();
+ * }
+ * expect(result.ok, result.issues?.join(', ')).toBeTruthy();
+ * ```
+ */
+async function aiReviewScreenshot(page, options) {
+    // 规范化选项
+    const opts = typeof options === 'string' ? { expected: options } : options;
+    // 合并配置
+    const config = mergeConfig(opts);
+    // 检查 API key
+    if (!config.apiKey) {
+        return {
+            ok: true,
+            skipped: true,
+            reason: '未配置 AI API Key，跳过 AI 检查',
+        };
+    }
+    try {
+        // 截取页面截图
+        const screenshot = await page.screenshot({
+            fullPage: opts.fullPage !== false,
+        });
+        // 保存截图（如果启用）
+        let screenshotPath;
+        if (config.saveScreenshots) {
+            screenshotPath = await saveScreenshot(screenshot, config.screenshotDir, opts.screenshotPrefix || 'ai-review');
+            console.log(`[smart-test] 截图已保存: ${screenshotPath}`);
+        }
+        // 构建 AI 请求
+        const prompt = buildPrompt(opts.expected);
+        const openai = new OpenAI({
+            apiKey: config.apiKey,
+            baseURL: config.baseURL,
+        });
+        // 调用 AI 模型
+        const completion = await openai.chat.completions.create({
+            model: config.model,
+            messages: [
+                {
+                    role: 'user',
+                    content: [
+                        {
+                            type: 'image_url',
+                            image_url: {
+                                url: `data:image/png;base64,${screenshotToBase64(screenshot)}`,
+                            },
+                        },
+                        {
+                            type: 'text',
+                            text: prompt,
+                        },
+                    ],
+                },
+            ],
+        });
+        // 解析 AI 响应
+        const content = completion?.choices[0]?.message?.content || '';
+        const result = parseAiResponse(content);
+        return {
+            ...result,
+            screenshotPath,
+            rawResponse: content,
+        };
+    }
+    catch (error) {
+        console.error('[smart-test] AI 检查失败:', error);
+        return {
+            ok: true,
+            skipped: true,
+            reason: `AI 检查失败: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+/**
+ * 构建 AI 检查的 prompt
+ *
+ * @param expected - 期望描述
+ * @returns prompt 字符串
+ */
+function buildPrompt(expected) {
+    return `请检查这张页面截图是否符合预期：${expected}。
+
+要求：
+1. 仔细检查页面的布局、内容、文本是否符合描述
+2. 如果发现问题，请详细说明问题的位置和具体情况
+3. 返回标准 JSON 格式，不要包含其他文本
+
+返回格式：
+{
+  "pass": true/false,
+  "issues": ["问题1的详细描述", "问题2的详细描述"]
+}
+
+如果检查通过，issues 可以为空数组。`;
+}
+/**
+ * 解析 AI 的响应内容
+ *
+ * @param content - AI 返回的文本内容
+ * @returns 检查结果
+ */
+function parseAiResponse(content) {
+    try {
+        // 提取 JSON 对象（AI 可能返回带有前后文本的内容）
+        const jsonMatch = content.match(/\{[\s\S]*\}/);
+        if (!jsonMatch) {
+            console.warn('[smart-test] AI 响应无法解析为 JSON:', content);
+            return {
+                ok: true,
+                issues: [`AI 响应格式异常，无法解析`],
+            };
+        }
+        const parsed = JSON.parse(jsonMatch[0]);
+        return {
+            ok: parsed.pass,
+            issues: parsed.issues || [],
+        };
+    }
+    catch (error) {
+        console.error('[smart-test] 解析 AI 响应失败:', error);
+        return {
+            ok: true,
+            issues: [`AI 响应解析失败: ${error instanceof Error ? error.message : String(error)}`],
+        };
+    }
+}
+
+export { aiReviewScreenshot, configure, getConfig, resetConfig };

package/dist/index.js

@@ -0,0 +1,272 @@
+'use strict';
+
+var openai = require('openai');
+var fs = require('fs');
+var path = require('path');
+
+function _interopNamespaceDefault(e) {
+    var n = Object.create(null);
+    if (e) {
+        Object.keys(e).forEach(function (k) {
+            if (k !== 'default') {
+                var d = Object.getOwnPropertyDescriptor(e, k);
+                Object.defineProperty(n, k, d.get ? d : {
+                    enumerable: true,
+                    get: function () { return e[k]; }
+                });
+            }
+        });
+    }
+    n.default = e;
+    return Object.freeze(n);
+}
+
+var fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs);
+var path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
+
+/**
+ * 默认配置
+ */
+const DEFAULT_CONFIG = {
+    apiKey: '',
+    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+    model: 'qwen3-vl-plus',
+    screenshotDir: './test-results/ai-screenshots',
+    saveScreenshots: true,
+    timeout: 30000,
+};
+/**
+ * 全局配置
+ */
+let globalConfig = { ...DEFAULT_CONFIG };
+/**
+ * 配置 AI 视觉检查的全局设置
+ *
+ * @param config - 配置选项
+ *
+ * @example
+ * ```typescript
+ * import { configure } from '@be-link/smart-test';
+ *
+ * configure({
+ *   apiKey: process.env.AI_API_KEY,
+ *   model: 'qwen3-vl-plus',
+ *   screenshotDir: './screenshots',
+ * });
+ * ```
+ */
+function configure(config) {
+    globalConfig = {
+        ...globalConfig,
+        ...config,
+    };
+}
+/**
+ * 获取当前的全局配置
+ *
+ * @returns 当前配置
+ */
+function getConfig() {
+    return { ...globalConfig };
+}
+/**
+ * 重置配置为默认值
+ */
+function resetConfig() {
+    globalConfig = { ...DEFAULT_CONFIG };
+}
+/**
+ * 合并全局配置和局部配置
+ *
+ * @param localConfig - 局部配置（会覆盖全局配置）
+ * @returns 合并后的配置
+ */
+function mergeConfig(localConfig = {}) {
+    return {
+        ...globalConfig,
+        ...localConfig,
+    };
+}
+
+/**
+ * 保存截图到文件
+ *
+ * @param screenshot - 截图 Buffer
+ * @param dir - 保存目录
+ * @param prefix - 文件名前缀
+ * @returns 截图文件的绝对路径
+ */
+async function saveScreenshot(screenshot, dir, prefix = 'ai-review') {
+    // 确保目录存在
+    await fs__namespace.promises.mkdir(dir, { recursive: true });
+    // 生成文件名（使用时间戳避免冲突）
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const filename = `${prefix}-${timestamp}.png`;
+    const screenshotPath = path__namespace.resolve(dir, filename);
+    // 写入文件
+    await fs__namespace.promises.writeFile(screenshotPath, screenshot);
+    return screenshotPath;
+}
+/**
+ * 将截图转换为 base64 编码
+ *
+ * @param screenshot - 截图 Buffer
+ * @returns base64 编码的字符串
+ */
+function screenshotToBase64(screenshot) {
+    return screenshot.toString('base64');
+}
+
+/**
+ * 使用 AI 视觉模型检查页面截图是否符合预期
+ *
+ * @param page - Playwright Page 对象
+ * @param options - 检查选项（字符串或配置对象）
+ * @returns 检查结果
+ *
+ * @example
+ * ```typescript
+ * // 简单使用
+ * const result = await aiReviewScreenshot(page, '页面应该显示优惠券列表');
+ *
+ * // 带配置使用
+ * const result = await aiReviewScreenshot(page, {
+ *   expected: '页面应该显示优惠券列表',
+ *   model: 'gpt-4-vision-preview',
+ *   saveScreenshots: false,
+ * });
+ *
+ * // 处理结果
+ * if (result.skipped) {
+ *   test.skip();
+ * }
+ * expect(result.ok, result.issues?.join(', ')).toBeTruthy();
+ * ```
+ */
+async function aiReviewScreenshot(page, options) {
+    // 规范化选项
+    const opts = typeof options === 'string' ? { expected: options } : options;
+    // 合并配置
+    const config = mergeConfig(opts);
+    // 检查 API key
+    if (!config.apiKey) {
+        return {
+            ok: true,
+            skipped: true,
+            reason: '未配置 AI API Key，跳过 AI 检查',
+        };
+    }
+    try {
+        // 截取页面截图
+        const screenshot = await page.screenshot({
+            fullPage: opts.fullPage !== false,
+        });
+        // 保存截图（如果启用）
+        let screenshotPath;
+        if (config.saveScreenshots) {
+            screenshotPath = await saveScreenshot(screenshot, config.screenshotDir, opts.screenshotPrefix || 'ai-review');
+            console.log(`[smart-test] 截图已保存: ${screenshotPath}`);
+        }
+        // 构建 AI 请求
+        const prompt = buildPrompt(opts.expected);
+        const openai$1 = new openai.OpenAI({
+            apiKey: config.apiKey,
+            baseURL: config.baseURL,
+        });
+        // 调用 AI 模型
+        const completion = await openai$1.chat.completions.create({
+            model: config.model,
+            messages: [
+                {
+                    role: 'user',
+                    content: [
+                        {
+                            type: 'image_url',
+                            image_url: {
+                                url: `data:image/png;base64,${screenshotToBase64(screenshot)}`,
+                            },
+                        },
+                        {
+                            type: 'text',
+                            text: prompt,
+                        },
+                    ],
+                },
+            ],
+        });
+        // 解析 AI 响应
+        const content = completion?.choices[0]?.message?.content || '';
+        const result = parseAiResponse(content);
+        return {
+            ...result,
+            screenshotPath,
+            rawResponse: content,
+        };
+    }
+    catch (error) {
+        console.error('[smart-test] AI 检查失败:', error);
+        return {
+            ok: true,
+            skipped: true,
+            reason: `AI 检查失败: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+/**
+ * 构建 AI 检查的 prompt
+ *
+ * @param expected - 期望描述
+ * @returns prompt 字符串
+ */
+function buildPrompt(expected) {
+    return `请检查这张页面截图是否符合预期：${expected}。
+
+要求：
+1. 仔细检查页面的布局、内容、文本是否符合描述
+2. 如果发现问题，请详细说明问题的位置和具体情况
+3. 返回标准 JSON 格式，不要包含其他文本
+
+返回格式：
+{
+  "pass": true/false,
+  "issues": ["问题1的详细描述", "问题2的详细描述"]
+}
+
+如果检查通过，issues 可以为空数组。`;
+}
+/**
+ * 解析 AI 的响应内容
+ *
+ * @param content - AI 返回的文本内容
+ * @returns 检查结果
+ */
+function parseAiResponse(content) {
+    try {
+        // 提取 JSON 对象（AI 可能返回带有前后文本的内容）
+        const jsonMatch = content.match(/\{[\s\S]*\}/);
+        if (!jsonMatch) {
+            console.warn('[smart-test] AI 响应无法解析为 JSON:', content);
+            return {
+                ok: true,
+                issues: [`AI 响应格式异常，无法解析`],
+            };
+        }
+        const parsed = JSON.parse(jsonMatch[0]);
+        return {
+            ok: parsed.pass,
+            issues: parsed.issues || [],
+        };
+    }
+    catch (error) {
+        console.error('[smart-test] 解析 AI 响应失败:', error);
+        return {
+            ok: true,
+            issues: [`AI 响应解析失败: ${error instanceof Error ? error.message : String(error)}`],
+        };
+    }
+}
+
+exports.aiReviewScreenshot = aiReviewScreenshot;
+exports.configure = configure;
+exports.getConfig = getConfig;
+exports.resetConfig = resetConfig;

package/dist/utils/screenshot.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 保存截图到文件
+ *
+ * @param screenshot - 截图 Buffer
+ * @param dir - 保存目录
+ * @param prefix - 文件名前缀
+ * @returns 截图文件的绝对路径
+ */
+export declare function saveScreenshot(screenshot: Buffer, dir: string, prefix?: string): Promise<string>;
+/**
+ * 将截图转换为 base64 编码
+ *
+ * @param screenshot - 截图 Buffer
+ * @returns base64 编码的字符串
+ */
+export declare function screenshotToBase64(screenshot: Buffer): string;
+//# sourceMappingURL=screenshot.d.ts.map

package/dist/utils/screenshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../src/utils/screenshot.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,MAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAanH;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE7D"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@be-link/smart-test",
+  "version": "1.0.1-beta.0",
+  "description": "AI-powered visual testing for Playwright - 基于 AI 视觉模型的 Playwright 测试工具",
+  "homepage": "https://github.com/snowmountain-top/be-link",
+  "author": "shian",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.esm.js"
+    },
+    "./dist/*": "./dist/*"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "openai": "^6.15.0"
+  },
+  "peerDependencies": {
+    "@playwright/test": "^1.40.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.50.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageInfo": {
+    "repoPath": "packages/smart-test"
+  },
+  "keywords": [
+    "playwright",
+    "ai",
+    "testing",
+    "visual-testing",
+    "e2e",
+    "qwen",
+    "vision",
+    "screenshot"
+  ],
+  "scripts": {
+    "clean": "rimraf ./dist && rimraf .rollup.cache",
+    "build:js": "rollup --config rollup.config.ts --configPlugin typescript",
+    "build:types": "tsc --project tsconfig.json",
+    "build": "pnpm clean && pnpm build:js && pnpm build:types",
+    "lint": "eslint src --ext .ts --fix"
+  }
+}