@be-link/smart-test 1.0.1-beta.8 → 1.0.1-beta.9

package/README.md

@@ -1,285 +1,461 @@
 # @be-link/smart-test
 
-> AI-powered visual testing for Playwright - 基于 AI 视觉模型的 Playwright 测试工具
-
-使用 AI 视觉识别能力，让你的 E2E 测试更智能、更可靠。
+AI-powered visual testing for Playwright | 基于 AI 视觉模型的 Playwright 测试工具
 
 ## ✨ 特性
 
-- 🤖 **AI 视觉检查**：基于通义千问等视觉模型，智能检查页面是否符合预期
-- 🎯 **零侵入设计**：与 Playwright 无缝集成，无需修改现有测试代码
-- 🔧 **灵活配置**：支持全局配置和单次调用配置
-- 📸 **自动截图**：自动保存测试截图，方便排查问题
-- 🚫 **优雅降级**：无 API Key 时自动跳过，不影响其他测试
-- 📦 **TypeScript**：完整的类型定义支持
+- 🎯 **AI 视觉检查**：使用 AI 视觉模型自动检查页面截图是否符合预期
+- 🤖 **AI 代码生成**：使用 AI 自动生成测试用例和 Mock 数据
+- 📝 **TypeScript 支持**：完整的 TypeScript 类型定义
+- 🔧 **灵活配置**：支持自定义 AI 模型和服务地址
 
 ## 📦 安装
 
 ```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
+### 1. 配置 AI API
 
-在项目根目录创建 `.env` 文件：
+```typescript
+import { configure } from '@be-link/smart-test';
 
-```bash
-AI_API_KEY=sk-your-api-key-here
+configure({
+  apiKey: process.env.AI_API_KEY,
+  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+  visionModel: 'qwen3-vl-plus',
+  codeModel: 'qwen3-coder-plus',
+});
 ```
 
-### 2. 初始化配置
+### 2. AI 视觉检查
 
-在 `playwright.config.ts` 中配置：
+在 Playwright 测试中使用 AI 检查页面截图：
 
 ```typescript
-import { defineConfig } from '@playwright/test';
-import { configure } from '@be-link/smart-test';
+import { test } from '@playwright/test';
+import { aiReviewScreenshot } from '@be-link/smart-test';
 
-// 初始化 AI 配置
-configure({
-  apiKey: process.env.AI_API_KEY,
-  screenshotDir: './test-results/ai-screenshots',
-});
+test('页面显示正确', async ({ page }) => {
+  await page.goto('/home');
 
-export default defineConfig({
-  // ... 其他 Playwright 配置
+  const result = await aiReviewScreenshot(page, '顶部显示logo和导航栏，主内容区域显示3个产品卡片');
+
+  if (!result.skipped && result.issues?.length) {
+    console.log('AI 发现的问题:', result.issues);
+  }
 });
 ```
 
-### 3. 在测试中使用
+### 3. AI 生成测试用例
+
+自动生成完整的 Playwright 测试用例：
 
 ```typescript
-import { test, expect } from '@playwright/test';
-import { aiReviewScreenshot } from '@be-link/smart-test';
+import { aiGenerateTestCase } from '@be-link/smart-test';
+
+const result = await aiGenerateTestCase({
+  pageUrl: '/coupon?userId=e2e-user&isPopup=true',
+  scenario: '优惠券页面展示和 Tab 切换功能',
+  apiMocks: [
+    {
+      path: '**/api/user/info/get-user-detail',
+      description: '返回用户信息，包含 id、nickname、memberLevel 等字段',
+    },
+    {
+      path: '**/api/user/coupon/get-available-coupons-grouped',
+      description: '返回可用优惠券列表，按券 ID 分组',
+    },
+  ],
+  aiCheckExpected: '顶部展示门店名称和用户昵称，列表中应显示3张优惠券卡片',
+  testSteps: ['验证页面显示"优惠券"标题', '验证显示"夏日满减券"', '点击"核销券"按钮', '验证显示"到店核销券"文本'],
+});
 
-test.describe('优惠券页面', () => {
-  test('AI 检查页面布局', async ({ page }) => {
-    await page.goto('/coupon');
+if (result.ok) {
+  console.log('生成的测试代码:\n', result.code);
+}
+```
 
