local-deep-research UI 测试套件治理指南基于命名约定的 CI 分层组织与工作流分配【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10 search engines - arXiv, PubMed, your private documents. Everything Local Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research导读本文围绕 local-deep-research 项目中tests/ui_tests/UI 测试套件的分析与重组报告展开系统讲解如何通过一套清晰的文件命名约定test_*/NO_CI_*/DEBUG_*/*_helper将 80 个 Puppeteer 浏览器测试划分为可进 CI、必须手工执行、临时调试三类并给出测试分片shard、CI 工作流映射与测试去重的完整方案。读完本文你将掌握该仓库 UI 测试的组织规则、本地与 CI 两种运行方式、各工作流的职责边界以及如何基于源码级证据评估测试覆盖率与排查 CI 失败。一、背景为什么 UI 测试需要一套命名与组织规范local-deep-research 的前端是一套基于 Puppeteer 的浏览器级测试体系见 tests/ui_tests/README.md其核心价值在于单元测试无法捕捉浏览器运行时的 JavaScript 错误而这类测试验证的是完整的请求 → 响应 → 渲染闭环。随着测试数量增长到 80 个仓库维护者面临的真实问题是哪些测试会真正提交并等待研究任务完成从而会消耗真实 LLM API 资源、绝不能放进 CI哪些测试是临时调试版修复合并后应当删除哪些测试虽然命名为 simple却是高价值的聚焦集成测试应当保留并纳入 CI为此tests/ui_tests/test_analysis_updated.md即本文主题文档给出了完整的分析与重组结论。二、核心组织规则文件命名约定文档给出的命名规范是整个治理体系的地基规则简单但边界清晰命名前缀含义CI 归属test_*.js常规测试可在 CI 中运行可进 CINO_CI_*.js会实际执行研究任务的测试不应在 CI 中运行仅手工执行DEBUG_*.js临时的调试/修复版本修复合并后删除*_helper.js/*_config.js共享工具与配置测试公共依赖这套约定把能不能进 CI这一关键决策从口头约定提升为文件系统级的事实任何人看到NO_CI_前缀就知道该测试涉及真实研究执行看到DEBUG_前缀就知道这是待清理的临时代码。当前测试统计类别数量说明CI 测试8已在 CI 工作流中配置常规测试~60可补充进 CINO_CI 测试13执行真实研究仅手工运行DEBUG 测试5临时调试/修复版本Helper 文件4共享工具重组后总计约 86 个测试文件含 4 个 helper其中 68 个常规测试、13 个 NO_CI 测试、5 个 DEBUG 测试。源码层面可验证tests/ui_tests/目录下确实存在 5 个DEBUG_*.js文件如DEBUG_metrics_thread_fix.js、DEBUG_settings_mobile_fix.js与文档中的统计一致。三、已在 CI 中的测试及其工作流归属文档列出了 9 个已进入 CI 的测试文件及其工作流文件CI 工作流状态用途test_auth_flow.jscritical-ui-tests活跃认证流程测试test_concurrent_limit.jscritical-ui-tests活跃并发请求限制test_export_functionality.jscritical-ui-tests活跃导出功能test_followup_research.jsfollowup-research-tests研究类后续研究可能失败test_metrics.jsperformance-tests活跃指标功能test_research_simple.jscritical-ui-tests研究类简单研究提交test_research_submit.jscritical-ui-tests研究类研究提交test_responsive_ui_comprehensive.jsresponsive-ui-tests-enhanced活跃UI 响应式含移动端mobile/test_mobile_navigation_ci.jsmobile-ui-tests活跃移动端导航测试值得注意的是表中将test_followup_research.js、test_research_simple.js、test_research_submit.js标记为研究类状态——它们虽然进入 CI但因为涉及研究提交仍存在不稳定可能这与研究类测试应手工执行的原则形成了一个权衡点少量研究类测试被保留在 CI 中用于回归探测而大规模研究类测试则统一收归NO_CI_前缀之下。与当前仓库工作流的事实对照从仓库现状看CI 工作流体系已经演进responsive-ui-tests-enhanced.yml确实存在于 .github/workflows/responsive-ui-tests-enhanced.yml其内容以HEADLESStrue node test_responsive_ui_comprehensive.js $VIEWPORT方式按视口运行响应式测试而完整的 UI 测试矩阵则统一收敛到了 .github/workflows/docker-tests.yml 的ui-testsjob 中见下文第六节这印证了文档按关注点拆分工作流、避免重复的方向在持续演进。四、移动端测试的组织移动端测试被单独整理到tests/ui_tests/mobile/子目录与主目录的移动相关测试做了区分mobile/ 目录内的移动端专项测试文件用途是否在 CItest_mobile_navigation_ci.jsCI 用移动端导航是mobile-ui-tests.ymltest_mobile_nav_all_pages.js全页面移动端导航否test_mobile_navigation_authenticated.js登录态移动端导航否test_mobile_ui_comprehensive.js移动端 UI 综合测试否主目录中的移动相关测试文件用途是否在 CItest_mobile_metrics.js移动端指标测试否test_responsive_ui_comprehensive.js覆盖所有视口含移动端是DEBUG_mobile_debug.js移动端调试临时否DEBUG_settings_mobile_fix.js移动端设置修复临时否这里的组织哲学是CI 只保留最小必需的移动端冒烟测试导航可点、页面可渲染深度的移动端交互与视觉测试留作本地手工执行同时把所有 DEBUG 移动测试与正式测试严格隔离避免临时调试代码污染 CI 结果。五、NO_CI 与 DEBUG 测试的完整清单NO_CI 测试真实执行研究的重活这些测试会真正提交研究任务并等待其完成因此消耗真实推理资源、耗时不可控只能手工运行。文档给出了重命名映射原名新名用途test_ajax_submit.jsNO_CI_executes_research_ajax_research_submission.jsAJAX 研究提交test_research_complete.jsNO_CI_executes_research_full_research_completion.js完整研究完成流程test_followup_simple.jsNO_CI_executes_research_followup_simple.js简单后续研究test_multi_research.jsNO_CI_executes_research_multiple_research.js多次研究提交test_complete_workflow.jsNO_CI_executes_research_complete_workflow.js端到端工作流test_simple_research.jsNO_CI_executes_research_basic_research_flow.js基础研究流程test_research_with_available_model.jsNO_CI_executes_research_research_with_model.js指定模型的研究当前tests/ui_tests/目录中实际存在 11 个NO_CI_*文件如NO_CI_executes_research_ajax_research_submission.js、NO_CI_executes_research_complete_workflow.js、NO_CI_test_egress_policy_live_research.js等与文档13 个 NO_CI 测试的统计方向一致——后续新增的研究类测试仍在持续并入这一前缀体系。DEBUG 测试临时调试的停机坪原名新名用途test_metrics_thread_fix.jsDEBUG_metrics_thread_fix.js线程问题修复test_mobile_debug.jsDEBUG_mobile_debug.js移动端 UI 调试test_news_features_fixed.jsDEBUG_news_features_fixed.js新闻功能修复test_research_submit_debug.jsDEBUG_research_submit_debug.js研究提交调试test_settings_mobile_fix.jsDEBUG_settings_mobile_fix.js移动端设置修复文档明确建议DEBUG 文件在修复合并后应删除避免调试代码长期滞留造成维护负担。六、有价值的 simple 测试与 CI 扩充建议文档特别指出一批命名为 simple 的测试并非低价值脚本而是高价值的聚焦集成测试应当保留甚至纳入 CI测试文件用途能否进 CItest_simple_auth.js基础认证流程可以test_simple_metrics.js指标面板访问可以test_simple_cost.js成本分析页面可以test_api_key_simple_verify.jsAPI Key 设置/读取可以test_settings_simple.js设置保存功能可以test_queue_simple.js研究队列提交待定需 mock按优先级划分的 CI 扩充清单高优先级核心功能test_api_key_comprehensive.jsAPI Key 管理、test_simple_auth.js认证基础、test_simple_metrics.js指标面板、test_settings_page.js设置功能中优先级功能测试test_history_page.js历史功能、test_news_subscription_form.js新闻功能、test_autocomplete_selection.jsUI 自动补全、test_benchmark_settings.js基准功能低优先级边界情况test_context_overflow_standalone.js上下文溢出边界处理、test_rate_limiting_settings.js限流设置扩充原则是在不执行真实研究的前提下获得良好覆盖率——这正是 mock 研究提交被反复提及的原因test_queue_simple.js之所以是待定状态正是因为它在当前形态下可能触发真实研究执行。七、共享工具与公共基础设施Helper 文件所有测试都依赖 4 个共享文件这是测试体系能够保持低重复度的关键文件用途auth_helper.js认证工具puppeteer_config.js浏览器配置model_helper.js模型设置工具browser_config.js浏览器设置从源码看这些 helper 的职责已经在进一步收敛到 tests/ui_tests/test_lib/index.js 这一统一入口对外导出setupTest/teardownTest/TestResults/navigateTo/findActionButton等能力。其中值得注意的设计细节setupTest({ authenticate: true })启动浏览器并按需认证当环境变量CItrue时使用预创建的 CI 测试用户test_admin否则注册全新用户——这直接呼应了 README 中本地跑全套会被登录限流阻断的坑findActionButton(page, ...)按文本内容查找操作按钮默认关键词为create/new/add并采用词边界匹配\b(?:create|new|add)\b专门避免把 News 之类的子串误判为按钮文本TestResults(suiteName)统一的结果收集器.run()/.skip()/.print()/.save()其中.save()会同时输出 JSON 与 JUnit XML 到test-results/便于 CI 解析。八、CI 工作流分布去重检查与覆盖分析文档对当前 CI 工作流的测试分布做了逐文件核对得到两个关键结论无重复每个测试文件恰好只在一个工作流中运行不存在跨工作流重复执行职责分离清晰每个工作流有明确关注点。测试到工作流的映射测试文件工作流用途test_auth_flow.jscritical-ui-tests.yml认证流程其他测试的基础test_concurrent_limit.jscritical-ui-tests.yml并发请求限制test_export_functionality.jscritical-ui-tests.yml导出功能test_research_simple.jscritical-ui-tests.yml简单研究提交test_research_submit.jscritical-ui-tests.yml研究提交测试test_followup_research.jsfollowup-research-tests.yml后续研究功能test_metrics.jsperformance-tests.yml指标与性能test_responsive_ui_comprehensive.jsresponsive-ui-tests-enhanced.yml各视口 UI 响应式工作流覆盖率工作流运行测试数关注点critical-ui-tests.yml5核心功能认证、研究、导出followup-research-tests.yml1后续研究功能performance-tests.yml1性能指标responsive-ui-tests-enhanced.yml1全视口 UI 响应式mobile-ui-tests.yml1移动端导航分析结论关注点分离良好、无冗余但多数工作流只运行 1-2 个测试扩展空间充足——这正是第六节扩充清单的价值所在。九、建议与后续行动清单文档给出的行动项可以分为四组其中既包含已完成项✅也包含待办项1. 立即执行保留所有test_simple_*.js——它们是高价值聚焦测试执行真实研究的测试统一改为NO_CI_前缀已完成调试测试统一改为DEBUG_前缀已完成。2. CI 改进将高优先级测试加入 CI 工作流考虑为 simple 测试新建 quick-tests 快速工作流为需要的研究提交类测试提供 mock 方案。3. 测试维护DEBUG 文件在修复合并后删除合并重复覆盖率例如 16 个指标测试合并为 3-4 个综合测试为所有测试文件补充规范描述。4. 按功能拆分的 CI 工作流蓝图critical-auth-tests.yml认证与用户管理api-tests.ymlAPI 端点与设置ui-tests.ymlUI 组件与响应式metrics-tests.yml指标与分析功能。十、从分析文档到落地实践当前仓库的 shard 体系文档的分析建议在仓库中已经演进为一套更精细的17 分片shard矩阵这可以作为理解测试治理的最终落地形态。权威分片列表定义在 tests/ui_tests/run_all_tests.js 顶部的VALID_SHARDS常量中并与 .github/workflows/docker-tests.yml 的strategy.matrix.shard保持同步源码注释明确警告两者不一致会导致测试静默错配。当前 17 个分片为分片范围auth-login登录/认证流程auth-register注册隔离运行——SQLCipher 加密数据库创建开销大auth-pages页面浏览、导航、综合认证research-workflow核心研究生命周期research-form研究表单交互与结果research-metrics指标图表、面板、进度settings-core设置页、错误、保存、交互settings-pages设置页签、星级评价、日志质量library收藏集、文档、下载管理器history-news历史页、新闻订阅mobile移动端导航、交互、UIapi-crudAPI 端点、CRUD、限流error-benchmark错误处理/恢复、基准、上下文溢出accessibility键盘导航与 ARIAchat-core聊天输入、ARIA、建议芯片、导航chat-lifecycle聊天会话生命周期、导出、持久化link-analytics/metrics/links 全页渲染与 XSS 运行时检查每个分片的设计约束是最多 4 个测试防止单个测试压垮服务器后引发级联失败重负载测试如创建加密数据库的auth-register被隔离到专属分片。这正是文档中Room for expansion / 避免级联失败思路的工程化放大。本地如何复现单个 CI 分片tests/ui_tests/README.md 提供了两种本地运行姿势关闭限流最简单本地认证端点按 IP 限流为15 分钟 5 次登录、每小时 3 次注册全套测试会反复认证数十次因此先禁用限流再起服务LDR_DISABLE_RATE_LIMITINGtrue python -m local_deep_research.web.app复刻 CI 测试用户模式一次性预创建test_admin然后以CItrue运行auth_helper.js会直接登录该用户而不再每次注册新用户python scripts/ci/init_test_database.py # 一次性初始化 CItrue node tests/ui_tests/run_all_tests.js --shardshard注意CItrue时必须提供--shardname否则 runner 会快速失败——这是刻意的设计用于在本地尽早暴露矩阵配置错误。CI 中的实际执行形态在 CI 中.github/workflows/docker-tests.yml 的ui-testsjob 以 17 路矩阵并行运行每个单元格启动独立 Docker 容器并执行node run_all_tests.js --shard${SHARD}并内置三层可靠性设计重试机制每个分片最多 3 次尝试每次尝试都是全新的服务器与数据库状态等价于 GitHub 的重新运行失败任务但免去重新下载镜像失败容忍的数学依据17 个独立分片若各自 ~98% 成功率整体通过率仅约 75%而 2 次重试可将单分片失败率压到约 0.0001%但超过 3 次就会开始掩盖真实缺陷——连续 3 次失败的是回归而非 flake分片聚合检查矩阵各单元格结果汇总到统一检查名 UI Tests (Puppeteer)任一单元格失败即整体失败。此外.github/workflows/ui-full-shards.yml 提供了按需全量触发入口给 PR 打上test:ui-full-shardslabel 或手工 dispatch即可在非发布期强制执行完整分片矩阵。十一、总结这套治理体系的要点回顾命名即约定test_*/NO_CI_*/DEBUG_*/*_helper四个前缀把能否进 CI是否临时是否共享三类决策固化为文件系统事实主次分离CI 只保留 8 个经筛选的测试13 个真实研究测试被隔离为手工执行5 个 DEBUG 测试随时可清理零重复每个测试只归属一个工作流关注点分离清晰且留有充足扩展空间分片化演进从按工作流划分升级为 17 分片矩阵每分片 ≤4 个测试、独立容器、3 次重试配合VALID_SHARDS与strategy.matrix.shard的强制同步机制防止错配本地友好限流开关LDR_DISABLE_RATE_LIMITING与 CI 测试用户CItrue--shard两条路径让开发者能低成本复现 CI 单元格。这套体系的核心思想可以推广到任何既有浏览器端到端测试、又需要区分 CI 与手工运行的项目先通过命名规范建立事实边界再按关注点拆分工作流最后用分片与重试机制保障矩阵的稳定性。延伸阅读仓库内路径测试组织分析文档本文主题来源UI 测试运行与分片指南本地运行、分片表、限流说明测试运行器与权威分片列表VALID_SHARDS定义测试工具统一入口setupTest/TestResults/findActionButtonCI 分片矩阵ui-testsjob 的 17 路矩阵与重试设计全量分片触发工作流label 触发完整矩阵响应式 UI 测试工作流按视口运行test_responsive_ui_comprehensive.js【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10 search engines - arXiv, PubMed, your private documents. Everything Local Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考