@chen-rmag/ai-runner 0.1.0

package/src/index.ts

@@ -0,0 +1,29 @@
+/**
+ * ai-runner SDK 主入口
+ * 提供 AI 驱动的测试运行能力
+ */
+
+// 类型
+export type {
+  AIHealConfig,
+  ExecutionContext,
+  ExecutionResult,
+  HealContext,
+  HealSummary,
+  HealingDetail,
+  RunStepOptions,
+  VariableBindings
+} from './types';
+
+
+// 核心类
+export { Runner } from './core/runner';
+
+
+// Agent
+export type {
+  HealAgentState,
+  HealAgentResult,
+  HealAgentConfig
+} from './agents/types';
+

package/src/types/external.ts

@@ -0,0 +1,7 @@
+/**
+ * 外部类型定义
+ * 直接从 core-infra 导入
+ */
+
+// 从 core-infra 重新导出 ModelConfig 相关类型
+export type { ModelConfig, ModelProvider } from '@ai-test/core-infra/dist/types';

package/src/types/index.ts

@@ -0,0 +1,200 @@
+/**
+ * ai-heal 核心类型定义 (MVP)
+ * 保持简洁，只包含必要的类型
+ */
+
+import type { Page, BrowserContext } from 'playwright';
+
+// ============================================================================
+// Ref<T>: 变量包装器
+// ============================================================================
+
+/**
+ * 变量包装器，支持跨作用域赋值
+ */
+export class Ref<T> {
+  constructor(public value: T) {}
+
+  get current(): T {
+    return this.value;
+  }
+
+  set current(value: T) {
+    this.value = value;
+  }
+}
+
+// ============================================================================
+// AIHeal 配置
+// ============================================================================
+
+/**
+ * AIHeal 配置选项
+ */
+export interface AIHealConfig {
+  /** 测试用例 ID */
+  testCaseId?: string;
+  /** 项目 ID */
+  projectId?: string;
+  /** 手动注入的脚本内容 */
+  scriptContent?: string;
+  /** 是否自动保存修复后的脚本 */
+  enableAutoSave?: boolean;
+  /** 最大自愈重试次数 */
+  /** 模型配置 ID（用于加载模型配置） */
+  modelConfigId?: string;
+  /** Agent 最大执行步数 */
+  agentMaxSteps?: number;
+  /** 是否开启调试模式 */
+  debugMode?: boolean;
+}
+
+// ============================================================================
+// 执行上下文
+// ============================================================================
+
+/**
+ * 执行上下文，包含用户的 Playwright 对象
+ */
+export interface ExecutionContext {
+  context: BrowserContext;
+  page: Page;
+}
+
+// ============================================================================
+// 变量绑定
+// ============================================================================
+
+/**
+ * 变量绑定映射
+ */
+export type VariableBindings = Record<string, Ref<any>>;
+
+// ============================================================================
+// Step 选项
+// ============================================================================
+
+/**
+ * runStep 选项
+ */
+export interface RunStepOptions {
+  /** 步骤描述，用于 AI 理解 */
+  description: string;
+  /** 需要传递的变量绑定 */
+  variables?: VariableBindings;
+  /** Playwright 上下文对象 */
+  context?: ExecutionContext;
+}
+
+// ============================================================================
+// 自愈上下文
+// ============================================================================
+
+/**
+ * ReAct 循环步骤记录
+ */
+export interface ReActStep {
+  /** 步骤序号 */
+  stepNumber: number;
+  /** 步骤类型 */
+  stepType: 'thought' | 'action' | 'observation' | 'reflection';
+  /** 时间戳 */
+  timestamp: number;
+  /** LLM 的思考内容（thought 步骤） */
+  thought?: string;
+  /** 工具调用信息（action 步骤） */
+  toolCall?: {
+    name: string;
+    input: any;
+  };
+  /** 工具执行结果（observation 步骤） */
+  toolResult?: {
+    output: string;
+    success: boolean;
+    duration?: number;
+  };
+  /** 反思内容（reflection 步骤） */
+  reflection?: string;
+}
+
+/**
+ * 单次自愈过程的上下文信息
+ */
+export interface HealContext {
+  /** 时间戳 */
+  timestamp: number;
+  /** 步骤描述 */
+  stepDescription: string;
+  /** 错误对象 */
+  error?: Error;
+  /** 堆栈信息 */
+  stackTrace?: string;
+  /** 原始代码 */
+  originalCode: string;
+  /** 恢复尝试次数 */
+  recoveryAttempts: number;
+  /** 变量快照（执行前） */
+  variablesBefore: Record<string, any>;
+  /** 变量快照（执行后） */
+  variablesAfter: Record<string, any>;
+  /** 是否成功 */
+  success: boolean;
+  /** 自愈耗时 */
+  healingTime?: number;
+  /** ReAct 循环详细记录（如果使用了 Agent） */
+  reactSteps?: ReActStep[];
+  /** Agent 的推理过程总结 */
+  reasoning?: string;
+  /** Agent 执行的总步数 */
+  agentSteps?: number;
+}
+
+// ============================================================================
+// 执行结果
+// ============================================================================
+
+/**
+ * 代码执行结果
+ */
+export interface ExecutionResult {
+  /** 是否成功 */
+  success: boolean;
+  /** 返回值 */
+  returnValue: any;
+  /** 局部变量 */
+  locals: Record<string, any>;
+  /** 错误信息 */
+  error?: Error;
+}
+
+// ============================================================================
+// 自愈摘要
+// ============================================================================
+
+/**
+ * 自愈摘要信息
+ */
+export interface HealSummary {
+  /** 总步骤数 */
+  totalSteps: number;
+  /** 自愈成功的步骤数 */
+  healedSteps: number;
+  /** 修复后的脚本 */
+  modifiedScript?: string;
+  /** 自愈详情列表 */
+  healingDetails: HealingDetail[];
+}
+
+/**
+ * 单次自愈详情
+ */
+export interface HealingDetail {
+  /** 步骤描述 */
+  step: string;
+  /** 错误信息 */
+  error: string;
+  /** 恢复时间 */
+  recoveryTime: number;
+  /** LLM 交互次数 */
+  llmInteractions: number;
+}

