docs/testing/ai-automation/electron-mcp-guide.md
本指南总结了使用MCP (Model Context Protocol) 对Electron桌面应用进行AI自动化测试的最佳实践和关键技巧。
// 1. 确保应用已构建
// 执行: pnpm clean && pnpm build
// 2. 启动Electron应用
app_launch_circuit-electron({
app: "/path/to/project/packages/desktop/dist/win-unpacked/YourApp.exe",
mode: "packaged", // 关键:使用packaged模式
includeSnapshots: true,
timeout: 60000
})
browser_navigate 到URLapp_launch_circuit-electron 启动可执行文件// ✅ 优先:文本点击
click_by_text_circuit-electron({
sessionId: "session-id",
text: "⚙️ Model Manager"
})
// ⚠️ 备选:CSS选择器
click_circuit-electron({
sessionId: "session-id",
selector: "button:nth-child(4)"
})
// 🔧 最后手段:JavaScript执行
evaluate_circuit-electron({
sessionId: "session-id",
script: `
const buttons = document.querySelectorAll('button');
for (let button of buttons) {
if (button.textContent.includes('Model Manager')) {
button.click();
break;
}
}
`
})
症状: Error: <element> intercepts pointer events
解决方案:
// 方案1: 使用Escape键关闭遮挡元素
key_circuit-electron({ sessionId: "session-id", key: "Escape" })
// 方案2: 点击空白区域
evaluate_circuit-electron({ script: "document.body.click();" })
// 方案3: JavaScript绕过遮挡
evaluate_circuit-electron({
script: `
const button = document.querySelector('button[text="Target"]');
if (button && !button.closest('.fixed')) {
button.click();
}
`
})
问题: 语言切换后,文本选择器失效
解决方案:
// ❌ 硬编码文本
click_by_text_circuit-electron({ text: "Model Manager" })
// ✅ 使用包含匹配
evaluate_circuit-electron({
script: `
const buttons = document.querySelectorAll('button');
for (let button of buttons) {
if (button.textContent.includes('Model') &&
button.textContent.includes('Manager')) {
button.click();
break;
}
}
`
})
重要: 不要仅依赖控制台错误信息判断功能状态
正确做法:
// ✅ 关注界面状态变化
// - 检查V1、V2按钮的出现
// - 检查Continue Optimize按钮的激活
// - 检查disabled/pressed/focused状态
// ❌ 错误做法:仅依赖控制台错误信息
evaluate_circuit-electron({
script: `
const textbox = document.querySelector('textarea[placeholder*="prompt"]');
if (textbox && textbox.offsetParent !== null) {
textbox.value = 'test content';
textbox.dispatchEvent(new Event('input', { bubbles: true }));
textbox.dispatchEvent(new Event('change', { bubbles: true }));
textbox.focus();
return 'success';
}
return 'not found';
`
})
// 基础等待
wait_for_load_state_circuit-electron({
sessionId: "session-id",
state: "load",
timeout: 5000
})
// AI请求等待(重要:AI请求需要更长时间)
wait_for_load_state_circuit-electron({
sessionId: "session-id",
state: "networkidle",
timeout: 15000
})
// 使用snapshot检查界面状态
snapshot_circuit-electron({ sessionId: "session-id" })
// 关键状态指标:
// - pressed状态 (按钮激活)
// - disabled状态 (按钮可用性)
// - focused状态 (当前焦点)
// - value字段 (输入内容)
// 调试元素可见性
evaluate_circuit-electron({
script: `
const elements = document.querySelectorAll('button');
return Array.from(elements).map(el => ({
text: el.textContent.trim(),
visible: el.offsetParent !== null,
disabled: el.disabled
}));
`
})
try {
click_by_text_circuit-electron({ sessionId, text: "button" })
} catch (error) {
if (error.message.includes('page has been closed')) {
// 重新启动应用
sessionId = app_launch_circuit-electron({
app: appPath,
mode: "packaged",
includeSnapshots: true
})
}
}
# 构建应用
pnpm clean && pnpm build
# 确保外部服务运行(如需要)
# 例如:启动Ollama服务
// 启动应用
const sessionId = app_launch_circuit-electron({...})
// 获取初始状态
snapshot_circuit-electron({ sessionId })
// 执行测试步骤
// ...
// 关闭应用
close_circuit-electron({ sessionId })
// 1. 启动应用
// 2. 检查初始状态
// 3. 执行功能操作
// 4. 验证结果
// 5. 检查持久化
// 1. 配置模型
// 2. 输入测试数据
// 3. 执行AI操作
// 4. 等待AI响应
// 5. 验证结果质量
最后更新: 2025-01-09
适用范围: Electron桌面应用AI自动化测试