@be-link/smart-test 1.0.1-beta.24 → 1.0.1-beta.25

package/README.md

@@ -1,420 +1,302 @@
 # @be-link/smart-test
 
-AI-powered visual testing for Playwright | 基于 AI 视觉模型的 Playwright 测试工具
+AI-powered test recorder for Playwright | 基于 AI 的 Playwright 测试录制工具
 
-## ✨ 特性
+## 特性
 
-- 🎯 **AI 视觉检查**：使用 AI 视觉模型自动检查页面截图是否符合预期
-- 🤖 **AI 代码生成**：使用 AI 自动生成测试用例和 Mock 数据
-- 📝 **TypeScript 支持**：完整的 TypeScript 类型定义
-- 🔧 **灵活配置**：支持自定义 AI 模型和服务地址
+- **交互式录制**：打开浏览器，手动操作页面，自动记录用户行为和 API 请求
+- **预设模式录制**：通过配置文件定义测试场景，批量执行录制
+- **AI 生成 Mock**：基于录制的 API 请求，AI 自动生成类型安全的 Mock 函数
+- **AI 生成测试**：基于录制的操作步骤，AI 自动生成 Midscene 测试用例
+- **TypeScript 支持**：完整的类型定义，生成的代码开箱即用
 
-## 📦 安装
+## 安装
 
 ```bash
+# 安装 smart-test
 pnpm add -D @be-link/smart-test
+
+# 安装必需的依赖
+pnpm add -D @midscene/web playwright @playwright/test dotenv tsx
 ```
 
-## 🚀 快速开始
+## 快速开始
 
 ### 1. 初始化配置
 
-首先在项目中初始化配置文件：
-
 ```bash
-# 在项目根目录运行
-smart-test init
+npx smart-test init
 ```
 
-然后编辑 `tests/smart-test.config.json`，配置 AI API 密钥：
-
-```json
-{
-  "ai": {
-    "apiKey": "${VITE_AI_API_KEY}",
-    "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
-    "visionModel": "qwen3-vl-plus",
-    "codeModel": "qwen3-coder-plus"
-  }
-}
-```
+这会在项目中生成：
 
-配置文件会在使用 AI 功能时自动加载，无需手动调用配置函数。
+- `tests/smart-test.config.ts` - Smart Test 配置
+- `playwright.config.ts` - Playwright 配置
+- `tests/e2e/` - 测试文件目录
+- `tests/mock/` - Mock 文件目录
 
-### 2. AI 视觉检查
+### 2. 配置环境变量
 
-在 Playwright 测试中使用 AI 检查页面截图：
+在项目根目录创建 `.env` 文件，配置 Midscene AI 相关的环境变量：
 
-```typescript
-import { test } from '@playwright/test';
-import { aiReviewScreenshot } from '@be-link/smart-test';
+```bash
+# AI 模型 API 地址
+MIDSCENE_MODEL_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
 
-test('页面显示正确', async ({ page }) => {
-  await page.goto('/home');
+# AI 模型 API 密钥
+MIDSCENE_MODEL_API_KEY=your_api_key
 
-  const result = await aiReviewScreenshot(page, '顶部显示logo和导航栏，主内容区域显示3个产品卡片');
+# AI 模型名称
+MIDSCENE_MODEL_NAME=qwen-vl-max-latest
 
-  if (!result.skipped && result.issues?.length) {
-    console.log('AI 发现的问题:', result.issues);
-  }
-});
+# AI 模型家族（可选，根据模型提供商设置）
+MIDSCENE_MODEL_FAMILY=qwen-vl
 ```
 
-### 3. AI 生成测试用例
+> 💡 Smart Test 和 Midscene 共用相同的环境变量，无需重复配置
 
-自动生成完整的 Playwright 测试用例：
+### 3. 开始录制
 
-```typescript
-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: ['验证页面显示"优惠券"标题', '验证显示"夏日满减券"', '点击"核销券"按钮', '验证显示"到店核销券"文本'],
-});
+先创建预设配置：
 
-if (result.ok) {
-  console.log('生成的测试代码:\n', result.code);
-}
+```bash
+npx smart-test preset
 ```
 