package/tests/agent/test-heal-agent.spec.ts

@@ -0,0 +1,81 @@
+/**
+ * 自愈 Agent 测试
+ */
+
+import { test, expect } from '@playwright/test';
+import { Runner } from '../../src/index';
+
+// const heal = new AIHeal({ modelConfigId:'f7858370-daae-4ce9-ba2e-a5cf2270bdc9', scriptContent: `  test('应该调用 ReAct Agent 接管执行', async ({ page, context }) => {
+
+//     await page.goto('https://example.com');
+
+//     // 成功步骤不需要 Agent
+//     await heal.runStep({
+//       description: '获取标题',
+//       context: { page, context }
+//     }, async () => {
+//       const title = await page.title();
+//       expect(title).toBeTruthy();
+//     });
+
+
+//     const userUrl = new Ref<string>('');
+//     // 失败步骤 - Agent 会接管并尝试修复（可能会失败，但至少执行了）
+//     try {
+//       await heal.runStep({
+//         description: '尝试点击不存在的元素',
+//         context: { page, context },
+//         variables: {userUrl: userUrl}  // key 必须和 Agent set_variable 使用的名称一致
+//       }, async () => {
+//         await page.click('#non-existent', { timeout: 100 });
+//         userUrl.value = await page.url();
+//       });
+//     } catch (error) {
+//       // Agent 可能无法修复，但已经执行了 ReAct 循环
+//     }
+
+//     // 验证变量被 Agent 更新
+//     console.log('userUrl.value:', userUrl.value);
+
+//     const summary = await heal.summary();
+//     expect(summary.totalSteps).toBe(2);
+//   });`  });
+
+test.describe('AIHeal - ReAct Agent 集成', () => {
+  test.setTimeout(100000000)
+  
+  const runner = Runner.NewInstance('12c57655-0ae2-4580-92f8-b4dc2388a7f5','71692142-7170-4246-898f-21a650dfa6d5' );
+  // heal.map()
+  test('应该调用 ReAct Agent 接管执行', async ({ page, context }) => {
+    await page.goto('https://example.com');
+
+    // 成功步骤不需要 Agent
+    await runner.runStep({
+      description: '获取标题',
+      context: { page, context }
+    }, async () => {
+      const title = await page.title();
+      
+      expect(title).toBeTruthy();
+    });
+
+    
+    // 失败步骤 - Agent 会接管并尝试修复（可能会失败，但至少执行了）
+    await runner.runStep({
+        description: '尝试点击不存在的元素',
+        context: { page, context },
+    }, async () => {
+        runner.set('current_url',  await page.url())
+        await page.click('#non-existent', { timeout: 100 });
+    });
+
+    // 验证变量被 Agent 更新
+    console.log('userUrl.value:', runner.get('current_url'));
+
+    const summary = await runner.summary();
+    console.log('summary', summary.modifiedScript);
+  });
+
+
+});
+

package/tests/tools/README.md

