# 测试执行与维护手册

当前 v0.6 的执行步骤、实际结果和新增用例见[发售测试](sale-testing.md)。早期 Windows 检查失败已修复回归；[审阅报告](../reports/2026-11-02-architecture-review.md)保留失败证据，不代表修复后状态。下方历史容量/覆盖率保持原环境含义。

> 当前基线：模拟 v0.3 保留，独立链模式升级为 v0.5。新增完整历史查询、任务版本保护、已确认事件索引、只读对账和基础告警，见 [设计](../07-history/v0.5-design.md)、[执行报告](../reports/2026-10-12-v0.5.md)。历史报告与证据保留原版本。

> v0.4新增独立链测试：[完整链测试设计与用例映射](web3-testing.md)，[真实执行报告](../reports/2026-10-12-v0.4.md)。本页原用例继续验证模拟模式；新增真实EVM/三中间件/钱包adapter/硬杀/重组/容器，不把旧测试数或性能继承为链成绩。


更新：2026-10-11。适用当前单市场、单实例、模拟资金架构。设计依据见[测试设计](test-design.md)，逐项输入与预期见[测试用例目录](test-cases.md)，本轮执行结果见[测试完善报告](../reports/2026-10-11-test-hardening.md)。

## 1. 测试分层与使用时机

| 层级 | 实际测试对象 | 执行方式 | 不能据此证明 |
| --- | --- | --- | --- |
| 单元 | decimal 输入、核心 Apply、幂等、资金/FIFO、游标/Origin/错误判断、前端恢复解析 | `bash scripts/test.sh unit` | 真实磁盘提交、网络与浏览器交互 |
| 组件/集成 | 真实 SQLite、认证事务/会话、HTTP/RBAC/分页、运行时资源与离线 CLI | `bash scripts/test.sh backend` | 断电耐久性、云环境容量 |
| 故障恢复 | 精确提交/执行/投影/恢复窗口，测试子进程被杀，真实服务 SIGKILL | Go 全套及 verify 中的 crash_check.py | OS/磁盘掉电与 fsync 硬件失败 |
| 前端单元 | APIError、超时/坏响应、原请求头、只读待确认记录的格式/作用域 | `npm --prefix frontend run test:unit` | React hook 生命周期、DOM、真实服务端执行 |
| 浏览器 E2E | 真实 Cookie、双账户成交、管理分页、请求丢响应后刷新、WS 重连 | `bash scripts/test.sh browser` | 所有浏览器、全断网/弱网矩阵、完整无障碍审计 |
| 容器 | 非 root/只读、静态资源、重启、同卷持久性、停机备份恢复 | `python3 scripts/container_check.py` | 真实云网络、HA、在线一致备份 |
| 性能 | 核心/日志/恢复基准，开放到达率 HTTP 与最终资金对账 | 独立 benchmark/load 脚本 | 未测负载的生产 TPS/SLA |

测试按风险选择：资金/核心/所有权变更执行全套 Go 与 race；协议/恢复变更增加真实浏览器；部署变更增加容器。性能实验顺序执行，避免与 race、构建或其他压力任务互相争抢机器资源。

## 2. 环境准备

本地使用 Linux/WSL、Go 1.26.9+、Node 22、npm、Python 3、bash；SQLite 内嵌在纯 Go driver，不需要外部数据库服务或 Redis。容器测试另外需要可用 Docker daemon。前端单元复用已安装 TypeScript 与 Node 内置 test，不新增测试框架依赖。

```bash
go mod download
npm --prefix frontend ci
# 浏览器第一次使用时安装；无浏览器依赖不会影响 unit/backend/coverage。
npx --prefix frontend playwright install chromium
```

CI Ubuntu 安装浏览器时使用 `playwright install --with-deps chromium`。离线/代理失败属于准备失败，不把测试没启动记成通过。

## 3. 日常与全套入口

从仓库根目录执行：

```bash
bash scripts/test.sh unit
bash scripts/test.sh backend
bash scripts/test.sh coverage
bash scripts/test.sh fuzz
bash scripts/test.sh all
```

