# 测试指南

更新日期：2026-03-24

本文档只描述当前项目已落地、已验证的测试路径。

## 1. 环境要求

- Go 1.25+
- Node.js 20+
- Windows PowerShell 环境下，如 `npm.ps1` 被策略拦截，请使用 `npm.cmd`

如果本机 Go 全局缓存目录受限，建议在执行 Go 命令前显式指定本地缓存目录：

```powershell
$env:GOMODCACHE = "D:\project\.cache\gomod"
$env:GOPATH = "D:\project\.cache\gopath"
$env:GOCACHE = "D:\project\.cache\go-build"
```

## 2. 后端验证

### 单元与集成测试

```powershell
go test ./... -count=1
```

如需执行默认回归之外的大并发压力测试，请显式开启：

```powershell
$env:RUN_STRESS_TESTS = "1"
go test ./... -count=1
```

### 静态检查

```powershell
go vet ./...
```

### 构建验证

```powershell
go build ./cmd/server
```

### 健康检查验证

启动服务后可验证：

```powershell
curl http://localhost:8080/health
curl http://localhost:8080/health/live
curl http://localhost:8080/health/ready
```

说明：

- `/health` 兼容历史探针，语义等同 readiness
- `/health/live` 只验证进程存活
- `/health/ready` 会检查数据库可用性

## 3. 前端验证

在 [`frontend/admin`](/D:/project/frontend/admin) 下执行：

```powershell
npm.cmd run test:run
npm.cmd run lint
npm.cmd run build
```

当前已补充并验证的前端重点包括：

- 认证服务契约测试
- 登录页按 `auth/capabilities` 动态展示登录方式
- 忘记密码入口按 `password_reset` 能力显隐

## 4. 真实浏览器验证

当前环境下 `playwright test` runner 会因 `spawn EPERM` 受限，因此真实浏览器验证主路径不是 runner，而是“外部启动真实浏览器 + Playwright 库经 CDP 接管”。
当前 CDP 验证脚本会把以下信号视为失败：

- console error
- native dialog
- popup page
- page error
- request failure
- `401` 响应
- 被前端 `window` guard 拦截的 `alert/confirm/prompt/open`

Windows 下 `e2e:full:win` 与 `e2e:auth-smoke:win` 都会自动把 Go 缓存写到 `%TEMP%\\ums-e2e-cache`，避免工作区权限问题。

### 全量真实浏览器 E2E

```powershell
cd D:\project\frontend\admin
npm.cmd run e2e:full:win
```

当前覆盖：

- `login-surface`
  - 登录页能力展示
  - 未登录访问受保护路由重定向
- `auth-workflow`
  - 真实登录
  - 用户列表
  - 用户详情抽屉
  - 分配角色弹窗
  - 角色页
  - 分配权限弹窗
  - Dashboard
  - 真实登出与登出后重定向
- `responsive-login`
  - desktop / tablet / mobile 视口渲染与横向溢出检查
- `desktop-mobile-navigation`
  - 桌面侧边导航
  - 移动端抽屉导航

### 补充页面与路由 smoke

```powershell
cd D:\project\frontend\admin
npm.cmd run e2e:smoke:win
```

当前覆盖：

- 未登录访问 `/dashboard`、`/users` 会重定向到 `/login`
- 登录页按后端能力动态显示可用登录方式
- 忘记密码入口按能力显隐
- 多视口下页面可正常渲染

### 补充真实认证链路 smoke

```powershell
cd D:\project\frontend\admin
npm.cmd run e2e:auth-smoke:win
```

当前覆盖：

- 从受保护路由跳转到登录页
- 真实登录后回到目标页面
- 用户列表加载
- 用户详情抽屉打开
- 分配角色弹窗打开
- 角色管理页跳转
- 分配权限弹窗打开
- Dashboard 加载
- 真实登出后再次访问受保护页面会被重定向到登录页

## 5. 边界说明

- 当前支持的 CDP 路径已经是浏览器级真实验证，不是 DOM mock。
- 当前支持的 CDP 路径不是完整 OS 级自动化。
  - 不覆盖系统文件选择器、原生桌面弹窗、操作系统级权限窗口等行为。
- `e2e:full:win` 是当前受支持的主验收路径；`smoke` 脚本保留为补充诊断，不代表产品运行时仍依赖 smoke。
- 测试层的 smoke 脚本和 mock helper 是允许的，但它们不应继续进入产品运行时。
- 认证相关接口当前会统一返回 `Cache-Control: no-store` 等响应头；如果在抓包或浏览器开发者工具中看不到缓存命中，这是预期行为。