-    // 使用 AI 检查页面
-    const result = await aiReviewScreenshot(page, '页面应该显示优惠券列表，包含标题、优惠券卡片和底部按钮');
+### 4. AI 生成 Mock 数据
 
-    // 处理结果
-    if (result.skipped) {
-      test.skip(); // 无 API Key 时跳过
-    }
+通过传入实际的 TypeScript 类型定义，AI 会生成完全符合接口规范的 Mock 数据：
 
-    expect(result.ok, result.issues?.join(', ')).toBeTruthy();
-  });
+```typescript
+import { aiGenerateMock } from '@be-link/smart-test';
+import fs from 'fs';
+
+// 读取类型定义文件
+const addressTypes = fs.readFileSync('./src/api/address/types.ts', 'utf-8');
+
+// 提取需要的类型定义
+const result = await aiGenerateMock({
+  apiPath: '**/api/user/address/get-default-address',
+  description: '返回用户默认地址信息',
+  responseType: 'IDefaultAddressResp',
+  typeDefinitions: [
+    {
+      typeName: 'IDefaultAddressResp',
+      content: `export interface IDefaultAddressResp {
+  /** 默认地址 */
+  defaultAddress: IUserAddress | null;
+  /** 自提地址 */
+  pickupAddress: IPickUpStoreUserInfo | null;
+}`,
+    },
+    {
+      typeName: 'IUserAddress',
+      content: `export interface IUserAddress {
+  /** 地址ID */
+  id: string;
+  /** 用户ID */
+  userId: string;
+  /** 收件人姓名 */
+  receiverName: string;
+  /** 收件人手机号 */
+  receiverMobile: string;
+  /** 省份名称 */
+  provinceName: string;
+  /** 城市名称 */
+  cityName: string;
+  /** 区县名称 */
+  districtName: string;
+  /** 详细地址 */
+  detailAddress: string;
+  /** 是否默认地址：1-是，0-否 */
+  isDefault: number;
+  /** 创建时间（毫秒时间戳） */
+  createdAt: number;
+}`,
+    },
+    {
+      typeName: 'IPickUpStoreUserInfo',
+      content: `export interface IPickUpStoreUserInfo {
+  id?: string;
+  /** 用户ID */
+  userId: string;
+  /** 提货人手机号 */
+  receiverMobile: string;
+  /** 提货人名称 */
+  receiverName: string;
+}`,
+    },
+  ],
 });
-```
 
-## 📖 API 文档
+if (result.ok) {
+  console.log('生成的 Mock 代码:\n', result.code);
+  // AI 会严格按照类型定义生成符合规范的 mock 数据
+}
+```
 
-### `configure(config)`
+### 5. 通用代码生成
 
-配置全局设置。
+使用 AI 生成任意 TypeScript 代码：
 
 ```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, // 超时时间（可选）
+import { aiGenerateCode } from '@be-link/smart-test';
+
+const result = await aiGenerateCode({
+  prompt: '生成一个函数，用于计算两个日期之间的天数差',
+  context: `// 项目中的日期工具示例
+function formatDate(date: Date): string {
+  return date.toISOString().split('T')[0];
+}`,
 });
