LaunchProof

LaunchProof 从一个正在运行的本地 Web 应用开始，生成一套可以打开、审阅、提交到 PR，或交给 coding agent 继续修复的验收证据。它使用 Chromium 检查桌面端和移动端页面，再输出 HTML 报告、JSON、截图和实验性的 SARIF 文件。

它不是用来替代你精心编写的 E2E 测试，而是让你在“还没有测试清单”或“AI 刚改完页面”的时候，先快速得到一轮客观反馈。

为什么需要 LaunchProof？

现在的 coding agent 可以很快写出一个“看起来能用”的页面，但真正需要回答的是：哪里坏了？运行时有没有报错？移动端是否溢出？我能在哪里看到证据？

LaunchProof 适合这些场景：

• 应用已经能启动，但还没有测试清单；
• AI agent 刚完成一轮 UI 修改，需要立即得到反馈；
• 想一次检查多个路由、桌面/移动端布局、浏览器错误和可访问性信号；
• 不想只看终端里的 pass/fail，而是要截图、选择器和具体问题；
• 想先在本地使用，之后再把同一命令接入 CI。

效果在哪里？

仓库自带一个故意写坏的示例应用，不需要外部服务就能生成真实报告：

HTML 报告会把路由、viewport、问题数量、严重级别、选择器、错误信息和标注截图放在一起。这里是最适合人和 agent 阅读的地方。

终端会给出简短结果：

$ launchproof scan http://localhost:48371 --fail-on error
Report: /path/to/launchproof-report/index.html
Findings: 3 errors, 5 warnings, 0 notices across 4 page runs.

同一次扫描的结果还会出现在这些位置：

| 位置 | 能看到什么 | 适合谁 | | --- | --- | --- | | 终端 | 摘要和稳定退出码 | 开发者、CI | | launchproof-report/index.html | 可过滤的问题和截图 | 人、审查者、agent | | launchproof-report/report.json | 路由、finding、coverage、交互和文件路径 | 脚本、agent | | launchproof-report/screenshots/ | 原始页面截图 | 视觉检查 | | launchproof-report/annotated/ | 带问题标记的截图 | 快速定位 | | launchproof-report/probes/ | 显式交互探测截图 | 交互检查 | | GitHub Actions | 可以阻断提交的 CI 检查 | 团队协作 |

核心闭环就是：运行 → 查看报告 → 修复 → 再运行。

快速开始

现在最快的方式是直接从 npm 安装到你的 Web 项目：

npm install --save-dev launchproof
npx playwright install chromium
npx launchproof doctor

启动你的应用，然后执行：

npx launchproof scan http://localhost:48371

打开报告：

open launchproof-report/index.html       # macOS
# xdg-open launchproof-report/index.html # Linux

如果你希望全局使用 CLI：

npm install --global launchproof
launchproof doctor

从源码安装

如果你要参与贡献，或需要测试尚未发布的改动，可以从仓库安装：

git clone https://github.com/aabbcdl/LaunchProof.git
cd LaunchProof
npm ci
npx playwright install chromium
npm link

LaunchProof 自己不会启动或监听 Web 应用端口。48371 是仓库统一使用的不规则五位示例端口，也是内置 fixture 的默认端口；实际使用时请替换成你的应用正在监听的端口。

不想把源码 checkout 建立成全局命令，也可以直接运行：

node bin/launchproof.js scan http://localhost:48371

npm 包已经公开在 npmjs.com/package/launchproof。从源码安装主要用于贡献代码和测试尚未发布的改动。

两个终端马上试一遍

# 终端 1
npm run example

# 终端 2
npm run scan:example

内置 fixture 监听在 http://127.0.0.1:48371。

示例应用故意包含错误，因此默认会产生 findings 和非零退出码；报告仍然会写入本地目录，方便查看完整效果。

它具体检查什么？

页面布局和 UI

• 页面横向溢出和元素溢出；
• 文本被裁切、交互控件互相覆盖；
• 空白页面或几乎空白的截图；
• 图片加载失败、图片缺少 alt；
• 重复 ID、触摸目标过小等问题。

浏览器和运行时

• console error 和未捕获的页面异常；
• 请求失败和 HTTP 错误；
• 从页面链接发现的同源路由；
• DOM、交互元素和路由的扫描上限。

可访问性信号

LaunchProof 会运行浏览器级检查，并对渲染后的页面运行 axe-core。这能发现一批高价值问题，但不等于完整的 WCAG 合规证明；隐藏状态和人工复核仍然需要单独处理。

