R语言测试与文档编写全攻略

### R 语言测试与文档编写全攻略 #### 1. 测试文件与对象的管理 在测试过程中，我们会遇到存储在 `tests/testthat/fixtures/` 目录下的静态测试文件，例如： ```plaintext │ │ └── useful_thing2.rds │ ├── helper.R │ ├── setup.R │ └── (all the test files) └── testthat.R ``` 同时，还有配套的 R 脚本 `make-useful-things.R`。需要注意的是，在数据分析中，很少有脚本只运行一次，对测试对象（如 `useful_thing1.rds`）的改进和迭代是不可避免的。因此，我们强烈建议保存用于创建测试对象的 R 代码，以便在需要时重新创建这些对象。 #### 2. 构建自定义测试工具 在测试代码中，我们虽然鼓励为了使测试更清晰而对重复代码有一定的容忍度，但重复程度仍需控制。以下是一些构建自定义测试工具的方法： ##### 2.1 测试内部定义的辅助函数 以 `stringr` 包中的 `str_trunc()` 函数测试为例，最初的测试代码存在大量重复： ```R # from stringr (hypothetically) test_that("truncations work for all sides", { expect_equal( str_trunc("This string is moderately long", width = 20, side = "right"), "This string is mo..." ) expect_equal( str_trunc("This string is moderately long", width = 20, side = "left"), "...s moderately long" ) expect_equal( str_trunc("This string is moderately long", width = 20, side = "center"), "This stri...ely long" ) }) ``` 为了减少重复，我们可以在测试内部定义一个超局部辅助函数 `trunc()`： ```R # from stringr (actually) test_that("truncations work for all sides", { trunc <- function(direction) str_trunc( "This string is moderately long", direction, width = 20 ) expect_equal(trunc("right"), "This string is mo...") expect_equal(trunc("left"), "...s moderately long") expect_equal(trunc("center"), "This stri...ely long") }) ``` 这种超局部辅助函数在使每个期望的重要业务能放在一行时特别有用，可使期望结果的对比更清晰。但要注意，应谨慎使用此技术，因为辅助函数也可能引入新的错误，所以要保持其简短和简单。 ##### 2.2 自定义期望函数 当需要更复杂的辅助函数时，我们可以考虑创建自定义期望函数。例如 `usethis` 包中的两个简单自定义期望函数： ```R expect_usethis_error <- function(...) { expect_error(..., class = "usethis_error") } expect_proj_file <- function(...) { expect_true(file_exists(proj_path(...))) } ``` `expect_usethis_error()` 用于检查错误是否具有 `"usethis_error"` 类，`expect_proj_file()` 是 `file_exists()` 的简单包装，用于在当前项目中搜索文件。创建一个合适的自定义期望函数相对复杂，如果想了解更多，可以参考 “Custom expectations” 小插曲。 ##### 2.3 testthat 运行时的可用信息 `testthat` 在运行时会提供一些特定信息： - 环境变量 `TESTTHAT` 会被设置为 `"true"`，可以使用 `testthat::is_testing()` 作为快捷方式： ```R is_testing <- function() { Sys.getenv("TESTTHAT") } ``` - 被测试的包可以通过环境变量 `TESTTHAT_PKG` 获取，`testthat::testing_package()` 是其快捷方式： ```R testing_package <- function() { Sys.getenv("TESTTHAT_PKG") } ``` 在某些情况下，如果不想对 `testthat` 产生运行时依赖，可以将这些函数的源代码直接嵌入到你的包中。 #### 3. 应对测试难题 尽管我们已经掌握了很多测试技术，但仍会遇到难以编写测试的情况，以下是一些应对方法： ##### 3.1 跳过测试 在某些情况下，可能无法执行测试，例如没有网络连接或没有必要的凭证。此时，可以使用 `testthat::skip()` 跳过测试。以下是一个自定义跳过函数的示例： ```R skip_if_no_api() <- function() { if (api_una ```