# 应用与系统组件测试

本流程包覆盖“可执行 → 应用与系统”的 **49 个组件 ID**，分为 13 个任务、74 个用例。同名组件的不同版本分别统计。11 个待接入组件不计入验收。

测试发现的 PID 空结果、类型判断／转换、毫秒等待、按模式校验参数、命令行编码及 BAT 路径问题现已修复。绿色运行状态仅表示引擎没有抛出异常；本流程还会核对实际值、返回类型、进程状态和等待耗时。

## 在当前应用中使用

1. 返回左侧“编排”首页，点击任务列表右上角的刷新按钮。
2. 搜索“组件测试”，打开所需任务并点击“编辑流程”。
3. 先使用 01～07 组。运行后打开底部“运行日志”，搜索“用例结果”或查看末尾的“本组汇总”。
4. 每条用例结果依次为：`[用例编号, 组件 ID, 状态, 输入, 预期, 实际]`。
5. 状态 `PASS` 是通过，`FAIL` 是失败，`BLOCKED` 是缺少条件或无法校验，`MANUAL` 是待人工确认。有任一未通过项目，任务最终显示“失败”，详细原因以用例结果为准。

01～07 组现可自动验证；类型选项使用明确的语义值，07 组只填写当前命令模式需要的参数。实际结果见本包的最新报告，修复前的失败证据另行保留。

## 分组与预期

| 组 | 测试目标 | 关键输入与验收条件 |
|---|---|---|
| 01 · 应用与 PID | 5 个组件，8 个用例 | 生成唯一 `rpatest_` 程序，启动两个实例；返回 PID 与列表应匹配；两个关闭组件各关闭一个实例；无匹配时应返回 `null` / `[]`。 |
| 02 · 数据转换 | 6 个组件，10 个用例 | `"123.5" → 123.5`、`"-42.25" → -42.25`、`-3.9 → -3`、真假布尔值、`42 → "42"`；通用转换分别检查数值、整数、布尔和文本。 |
| 03 · 数据判断 | 6 个组件，12 个用例 | 对象与数组、数字与中文、`null` / 空文本 / `0`、真实数组与文本 `"[]"`；“判断数据类型”按目录契约应返回布尔值。 |
| 04 · 变量与配置 | 7 个组件，10 个用例 | 中文变量、整数和列表、深复制内容及引用独立、当前流程 ID、自定义配置命中与未命中、计数 `10 → 12 → 14`。 |
| 05 · 等待与随机数 | 5 个组件，7 个用例 | 三个等待组件按独立毫秒时钟测量；毫秒版本设置 `3000`，预期 `2800～6500 ms`；随机整数包含 `min=max=7` 与负数范围，小数应处于 `[0,1)`。 |
| 06 · 系统路径与环境变量 | 5 个组件，7 个用例 | 与 Windows 独立查询的临时、用户、桌面路径比较；只读写专用变量 `RPA_APP_SYSTEM_TEST_VALUE`，结束恢复原先读到的值。 |
| 07 · 命令行 | 2 个组件，5 个用例 | PowerShell 中文固定输出；DOS、BAT、PowerShell 三种 V1 模式；非零退出码应报错。只校验当前模式的参数，另有含中文和空格 BAT 路径的回归测试。 |
| 08 · Windows 凭据【手动】 | 3 个组件，3 个用例 | 仅操作唯一新建测试目标。缺少安全的秘密输入机制，默认阻塞，不能把真实密码填进流程。 |
| 09 · 输入法【手动】 | 2 个组件，3 个用例 | 读取、切换到 `en-US`、尝试恢复原状态；必须人工核对前台窗口与任务栏，子进程返回成功不算通过。 |
| 10 · 音频【手动】 | 1 个组件，1 个用例 | 使用自制 0.3 秒、440 Hz 低音量 WAV；人工确认确实听到声音。 |
| 11 · 屏保【手动】 | 3 个组件，4 个用例 | 两个开启版本分别配对关闭，需观察实际屏保；V1 按 Windows 已有屏保设置运行，已去掉未实现的自定义文字、效果和密码参数。 |
| 12 · 锁屏与解锁【手动】 | 2 个组件，2 个用例 | 锁屏仍要求账户等参数，该组保持阻塞。原“屏幕解锁”已明确标为“唤醒屏幕（非登录解锁）”，无需账号密码，不支持 Windows 登录解锁。 |
| 13 · 远程桌面【手动】 | 2 个组件，2 个用例 | 填写自己的测试地址，人工完成登录并验证目标；`tsdiscon` 可能断开当前会话，关闭操作有独立开关。 |

## 手动测试的执行开关

08～13 组不会由自动脚本执行。任务中名为“手动执行开关”的初始化节点，默认值是布尔 `false`。

只有确认该组的运行环境、影响和恢复方式后，才把该节点的“值”改为 `${true}`。恢复关闭使用 `${false}`。不要填写普通文本 `true` / `false`，保护条件只接受真正的布尔值。

