Skip to content

Web 质量插件 ​

文档导航

quality-web 是随包提供、需要显式启用的可选插件。它管理测试工具安装与检查声明;项目仍负责自己的测试、框架兼容和验收标准。

适用范围 ​

quality-web 负责 @wenext/test-tool 的发现、安装、回退和命令声明。核心仅分发通用生命周期钩子;quality-command 保持语言无关。服务端项目不启用此插件,也不会查询或安装 Web 工具。

首次选中 business-tests 检查时会调用 prepareChecks,查询包仓库的 latest 标签,即使已有缓存安装也会查询。仅打开项目不会更新工具。文档任务只有在其改动被适用性策略排除时才跳过准备。会话切换复用初始化结果,执行或复核期间不更新工具。

启用配置 ​

json
{
  "schemaVersion": 1,
  "plugins": { "enable": ["quality-web"] },
  "quality": { "schemaVersion": 2, "requireVerified": true, "checks": [] },
  "webQuality": {
    "schemaVersion": 1,
    "runtimePaths": ["src", "package.json", "package-lock.json"],
    "nonRuntimePaths": ["docs"],
    "nonRuntimeFiles": ["AGENTS.md"]
  }
}

按实际源码、配置和锁文件调整路径;运行规则优先,未映射或不完整影响会在准备工具前阻断。插件自动识别根级常见 README 等说明文件。仅启用插件而不声明 webQuality 时,检查默认无条件执行。另行补充文档或静态检查,否则纯文档变化在 requireVerified 下仍为未验证。详见按影响选择检查。

插件贡献必需的 business-tests 检查,通过既有公开请求/输出协议执行与复核,使用 result.json、plan.json、report.json、evidence.json,执行预算为 30 分钟。仓库检查中不要再次声明 business-tests;其它仓库检查仍受支持。

内部接口 updateWebTool(root, {cacheRoot?, execute?, signal?}) 返回 {status: current|updated|fallback|unavailable, tool?: {version,entry}, latest?,reason?}。LifecycleContext.notify?(message, level) 提供通用启动诊断。web_tool_update 事件保留选中的版本/路径、发现的最新版本、状态及有界失败码,不记录包仓库凭据。

每个插件实例只为实际初始化发出一次 web_tool_update,包括命令绑定和最终通知。并发准备、后续检查与会话切换都等待同一次初始化,不重复发出事件或通知。新插件实例会重新查询并产生新结果,包括 current、fallback 或 unavailable。这不会改变传输模式或重写历史事件,检查结果仍独立观测。

安装与证据 ​

默认存储目录为 ~/.wenext-pi/tools/test-tool/<canonical-root-sha256>/versions/。每个版本使用按版本号和完整性摘要命名的不可变目录。私有暂存目录接收仓库的 npmrc,以沿用包源和认证;用户 npm 配置及环境也照常生效。npm 安装精确版本,禁用脚本并强制检查运行引擎要求。原子发布安装目录前,会校验包身份、锁文件完整性和命令行健康状态。临时 npmrc 随后删除;安装失败时清理暂存目录。

插件不修改业务包清单、锁文件或 node_modules。工作区未提交改动、无关锁文件变化、活动会话和语义化版本跨级都不会阻止更新。发布者的 latest 是目标版本,包括主版本升级。仓库原有依赖仍可手动使用,其固定版本不约束插件选择。插件不会更新 Pi 自身。

LifecyclePluginHost 先预判适用性,只对贡献了已选中检查的插件调用 prepareChecks,然后冻结命令。准备过程不能修改选择 ID 或条件;impactPaths 范围未知时会在准备前阻断。插件必须在返回前完成初始化,并保持解析后的命令稳定。

质量计划绑定所选二进制的绝对路径,版本变化会使旧质量证据失效。当前会话继续使用原目录,即使其它进程同时升级。缓存目录不会自动删除,因为活动会话或证据可能仍引用它们。

错误与恢复 ​

条件行为
已缓存健康的最新版本查询包仓库,复用该精确安装
出现新的最新版本安装并校验后选用
临时传输错误npm 在有界超时内重试两次
下载、安装、引擎、完整性或健康检查失败明确警告并记录更新事件;回退到最高的健康缓存版本,或健康的仓库本地安装
没有可用工具显示错误并保留一个必需的失败检查,不能以空检查冒充通过
失败后下一个宿主选中 business-tests重新查询并尝试更新,不设置失败缓存有效期
并发安装同一版本各用独立暂存目录,原子发布,共享健康的完整安装

元数据查询的外层预算为 60 秒,安装为 180 秒,健康检查为 15 秒。失败只报告 npm 错误码/状态,不输出可能含凭据的原始内容。健康校验只证明命令行工具能够加载,不证明所有业务测试通过,也不保证未来所有版本的语义兼容。

浏览器诊断与质量分类 ​

quality-web 在首次需要业务检查的 prepareChecks 中做一次可选的 agent-browser PATH/可执行性诊断。缺失时提示使用诊断命令或已有 Playwright,不自动安装、不阻断任务。此探针只证明二进制可发现,不代表页面可用或视觉验收完成。业务检查不适用的任务不执行此诊断。

质量分类优先使用报告中的显式元数据;缺失时,从已绑定且冻结的计划中读取相同 id/packagePath 声明的 category,或使用明确的 unit/test:unit、test:e2e[:…] 声明。不能仅依据 Jest/Playwright 推断测试类型;无法匹配的报告保持 unknown。runner_error 继续与业务用例数分开。

归档后的附件回收 ​

Pi 0.1.4 在任务完成后,由 Web 插件调用已初始化的 test-tool 0.1.7+ 回收较早失败的 Playwright 诊断附件。按业务包和检查分别保留最近失败运行;成功检查产物、会话、每轮报告、日志与错误文字不删除。基座不包含附件文件名规则,CI、重试和质量门禁不变。

原始 evidence.json 和 Pi 冻结证据保持不变,test-tool 在每个 command-run 下记录 diagnostic-retention.json。启动 Pi 前设置 WENEXT_TEST_RETAIN_ALL=1 可保留所有附件。旧版工具、未初始化 Web 检查或不支持的产物保持原状。清理失败不影响任务完成,终端给出重试提示;中断后按持久收据继续,不自动重新执行测试。

已有任务可手动运行 wenext-test compact --task-dir <已完成任务目录> 预览,加 --apply 执行。verify-evidence --output <command-run/output> 核验历史文件及合法回收记录,不宣称检查通过。执行顺序要求正常走 wenext_finish;进程在完成与清理之间退出时,可用手动命令补做,不在启动时扫描所有历史任务。