+
+if (result.ok) {
+  console.log('生成的代码:\n', result.code);
+}
 ```
 
-### `aiReviewScreenshot(page, options)`
+## 📖 API 文档
+
+### aiReviewScreenshot
 
-使用 AI 检查页面截图。
+使用 AI 视觉模型检查页面截图是否符合预期。
+
+```typescript
+function aiReviewScreenshot(page: Page, options: string | AiCheckOptions): Promise<AiCheckResult>;
+```
 
 **参数：**
 
-- `page: Page` - Playwright Page 对象
-- `options: string | AiCheckOptions` - 检查选项
+- `page`: Playwright Page 对象
+- `options`: 检查选项
+  - 字符串：直接传入预期描述
+  - 对象：包含 `expected`（预期描述）、`fullPage`（是否全页截图）等配置
 
-**返回值：** `Promise<AiCheckResult>`
+**返回值：**
 
 ```typescript
 interface AiCheckResult {
   ok: boolean; // 检查是否通过
-  issues?: string[]; // 问题列表
-  skipped?: boolean; // 是否跳过
+  issues?: string[]; // 发现的问题列表
+  suggestion?: string[]; // 改进建议列表
+  skipped?: boolean; // 是否跳过检查
   reason?: string; // 跳过原因
-  screenshotPath?: string; // 截图路径
   rawResponse?: string; // AI 原始响应
 }
 ```
 
-## 🎨 使用示例
+### aiGenerateTestCase
 
-### 基础用法
+使用 AI 生成完整的 Playwright 测试用例。
 
 ```typescript
-// 简单字符串描述
-const result = await aiReviewScreenshot(page, '页面应该显示登录表单');
+function aiGenerateTestCase(options: AiTestCaseGenerationOptions): Promise<AiCodeGenerationResult>;
 ```
 
-### 带配置的用法
+**参数：**
 
 ```typescript
-// 带配置对象
-const result = await aiReviewScreenshot(page, {
-  expected: '页面应该显示商品列表',
-  model: 'gpt-4-vision-preview', // 使用其他模型
-});
+interface AiTestCaseGenerationOptions {
+  pageUrl: string; // 页面 URL
+  scenario: string; // 测试场景描述
+  apiMocks?: ApiMockConfig[]; // API Mock 配置列表
+  aiCheckExpected?: string; // AI 视觉检查预期
+  testSteps?: string[]; // 测试步骤列表
+  referenceCode?: string; // 参考代码
+  // ... 以及 AiBaseConfig 的所有配置项
+}
+
+interface ApiMockConfig {
+  path: string; // API 路径（支持通配符）
+  description: string; // Mock 数据描述
+}
 ```
 
-### 完整测试示例
+### aiGenerateMock
+
+使用 AI 生成 API Mock 函数。
 
 ```typescript
-import { test, expect } from '@playwright/test';
-import { aiReviewScreenshot } from '@be-link/smart-test';
+function aiGenerateMock(options: AiMockGenerationOptions): Promise<AiCodeGenerationResult>;
+```
 
-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,
-    });
+```typescript
+interface AiMockGenerationOptions {
+  apiPath: string; // API 路径
+  description: string; // Mock 数据描述
+  responseType?: string; // 响应数据类型名称（可选）
+  typeDefinitions?: TypeDefinition[]; // TypeScript 类型定义列表（可选）
+  referenceCode?: string; // 参考代码
+  // ... 以及 AiBaseConfig 的所有配置项
+}
 
-    if (result.skipped) {
-      console.log('跳过原因:', result.reason);
-      test.skip();
-    }
+interface TypeDefinition {
+  typeName: string; // 类型名称
+  content: string; // 类型定义内容
+}
+```
 
-    if (!result.ok && result.issues) {
-      console.warn('发现的问题:', result.issues);
-    }
+**使用说明：**
+传入 `typeDefinitions` 和 `responseType`，AI 会严格按照 TypeScript 类型定义生成 mock 数据，确保类型安全和数据准确性
 
-    expect(result.ok, `AI 检查失败: ${result.issues?.join(', ')}`).toBeTruthy();
-  });
+### aiGenerateCode
 
-  test('检查响应式布局', async ({ page }) => {
-    // 切换到移动端视图
-    await page.setViewportSize({ width: 375, height: 667 });
+通用的 AI 代码生成函数。
 
-    const result = await aiReviewScreenshot(page, '移动端布局：商品应该以单列显示，每个卡片占满宽度');
+```typescript
+function aiGenerateCode(options: AiCodeGenerationOptions): Promise<AiCodeGenerationResult>;
+```
 
-    if (!result.skipped) {
-      expect(result.ok).toBeTruthy();
-    }
-  });
-});
+**参数：**
+
+```typescript
+interface AiCodeGenerationOptions {
+  prompt: string; // 代码生成描述
+  context?: string; // 上下文代码
+  // ... 以及 AiBaseConfig 的所有配置项
+}
 ```
 
-### 批量检查多个元素
+**返回值：**
 
 ```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();
