run_test: Run a test
In precommit: Pre-Commit Hooks

run_test

R Documentation

Run a test

Description

Tests for the executables used as pre-commit hooks via entrypoint in .pre-commit-config.yaml. Set's the env variable R_PRECOMMIT_HOOK_ENV to when running.

Usage

run_test(
  hook_name,
  file_name = hook_name,
  suffix = ".R",
  std_err = NULL,
  std_out = NULL,
  cmd_args = NULL,
  artifacts = NULL,
  file_transformer = function(files) files,
  env = character(),
  expect_success = is.null(std_err),
  read_only = FALSE
)

Arguments

`hook_name`	The name of the hook in `⁠inst/hooks/exported/⁠`, without file extension.
`file_name`	The file to test in `⁠tests/in⁠` (without extension). Can be a named vector of length one where the name is the target location relative to the temporary location and the value is the source of the file.
`suffix`	The suffix of `file_name`.
`std_err`	An expected error message. If no error is expected, this can be `NULL`. In that case, the `comparator` is applied.
`std_out`	The expected stdout message. If `NULL`, this check is omitted.
`cmd_args`	More arguments passed to the file. Pre-commit handles it as described here.
`artifacts`	Path with artifact files to copy to the temp directory root where the test is run. If you don't target the root, this can be a named vector of length one where the name is the target location relative to the temporary location and the value is the source of the file.
`file_transformer`	A function that takes the file names as input and is ran right before the hook script is invoked, returning the path to the files, potentially modified (if renamed). This can be useful if you need to make in-place modifications to the file, e.g. to test hooks that operate on `.Rprofile`. You can't have different names for different tests on that file because it must be called `.Rprofile` all the time. And R CMD check seems to remove hidden files, so we must also rename it. The transformation is also applied to a temp copy of the reference file before a comparison is made.
`env`	The environment variables to set with `base::system2()`.
`expect_success`	Whether or not an exit code 0 is expected. This can be derived from `std_err`, but sometimes, non-empty stderr does not mean error, but just a message.
`read_only`	If `TRUE`, then assert that no new files were created. Additionally, if `artifacts` are not `NULL`, then assert that hook did not modify the artifacts.

Details

Two potential outcomes of a hooks are pass or fail. This is reflected on the level of the executable: Fail means the executable fails or the file is changed. Pass means the executable succeeds and the file is unchanged. We check if the executable passes as follows:

If we expect success (by setting std_err to NULL), we make sure nothing was written to sterr and the file content does not change.
If we expect failure, it can be due to changed file or due to failed executable. To check for failed executable, we set std_err to the message we expect. To check changed file content, we set std_err to NA.