Run a test — run_test • precommit

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.

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.