-
-    // 这里可以扩展为单独检查某个元素的功能
-    // 当前版本检查整页，后续可以增强
-  }
-});
+interface AiCodeGenerationResult {
+  ok: boolean; // 是否成功生成
+  code?: string; // 生成的代码
+  skipped?: boolean; // 是否跳过
+  reason?: string; // 跳过或失败原因
+  rawResponse?: string; // AI 原始响应
+}
 ```
 
-## 🔧 高级配置
+### configure
 
-### 支持多种 AI 模型
+配置全局 AI 设置。
 
 ```typescript
-// 使用通义千问（默认）
-configure({
-  apiKey: process.env.QWEN_API_KEY,
-  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
-  model: 'qwen3-vl-plus',
-});
+function configure(config: Partial<AiBaseConfig>): void;
+
+interface AiBaseConfig {
+  apiKey?: string; // AI API 密钥
+  baseURL?: string; // AI 服务地址
+  visionModel?: string; // 视觉模型名称
+  codeModel?: string; // 代码模型名称
+  timeout?: number; // 请求超时时间（毫秒）
+}
+```
 
-// 使用 OpenAI GPT-4 Vision
-configure({
-  apiKey: process.env.OPENAI_API_KEY,
-  baseURL: 'https://api.openai.com/v1',
-  model: 'gpt-4-vision-preview',
+## 🎯 使用场景
+
+### 场景 1：视觉回归测试
+
+使用 AI 自动检测页面的视觉变化，无需手动维护大量的断言代码：
+
+```typescript
+test('首页显示正常', async ({ page }) => {
+  await page.goto('/');
+
+  const result = await aiReviewScreenshot(page, {
+    expected: '页面顶部显示网站logo和主导航，中间显示轮播图，下方显示4个产品分类卡片',
+    fullPage: true,
+  });
+
+  expect(result.ok).toBeTruthy();
 });
 ```
 
-### 自定义截图存储
+### 场景 2：快速生成测试代码
+
+为新功能快速生成测试用例骨架，节省编写测试代码的时间：
 
 ```typescript
