@be-link/smart-test 1.0.1-beta.3 → 1.0.1-beta.31

package/README.md

@@ -1,524 +1,301 @@
 # @be-link/smart-test
 
-> AI-powered visual testing for Playwright - 基于 AI 视觉模型的 Playwright 测试工具
+AI-powered test recorder for Playwright | 基于 AI 的 Playwright 测试录制工具
 
-使用 AI 视觉识别能力，让你的 E2E 测试更智能、更可靠。
+## 特性
 
-## ✨ 特性
+- **交互式录制**：打开浏览器，手动操作页面，自动记录用户行为和 API 请求
+- **预设模式录制**：通过配置文件定义测试场景，批量执行录制
+- **AI 生成 Mock**：基于录制的 API 请求，AI 自动生成类型安全的 Mock 函数
+- **AI 生成测试**：基于录制的操作步骤，AI 自动生成 Midscene 测试用例
+- **TypeScript 支持**：完整的类型定义，生成的代码开箱即用
 
-### 🤖 AI 视觉检查
-
-- 基于通义千问等视觉模型，智能检查页面是否符合预期
-- 支持自然语言描述测试预期
-- 自动识别页面问题并给出详细反馈
-
-### 🎯 零代码测试生成（开发中）
-
-- **CLI 工具**：一条命令自动生成测试代码
-- **录制模式**：访问页面自动录制接口和交互
-- **代码分析**：扫描项目代码自动生成 Mock 数据
-- **AI 生成**：基于自然语言描述生成完整测试
-
-### 🔧 灵活易用
-
-- 与 Playwright 无缝集成，零侵入设计
-- 支持全局配置和单次调用配置
-- 优雅降级：无 API Key 时自动跳过
-- 完整的 TypeScript 类型支持
-
-### 📸 自动化
-
-- 自动截图并保存
-- 自动生成 Mock 数据
-- 自动生成测试用例
-
-## 📦 安装
+## 安装
 
 ```bash
-# 使用 pnpm（推荐）
+# 安装 smart-test
 pnpm add -D @be-link/smart-test
 
-# 使用 npm
-npm install -D @be-link/smart-test
-
-# 使用 yarn
-yarn add -D @be-link/smart-test
+# 安装必需的依赖
+pnpm add -D @midscene/web playwright @playwright/test dotenv tsx
 ```
 
-## 🚀 快速开始
-
-### 方式一：使用 CLI 工具（推荐）⭐
+## 快速开始
 
-#### 1. 初始化配置
+### 1. 初始化配置
 
 ```bash
 npx smart-test init
 ```
 
-交互式配置向导会引导你完成设置：
-
-```
-━━━ 初始化 Smart Test 配置 ━━━
+这会在项目中生成：
 
-? 请输入 AI API Key: sk-xxxxx
-? 选择 AI 模型: 通义千问 (qwen3-vl-plus)
-? 测试文件目录: ./tests/e2e
-? Helpers 目录: ./tests/helpers
-? Playwright Base URL: http://localhost:8080
-? 文件命名风格: kebab-case
+- `tests/smart-test.config.ts` - Smart Test 配置
+- `playwright.config.ts` - Playwright 配置
+- `tests/e2e/` - 测试文件目录
+- `tests/mock/` - Mock 文件目录
 
-✓ 配置文件已创建: .smarttestrc.json
-```
+### 2. 配置环境变量
 
-#### 2. 生成测试代码（开发中）
+在项目根目录创建 `.env` 文件，配置 Midscene AI 相关的环境变量：
 
 ```bash
-# 录制模式 - 访问页面自动录制
-npx smart-test record --url http://localhost:8080/coupon
-
-# 代码分析模式 - 扫描页面代码
-npx smart-test generate --page src/pages/coupon/index.tsx
+# AI 模型 API 地址
+MIDSCENE_MODEL_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
 
-# 描述生成模式 - 基于自然语言
-npx smart-test generate --desc "优惠券列表页，有可用券和已用券两个 tab"
-
-# 交互式模式 - 引导式生成
-npx smart-test generate --interactive
-```
+# AI 模型 API 密钥
+MIDSCENE_MODEL_API_KEY=your_api_key
 
-#### 3. 运行测试
+# AI 模型名称
+MIDSCENE_MODEL_NAME=qwen-vl-max-latest
 
-```bash
-npx playwright test
+# AI 模型家族（可选，根据模型提供商设置）
+MIDSCENE_MODEL_FAMILY=qwen-vl
 ```
 
----
+> 💡 Smart Test 和 Midscene 共用相同的环境变量，无需重复配置
 
-### 方式二：手动编程
+### 3. 开始录制
 
-#### 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 配置
-});
+npx smart-test preset
 ```
 
-#### 3. 在测试中使用
+编辑生成的 `*.preset.ts` 文件：
 
 ```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 时跳过