-### 4. AI 生成 Mock 数据
-
-通过传入实际的 TypeScript 类型定义，AI 会生成完全符合接口规范的 Mock 数据：
+编辑生成的 `*.preset.ts` 文件：
 
 ```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;
-}`,
-    },
+import type { RecordingPreset } from '@be-link/smart-test';
+
+const preset: RecordingPreset = {
+  pageUrl: 'http://localhost:8080/login',
+  caseName: 'user-login',
+  testCases: [
     {
-      typeName: 'IPickUpStoreUserInfo',
-      content: `export interface IPickUpStoreUserInfo {
-  id?: string;
-  /** 用户ID */
-  userId: string;
-  /** 提货人手机号 */
-  receiverMobile: string;
-  /** 提货人名称 */
-  receiverName: string;
-}`,
+      name: '用户登录成功',
+      steps: ['输入用户名 testuser', '输入密码 123456', '点击登录按钮'],
+      expected: '跳转到首页，显示欢迎信息',
     },
   ],
-});
+  viewport: 'mobile-ios',
+  headless: false,
+};
 
-if (result.ok) {
-  console.log('生成的 Mock 代码:\n', result.code);
-  // AI 会严格按照类型定义生成符合规范的 mock 数据
-}
+export default preset;
 ```
 
-### 5. 通用代码生成
-
-使用 AI 生成任意 TypeScript 代码：
-
-```typescript
-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);
-}
+```bash
+npx smart-test run login.preset.ts
 ```
 
-## 📖 API 文档
-
-### aiReviewScreenshot
+#### 方式二：交互式录制
 
-使用 AI 视觉模型检查页面截图是否符合预期。
-
-```typescript
-function aiReviewScreenshot(page: Page, options: string | AiCheckOptions): Promise<AiCheckResult>;
+```bash
+npx smart-test record
 ```
 
-**参数：**
+按照提示输入：
 
-- `page`: Playwright Page 对象
-- `options`: 检查选项
-  - 字符串：直接传入预期描述
-  - 对象：包含 `expected`（预期描述）、`fullPage`（是否全页截图）等配置
+1. 页面 URL
+2. 测试用例名称
+3. 测试场景描述
+4. 视口尺寸
 
-**返回值：**
+### 4. 运行测试
 
-```typescript
-interface AiCheckResult {
-  ok: boolean; // 检查是否通过
-  issues?: string[]; // 发现的问题列表
-  suggestion?: string[]; // 改进建议列表
-  skipped?: boolean; // 是否跳过检查
-  reason?: string; // 跳过原因
-  rawResponse?: string; // AI 原始响应
-}
+```bash
+npx playwright test
 ```
 
-### aiGenerateTestCase
+## 生成的文件
 
-使用 AI 生成完整的 Playwright 测试用例。
+录制完成后，会在 `tests/` 目录生成：
 
-```typescript
-function aiGenerateTestCase(options: AiTestCaseGenerationOptions): Promise<AiCodeGenerationResult>;
 ```
-
-**参数：**
-
-```typescript
-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 数据描述
-}
+tests/
+├── e2e/
+│   └── {caseName}.spec.ts    # Midscene 测试用例
+├── mock/
+│   └── {caseName}.mock.ts    # Mock 函数
+└── smart-test.config.ts      # 配置文件
 ```
 
-### aiGenerateMock
-
-使用 AI 生成 API Mock 函数。
+### Mock 文件示例
 
 ```typescript
-function aiGenerateMock(options: AiMockGenerationOptions): Promise<AiCodeGenerationResult>;
+/**
+ * 自动生成的 Mock 文件
+ * @generated by @be-link/smart-test
+ */
+import type { Page } from '@playwright/test';
+
+export async function mockUserLoginApis(page: Page): Promise<void> {
+  await page.route('**/api/user/login', async (route) => {
+    await route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        code: 0,
+        data: { token: 'xxx', userId: '123' },
+      }),
+    });
+  });
+}
 ```
 
