# Unreal Tran E2E

本目录是独立的 Playwright E2E 工程，不参与前后端构建。测试默认访问
`http://127.0.0.1:6180`，也可通过 `BASE_URL` 指向局域网地址或其它环境。

## 环境变量

工程内不提供默认密码。可以通过进程环境变量传入管理员凭据，也可以从
`.env.example` 复制本地 `.env`；Playwright 启动时会读取该文件，但不会覆盖已经设置的进程变量：

```powershell
$env:BASE_URL='http://127.0.0.1:6180'
$env:E2E_ADMIN_USERNAME='admin'
$env:E2E_ADMIN_PASSWORD='<通过安全渠道取得>'
```

```powershell
Copy-Item .env.example .env
# 只在本机编辑 .env；该文件已被 .gitignore 排除。
```

强制改密属于有状态、一次性的条件用例，必须使用可重复创建的独立账号；未配置时自动跳过：

```powershell
$env:E2E_FORCE_CHANGE_USERNAME='e2e_force_change'
$env:E2E_FORCE_CHANGE_PASSWORD='<一次性旧密码>'
$env:E2E_FORCE_CHANGE_NEW_PASSWORD='<本轮新密码>'
$env:E2E_FORCE_CHANGE_ROLE_CODE='teacher'
```

不要把真实值写进 `.env.example`、命令历史、测试报告或版本库。

## 安装与执行

先启动 6100/6101/6102 服务和 6180 前端，再在本目录执行：

```powershell
mise install
pnpm install --frozen-lockfile
pnpm run install:browsers
pnpm test
```

完整业务 E2E 只在四个服务就绪且提供本机测试凭据后运行；缺少凭据时仍可执行类型检查与无登录烟测。常用命令：

- `pnpm test`：无头执行 Chromium。
- `pnpm run test:headed`：显示浏览器执行。
- `pnpm run test:ui`：使用 Playwright UI。
- `pnpm run typecheck`：只检查 E2E TypeScript，不启动浏览器或服务。
- `pnpm run report`：打开上次 HTML 报告。

三维编辑器用例默认读取同一工作区中的
`../unreal_tran_web/public/models/excavator-a.glb`。若测试资源位于其它位置，可通过
`E2E_EXCAVATOR_GLB` 指定；不要把带凭据的网络地址写入该变量。

## 报告与制品

- HTML 报告：`artifacts/html-report`
- JSON 报告：`artifacts/results.json`
- 成功与失败截图：`artifacts/screenshots`
- trace、video 与 Playwright 原始结果：`artifacts/test-results`

成功截图以项目、测试文件、用例标题和检查点稳定命名；每个用例/重试开始时先清理自己的旧成功图，再生成新图并附加到 HTML/JSON 报告。截图覆盖登录、三种导航、三种主题、侧栏收展、七个系统页、菜单草稿操作、内容导航以及 CRUD 各成功节点。失败截图额外带 retry 次数和时间戳，trace 与 video 只在失败时保留。

## 测试分层说明

教学实施模块采用三层验证，三者不能互相替代：

- Java 策略与服务测试负责验证后端授权、状态机、正式考核时间窗、岗位约束、故障私密字段脱敏和服务端派生进度。
- `tests/teaching-module.spec.ts` 是浏览器端的状态化 Mock 契约测试。Mock 会按最终 DTO 校验请求、维护运行版本与状态并返回服务端权威响应，用来验证 UI 分支和前端请求契约；它不连接 KingBase，也不等同于真实 API 联调。
- 测试环境部署后只做 IP + 端口烟测，确认 Nginx、网关、鉴权和主要页面可访问。烟测通过不代表完整业务状态机已在真实环境回归。

教学 UI 契约可单独执行：

```powershell
npm run typecheck
npm test -- teaching-module.spec.ts
```