-    }
+import type { RecordingPreset } from '@be-link/smart-test';
+
+const preset: RecordingPreset = {
+  pageUrl: 'http://localhost:8080/login',
+  caseName: 'user-login',
+  testCases: [
+    {
+      name: '用户登录成功',
+      steps: ['输入用户名 testuser', '输入密码 123456', '点击登录按钮'],
+      expected: '跳转到首页，显示欢迎信息',
+    },
+  ],
+  viewport: 'mobile-ios',
+  headless: false,
+};
 
-    expect(result.ok, result.issues?.join(', ')).toBeTruthy();
-  });
-});
+export default preset;
 ```
 
-## 📖 CLI 命令参考
-
-### `smart-test init`
-
-初始化配置文件，交互式设置 AI API Key、模型、输出目录等。
+然后执行录制：
 
 ```bash
-smart-test init
+npx smart-test run login.preset.ts
 ```
 
-### `smart-test generate` (开发中)
-
-生成测试代码。
+#### 方式二：交互式录制
 
 ```bash
-# 基础用法
-smart-test generate
-
-# 指定页面（代码分析模式）
-smart-test generate --page <path>
-
-# 指定 URL（录制模式）
-smart-test generate --url <url>
-
-# 基于描述（自然语言模式）
-smart-test generate --desc <description>
-
-# 交互式模式
-smart-test generate --interactive
-
-# 指定输出目录
-smart-test generate --page <path> --output tests/custom
-
-# 预览模式（不写入文件）
-smart-test generate --page <path> --dry-run
+npx smart-test record
 ```
 
-**选项：**
+按照提示输入：
 
-| 选项                   | 简写 | 说明                         |
-| ---------------------- | ---- | ---------------------------- |
-| `--page <path>`        | `-p` | 页面文件路径（代码分析模式） |
-| `--url <url>`          | `-u` | 页面 URL（录制模式）         |
-| `--desc <description>` | `-d` | 页面描述（自然语言模式）     |
-| `--output <dir>`       | `-o` | 输出目录                     |
-| `--interactive`        | `-i` | 交互式模式                   |
-| `--dry-run`            |      | 预览模式，不写入文件         |
+1. 页面 URL
+2. 测试用例名称
+3. 测试场景描述
+4. 视口尺寸
 
-### `smart-test record` (开发中)
-
-录制模式的快捷命令（`generate --url` 的别名）。
+### 4. 运行测试
 
 ```bash
-# 基础录制
-smart-test record --url http://localhost:8080/coupon
-
-# 手动操作模式
-smart-test record --url http://localhost:8080/coupon --manual
-
-# 交互式引导
-smart-test record --url http://localhost:8080/coupon --interactive
+npx playwright test
 ```
 
-**选项：**
-
-| 选项             | 简写 | 说明                     |
-| ---------------- | ---- | ------------------------ |
-| `--url <url>`    | `-u` | 要录制的页面 URL（必需） |
-| `--output <dir>` | `-o` | 输出目录                 |
-| `--manual`       |      | 手动操作模式             |
-| `--interactive`  |      | 交互式引导               |
-
-### `smart-test config`
+## 生成的文件
 
-查看当前配置。
+录制完成后，会在 `tests/` 目录生成：
 
-```bash
-smart-test config
 ```
-
-### 全局选项
-
-| 选项        | 简写 | 说明                 |
-| ----------- | ---- | -------------------- |
-| `--version` | `-V` | 显示版本号           |
-| `--verbose` | `-v` | 详细输出（调试模式） |
-| `--help`    | `-h` | 显示帮助信息         |
-
-## 📖 编程 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 模型（可选）
-  timeout: 30000, // 超时时间（可选）
-});
+tests/
+├── e2e/
+│   └── {caseName}.spec.ts    # Midscene 测试用例
+├── mock/
+│   └── {caseName}.mock.ts    # Mock 函数
+└── smart-test.config.ts      # 配置文件
 ```
 
