ruflo 平台 E2E 测试架构实战基于 Playwright 与 claude-flow/browser 的容器化浏览器自动化体系【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo本篇技术指南以 ruflo 仓库中的架构决策记录 ADR-018 为主体深入讲解如何在 Cloud Run 容器化环境中搭建一套完整的端到端E2E浏览器自动化测试服务覆盖认证、聊天、文档解析、云函数等核心业务流的测试套件设计、混合浏览器架构、AI 优化元素引用、轨迹学习集成、容器与 CI/CD 部署方式以及故障排查与性能优化方法。读者学完后可以直接参照文中配置在任意基于 Node.js Playwright 的平台上复刻一套可投入生产、可随需或定时触发的 E2E 测试服务。一、背景为什么要做容器化 E2E 测试Conveyor AI 平台ruflo 生态的聊天/Agent 系统其架构详见 ADR-014: Chat System Architecture需要持续验证以下关键链路用户认证流程登录、登出、会话聊天系统功能消息收发、斜杠命令、实时响应Cloud Function 集成Airtable 查询、数据库查询、搜索等文档解析工作流/parse命令与提取结果校验实时功能等待 AI 响应、流式交互人工回归测试耗时且易出错因此 ADR-018 决策引入自动化 E2E 方案其目标约束如下运行在容器化环境中Cloud Run随请求伸缩、按用量计费使用浏览器自动化模拟真实用户操作可集成进 CI/CD 流水线产出详细测试报告与失败截图支持按需触发或定时触发二、总体架构与技术选型2.1 技术栈层次选型说明运行时Cloud Run容器化、可自动伸缩、按用量付费浏览器自动化claude-flow/browserPlaywright 基础AI 优化的浏览器操作层提供元素引用与轨迹学习测试框架claude-flow/testing断言库 报告器仓库内实现于 v3/claude-flow/testing浏览器内核ChromiumCI 用 headless 模式调试用 headed 模式凭据管理Google Secret Manager集中、安全地存储测试账号等敏感信息2.2 架构图┌─────────────────────────────────────────────────────────────────┐ │ E2E Test Runner (Cloud Run) │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Test Suites │ │ Browser │ │ Reporter │ │ │ │ │───▶│ Automation │───▶│ │ │ │ │ - Auth │ │ (Playwright)│ │ - Console │ │ │ │ - Chat │ │ │ │ - HTML │ │ │ │ - Documents │ │ │ │ - Screenshots│ │ │ │ - Functions │ │ │ │ - Artifacts │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────┐ │ │ │ Secret │ │ │ │ Manager │ │ │ │ (credentials)│ │ │ └──────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Target Applications │ ├─────────────────────────────────────────────────────────────────┤ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Chat System │ │ Cloud │ │ Airtable │ │ │ │ (Cloud Run) │ │ Functions │ │ API │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────────────┘数据流上测试套件通过浏览器自动化层驱动 Chromium 访问目标应用浏览器自动化层对接agent-browserCLI 进而驱动 Playwright对应调用链见 v3/claude-flow/browser/src/infrastructure/agent-browser-adapter.ts报告器将结果与截图产出为 Console / HTML 报告与构建产物供 CI/CD 与人工查阅。三、测试套件设计3.1 四个核心套件Authentication Tests认证有效凭据登录、无效凭据登录、会话持久化、登出功能。Chat System Tests聊天发送消息、接收 AI 回复、斜杠命令/help、/search、/parse等、自然语言查询、错误处理。Document Parsing Tests文档解析从 Airtable 记录解析文档、校验提取结果、处理不支持的格式。Cloud Function Tests云函数健康检查、API 响应校验、错误场景。3.2 测试规模与套件分布SuiteTests覆盖范围auth.js5登录流程、表单校验、重定向、会话处理chat.js8消息发送、/help、/search、命令、历史、响应性documents.js6/parse命令、文档提取、错误处理functions.js8Airtable 查询、数据库查询、搜索、模拟、研究总计 27 个测试覆盖平台的核心用户路径。3.3 套件统一模板每个套件遵循一致的代码骨架对应infrastructure/gcp/e2e-runner/src/tests/suite.jsexport async function runSuiteTests({ browser, // Browser instance credentials, // { email, password } options, // { baseUrl, headless, timeout } runId, // Unique run identifier screenshotDir // Path for failure screenshots }) { const results { total: 0, passed: 0, failed: 0, tests: [], screenshots: [], }; // Test helper with auto-screenshot on failure async function runTest(name, testFn) { results.total; try { await testFn(); results.passed; results.tests.push({ name, status: passed, duration }); } catch (error) { results.failed; const screenshotPath path.join(screenshotDir, ${name}-failure.png); await browser.screenshot({ path: screenshotPath, fullPage: true }); results.tests.push({ name, status: failed, error: error.message }); } } // Common helpers async function sendMessage(message) { /* ... */ } async function waitForResponse(timeout 30000) { /* ... */ } // Navigate to app await browser.open(options.baseUrl); await browser.wait({ timeout: 3000 }); // Run tests await runTest(test name, async () { /* ... */ }); return results; }关键设计runTest包装器统一计数、捕获异常并在失败时自动截取整页截图保证每次失败都有可追溯的证据。四、HTTP API 端点E2E Runner 对外暴露以下 REST 端点便于 CI/CD、调度器或人工触发EndpointMethodDescription/healthGET健康检查/runPOST运行全部测试套件/run/:suitePOST运行指定套件/resultsGET获取最近一次结果/results/:runIdGET获取指定运行结果/screenshots/:runIdGET获取运行截图4.1 请求/响应 Schema运行测试请求POST /run{ suites: [auth, chat, documents], headless: true, timeout: 60000, retries: 2, screenshot: on-failure }字段说明suites指定要执行的套件名headless控制是否无头运行CI 中为true调试时设falsetimeout为单测试超时毫秒retries为失败重试次数screenshot取值如on-failure即仅在失败时截图。运行测试响应{ success: true, runId: run-123456, summary: { total: 25, passed: 24, failed: 1, skipped: 0, duration: 45230 }, suites: [ { name: auth, passed: 5, failed: 0, tests: [...] } ], artifacts: { screenshots: [url1, url2], report: html-report-url } }runId是后续通过/results/:runId与/screenshots/:runId拉取详情的唯一标识artifacts汇总截图 URL 与 HTML 报告地址。五、混合浏览器架构Playwright claude-flow/browserADR-018 的核心创新在于采用混合浏览器方案同时使用Playwright直接启动真实浏览器并执行底层操作claude-flow/browser API提供 AI 优化的元素引用与轨迹学习能力。之所以这样设计是因为claude-flow/browser的createBrowserService()依赖agent-browserCLI而该 CLI 在容器化环境中不会直接拉起浏览器——因此需要先用 Playwright 的chromium.launch()启动浏览器再包一层与claude-flow/browser兼容的 API详见 v3/claude-flow/browser/src/application/browser-service.ts 中的createBrowserService工厂函数以及 v3/claude-flow/browser/src/infrastructure/agent-browser-adapter.ts 中通过execFileSync(agent-browser, ...)拼接--session、--timeout、--headed、--json等参数的实际调用逻辑。5.1 浏览器包装器实现// infrastructure/gcp/e2e-runner/src/run-tests.js import { chromium } from playwright; async function createBrowser(options, runId) { // Launch real Playwright browser with container-safe flags const playwrightBrowser await chromium.launch({ headless: options.headless ! false, args: [ --no-sandbox, --disable-setuid-sandbox, --disable-dev-shm-usage, --disable-gpu, ], }); const context await playwrightBrowser.newContext({ viewport: { width: 1920, height: 1080 }, userAgent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36..., }); const page await context.newPage(); // Return claude-flow/browser compatible API return { async open(url) { /* ... */ }, async snapshot(opts) { /* ... */ }, async fill(target, value) { /* ... */ }, async click(target) { /* ... */ }, async press(key) { /* ... */ }, async wait(opts) { /* ... */ }, async screenshot(opts) { /* ... */ }, async eval(script) { /* ... */ }, async close() { /* ... */ }, // Trajectory learning integration startTrajectory(description) { /* ... */ }, async endTrajectory(success, verdict) { /* ... */ }, }; }在真实仓库中claude-flow/browser的BrowserService完整实现了这套 API——open在导航前还会先执行安全扫描URL 验证、钓鱼检测fill会对输入做 PII 检测并将轨迹中的值脱敏记录snapshot带缓存并把最新快照挂到当前轨迹上见 browser-service.ts这些都是值得在 E2E 包装器中继承的防御性行为。六、AI 优化元素引用告别脆弱 CSS 选择器传统 E2E 测试最大的痛点之一是 CSS 选择器随 UI 重构频繁失效。ADR-018 采用claude-flow/browser的**元素引用element refs**机制snapshot()返回e1、e2等简短引用抽象掉底层 DOM 复杂度同时大幅压缩 Agent 上下文仓库 README 中标注可减少约 93% 的上下文体积见 v3/claude-flow/browser/README.md。async snapshot({ interactive false } {}) { const selector interactive ? button, input, textarea, select, a[href], [rolebutton], [roletextbox], [contenteditabletrue] : button, input, textarea, select, a, div, span, p; const elements await page.$eval(selector, (els) els.slice(0, 200).map((el) ({ tag: el.tagName.toLowerCase(), role: el.getAttribute(role) || el.tagName.toLowerCase(), name: el.getAttribute(aria-label) || el.getAttribute(placeholder) || el.innerText?.slice(0, 100)?.trim() || , className: el.className || , })) ); // Create refs map: e1, e2, etc. const refs {}; elements.forEach((el, idx) { refs[e${idx 1}] el; }); return { refs }; }使用方式对比传统写法await page.click(body div.container form#login button[typesubmit].btn.btn-primary)冗长且脆弱引用写法只需await browser.click(e3)。引用来自可访问性树快照accessibility tree对支持 ARIA 的应用天然稳定。在仓库自带的 E2E 测试 v3/claude-flow/browser/tests/e2e/browser-e2e.test.ts 中可以看到这一机制的落地通过agent-browser snapshot -i获取交互元素再以fill #email testexample.com操作表单。值得注意的细节是该测试用execFileSync(agent-browser, argv)把命令按空格切分为离散 token 传入避免 shell 注入CWE-78——在自己的 Runner 中调用 CLI 时应沿用这一安全实践。七、灵活元素检测策略多条件兜底定位不同 UI 实现React/Vue/原生 HTML的输入框写法千差万别仅靠单一选择器极易失败。ADR-018 提出多条件级联检测同时按 ARIA 角色、HTML 标签、可访问名称、CSS 类名多路匹配聊天输入框async function getChatInputRef() { const snapshot await browser.snapshot({ interactive: true }); const entries Object.entries(snapshot.refs || {}); const inputRef entries.find(([_, ref]) ( // By ARIA role ref.role textbox || ref.role searchbox || // By HTML tag ref.tag input || ref.tag textarea || // By accessible name ref.name?.toLowerCase().includes(message) || ref.name?.toLowerCase().includes(command) || ref.name?.toLowerCase().includes(type) || ref.name?.toLowerCase().includes(ask) || // By CSS class ref.className?.includes(input) || ref.className?.includes(message) )); if (!inputRef) throw new Error(Chat input not found); return inputRef[0]; // Returns e1, e2, etc. }该策略把找不到元素的硬失败概率降到最低——只要任一维度命中即可定位同时保留明确报错Chat input not found以便排查。八、轨迹学习集成让 E2E 结果反哺 Agent 智能这是 ADR-018 区别于普通 E2E 方案的关键设计每次测试运行都生成轨迹数据供 ReasoningBank/SONA 模式学习使用。仓库中BrowserService实现了完整的轨迹生命周期browser-service.ts// Start trajectory before test suite const trajectoryId browser.startTrajectory(E2E: Chat system validation); // Run tests... // End trajectory with results await browser.endTrajectory(results.failed 0, { total: results.total, passed: results.passed, failed: results.failed, duration: results.duration, });轨迹数据存储在/tmp/e2e-trajectories/供后续训练使用。从源码看startTrajectory(goal)会为当前会话登记 goal 与起始时间每次open/click/fill/type/wait等操作都会被recordStep记录进轨迹含动作、输入、结果与最近一次快照endTrajectory(success, verdict)将完整轨迹写入内存管理器HNSW 索引供后续语义检索并可配合signTrajectories: true配置把完成轨迹封入 Ed25519 签名信封对应仓库 ADR-122 的实现见 v3/claude-flow/browser/src/application/signed-trajectory-service.ts。这套机制带来两个直接收益失败模式沉淀每次测试失败都会留下可检索的轨迹后续 Agent 可通过findSimilarTrajectories(goal)找到相似历史成功或失败减少重复踩坑成功模式复用成功的交互序列可被提炼为模式pattern供未来的自动化流程参考形成测试即学习的闭环。九、容器配置与部署9.1 DockerfileFROM mcr.microsoft.com/playwright:v1.49.0-jammy WORKDIR /app COPY package*.json ./ RUN npm ci --onlyproduction COPY src/ ./src/ ENV PORT8080 ENV NODE_ENVproduction EXPOSE 8080 CMD [node, src/index.js]仓库内 v3/claude-flow/browser/docker/Dockerfile 提供了同源参考实现同样基于官方 Playwright 镜像mcr.microsoft.com/playwright该版本为v1.40.0-jammy并额外全局安装agent-browserlatest——这印证了混合架构中CLI 负责驱动、容器负责提供浏览器运行环境的分工。9.2 容器化 Chromium 关键启动参数Flag作用--no-sandbox容器内运行 Chromium 的必需参数--disable-setuid-sandbox安全命名空间setuid sandbox的绕过方案--disable-dev-shm-usage改用/tmp而非/dev/shm容器内共享内存受限--disable-gpuCloud Run 无 GPU禁用 GPU 加速9.3 构建与部署Cloud Build 构建 Cloud Run 部署cd infrastructure/gcp/e2e-runner # Build with Cloud Build gcloud builds submit --configcloudbuild.yaml --substitutions_VERSIONv10 # Deploy to Cloud Run (if not using cloudbuild.yaml deploy step) gcloud run deploy e2e-runner \ --imagegcr.io/PROJECT_ID/e2e-runner:v10 \ --platformmanaged \ --regionus-central1 \ --memory2Gi \ --timeout900 \ --set-secretsE2E_TEST_EMAILe2e-test-email:latest,E2E_TEST_PASSWORDe2e-test-password:latest部署要点--memory2Gi为 Chromium 预留足够内存--timeout900保证完整套件约 113 秒有充足执行窗口--set-secrets把 Secret Manager 中的e2e-test-email:latest、e2e-test-password:latest直接映射为环境变量凭据永不落入镜像。Cloud Build 配置cloudbuild.yamlsteps: - name: gcr.io/cloud-builders/docker args: [build, -t, gcr.io/$PROJECT_ID/e2e-runner:${_VERSION}, .] - name: gcr.io/cloud-builders/docker args: [push, gcr.io/$PROJECT_ID/e2e-runner:${_VERSION}] images: - gcr.io/$PROJECT_ID/e2e-runner:${_VERSION} substitutions: _VERSION: latest timeout: 1200s构建超时设为1200s20 分钟需覆盖基础镜像拉取与依赖安装实测构建约 11–12 分钟。9.4 使用示例运行全部测试curl -X POST https://e2e-runner-xxxxx-uc.a.run.app/run \ -H Content-Type: application/json \ -d { baseUrl: https://chat-system-xxxxx-uc.a.run.app, suites: [auth, chat, documents, functions], headless: true }运行指定套件curl -X POST https://e2e-runner-xxxxx-uc.a.run.app/run/chat \ -H Content-Type: application/json \ -d {baseUrl: https://chat-system-xxxxx-uc.a.run.app}获取结果curl https://e2e-runner-xxxxx-uc.a.run.app/results/run-20260121-123456十、环境变量配置# Required E2E_TEST_EMAILfrom-secret-manager E2E_TEST_PASSWORDfrom-secret-manager CHAT_SYSTEM_URLhttps://chat-system-hwqrrwrlna-uc.a.run.app # Optional HEADLESStrue SCREENSHOT_MODEon-failure TEST_TIMEOUT60000 MAX_RETRIES2必填三项测试账号凭据来自 Secret Manager与被测聊天系统地址可选四项HEADLESS默认true调试时设false以观察浏览器行为、SCREENSHOT_MODE如on-failure失败才截图、TEST_TIMEOUT单测试超时默认 60000ms、MAX_RETRIES失败重试次数默认 2。仓库中claude-flow/browser也定义了同级环境变量体系如BROWSER_HEADLESS、BROWSER_DEFAULT_TIMEOUT30000、BROWSER_REQUIRE_HTTPS、BROWSER_BLOCKED_DOMAINS等见 v3/claude-flow/browser/README.md可结合使用以统一配置入口。十一、安全设计凭据存储所有测试凭据存放于 Google Secret Manager不硬编码、不进镜像层网络隔离Cloud Run 服务部署在私有 VPC 中避免公网暴露被测系统访问控制API 采用 IAM 认证未授权请求无法触发测试或读取结果审计日志所有测试运行通过 Cloud Logging 记录便于追溯数据保护测试报告不包含个人身份信息PII凭据一律脱敏显示。仓库的BrowserService同样把安全内建在浏览器层open()导航前默认执行 URL 安全扫描钓鱼/仿冒域名检测、可选强制 HTTPSfill()对表单值做 PII 检测并在轨迹日志中替换为[REDACTED]见 browser-service.tsE2E Runner 应保留这些默认行为。十二、故障排查指南IssueCauseSolutionTests complete in 100msBrowser not launchingCheck Playwright installation, container flagsChat input not foundStrict element detectionUse flexible detection (roles, tags, classes)Timeout waiting for responseSlow app or wrong selectorIncrease timeout, verify app is responsiveScreenshots emptyScreenshot before page loadAdd explicit wait after navigationNavigation timeoutnetworkidletoo strictUsedomcontentloaded explicit waitTests pass locally, fail in containerDifferent environmentEnsure same Chrome version, check sandbox flags补充排查要点结合仓库实践若agent-browser命令不存在需全局安装npm install -g agent-browser若报缺少浏览器内核执行npx playwright install本地与容器行为不一致时核对 Dockerfile 中 Playwright 镜像版本与本地 Chromium 版本是否一致并确认--no-sandbox等标志已注入。十三、性能指标与已知代价实测指标来自 ADR-018 记录MetricValueTotal Tests27Pass Rate100%Full Suite Duration~113 secondsContainer Cold Start~5-10 secondsBuild Time~11-12 minutesImage Size~1.2 GB (Playwright base)ADR-018 明确识别的负面影响及缓解方案负面项缓解措施浏览器自动化偶发 flaky失败重试逻辑MAX_RETRIES冷启动延迟约 5–10 秒预热端点/health定期探测保活Chromium 镜像体积大约 500MB–1.2GB多阶段 Docker 构建npm ci --onlyproduction测试间相互干扰测试隔离模式独立会话/独立浏览器上下文仓库中的BrowserSwarmCoordinatorbrowser-service.ts提供了另一种性能解法按角色navigator/scraper/validator/tester/monitor并发spawnAgent多会话并行执行验证任务——这为 ADR-018 中并行测试执行的远期目标提供了现成的底层能力。十四、实施里程碑与后续增强已完成的实施阶段Phase 1核心基础设施——Cloud Run 服务搭建、Secret Manager 集成、基础认证测试套件Phase 2测试套件——聊天系统测试、文档解析测试、云函数测试Phase 3优化——并行测试执行、缓存策略、性能调优。未来增强方向并行测试执行——套件并发运行可复用createBrowserSwarm的并发会话能力视觉回归——基于截图的像素级对比测试性能指标——接入 Lighthouse 做页面性能审计CI/CD 触发器——PR 合并时自动触发Slack 通知——失败时即时告警测试覆盖率——追踪哪些 UI 路径已被测试覆盖。结语ADR-018 展示了一条务实的容器化 E2E 路线以 Cloud Run 承载、Playwright 驱动真实浏览器claude-flow/browser提供 AI 优化的元素引用与轨迹学习能力claude-flow/testing提供断言与报告Secret Manager 私有 VPC IAM 保障安全边界。其混合浏览器架构灵活元素检测测试轨迹反哺学习三个设计尤其值得在大型 Agent 平台的回归测试体系中借鉴。仓库内的实现证据——browser-service.ts、agent-browser-adapter.ts、browser-e2e.test.ts、v3/claude-flow/testing 与 docker/Dockerfile——均可作为落地此架构时的第一手参考资料。参考ADR-018: E2E Testing Architecture本文所依据的原始文档ADR-014: Chat System Architecture被测系统架构claude-flow/browser 使用文档与 API 参考claude-flow/testing 断言库实现BrowserService 轨迹/安全/快照核心实现agent-browser CLI 适配器浏览器 E2E 测试用例浏览器自动化测试容器 Dockerfile【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考