-**参数：**
+### 测试文件示例
 
 ```typescript
-interface AiMockGenerationOptions {
-  apiPath: string; // API 路径
-  description: string; // Mock 数据描述
-  responseType?: string; // 响应数据类型名称（可选）
-  typeDefinitions?: TypeDefinition[]; // TypeScript 类型定义列表（可选）
-  referenceCode?: string; // 参考代码
-  // ... 以及 AiBaseConfig 的所有配置项
-}
+/**
+ * 自动生成的测试文件
+ * @generated by @be-link/smart-test
+ */
+import { expect, test } from '@playwright/test';
+import { PlaywrightAgent } from '@midscene/web/playwright';
+
+import { mockUserLoginApis } from '../mock/user-login.mock';
+
+test.describe('user-login', () => {
+  let agent: PlaywrightAgent;
+
+  test.beforeEach(async ({ page }) => {
+    await mockUserLoginApis(page);
+    await page.goto('/login');
+    await page.waitForLoadState('networkidle');
+    agent = new PlaywrightAgent(page);
+  });
 
-interface TypeDefinition {
-  typeName: string; // 类型名称
-  content: string; // 类型定义内容
-}
+  test('用户登录成功', async () => {
+    await agent.aiAction('输入用户名 testuser');
+    await agent.aiAction('输入密码 123456');
+    await agent.aiAction('点击登录按钮');
+    await agent.aiAssert('跳转到首页，显示欢迎信息');
+  });
+});
 ```
 
-**使用说明：**
-传入 `typeDefinitions` 和 `responseType`，AI 会严格按照 TypeScript 类型定义生成 mock 数据，确保类型安全和数据准确性
+## CLI 命令
 
-### aiGenerateCode
+### smart-test init
 
-通用的 AI 代码生成函数。
+初始化配置文件和目录结构。
 
-```typescript
-function aiGenerateCode(options: AiCodeGenerationOptions): Promise<AiCodeGenerationResult>;
+```bash
+npx smart-test init
 ```
 
-**参数：**
+### smart-test preset
 
-```typescript
-interface AiCodeGenerationOptions {
-  prompt: string; // 代码生成描述
-  context?: string; // 上下文代码
-  // ... 以及 AiBaseConfig 的所有配置项
-}
-```
-
-**返回值：**
+创建录制预设配置文件。
 
-```typescript
-interface AiCodeGenerationResult {
-  ok: boolean; // 是否成功生成
-  code?: string; // 生成的代码
-  skipped?: boolean; // 是否跳过
-  reason?: string; // 跳过或失败原因
-  rawResponse?: string; // AI 原始响应
-}
+```bash
+npx smart-test preset [filename]
 ```
 
-## 🎯 使用场景
+### smart-test run
 
-### 场景 1：视觉回归测试
+使用预设配置执行录制。
 
-使用 AI 自动检测页面的视觉变化，无需手动维护大量的断言代码：
+```bash
+npx smart-test run <preset-file>
+```
 
-```typescript
-test('首页显示正常', async ({ page }) => {
-  await page.goto('/');
+### smart-test record
 
-  const result = await aiReviewScreenshot(page, {
-    expected: '页面顶部显示网站logo和主导航，中间显示轮播图，下方显示4个产品分类卡片',
-    fullPage: true,
-  });
+启动交互式录制模式。
 
-  expect(result.ok).toBeTruthy();
-});
+```bash
+npx smart-test record
 ```
 
-### 场景 2：快速生成测试代码
+## 配置文件
 
-为新功能快速生成测试用例骨架，节省编写测试代码的时间：
+### smart-test.config.ts
 
 ```typescript