-configure({
-  screenshotDir: './custom-screenshots',
-  saveScreenshots: true,
+// 生成测试用例
+const result = await aiGenerateTestCase({
+  pageUrl: '/product/123',
+  scenario: '产品详情页展示和加入购物车功能',
+  apiMocks: [
+    { path: '**/api/product/detail', description: '返回产品详情' },
+    { path: '**/api/cart/add', description: '加入购物车成功' },
+  ],
+  testSteps: ['验证显示产品名称和价格', '点击"加入购物车"按钮', '验证显示成功提示'],
 });
 
-// 单次调用自定义
-const result = await aiReviewScreenshot(page, {
-  expected: '...',
+// 将生成的代码保存到文件，然后根据实际需要调整
+```
+
+### 场景 3：Mock 数据管理
+
+通过传入实际的类型定义，确保生成的 Mock 数据完全符合接口规范：
+
+```typescript
+// 读取或定义类型
+import { readFileSync } from 'fs';
+
+const addressTypeContent = readFileSync('./src/api/address/types.ts', 'utf-8');
+// 或者直接定义类型字符串
+
+const result = await aiGenerateMock({
+  apiPath: '**/api/user/address/get-default-address',
+  description: '返回用户默认地址',
+  responseType: 'IDefaultAddressResp',
+  typeDefinitions: [
+    {
+      typeName: 'IDefaultAddressResp',
+      content: extractTypeFromFile(addressTypeContent, 'IDefaultAddressResp'),
+    },
+    {
+      typeName: 'IUserAddress',
+      content: extractTypeFromFile(addressTypeContent, 'IUserAddress'),
+    },
+  ],
 });
+
+// 生成的 mock 数据会严格符合类型定义，包括：
+// - 字段类型匹配（string、number、boolean、null 等）
+// - 必填/可选字段正确
+// - 嵌套对象结构准确
+// - 根据注释生成合理的测试数据
 ```
 
-### 在 CI 环境中使用
+## ⚙️ 配置说明
+
+### 默认配置
 
 ```typescript
-// 在 CI 中可能不需要保存截图，减少存储开销
+{
+  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+  visionModel: 'qwen3-vl-plus',
+  codeModel: 'qwen3-coder-plus',
+  timeout: 30000
+}
+```
+
+### 自定义配置
+
+可以在全局配置中设置默认值，也可以在每次调用时覆盖：
+
+```typescript
+// 全局配置
 configure({
   apiKey: process.env.AI_API_KEY,
-  saveScreenshots: process.env.CI !== 'true',
+  visionModel: 'custom-vision-model',
+});
+
+// 单次调用覆盖
+await aiReviewScreenshot(page, {
+  expected: '...',
+  visionModel: 'another-model', // 仅此次调用使用
 });
 ```
 
-## 🤔 常见问题
+## 🔍 最佳实践
 
-### Q: 没有配置 API Key 会怎样？
+### 1. 环境变量管理
 
-A: 测试会自动跳过 AI 检查，返回 `skipped: true`，不会影响其他测试的执行。
+建议将 API Key 存储在环境变量中：
 
-### Q: 支持哪些 AI 模型？
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+import { configure } from '@be-link/smart-test';
 
-A: 理论上支持所有兼容 OpenAI Chat Completions API 的视觉模型，包括：
+configure({
+  apiKey: process.env.AI_API_KEY,
+});
 
-- 通义千问 (qwen3-vl-plus) - 默认
-- OpenAI GPT-4 Vision
-- 其他兼容的模型服务
+export default defineConfig({
+  // ... 其他配置
+});
+```
 
-### Q: 截图保存在哪里？
+### 2. 合理使用 AI 检查
 
-A: 默认保存在 `./test-results/ai-screenshots/` 目录，可以通过 `screenshotDir` 配置修改。
+AI 视觉检查适合用于：
 
-### Q: 如何查看 AI 的原始响应？
+- ✅ 整体布局和结构验证
+- ✅ 内容完整性检查
+- ✅ 视觉回归测试
 
-A: 检查结果中的 `rawResponse` 字段包含了 AI 的原始响应内容。
+不适合用于：
 
-```typescript
-const result = await aiReviewScreenshot(page, '...');
-console.log('AI 原始响应:', result.rawResponse);
-```
+- ❌ 精确的像素级对比
+- ❌ 颜色值精确匹配
+- ❌ 性能敏感的场景
 
-## 📝 License
+### 3. 组合使用
 
-MIT
+将 AI 检查与传统断言结合使用，获得最佳效果：
 
-## 🤝 贡献
+```typescript
+test('优惠券页面', async ({ page }) => {
+  await page.goto('/coupon');
 
-欢迎提交 Issue 和 Pull Request！
+  // 传统断言：精确的功能验证
+  await expect(page.getByText('优惠券')).toBeVisible();
+  await expect(page.getByRole('button', { name: '核销券' })).toBeVisible();
 
-## 📮 联系方式
+  // AI 检查：整体视觉验证
+  const aiResult = await aiReviewScreenshot(page, '页面整体布局合理，优惠券卡片排列整齐，信息展示清晰');
 
-如有问题，请在 [GitHub Issues](https://github.com/snowmountain-top/be-link/issues) 中提出。
+  if (!aiResult.skipped && aiResult.issues?.length) {
+    console.warn('AI 发现的潜在问题:', aiResult.issues);
+  }
+});
+```