@ai-test/ai-heal

AI-powered self-healing SDK for Playwright test scripts.

版本: v0.2.0 状态: 核心设计完成，准备开发 重大更新: 基于 MCP 工具限制重新设计架构，可行性提升至 ⭐⭐⭐⭐⭐

概述

ai-heal 是一个为 Playwright 测试脚本设计的自愈 SDK，通过 AI Agent 在测试执行失败时自动修复脚本错误，提高测试稳定性和维护效率。

核心特性

• 🔄 自动自愈: 测试步骤失败时自动触发 AI 修复流程
• 🤖 智能 Agent: 基于 LangGraph 的 ReAct 循环实现智能决策
• 🔧 变量绑定: Ref 包装器支持复杂 Playwright 对象的引用传递
• 📝 代码生成: Agent 分析错误并生成修复代码，在用户 Browser 上下文执行
• 🎯 类型安全: 完整的 TypeScript 类型支持
• ⚡ 零状态隔离: 在用户真实 Browser 中执行，状态完全一致

架构亮点

✅ 解决核心问题

问题: Playwright MCP 工具无法返回 Page、Tab、DOM 节点等复杂对象。

方案:

Agent 使用 MCP 观察（只读）→ 生成修复代码 → SDK 在用户 Browser 执行

优势:

• ✅ 完全绕过 MCP 返回值限制
• ✅ 支持所有 Playwright 复杂对象
• ✅ Cookie、Session、Storage 完全共享
• ✅ 原生 Playwright API 完全可用

快速开始

安装

npm install @ai-test/ai-heal

基本使用

import { AIHeal, Ref } from '@ai-test/ai-heal';
import { test, expect } from '@playwright/test';

test('示例测试', async ({ page }) => {
  // 初始化自愈实例
  const heal = new AIHeal({
    testCaseId: 'test-123',
    projectId: 'project-456'
  });

  // 声明需要自愈的变量
  const userPage = new Ref<typeof>(null);
  const userData = new Ref<any>(null);

  // 使用 runStep 包装测试步骤
  await heal.runStep({
    description: '打开登录页面并输入用户信息',
    variables: {
      page: userPage,
      data: userData
    },
    context: page
  }, async () => {
    await page.goto('https://example.com/login');
    await page.fill('#username', 'testuser');
    await page.fill('#password', 'password123');
    await page.click('#login-button');

    // 保存变量供后续使用
    userData.current = { username: 'testuser' };
  });

  // 继续使用自愈后的变量
  await heal.runStep({
    description: '验证用户登录成功',
    variables: { page: userPage }
  }, async () => {
    await expect(userPage.current).toHaveURL(/.*dashboard/);
  });

  // 生成自愈报告和修复后的脚本
  const summary = await heal.summary();
  console.log(`总步骤数: ${summary.totalSteps}`);
  console.log(`自愈成功数: ${summary.healedSteps}`);
});

API 文档

AIHeal

构造函数

new AIHeal(config: AIHealConfig)

参数:

• testCaseId?: string - 测试用例 ID，用于查询原始脚本
• projectId?: string - 项目 ID
• scriptContent?: string - 手动注入的脚本内容
• modelConfig?: ModelConfig - AI 模型配置
• enableAutoSave?: boolean - 是否自动保存修复后的脚本（默认 false）
• maxRetries?: number - 最大自愈重试次数（默认 3）

runStep

async runStep<T>(
  options: RunStepOptions,
  fn: () => Promise
): Promise<T>

参数:

• description: string - 步骤描述，用于 AI 理解
• variables?: Record<string, Ref<any>> - 需要传递的变量绑定
• context?: any - Playwright 上下文对象（Page, BrowserContext 等）

返回:

• 泛型 T - 步骤执行结果

summary

async summary(): Promise<HealSummary>

返回:

• totalSteps: number - 总步骤数
• healedSteps: number - 自愈成功的步骤数
• modifiedScript?: string - 修复后的脚本
• healingDetails: HealingDetail[] - 每次自愈的详细信息

Ref

用于包装需要跨步骤传递的变量，支持 AI Agent 修改外部变量。

const page = new Ref<Page>(null);

// 获取值
const currentPage = page.current;

// 赋值
page.current = await context.newPage();

架构设计

核心组件

ai-heal/
├── src/
│   ├── core/              # 核心逻辑
│   │   ├── ai-heal.ts     # AIHeal 主类
│   │   ├── healer.ts      # 自愈执行器
│   │   └── variable-binding.ts  # 变量绑定机制
│   ├── agents/            # AI Agent
│   │   ├── heal-agent.ts  # 自愈 Agent
│   │   └── graph.ts       # LangGraph 定义
│   ├── types/             # 类型定义
│   ├── utils/             # 工具函数
│   └── index.ts           # 导出入口
├── docs/                  # 文档
├── examples/              # 使用示例
└── tests/                 # 测试

自愈流程

1. 执行原始代码
   ↓
2. 捕获错误
   ↓
3. 判断是否可自愈
   ↓
4. 构建 ReAct Agent
   ↓
5. Agent 使用 Playwright 工具重新执行
   ↓
6. 解析并应用变量赋值
   ↓
7. 记录自愈上下文
   ↓
8. 返回结果

开发计划

• [x] 核心架构设计
• [x] 技术方案文档
• [x] POC 验证 (3个)
• [ ] 基础类型定义
• [ ] 变量绑定机制实现
• [ ] AIHeal 主类实现
• [ ] LangGraph Agent 集成
• [ ] Playwright MCP 集成
• [ ] 脚本修复逻辑
• [ ] 单元测试
• [ ] 集成测试
• [ ] 文档完善

POC 验证

当前状态: ✅ 准备就绪

我们已经创建了 3 个 POC 验证脚本，用于验证核心技术方案的可行性：

POC 清单

| POC | 验证内容 | 文件 | 预期时间 | |-----|---------|------|---------| | POC 1 | Ref 类型推断 | src/poc/poc1-ref-type-inference.ts | ~2s | | POC 2 | 上下文代码执行 | src/poc/poc2-context-execution.ts | ~15s | | POC 3 | 复杂对象序列化 | src/poc/poc3-object-serialization.ts | ~10s |

快速运行

# 进入项目目录
cd ai-heal

# 安装依赖
npm install
npx playwright install

# 运行所有 POC 测试
npm test

# 或使用 Playwright 直接运行
npx playwright test src/poc/

# 查看详细报告
npx playwright show-report

详细说明

请查看 POC README 了解完整的验证说明和验收标准。

技术方案

详见 docs/technical-design.md

可行性分析

详见 docs/feasibility-analysis.md

许可证

MIT