@@ -0,0 +1,227 @@
+# Playwright 工具测试
+
+本目录包含 LangChain 兼容的 Playwright 工具测试。
+
+## 测试文件
+
+- **[tools.test.ts](tools.test.ts)** - 完整的工具集成测试
+- **[unit.test.ts](unit.test.ts)** - 单个工具的单元测试
+
+## 运行测试
+
+### 运行所有工具测试
+
+```bash
+# 从 ai-heal 目录运行
+npm run test -- tests/tools/tools.test.ts
+
+# 或者使用 Playwright CLI
+npx playwright test tests/tools/
+```
+
+### 运行单元测试
+
+```bash
+npm run test -- tests/tools/unit.test.ts
+```
+
+### 运行特定测试
+
+```bash
+# 只测试导航工具
+npm run test -- tests/tools/tools.test.ts -g "Navigation Tools"
+
+# 只测试表单工具
+npm run test -- tests/tools/tools.test.ts -g "Form Tools"
+
+# 只测试错误处理
+npm run test -- tests/tools/tools.test.ts -g "Error Handling"
+```
+
+### 调试模式
+
+```bash
+# 显示浏览器
+HEADED=true npm run test -- tests/tools/
+
+# 使用 Playwright Inspector
+npm run test:debug -- tests/tools/
+
+# 慢速模式
+SLOW_MO=1000 npm run test -- tests/tools/
+```
+
+## 测试覆盖
+
+### 工具功能测试
+
+✅ **导航工具**
+- 导航到 URL
+- 前进/后退
+
+✅ **交互工具**
+- 点击元素（文本选择器）
+- 点击元素（CSS 选择器）
+- 多选择器支持
+- 悬停元素
+
+✅ **表单工具**
+- 填写文本输入
+- 通过 label 填写
+- 选择下拉选项
+- 勾选/取消复选框
+
+✅ **等待工具**
+- 等待指定时间
+- 等待元素出现
+- 等待 URL 匹配
+- 超时参数
+
+✅ **验证工具**
+- 获取 URL
+- 获取页面内容
+- 获取元素文本
+- 截图
+- 验证文本可见
+- 验证元素可见
+
+### 错误处理测试
+
+- 无效 JSON 输入
+- 不存在的元素
+- 超时处理
+- 选择器失败
+
+### 集成测试
+
+- 完整表单工作流
+- 导航和交互
+- 等待和验证
+- 多选择器回退
+
+## 测试结果
+
+运行测试后，结果将保存在：
+- `test-results/` - 测试结果和截图
+- `playwright-report/` - HTML 报告
+
+查看报告：
+
+```bash
+npx playwright show-report
+```
+
+## 调试技巧
+
+### 1. 查看 Playwright Inspector
+
+```bash
+npm run test:debug -- tests/tools/tools.test.ts
+```
+
+### 2. 保留浏览器窗口
+
+```bash
+HEADED=true npm run test -- tests/tools/tools.test.ts
+```
+
+### 3. 保留追踪
+
+```typescript
+test.use({ trace: 'on' });
+
+test('my test', async ({ page }) => {
+  // 测试代码
+});
+```
+
+### 4. 查看控制台日志
+
+测试中的 `console.log` 会显示在终端输出中。
+
+## 添加新测试
+
+### 测试新工具
+
+```typescript
+test('my new tool - should do something', async ({ page }) => {
+  // 准备测试页面
+  await page.setContent(`...`);
+
+  // 创建工具实例
+  const tools = getAllTools(page);
+  const myTool = tools.find(t => t.name === 'browser_my_tool');
+
+  // 调用工具
+  const result = await myTool!.invoke('input');
+
+  // 验证结果
+  expect(result).toContain('expected output');
+});
+```
+
+### 测试错误场景
+
+```typescript
+test('should handle error gracefully', async ({ page }) => {
+  const tools = getAllTools(page);
+  const tool = tools.find(t => t.name === 'browser_tool');
+
+  try {
+    await tool!.invoke('invalid input');
+    expect.fail('Should have thrown an error');
+  } catch (error) {
+    expect((error as Error).message).toContain('expected error');
+  }
+});
+```
+
+## 已知问题
+
+### 1. ariaSnapshot 兼容性
+
+`browser_snapshot` 工具使用了 `ariaSnapshot()` API，这在较旧版本的 Playwright 中可能不可用。
+
+**解决方案**：确保使用 Playwright 1.40 或更高版本。
+
+### 2. 多选择器性能
+
+当提供多个选择器时，工具会依次尝试，这可能影响性能。
+
+**优化建议**：按最可能成功到最不可能成功的顺序排列选择器。
+
+## 持续集成
+
+### GitHub Actions 示例
+
+```yaml
+name: Test Tools
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+
+      - run: npm ci
+      - run: npm run test -- tests/tools/
+
+      - uses: actions/upload-artifact@v3
+        if: failure()
+        with:
+          name: test-results
+          path: test-results/
+```
+
+## 相关文档
+
+- [Playwright Testing Guide](https://playwright.dev/docs/intro)
+- [LangChain Tools](https://js.langchain.com/docs/concepts/tools)
+- [工具 README](../../src/agents/tools/README.md)
+- [工具示例](../../src/agents/tools/EXAMPLES.md)