- **08 组和 12 组的锁屏节点**：当前没有不会把秘密写入流程或 `run.json` 的输入途径，因此保持阻塞；不要填 Windows 登录密码，不创建、覆盖或删除已有业务凭据。“唤醒屏幕”本身已无需任何凭据，可在单独任务中测试。
- **09 组**：先准备一个没有未保存内容的文本编辑窗口，人工记录原输入法，执行后核对是否真的切换并恢复。异常时人工切回原状态。
- **10 组**：确认音量和输出设备后，只播放本包的短测试音。
- **11 组**：需人在机器旁，有办法手动退出屏保；只调用 Windows 已配置的屏保，不设置自定义解锁密码。旧节点若保留 `set_password=1`，会在桌面操作前给出明确错误，可删除该旧节点后重新添加。
- **12 组**：实际锁屏须先明确确认影响和恢复方式，人在机器旁并能正常用 Windows 登录；不能测试自动输入登录密码。
- **13 组**：先设置“填写用户自己的测试远程地址”。连接成功须人工确认，启动 `mstsc` 不算已经登录。断连还要求“断连单独开关”为 `${true}`，必须另行确认操作的是哪个会话及如何重新连接。确认前保持 `${false}`。

人工项目即使组件返回成功，也继续显示 `MANUAL`，本工具不会自动写成通过。人工证据请附实际观察、时间和必要截图，不能仅记录返回标志。

## 安装、校验与报告命令

在项目根目录运行：

```powershell
# 校验 13 组 / 49 项覆盖、连接关系及现有运行前校验
node scripts/app-system-tests.mjs verify

# 安装到当前用户：只新增；同 ID 已存在则跳过，保留用户修改
node scripts/app-system-tests.mjs install --user-data "$env:APPDATA\rpa-studio"

# 重建仓库里的流程 JSON；不会覆盖应用中已安装的任务
node scripts/app-system-tests.mjs generate

# 构建后，在全新的 Electron 用户目录运行非手动任务
npm run build
node scripts/app-system-tests.mjs run-safe

# 同时用临时可见的独立 Electron 窗口验证下拉选项、模式切换和唤醒提示
node scripts/app-system-tests.mjs run-safe --ui-check

# 从本次真实证据重新生成报告
node scripts/app-system-tests.mjs report
```

安装默认使用 `%APPDATA%\rpa-studio`；非标准用户目录需要显式传入 `--user-data`。重复安装不会覆盖已有测试任务，也不改变用户原有任务。

`run-safe` 退出码：`0` 表示报告没有失败或阻塞，`2` 表示存在失败或阻塞（包含手动任务缺少前置条件），`1` 表示工具自身异常。报告和原始事件保存在项目的 `test-output/app-system/`，该目录已由现有 `.gitignore` 忽略。

每次自动运行保留独立 Electron 用户目录及 `runs/<runId>/run.json`，测试不会占用当前日常实例，也不会把隔离验证结果伪装为用户任务列表中的运行历史。任务列表的新任务初始仍显示“尚未运行”。

## 边界与恢复

- 测试进程名称和可执行路径唯一，两个关闭组件只操作新建夹具 PID。常规异常后仍执行专用进程清理；中止流程可能跳过收尾，夹具会在 90 秒内自动退出。
- 临时文件仅写入系统临时目录下的新建 `RPA-AppSystem-Tests` 子目录，保留供排查，不批量删除文件。
- 环境变量组件只操作当前应用进程，不修改 Windows 用户／系统环境变量。本包恢复原读取值；原本不存在时只能恢复为空文本，当前组件不支持删除进程内变量，退出应用后消失。隔离运行预设原始值并验证恢复。
- 凭据、输入法、屏保、锁屏、远程会话均未在自动验收中改变。
- 缺少类型选项映射、真实桌面观察或测试远程主机时，状态保持阻塞或待人工确认。

## 修复结果与保留的限制

- PID：无匹配返回 `[]` / `null`，过滤空行、零和无效 PID。
- 类型判断：按目标类型返回布尔值；数值类型与数字文本分开判断。
- 类型转换：使用 `number`、`int`、`bool`、`string` 选项，输入无效时报错。历史默认值 `1` 兼容数值类型；其他数字别名为本项目明确规定的兼容值，前端统一使用语义值。
- 等待：毫秒组件读取 `mileSecond`，其他秒制等待组件保持秒制；支持取消，拒绝超出计时器范围的值。
- 关闭程序：PID／名称模式分别显示并校验参数；无效 PID 不会降级成按名称批量关闭。名称模式尊重“关闭所有会话”选项，并排除 RPA Studio 主进程。
- 命令行：DOS／BAT／PowerShell 分别校验，修复中文输出编码和含空格、中文 BAT 路径的引号处理。
- 屏保 V1：仅提供实际实现的系统屏保入口，不再要求自定义密码，也不展示未实现的自定义效果。
- 原“屏幕解锁”：名称改为“唤醒屏幕（非登录解锁）”，不收集账号密码，返回 `loginUnlockSupported:false`；本人仍需完成 Windows 登录。

目录修正保存在 `resources/catalog-overrides.json`，重新生成目录也会应用；不会恢复错误的下拉选项或密码字段。

安装仍只新增、不覆盖已有任务。需要升级本包旧任务时，使用 `upgrade --baseline <升级前的模板目录>`；仅升级仍匹配旧模板的任务，并备份原文件，用户修改过的任务会跳过。

输入法、音频、屏保、锁屏和远程桌面仍需要人工证据或专门环境，不自动执行高影响操作。输入法子进程实现和 `tsdiscon` 会话语义不在本轮 9 项修复范围内。

最新逐用例证据见 [REPORT.md](REPORT.md)，修复前证据见 [REPORT-before-fix.md](REPORT-before-fix.md)。