运行拼图测试

运行 jigsawR 测试套件并解读结果。

适用场景

• 修改包中任何 R 源代码后
• 添加新拼图类型或功能后
• 提交更改前验证无破坏
• 调试特定测试失败

输入

• 必需：测试范围（

  full

  、

  filtered

  或

  single

  ）
• 可选：过滤模式（用于 filtered 模式，如

  "snic"

  、

  "rectangular"

  ）
• 可选：指定测试文件路径（用于 single 模式）

步骤

第 1 步：选择测试范围

范围	使用时机	耗时
完整	提交前、重大更改后	~2-5 分钟
过滤	处理某个拼图类型时	~30 秒
单文件	调试特定测试文件	~10 秒

预期结果： 根据当前工作流选择测试范围：提交前选完整套件，处理特定拼图类型时选过滤，调试单个测试时选单文件。

失败处理： 如果不确定选哪个范围，默认使用完整套件。耗时更长但能捕获跨类型回归。

第 2 步：创建并执行测试脚本

完整套件：

创建脚本文件（如

/tmp/run_tests.R

）：

devtools::test()

R_EXE="/mnt/c/Program Files/R/R-4.5.0/bin/Rscript.exe"
cd /mnt/d/dev/p/jigsawR && "$R_EXE" -e "devtools::test()"

按模式过滤：

"$R_EXE" -e "devtools::test(filter = 'snic')"

单文件：

"$R_EXE" -e "testthat::test_file('tests/testthat/test-snic-puzzles.R')"

预期结果： 测试输出含通过/失败/跳过计数。

失败处理：

• 不要使用

  --vanilla

  标志；renv 需要

  .Rprofile

  来激活
• 如果 renv 报错，先运行

  renv::restore()

• 对于因退出码 5 失败的复杂命令，写入脚本文件替代

第 3 步：解读结果

查找汇总行：

[ FAIL 0 | WARN 0 | SKIP 7 | PASS 2042 ]

• PASS：通过的测试
• FAIL：失败的测试（需要排查）
• SKIP：跳过的测试（通常因缺少可选包如

  snic

  ）
• WARN：测试中的警告（需审查但非阻塞）

预期结果： 汇总行已解析，识别出 PASS、FAIL、SKIP 和 WARN 计数。干净测试运行应 FAIL = 0。

失败处理： 如果汇总行不可见，测试运行器可能在完成前崩溃。检查汇总行上方的 R 级错误。如果输出被截断，重定向到文件：

"$R_EXE" -e "devtools::test()" > test_results.txt 2>&1

。

第 4 步：排查失败

如果测试失败：

1. 阅读失败消息——包含文件、行号及预期与实际值
2. 检查是新故障还是已有的
3. 对于断言失败，阅读测试和被测函数
4. 对于错误失败，检查函数签名是否变更

# 使用详细输出运行失败的测试
"$R_EXE" -e "testthat::test_file('tests/testthat/test-failing.R', reporter = 'summary')"

预期结果： 每个失败测试的根因已识别。失败要么是真正的回归（代码需修复），要么是测试环境问题（缺少依赖、路径问题）。

失败处理： 如果失败消息不清楚，在测试中添加

browser()

或

print()

语句，使用

testthat::test_file()

重新运行以交互调试。

第 5 步：验证跳过原因

缺少可选依赖时跳过测试是正常的：

• snic

  包的测试通过

  skip_if_not_installed("snic")

  跳过
• 要求特定操作系统的测试通过

  skip_on_os()

  跳过
• 仅 CRAN 的跳过通过

  skip_on_cran()

  实现

确认跳过原因合理，不是在掩盖真实故障。

预期结果： 所有跳过都有合理原因（可选依赖未安装、平台特定跳过、仅 CRAN 跳过）。没有跳过在掩盖实际测试失败。

失败处理： 如果某个跳过看起来可疑，临时移除

skip_if_*()

调用并运行测试，看它是通过还是暴露隐藏的失败。

验证清单

• 所有测试通过（FAIL = 0）
• 无意外警告
• 跳过计数与预期匹配（仅可选依赖跳过）
• 测试数量未减少（没有测试被意外删除）

常见问题

• 使用

  --vanilla

  ：会破坏 renv 激活。jigsawR 中绝不使用。
• 复杂的

  -e

  字符串：shell 转义问题导致退出码 5。使用脚本文件。
• 过时的包状态：如果更改了影响 NAMESPACE 的代码，测试前运行

  devtools::load_all()

  或

  devtools::document()

  。
• 缺少测试依赖：某些测试需要 suggested 包。检查

  DESCRIPTION

  的 Suggests 字段。
• 并行测试问题：如果测试互相干扰，使用

  testthat::test_file()

  顺序运行。

相关技能

• generate-puzzle

  — 生成拼图以验证行为是否与测试一致

• add-puzzle-type

  — 新类型需要全面的测试套件

• write-testthat-tests

  — 编写 R 测试的通用模式

• validate-piles-notation

  — 独立测试 PILES 解析