# Run Puzzle Tests

> 通过 WSL R 执行运行 jigsawR 测试套件。支持完整套件、按模式过滤或单文件运行。 解读通过/失败/跳过计数并定位失败测试。绝不使用 --vanilla 标志（renv 需要 .Rprofile 激活）。适用于修改 R 源代码后、添加新拼图类型或功能后、提交更改前 验证无破坏，以及调试特定测试失败时。

- Skill: `pjt222/run-puzzle-tests-4` (Agent Skill)
- Install (CLI): `npx get-skill add pjt222/run-puzzle-tests-4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pjt222/run-puzzle-tests-4/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: pjt222 (https://skillmd.com/u/pjt222)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/pjt222/run-puzzle-tests-4

---


# 运行拼图测试

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

## 适用场景

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

## 输入

- **必需**：测试范围（`full`、`filtered` 或 `single`）
- **可选**：过滤模式（用于 filtered 模式，如 `"snic"`、`"rectangular"`）
- **可选**：指定测试文件路径（用于 single 模式）

## 步骤

### 第 1 步：选择测试范围

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

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

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

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

**完整套件**：

创建脚本文件（如 `/tmp/run_tests.R`）：

```r
devtools::test()
```

```bash
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()"
```

**按模式过滤**：

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

**单文件**：

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

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

**失败处理：**
- 不要使用 `--vanilla` 标志；renv 需要 `.Rprofile` 来激活
- 如果 renv 报错，先运行 `renv::restore()`
- 对于因退出码 5 失败的复杂命令，写入脚本文件替代

### 第 3 步：解读结果

查找汇总行：

```text
[ 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. 对于错误失败，检查函数签名是否变更

```bash
# Run just the failing test with verbose output
"$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 解析