-### `aiReviewScreenshot(page, options)`
-
-使用 AI 检查页面截图。
-
-**参数：**
-
-- `page: Page` - Playwright Page 对象
-- `options: string | AiCheckOptions` - 检查选项
-
-**返回值：** `Promise<AiCheckResult>`
+### Mock 文件示例
 
 ```typescript
-interface AiCheckResult {
-  ok: boolean; // 检查是否通过
-  issues?: string[]; // 问题列表
-  skipped?: boolean; // 是否跳过
-  reason?: string; // 跳过原因
-  screenshotPath?: string; // 截图路径
-  rawResponse?: string; // AI 原始响应
+/**
+ * 自动生成的 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
-// 简单字符串描述
-const result = await aiReviewScreenshot(page, '页面应该显示登录表单');
-```
-
-### 带配置的用法
+### 测试文件示例
 
 ```typescript
-// 带配置对象
-const result = await aiReviewScreenshot(page, {
-  expected: '页面应该显示商品列表',
-  model: 'gpt-4-vision-preview', // 使用其他模型
-});
-```
+/**
+ * 自动生成的测试文件
+ * @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';
 
-```typescript
-import { test, expect } from '@playwright/test';
-import { aiReviewScreenshot } from '@be-link/smart-test';
+test.describe('user-login', () => {
+  let agent: PlaywrightAgent;
 
-test.describe('商品页面测试', () => {
   test.beforeEach(async ({ page }) => {
-    await page.goto('/products');
+    await mockUserLoginApis(page);
+    await page.goto('/login');
     await page.waitForLoadState('networkidle');
+    agent = new PlaywrightAgent(page);
   });
 
-  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();
-    }
+  test('用户登录成功', async () => {
+    await agent.aiAction('输入用户名 testuser');
+    await agent.aiAction('输入密码 123456');
+    await agent.aiAction('点击登录按钮');
+    await agent.aiAssert('跳转到首页，显示欢迎信息');
   });
 });
 ```
 
-## 🔧 配置文件
+## CLI 命令
 
-### `.smarttestrc.json`
+### smart-test init
 
-使用 `smart-test init` 命令生成的配置文件：
+初始化配置文件和目录结构。
 
-```json
-{
-  "version": "1.0.0",
-  "ai": {
-    "model": "qwen3-vl-plus",
-    "apiKey": "${AI_API_KEY}",
-    "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
-    "timeout": 30000
-  },
-  "output": {
-    "testsDir": "./tests/e2e",
-    "helpersDir": "./tests/helpers",
-    "naming": "kebab-case"
-  },
-  "templates": {
-    "mock": "default",
-    "test": "default"
-  },
-  "playwright": {
-    "baseURL": "http://localhost:8080",
-    "viewport": {
-      "width": 375,
-      "height": 667
-    },
-    "browser": "chromium"
-  }
-}
+```bash
+npx smart-test init
 ```
 
-### 支持的配置格式
-
-- `.smarttestrc.json`
-- `.smarttestrc.js`
-- `smarttest.config.js`
-- `package.json` 中的 `smarttest` 字段
+### smart-test preset
 
-## 🔧 高级配置
+创建录制预设配置文件。
 
-### 支持多种 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',
-});
+```bash
+npx smart-test preset [filename]
 ```
 
-### 自定义截图存储
-
-```typescript
-configure({
-  screenshotDir: './custom-screenshots',
-  saveScreenshots: true,
-});
-
-// 单次调用自定义
-const result = await aiReviewScreenshot(page, {
-  expected: '...',
-  screenshotPrefix: 'my-feature',
-  screenshotDir: './feature-screenshots',
-});
-```
+### smart-test run
 
-### 在 CI 环境中使用
+使用预设配置执行录制。
 
-```typescript
-// 在 CI 中可能不需要保存截图，减少存储开销
-configure({
-  apiKey: process.env.AI_API_KEY,
-  saveScreenshots: process.env.CI !== 'true',
-});
+```bash
+npx smart-test run <preset-file>
 ```
 
-## 🤔 常见问题
-
-### Q: 没有配置 API Key 会怎样？
+### smart-test record
 
-A: 测试会自动跳过 AI 检查，返回 `skipped: true`，不会影响其他测试的执行。
+启动交互式录制模式。
 
-### Q: 支持哪些 AI 模型？
-
-A: 理论上支持所有兼容 OpenAI Chat Completions API 的视觉模型，包括：
-
-- 通义千问 (qwen3-vl-plus) - 默认
-- OpenAI GPT-4 Vision
-- 其他兼容的模型服务
-
-### Q: CLI 生成的测试代码需要手动修改吗？
+```bash
+npx smart-test record
+```
 
-A: 生成的代码是可以直接运行的，但建议根据实际需求进行调整。AI 会尽量生成合理的测试用例，但可能无法覆盖所有业务场景。
+## 配置文件
 
-### Q: 录制模式如何处理需要点击才能触发的接口？
+### smart-test.config.ts
 
-A: 录制模式支持三种方式：
+```typescript
+import type { SmartTestConfig } from '@be-link/smart-test';
 
-1. **手动操作**：`--manual` 参数，用户手动操作浏览器
-2. **交互式引导**：`--interactive` 参数，AI 引导用户操作
-3. **脚本引导**：`--actions` 参数，提供操作脚本自动执行
+const config: SmartTestConfig = {
+  ai: {
+    // AI 模型配置（API Key 和 Base URL 从环境变量读取）
+    codeModel: 'qwen3-coder-plus',
+  },
+  recording: {
+    // 测试文件输出目录
+    testDir: 'tests/e2e',
+    // Mock 文件输出目录
+    mockDir: 'tests/mock',
+    // API 路径匹配模式
+    apiPathPattern: '**/c-bff/**',
+    // 排除的 API 路径
+    excludeApiPatterns: [],
+  },
+};
 
-### Q: 如何查看 AI 的原始响应？
+export default config;
+```
 
-A: 检查结果中的 `rawResponse` 字段包含了 AI 的原始响应内容。
+### 预设配置 (\*.preset.ts)
 
 ```typescript
-const result = await aiReviewScreenshot(page, '...');
-console.log('AI 原始响应:', result.rawResponse);
+import type { RecordingPreset } from '@be-link/smart-test';
+
+const preset: RecordingPreset = {
+  // 要测试的页面 URL
+  pageUrl: 'http://localhost:8080/page',
+  // 测试用例名称（用于文件命名）
+  caseName: 'test-case',
+  // 测试场景列表
+  testCases: [
+    {
+      name: '场景名称',
+      steps: ['步骤1', '步骤2'],
+      expected: '预期结果',
+    },
+  ],
+  // 子目录（可选）
+  subDir: '',
+  // 视口尺寸：'mobile-ios' | 'mobile-android' | 'tablet' | 'desktop' | 'desktop-wide'
+  viewport: 'mobile-ios',
+  // 是否使用无头模式
+  headless: false,
+};
+
+export default preset;
 ```
 
-### Q: 生成的代码文件如何组织？
-
-A: 默认按页面分组：
-
-- `tests/helpers/mock-{页面名}.ts` - Mock 数据
-- `tests/e2e/{页面名}.spec.ts` - 测试用例
-
-可以通过 `--output` 参数自定义输出目录。
-
-## 🗺️ 开发路线图
-
-### ✅ 已完成
-
-- [x] AI 视觉检查核心功能
-- [x] CLI 基础架构
-- [x] 配置系统
-- [x] 交互式初始化
+## 环境变量
 
-### 🚧 开发中
+| 变量名                    | 说明             | 必填 |
+| ------------------------- | ---------------- | ---- |
+| `MIDSCENE_MODEL_BASE_URL` | AI 模型 API 地址 | 是   |
+| `MIDSCENE_MODEL_API_KEY`  | AI 模型 API 密钥 | 是   |
+| `MIDSCENE_MODEL_NAME`     | AI 模型名称      | 是   |
+| `MIDSCENE_MODEL_FAMILY`   | AI 模型家族      | 否   |
 
-- [ ] 录制模式（Phase 2）
-  - [ ] 网络请求录制
-  - [ ] HAR 文件解析
-  - [ ] AI 生成 Mock 代码
-  - [ ] 交互操作录制
+## 依赖说明
 
-### 📅 计划中
+| 依赖               | 说明                          |
+| ------------------ | ----------------------------- |
+| `@midscene/web`    | Midscene AI 驱动的 Web 测试库 |
+| `playwright`       | 浏览器自动化核心库            |
+| `@playwright/test` | Playwright 测试框架           |
+| `dotenv`           | 环境变量加载                  |
+| `tsx`              | TypeScript 执行器             |
 
-- [ ] 代码分析模式（Phase 3）
-  - [ ] TypeScript AST 解析
-  - [ ] API 调用提取
-  - [ ] 类型定义分析
+## 与 Midscene 配合
 
-- [ ] 描述生成模式（Phase 4）
-  - [ ] 自然语言理解
-  - [ ] 交互式问答
-  - [ ] 代码生成
+生成的测试用例基于 [Midscene](https://midscenejs.com/) 的 AI 驱动 API：
 
-- [ ] 增强功能（Phase 5+）
-  - [ ] 增量更新
-  - [ ] 自定义模板
-  - [ ] 测试覆盖率分析
-  - [ ] VS Code 插件
+- `agent.aiAction()` - AI 驱动的页面操作
+- `agent.aiQuery()` - AI 驱动的数据查询
+- `agent.aiAssert()` - AI 驱动的断言
 
-## 📄 文档
-
-- [CLI 设计文档](./docs/CLI_DESIGN.md) - 完整的 CLI 工具设计方案
-- [使用示例](./examples/) - 更多使用示例
-
-## 📝 License
+## License
 
 MIT
-
-## 🤝 贡献
-
-欢迎提交 Issue 和 Pull Request！
-
-## 📮 联系方式
-
-如有问题，请在 [GitHub Issues](https://github.com/snowmountain-top/be-link/issues) 中提出。
-
----
-
-**版本**：v1.0.0 | **最后更新**：2025-12-30