教学实施真实环境只读联调与状态化 Mock 是两类测试：`teaching-module.spec.ts` 拦截 API，用于稳定验证 12 条前端状态机闭环，但不代表 Java、Redis 或 KingBase 联调；`teaching-live.spec.ts` 不拦截 API，只读取测试环境中保留的 `UAT-` 教学数据。真实联调用短期访问令牌注入 `sessionStorage`，测试文件已关闭 trace/video，且不会提交业务写请求或清理 UAT 数据。未配置令牌时自动跳过：

```powershell
$env:BASE_URL='http://<测试环境IP>:6180'
$env:E2E_LIVE_ACCESS_TOKEN='<短期访问令牌>'
npm test -- teaching-live.spec.ts
```

不要把令牌写入命令历史、截图、HTML/JSON 报告或版本库；执行完成后应按测试环境会话管理策略撤销令牌。

内容制作的作业指导书（OFD）走同一套状态化 Mock 分层：`tests/content-guide-lifecycle.spec.ts` 按
`wiki/11-内容制作模块.md` 的契约打桩内容制作接口，覆盖编制 → 送审 → 审批时间线 → 预览 → 预检 →
批准 → 发布 → 交付物下载，并解包核对生成的 `.ofd` 与离线 HTML。Mock 的状态流转表与服务端
`REVIEW_TRANSITIONS` 同源，契约分叉会直接失败；它同样不代表 KingBase 联调。截图与生成的交付物落在
`artifacts/content-guide-lifecycle/`（已忽略提交）：

训练编排走同一层：`tests/content-training-studio.spec.ts` 覆盖 8 个流程视图、绑定场景的目标解析、
步骤编排与保存产出的运行时编码、实装进度递增与对抗岗位校验。截图落在
`artifacts/content-training-studio/`（已忽略提交）。

```powershell
npm test -- content-guide-lifecycle.spec.ts
npm test -- content-training-studio.spec.ts
```

## 用例范围

- 管理员登录与退出。
- 四身份展示顺序、默认管理员、组织级联选择与密码 eye 图标。
- 精简平台页头、账号菜单和个人中心资料/修改密码契约。
- 独立账号强制改密（条件执行）。
- 三种导航模式、明亮/暗黑/跟随系统主题及刷新后持久化。
- 用户、部门、角色、菜单、权限、审计、接口配置七个页面加载。
- 菜单搜索、布局预览、编辑与同级排序草稿撤销；用例不调用菜单写接口。
- 内容制作四类新名称、训练三模式及编辑/预览子路由活动态。
- 教学实施六个侧栏入口与内部作业指导书、纯行政只读聚合、UNION 行政+学员本人运行、COMMON 领取到评定闭环。
- 实装训练两步 `physical-events`、对抗岗位动作/负责人提交/公开故障/分队编组干预、正式考核 Unix 秒和辅助能力硬锁。
- 运行场景与沉浸交互必须请求教学资产清单并消费发布 `definitionSnapshot`；WebXR 测试不会用“只有 canvas”作为通过条件。
- 数据中心筛选、分页安全明细和详情抽屉；个人检查点、答案及私密载荷不得进入页面。
- 装备模型编辑器和数字车间场景编辑器均为原生 Three.js canvas，断言页面不存在 iframe。
- 真实 `excavator-a.glb` 上传进度、SHA-256 内容寻址、READY 资产、服务端文件元数据及刷新恢复。
- 模型选择/变换/软删除恢复、时间轴、蓝图、保存发布；真实车间部件软删除恢复、发布模型目录引用、放置变换、精确版本依赖及场景发布。
- 使用 `UTE2E-<唯一值>` 前缀创建部门、角色和用户，完成编辑、搜索、角色授权、审计验证，并在 `finally` 中按用户 → 角色 → 部门顺序清理。

测试配置为单 worker 串行执行，避免管理数据之间相互污染。三维编辑器用例在
`finally` 中按场景 → 模型顺序调用 API 清理，并始终附加中文清理报告；若服务异常导致清理失败，可在内容制作页面按 `UTE2E-` 搜索并人工清理残留。静态测试设计和待执行状态见
[`reports/三维编辑器E2E测试报告.md`](reports/三维编辑器E2E测试报告.md)。