`unit` 选择纯核心和独立外围 helper、运行负载工具的小组件测试以及前端纯函数测试，不启动业务服务。`backend` 执行全部 Go 包，包含真实库、HTTP 与子进程。`all` 顺序执行 verify → 覆盖率 → 两个有限 fuzz 目标 → 真实浏览器：verify 包含格式、mod verify、关键故障用例收集检查、vet、Go 测试、race、前端单元、契约一致性、格式、构建三种二进制和真实服务 SIGKILL。

所有脚本遇错退出非零。故障 helper `TestCrashWindowChild` 在父进程未设置注入参数时明确 skip，这是预期；真正验收用例是 `TestCrashRecoveryWindows` 的六个子场景。verify 显式确认父用例被当前平台收集，避免 `_windows_test.go` 这样的文件名使 Linux 静默漏测。

### 单个场景与可重复运行

```bash
go test -count=1 -v -run '^TestPricePriorityBothDirections$' ./backend
go test -count=1 -v -run '^TestRuntimeResponseCannotMutateProjection$' ./backend
go test -count=1 -v -run '^TestCrashRecoveryWindows$' ./backend
go test -count=1 -v -run '^TestCLIInitCheckBackupRestoreThroughPublicEntry$' ./cmd/exchangectl
go test -race -count=3 -run 'TestCoreResultOwnership|TestRuntimeResponseCannotMutateProjection|TestDisableAuditFailureRollsBack' ./backend
```

`-count=1` 禁用成功结果缓存。不要把 `(cached)` 输出当成本次重新执行的耗时。单个测试失败先用其准确名称重现，不靠扩大超时或删断言让它通过。

## 4. 覆盖率与执行清单

```bash
# 默认输出到已忽略的 bin/test-results；也可以指定新的独立证据目录。
EXCHANGE_TEST_OUTPUT_DIR=/tmp/exchange-test-evidence bash scripts/test.sh coverage
go tool cover -func=/tmp/exchange-test-evidence/coverage.out
go tool cover -html=/tmp/exchange-test-evidence/coverage.out -o /tmp/exchange-coverage.html
```

| 产物 | 含义 |
| --- | --- |
| `go-tests.jsonl` | `go test -json` 的逐包/逐用例 run/pass/fail/skip，保留子用例名称 |
| `coverage.out` | Go 标准语句覆盖率 profile，可再次生成报告 |
| `coverage.txt` | 按函数及整个 profile 加权的语句覆盖率 |
| `coverage.html` | 源码级 HTML，查看哪些代码块没有执行 |

总覆盖率按语句数量加权，不能平均各包百分比。纯生成类型和嵌入契约没有可执行语句，不以“0%”评价。进程 `main`、长时负载、真实故障子进程的被杀路径不保证进入父进程 profile；容器/E2E 也不自动加入 Go coverage。前端当前报告 34 个用例结果，不声称前端行/分支覆盖率。重点审阅未覆盖行为和风险，不为达到 100% 模拟不可能发生的随机源/磁盘硬件故障。

## 5. Fuzz 与属性测试

```bash
# 默认各目标 3s、2 workers；长时运行另开实验，记录环境与失败输入。
EXCHANGE_FUZZ_TIME=30s bash scripts/test.sh fuzz
# 只测金额解析
go test -run '^$' -fuzz '^FuzzAmountParsing$' -fuzztime 30s -parallel 2 ./backend
```

普通 `go test` 只执行 fuzz 种子；持续 fuzz 必须看到实际执行次数。失败输入写入 Go `testdata/fuzz/<目标>/` 后成为普通回归种子，保留它并使用 `go test -run '目标/输入名'` 重现。生成的探索缓存保存在 Go cache，不复制成已审阅的业务用例。

`TestRandomizedCoreProperties` 固定 seed `1/42/20261011`，各 500 步；失败日志给出 seed/step。每一步重算资产总量、冻结与树/FIFO/反向索引。随机只用于生成测试输入，生产核心不使用随机数。现有持续 fuzz 只覆盖金额和游标，不能称为完整撮合状态机 fuzz 或完整参考模型对拍。

