Unreal Tran E2E

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

环境变量

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

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

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

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

$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 前端，再在本目录执行：

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 契约可单独执行：

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 数据。未配置令牌时自动跳过：

$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/（已忽略提交）。

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。