---
name: 测试报告可追踪输出
overview: 在现有 WalletRegisterBetWinTest 上增加“可追踪测试报告”：每次执行输出并落盘 uid/round_id/biz_id/余额快照，失败时可直接按用户复现。
todos:
  - id: add-reporter-support
    content: 新增 WalletTestRunContext 与 WalletTestReporter（JSON+Markdown 落盘）
    status: completed
  - id: wire-test-class
    content: 改造 WalletRegisterBetWinTest：记录 uid/round/biz_id，tearDown 输出摘要
    status: completed
  - id: config-and-doc
    content: phpunit.xml 增加 WALLET_TEST_UID/REPORT_DIR；更新 doc 执行说明
    status: completed
  - id: verify-run
    content: 容器执行 phpunit 并确认控制台+报告文件含 uid
    status: completed
isProject: false
---

# 钱包集成测试可追踪报告方案

## 问题
当前 [tests/Feature/WalletRegisterBetWinTest.php](tests/Feature/WalletRegisterBetWinTest.php) 每个用例都会 `makeUid()` 生成随机用户，PHPUnit 默认只显示 `OK (3 tests, 37 assertions)`，**看不到本次用了哪个 `uid`、`round_id`、`biz_id`**，联调排障和 DB 核对都不方便。

## 目标
- 跑完测试后，**控制台**能看到每个用例的测试用户与关键业务 ID。
- **落盘一份报告**（JSON + 可读 Markdown），便于复制 `uid` 去查库或手工 curl 复现。
- 可选：通过环境变量固定 `uid`，便于反复验证同一用户。

## 实现方案

### 1. 新增测试上下文与报告器
新增 [tests/Support/WalletTestRunContext.php](tests/Support/WalletTestRunContext.php)：
- 字段：`testName`, `uid`, `currency`, `roundId`, `bizIds`（register/bet/win_mid/win_final）, `traceId`, `steps[]`（每步 API、code、余额快照）, `status`, `errorMsg`。

新增 [tests/Support/WalletTestReporter.php](tests/Support/WalletTestReporter.php)：
- `startRun()` / `recordStep()` / `finishTest()` / `writeReport()`
- 报告目录：`runtime/test-reports/`（文件名含时间戳，如 `wallet-register-bet-win-20260515-160530.json` 与同名 `.md`）
- Markdown 表格示例列：用例名 | uid | round_id | biz_id 列表 | 结果 | 最终余额(deposit/withdraw/b)

### 2. 改造现有 Feature 测试
在 [tests/Feature/WalletRegisterBetWinTest.php](tests/Feature/WalletRegisterBetWinTest.php) 中：
- `setUp()`：初始化 reporter；若存在 `WALLET_TEST_UID` 则使用该固定 uid（否则继续随机）。
- 每个 `test*` 开始：创建 `WalletTestRunContext` 并记录 uid/round_id/biz_id。
- `postJson()` / `wallet()`：成功后把 `code`、关键 `data`、查询余额写入 `steps`。
- `tearDown()`：标记 pass/fail，调用 `writeReport()`；**向 STDOUT 打印一行摘要**（PHPUnit 控制台可见），例如：
  - `[WalletTest] testRegisterBetWinFlow uid=90012345 round=r_... bet=bet_... => PASS`

失败时 assertion message 附带 context 摘要，便于一眼定位用户。

### 3. 配置与文档
- [phpunit.xml](phpunit.xml) 增加可选 env：
  - `WALLET_TEST_UID`（空=随机）
  - `WALLET_TEST_REPORT_DIR`（默认 `runtime/test-reports`）
  - `WALLET_TEST_VERBOSE`（`1` 时打印每步明细）
- 更新 [doc/register-bet-win-test.md](doc/register-bet-win-test.md) §7：
  - 报告路径说明
  - 固定 uid 复现示例：`WALLET_TEST_UID=90012345 docker compose exec ... phpunit ...`

### 4. 执行验证
容器内执行：
```bash
docker compose exec -T -w /app/www/ray/slot-wallet php82 php vendor/bin/phpunit --filter WalletRegisterBetWinTest
```
验收：
- 控制台出现每个用例的 `uid` 摘要行
- `runtime/test-reports/` 生成 `.json` + `.md`
- 测试仍全部通过（3 tests）

## 报告结构示意
```mermaid
flowchart LR
    testCase[WalletRegisterBetWinTest] --> context[WalletTestRunContext]
    context --> reporter[WalletTestReporter]
    reporter --> stdout[ConsoleSummary]
    reporter --> jsonFile[runtime/test-reports/*.json]
    reporter --> mdFile[runtime/test-reports/*.md]
```

## 不在本阶段做的（可选后续）
- HTML 可视化报告、CI artifact 上传
- DB 直连断言（wallet_log / wallet_fund_lot）