受保护的交互探测

交互探测默认关闭，并且必须同时提供 --interact 和明确选择器：

launchproof scan http://localhost:48371 \
  --interact \
  --interaction-selector "#open-menu"

只有唯一、可见的 button[type="button"] 和受保护的非表单 [role="button"] 会进入探测。表单提交、链接、submit/reset 控件、破坏性标签、文档导航以及 POST/PUT/PATCH/DELETE 请求会被跳过或阻断，并记录在证据中。

这是一道安全边界，不是完整沙箱。页面脚本仍可能产生内存、localStorage 或 GET 副作用，所以只对 disposable/test data 使用探测。

为什么不直接写 E2E？

LaunchProof 和现有工具是互补关系：

| 需求 | LaunchProof | Authored E2E | Lighthouse | | --- | --- | --- | --- | | 不写断言就先做一轮验收 | 可以 | 不可以 | 有限支持 | | 自动发现同源路由 | 可以 | 需要自己写 | 有限支持 | | 同时留下布局、运行时和请求证据 | 可以 | 需要自己组装 | 部分支持 | | 验证完整业务流程 | 不可以 | 可以 | 不可以 | | 像素基线视觉回归 | 不可以 | 自行配置 | 不可以 | | 生成本地可审阅报告 | 可以 | 取决于配置 | 可以 |

CI 中使用

在 CI 里先启动应用并安装 Chromium，然后把扫描作为普通步骤：

- name: Install dependencies
  run: npm ci

- name: Install Chromium
  run: npx playwright install --with-deps chromium

- name: Start application
  run: npm run start -- --host 127.0.0.1 &

- name: LaunchProof acceptance scan
  run: launchproof scan http://127.0.0.1:48371 --fail-on error --json > launchproof-summary.json

启动命令和端口需要按你的 Web 框架调整。达到 --fail-on 阈值时，扫描以 2 退出，CI 可以在坏版本继续发布前阻断它。

命令和选项

launchproof scan <url> [options]
launchproof doctor

| 选项 | 作用 | | --- | --- | | --output <dir> | 报告目录，默认 launchproof-report | | --config <file> | 从 JSON 读取普通配置 | | --max-pages <number> | 最多扫描的同源路由数，默认 20 | | --timeout <ms> | 单页面超时，默认 20000 | | --viewports <names> | 逗号分隔的 desktop,mobile | | --fail-on <level> | 阈值：error、warning 或 none | | --json | stdout 只输出一个 JSON envelope，诊断写入 stderr | | --interaction-selector <css> | 明确指定要探测的选择器，可重复 | | --interact | 开启明确授权的交互探测 | | --allow-remote | 显式允许扫描非本地 HTTP(S) 地址 | | --ignore-https-errors | 忽略 TLS 证书错误 |

要保存可重复的普通配置：

cp launchproof.config.example.json launchproof.config.json
launchproof scan http://localhost:48371 --config launchproof.config.json

安全和隐私

• 默认只扫描 loopback HTTP(S) 地址；远程目标必须使用 --allow-remote；
• 含用户名或密码的 URL 会被拒绝；
• 敏感 query 参数会在证据中脱敏；
• LaunchProof 不上传页面数据；
• 截图和页面文本保存在本地报告目录中，该目录可能包含应用的敏感数据；
• 高风险选项不能只通过配置文件开启；
• 如果扫描达到元素或路由上限，报告会明确写出 coverage.truncated 和 warning。

退出码

| 退出码 | 含义 | | --- | --- | | 0 | 扫描完成，未达到设定阈值 | | 1 | 输入、配置、浏览器或基础设施错误 | | 2 | 扫描完成，但 findings 达到设定阈值 |

能力边界

LaunchProof 不是：

• authored end-to-end 测试的替代品；
• 完整的业务逻辑、登录、支付或生产监控系统；
• 完整的可访问性合规证明；
• 像素基线视觉回归工具；
• 通用浏览器 agent 或远程爬虫。

它的目标是尽早发现客观、可行动的问题，并把证据交给人和 coding agent 去检查和修复。

开发

npm ci
npx playwright install chromium
npm test
npm run doctor
npm pack --dry-run

新增检测规则时，应提供一个确定性的 fixture，证明修复前失败、修复后通过。请保持远程扫描默认关闭，交互探测只针对 disposable/test data。

许可证

MIT