From 55d368d98b69171b9471a5b3a2301ea7af6d5b61 Mon Sep 17 00:00:00 2001 From: wangjia <809946525@qq.com> Date: Thu, 25 Jun 2026 21:30:54 +0800 Subject: [PATCH] =?UTF-8?q?docs(test):=20=E6=B5=8B=E8=AF=95=E6=9E=B6?= =?UTF-8?q?=E6=9E=84=E8=A1=A5=E3=80=8C=E2=91=A9=20=E5=B7=B2=E7=9F=A5?= =?UTF-8?q?=E7=BC=BA=E5=8F=A3/=E6=B5=8B=E8=AF=95=E7=9B=B2=E5=8C=BA?= =?UTF-8?q?=E3=80=8D=E5=8D=95=E4=B8=80=E8=B7=9F=E8=B8=AA=E6=BA=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 把散在对话里的盲区收进架构文档,作为单一跟踪源(补一项划一项): - A 覆盖盲区:前端统计上屏数值未验证(诉求半覆盖)、真实流量数据路径 (注入非真出网,最大盲区)、原生隧道层零自动化、契约双份可能漂移。 - B 运维/工程缺口:CI 单点 mac(持久化未激活)、go-integration 裸宿主脆性、 analyze 严格化(B1)+ golden 全集(B2)被 stats-overhaul 耦合阻塞、 golden 本地难重生。 每项标严重度 + 现状为什么 + 何时怎么补;同步登记 docs/index.html。 Co-Authored-By: Claude Opus 4.8 --- docs/index.html | 2 +- docs/test-architecture.html | 74 +++++++++++++++++++++++++++++++++++++ 2 files changed, 75 insertions(+), 1 deletion(-) diff --git a/docs/index.html b/docs/index.html index fff1df3..0f3cfcf 100644 --- a/docs/index.html +++ b/docs/index.html @@ -90,7 +90,7 @@
统一测试框架 · 架构说明 HTML
-
多端项目可复用的分层测试方法论（L0 契约→L4 E2E）+ 四类诉求(界面一致/交互/数值/后端记账)→层→工具→量化指标映射 + 五张架构图（金字塔/契约接缝/CI 流水线/E2E 拓扑）。
+
多端项目可复用的分层测试方法论（L0 契约→L4 E2E）+ 四类诉求(界面一致/交互/数值/后端记账)→层→工具→量化指标映射 + 五张架构图（金字塔/契约接缝/CI 流水线/E2E 拓扑）+ ⑩「已知缺口/测试盲区」单一跟踪源（没测什么·为什么·何时补）。
docs/test-architecture.html
 diff --git a/docs/test-architecture.html b/docs/test-architecture.html index 244b4df..a880cc1 100644 --- a/docs/test-architecture.html +++ b/docs/test-architecture.html @@ -426,6 +426,80 @@

本文档仅为架构说明（设计真相源）。具体落地拆解（契约快照实现、前端 flow 用例、L4 冒烟脚本）走各自实现计划（writing-plans）。

+

⑩ 已知缺口 / 测试盲区

+
+框架不是「测了什么」的清单，更要诚实地记「没测什么、为什么、何时补」——否则盲区会散在对话与脑子里被遗忘。本节是这些缺口的单一跟踪源，补上一项就划掉一项。 +
+ +

A. 覆盖盲区（功能上没被验证到的部分）

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
缺口严重度现状 & 为什么没测何时 / 怎么补
前端统计「上屏数值对不对」中·诉求半覆盖最初诉求是「统计数据对不对」。后端记账已 L4 e2e（ReportUsage → /v1/usage 断言字节）；前端只到单测（device_usage_test/format_test 解析+格式化）。解析对 ≠ 渲染对——没有测试验证统计页拿到真实响应后上屏的数字/曲线是对的。可立即补：widget 级测试，用 e2e server 的真实 /v1/usage 响应喂 stats_page，断言关键数值/曲线上屏。闭合诉求最后一环。
真实流量数据路径高·最大盲区L4 e2e 是注入假 ReportUsage，不是「真 sing-box 出网 → v2ray stats 采集 → 上报记账」。真链路从未自动跑过——这是「我们其实不知道线上准不准」的根盲区。真出网那环仅 usage_v2ray.go 单测覆盖采集解析。贵且脆（单机 docker 真出网重、CI 跑不动）。留后续按需，或本地手动跑一次真连基准。
原生隧道层高真正承载流量的代码——client/ios/Runner/VpnManager.swift、client/android/…/PangolinVpnService.kt、macOS 系统扩展——零自动化测试，全靠真机/模拟器手测。依赖真机/模拟器，难纯 CI 化。至少补「连上→可达性探针→断开」的半自动脚本。
契约双份可能各自漂移中Dart 与 Go 各冻一份字段面快照，两边是各自独立的真相，理论上可各自漂移（OpenAPI 改了、只更了一边）。真·单源（从 OpenAPI 生成两端契约）是大改，列入 C 类效率项后续做。
+ +

B. 运维 / 工程缺口（能跑，但脆或欠账）

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
缺口严重度现状 & 为什么何时 / 怎么补
CI 是单点中·运维整条 CI 吊在一台 mac（mac-pangolin-2）+ 依赖 jiu 的 relay + Docker Desktop。launchd 持久化尚未激活（见 docs/ci-runner.md 的一次性 ! 命令）——mac 一关/重启 CI 就全停。激活持久化（脚本已就位）；理想归宿是 NAS Linux host runner。
go-integration job 脆性中跑在裸宿主机（go1.26.1，非容器，testcontainers 要真 docker，DooD 在 Docker Desktop mac 网络不通）——宿主 go 版本漂移即挂；套件 ~5min；曾踩 ryuk 关闭→容器泄漏坑（已用默认 ryuk + -p 1 串行规避）。迁 NAS Linux host runner 可恢复容器化 hermetic；保持 ryuk 开启。
analyze 严格化（闸·B1）中·阻塞去掉 --no-fatal-infos 让 info 变致命，会因 HEAD stats_page.dart 的 withOpacity info 当场红；而清 info 正动 stats-overhaul 在改的同一文件。被 stats-overhaul 耦合阻塞，其合并后立刻做。
golden 全集（闸·B2）中·阻塞golden job 现只跑 components + auth；tablet/desktop-stats golden 与 tablet_pages_golden_test.dart 全是 dirty WIP，并入等于钉死未定稿基线。stats-overhaul 合并后并入；连带补回临时摘除的 DeviceUsage 契约快照（Dart+Go）+ e2e /v1/usage/devices 断言。
golden 本地难重生低·摩擦Linux 权威基线（mac 渲染不一致），开发机改 UI 后须 docker 起 flutter 容器重生基线，非纯本地。scripts/update-goldens.sh 已封装，文档化即可，非真缺口。
+

维护约定：补上某项缺口后，从本表删去对应行（或标 已补）；新发现的盲区即时登记到此，使本节始终等于「当前真实缺口」。

+