-// 生成测试用例
-const result = await aiGenerateTestCase({
-  pageUrl: '/product/123',
-  scenario: '产品详情页展示和加入购物车功能',
-  apiMocks: [
-    { path: '**/api/product/detail', description: '返回产品详情' },
-    { path: '**/api/cart/add', description: '加入购物车成功' },
-  ],
-  testSteps: ['验证显示产品名称和价格', '点击"加入购物车"按钮', '验证显示成功提示'],
-});
-
-// 将生成的代码保存到文件，然后根据实际需要调整
+import type { SmartTestConfig } from '@be-link/smart-test';
+
+const config: SmartTestConfig = {
+  ai: {
+    // AI 模型配置（API Key 和 Base URL 从环境变量读取）
+    visionModel: 'qwen3-vl-plus',
+    codeModel: 'qwen3-coder-plus',
+  },
+  recording: {
+    // 测试文件输出目录
+    testDir: 'tests/e2e',
+    // Mock 文件输出目录
+    mockDir: 'tests/mock',
+    // API 路径匹配模式
+    apiPathPattern: '**/c-bff/**',
+    // 排除的 API 路径
+    excludeApiPatterns: [],
+  },
+};
+
+export default config;
 ```
 
-### 场景 3：Mock 数据管理
-
-通过传入实际的类型定义，确保生成的 Mock 数据完全符合接口规范：
+### 预设配置 (\*.preset.ts)
 
 ```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: [
+import type { RecordingPreset } from '@be-link/smart-test';
+
+const preset: RecordingPreset = {
+  // 要测试的页面 URL
+  pageUrl: 'http://localhost:8080/page',
+  // 测试用例名称（用于文件命名）
+  caseName: 'test-case',
+  // 测试场景列表
+  testCases: [
     {
-      typeName: 'IDefaultAddressResp',
-      content: extractTypeFromFile(addressTypeContent, 'IDefaultAddressResp'),
-    },
-    {
-      typeName: 'IUserAddress',
-      content: extractTypeFromFile(addressTypeContent, 'IUserAddress'),
+      name: '场景名称',
+      steps: ['步骤1', '步骤2'],
+      expected: '预期结果',
     },
   ],
-});
-
-// 生成的 mock 数据会严格符合类型定义，包括：
-// - 字段类型匹配（string、number、boolean、null 等）
-// - 必填/可选字段正确
-// - 嵌套对象结构准确
-// - 根据注释生成合理的测试数据
-```
-
-## ⚙️ 配置说明
-
-### 默认配置
-
-```typescript
-{
-  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
-  visionModel: 'qwen3-vl-plus',
-  codeModel: 'qwen3-coder-plus',
-  timeout: 30000
-}
+  // 子目录（可选）
+  subDir: '',
+  // 视口尺寸：'mobile-ios' | 'mobile-android' | 'tablet' | 'desktop' | 'desktop-wide'
+  viewport: 'mobile-ios',
+  // 是否使用无头模式
+  headless: false,
+};
+
+export default preset;
 ```
 
-## 🔍 最佳实践
+## 环境变量
 
-### 1. 合理使用 AI 检查
+| 变量名                    | 说明             | 必填 |
+| ------------------------- | ---------------- | ---- |
+| `MIDSCENE_MODEL_BASE_URL` | AI 模型 API 地址 | 是   |
+| `MIDSCENE_MODEL_API_KEY`  | AI 模型 API 密钥 | 是   |
+| `MIDSCENE_MODEL_NAME`     | AI 模型名称      | 是   |
+| `MIDSCENE_MODEL_FAMILY`   | AI 模型家族      | 否   |
 
-AI 视觉检查适合用于：
+## 依赖说明
 
-- ✅ 整体布局和结构验证
-- ✅ 内容完整性检查
-- ✅ 视觉回归测试
+| 依赖               | 说明                          |
+| ------------------ | ----------------------------- |
+| `@midscene/web`    | Midscene AI 驱动的 Web 测试库 |
+| `playwright`       | 浏览器自动化核心库            |
+| `@playwright/test` | Playwright 测试框架           |
+| `dotenv`           | 环境变量加载                  |
+| `tsx`              | TypeScript 执行器             |
 
-不适合用于：
+## 与 Midscene 配合
 
-- ❌ 精确的像素级对比
-- ❌ 颜色值精确匹配
-- ❌ 性能敏感的场景
+生成的测试用例基于 [Midscene](https://midscenejs.com/) 的 AI 驱动 API：
 
-### 2. 组合使用
+- `agent.aiAction()` - AI 驱动的页面操作
+- `agent.aiQuery()` - AI 驱动的数据查询
+- `agent.aiAssert()` - AI 驱动的断言
 
-将 AI 检查与传统断言结合使用，获得最佳效果：
+## License
 
-```typescript
-test('优惠券页面', async ({ page }) => {
-  await page.goto('/coupon');
-
-  // 传统断言：精确的功能验证
-  await expect(page.getByText('优惠券')).toBeVisible();
-  await expect(page.getByRole('button', { name: '核销券' })).toBeVisible();
-
-  // AI 检查：整体视觉验证
-  const aiResult = await aiReviewScreenshot(page, '页面整体布局合理，优惠券卡片排列整齐，信息展示清晰');
-
-  if (!aiResult.skipped && aiResult.issues?.length) {
-    console.warn('AI 发现的潜在问题:', aiResult.issues);
-  }
-});
-```
+MIT