## 6. 浏览器准备与运行

只跑浏览器前，准备同版二进制与静态页：

```bash
npm --prefix frontend run build
CGO_ENABLED=0 go build -trimpath -o bin/exchange ./cmd/server
CGO_ENABLED=0 go build -trimpath -o bin/exchangectl ./cmd/exchangectl
bash scripts/test.sh browser
```

`scripts/e2e_check.py` 使用新的临时目录、真实初始化管理员、不可登录的分页 fixture 和本机随机端口；运行 Playwright 后 SIGTERM 排空服务、检查退出码，结束后删除自己的临时目录。不会启动/重置用户 `data/`。测试管理员 `admin-e2e@example.com / admin-e2e-password-123` 只用于该独立目录。

Playwright 只收集 `**/*.spec.ts`，Node 的 `tests/unit/*.test.mjs` 不被浏览器再次执行。测试逐个使用独立 Cookie 上下文，workers=1 避免交易场景争抢同一订单簿。截图在 `playwright-results/`，它们是辅助证据，订单/余额和恢复结论仍来自页面与真实 API 断言。

前端单元使用真实 TS 源码，经项目 TypeScript 擦除类型后由 Node test 运行。fetch/定时器/只读存储可控；未复制生产算法到测试。类型检查单独由 build 中的 tsc 执行，成功 mock 不能代替真实浏览器。

## 7. 测试数据与生命周期

| 测试 | 数据/资源所有权 | 清理方式 |
| --- | --- | --- |
| 纯核心 | 测试函数内 Engine，资金由 CREDIT 准备 | 函数结束释放，无真实库 |
| Store/HTTP/runtime | `t.TempDir`，真实三个数据库，httptest | 关 WS → HTTP → drain runtime → Store，最后清理目录 |
| 会话/回滚 | 隔离 auth.db，真实 bcrypt；分页 fixture 不用于登录 | 会话过期由 SQL 写到过去，失败 trigger 只存在测试库 |
| 崩溃窗口 | 父进程自建目录、标记文件和测试子进程 | Kill/Wait 确认，重开同目录验证，然后父测试清理 |
| CLI | 新的 data/backup/restored 路径，密码通过 `t.Setenv` | execute 释放同一目录锁，测试结束清理 |
| 浏览器 | e2e 脚本独立服务/随机端口/新目录 | finally 停机排空，临时目录自动清理 |
| 容器 | container_check 自建命名卷/容器 | 停止后保留卷供复查；不自动删除用户数据 |

不连接生产 API，不使用真实资金，不把真实密码/Cookie 写入测试报告。SQL 只注入本次临时库；数据库故障不通过删除权威 journal/auth 恢复。不要对用户目录运行破坏性 fault fixture。

## 8. 失败定位

| 表现 | 先检查 | 处理/不能做的事 |
| --- | --- | --- |
| 某组测试不出现在 JSON/list | 文件 GOOS 后缀/build tags、运行正则、是否只是 helper | 用 `go test -list` 确认收集；测试存在不等于执行 |
| 冻结/数量不变量失败 | 最小命令序列、maker 价格、释放余量、seed/step | 保留输入，不能改成 float 或放松精确比较 |
| 原键结果被修改 | 指针/切片所有权，响应与幂等记忆/投影是否共用 | 检查独立副本回归，不只用 race 代替业务断言 |
| 恢复标记未到达 | 子进程输出、真实 hook 位置、Store/锁错误 | 报告子进程日志；不能把 kill 超时算通过 |
| AUTH_UNAVAILABLE | 认证库打开/事务错误 | 与 401 区分，不当作用户未登录掩盖故障 |
| 浏览器无法启动 | Chromium/系统依赖、二进制/dist 版本、端口/ready | 补环境后重跑；不用静态页面截图代替联调 |
| 容器在线构建失败 | Docker daemon/镜像源 DNS | 保留准备失败边界，不改写成应用测试通过 |
| coverage 百分比变低 | 新增代码语句、GOOS 收集变化、子进程口径 | 查看 HTML/JSON 与历史基线，不能直接删除难测代码 |

