lanyuanxiaoyao
0d709c7681
- toImportSpecifier() 使用 replaceAll 替代 split(sep).join，明确 ESM import specifier 语义 - 增加 relativePath 可选参数支持测试注入 Windows relative 语义 - 重写 Windows 路径测试，使用 node:path.win32 显式模拟而非依赖当前平台 sep - 更新 DEVELOPMENT.md 记录构建 code generation 约定 - 同步 static-asset-embedding 和 windows-test-compat spec 新增要求
70 lines
3.8 KiB
Markdown
70 lines
3.8 KiB
Markdown
# Capability: windows-test-compat
|
||
|
||
## Purpose
|
||
|
||
确保测试在 Windows、macOS、Linux 平台上的兼容性，包括文件句柄释放后的目录清理重试机制和跨平台命令测试约定。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: 测试临时目录清理 SHALL 支持重试
|
||
|
||
使用 SQLite 数据库的测试 SHALL 在 `afterAll` 中使用带重试的目录删除机制，确保在 Windows 上文件句柄未及时释放时不会导致测试失败。
|
||
|
||
#### Scenario: Windows 上 SQLite 文件句柄延迟释放
|
||
|
||
- **WHEN** 测试在 Windows 上运行，`store.close()` 后立即尝试删除临时目录
|
||
- **THEN** 删除操作 SHALL 自动重试（最多 3 次，间隔 200ms），直到成功或耗尽重试次数
|
||
|
||
### Requirement: 命令检测器测试 SHALL 使用跨平台命令
|
||
命令检测器的测试 SHALL 使用 `bun -e` 脚本替代所有系统命令（包括 `true`、`false`、`sleep`、`bash`、`echo`、`yes | head`），确保测试在 Windows、macOS、Linux 三平台上行为一致。
|
||
|
||
#### Scenario: 进程退出码 0
|
||
- **WHEN** 测试需要一个正常退出的命令
|
||
- **THEN** 测试 SHALL 使用 `bun -e "process.exit(0)"` 替代 `true`
|
||
|
||
#### Scenario: 进程退出码非零
|
||
- **WHEN** 测试需要一个失败退出的命令
|
||
- **THEN** 测试 SHALL 使用 `bun -e "process.exit(1)"` 替代 `false`
|
||
|
||
#### Scenario: stdout 输出
|
||
- **WHEN** 测试需要一个输出文本到 stdout 的命令
|
||
- **THEN** 测试 SHALL 使用 `bun -e "console.log('text')"` 替代 `echo text`
|
||
|
||
#### Scenario: stderr 输出
|
||
- **WHEN** 测试需要一个输出文本到 stderr 的命令
|
||
- **THEN** 测试 SHALL 使用 `bun -e "process.stderr.write('error\n')"` 替代 `bash -c "echo error >&2"`
|
||
|
||
#### Scenario: 长时间运行命令
|
||
- **WHEN** 测试需要一个超时场景的长时间运行命令
|
||
- **THEN** 测试 SHALL 使用 `bun -e "await Bun.sleep(10000)"` 替代 `sleep 10`
|
||
|
||
#### Scenario: 大量输出
|
||
- **WHEN** 测试需要一个产生大量输出的命令
|
||
- **THEN** 测试 SHALL 使用 `bun -e "process.stdout.write('y\n'.repeat(N))"` 替代 `bash -c "yes | head -N"`
|
||
|
||
#### Scenario: 验证非 shell 模式下特殊字符不被展开
|
||
- **WHEN** 通过 `Bun.spawn` 执行 `bun -e "console.log('*')"` 并检查 stdout 包含 `*`
|
||
- **THEN** 测试 SHALL 在 Windows、macOS 和 Linux 上均返回 `matched: true`
|
||
|
||
### Requirement: probes.example.yaml 使用跨平台示例
|
||
probes.example.yaml 中的 cmd 类型示例 SHALL 使用跨平台命令（如 `bun -e "..."`、`bun --version`），不使用 Unix 专属命令（如 `uname`、`ls /tmp`、`date`）。
|
||
|
||
#### Scenario: 示例命令跨平台可执行
|
||
- **WHEN** 用户在 Windows、macOS 或 Linux 上直接使用 probes.example.yaml 中的 cmd 示例
|
||
- **THEN** 所有 cmd 示例 SHALL 能正常执行，不依赖平台特定命令
|
||
|
||
#### Scenario: ICMP checker 测试使用 platform 注入
|
||
- **WHEN** 在 Windows 上运行 ICMP checker 测试，mock 的 stdout 为 Unix 格式
|
||
- **THEN** 测试 SHALL 通过 `new IcmpChecker("linux")` 构造 checker 实例，使 parsePingOutput 使用 Unix 解析器，确保测试在所有平台上通过
|
||
|
||
### Requirement: 路径语义测试 SHALL 显式模拟目标平台
|
||
路径相关跨平台测试 SHALL 使用显式平台路径工具、依赖注入或等价测试 seam 表达目标平台语义，MUST NOT 依赖当前运行平台的 `path.sep` 伪装其他平台行为。
|
||
|
||
#### Scenario: 在非 Windows 平台验证 Windows 路径分隔符
|
||
- **WHEN** 测试需要验证 Windows 文件系统路径中的反斜杠会被转换为平台无关输出
|
||
- **THEN** 测试 SHALL 使用 `node:path.win32` 或等价注入方式生成 Windows relative path，并断言输出不包含 `\\`
|
||
|
||
#### Scenario: 验证 import specifier 输出
|
||
- **WHEN** 测试验证构建脚本生成的 ESM import specifier
|
||
- **THEN** 测试 SHALL 断言输出使用 `/` 分隔，MUST NOT 使用 `path.sep` 禁止当前平台的合法 `/` 字符
|