## 9. CI、验收与记录

GitHub workflow 执行 verify、覆盖率、漏洞检查、浏览器，保留 `bin/test-results/` 和截图，即使失败也上传证据。远程 CI 需要推送到 Git 仓库才会运行，本项目仍不把 workflow 文件当远程成绩。

本地验收要求：相关单元/集成用例通过、没有未解释的 race、真实故障关键窗口确实被收集且执行、契约生成一致、前端单元/构建/必要浏览器通过、文档与原始证据一致。覆盖率提供风险视图，不作为唯一准入线；性能不设置跨机器不稳定的墙钟通过阈值。

每次记录日期、源码状态（无 Git 就明确说明）、环境、完整命令、预期/实际、失败与修复、原始输出、未执行项。真实断电、满盘/fsync 硬件失败、云实机、长时间生产混合负载、冷缓存恢复和跨浏览器/完整无障碍仍需专项环境；见用例目录的待执行区。

## 文档与注释审阅后的使用

最新文档一致性与注释检查见[本轮报告](../reports/2026-10-11-documentation.md)。测试完善报告的 source-SHA256SUMS 对应当时源码，中文注释变更后逐字摘要自然不同；不要重新生成后覆盖它。当前脚本与源码先核对行为不变，再按本手册执行所需测试。

HTTP 手动调试见[接口指南](../03-development/api-guide.md)，真实数据的停机/备份/投影恢复见[数据生命周期](../05-deployment/data-lifecycle.md)；测试临时数据与用户生产目录分开。容器验证脚本固定标签与报告路径，重跑前保存旧证据，具体说明见[部署手册](../05-deployment/deployment.md)。

## Windows 启动验证

新增本地管理员边界可运行 `go test -count=1 -run TestLocalAdmin ./backend ./cmd/server`。Windows 执行 `run-windows.cmd -PrepareOnly` 只构建；真实联调使用独立 -DataDir/-Port/-NoBrowser，避免修改默认演示用户数据，验证后只停止自己创建的进程。完整记录见[Windows 报告](../reports/2026-10-11-windows-launcher.md)。

## v0.5 链闭环验证

chaintrade/production_test.go 新增 TestHistoryBoundaries（111条/上界/筛选/游标隔离）、TestTaskMigrationAndCAS（旧表升级/raw不变/冲突/终态）、TestIndexerAtomicRestartReorganization（重启/浅尾部/深锚点）、TestIndexTransactionFailure（事件失败游标不推进）、TestReconciliationDetectsCorruption（全量投影守恒/只读/lag）、TestHistoryContractAndDiagnostics（新接口真实契约/raw不泄漏）。

真实 scripts/web3_check.mjs 额外覆盖历史翻页、钱包筛选、详情、重启索引、对账和直方图；浏览器进入成交历史并打开任务详情。先构建同版前后端，再运行真实 Anvil/中间件/容器。WEB3_CHECK_EVIDENCE_DIR 指定本次独立目录，默认为 docs/reports/evidence-v0.5；历史 evidence-web3 不改写。全套命令、失败重试与执行结果见 web3-testing.md 和 v0.5 报告；公共链/云/原生 Windows、硬件断电没有在本轮执行。

最终补充 TestFinalizedReconciliation（正确终态零差异，缺失事件/终态冲突检测）、TestIndexDiskRestart（真实关闭重开仍保留游标与事件）、TestReadSnapshotDoesNotBlockWriter（读事务持有旧水位，新命令可完成且只读池拒写）。

告警配置校验：项目根执行 `docker run --rm --entrypoint /bin/promtool -v "$PWD/deploy:/etc/prometheus:ro" quay.io/prometheus/prometheus:v3.2.1 test rules /etc/prometheus/web3-alerts-test.yml`，预期 SUCCESS；配置另用 `check config /etc/prometheus/web3-prometheus.yml`。指标输出包含 HELP/TYPE，使用 `docker run --rm -i --entrypoint /bin/promtool quay.io/prometheus/prometheus:v3.2.1 check metrics < 保存的metrics.txt` 检查实际格式。规则评估测试不向外发送消息。
