testthat: expect_known_output – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

expect_known_output

Expectations: is the output or the value equal to a known good value?

Description

For complex printed output and objects, it is often challenging to describe exactly what you expect to see. expect_known_value() and expect_known_output() provide a slightly weaker guarantee, simply asserting that the values have not changed since the last time that you ran them.

Usage

expect_known_output(
  object,
  file,
  update = TRUE,
  ...,
  info = NULL,
  label = NULL,
  print = FALSE,
  width = 80
)

expect_known_value(
  object,
  file,
  update = TRUE,
  ...,
  info = NULL,
  label = NULL,
  version = 2
)

expect_known_hash(object, hash = NULL)

Arguments

`object`	Computation and value to compare it to. Both arguments supports limited unquoting to make it easier to generate readable failures within a function or for loop. See quasi_label for more details.
`file`	File path where known value/output will be stored.
`update`	Should the file be updated? Defaults to `TRUE`, with the expectation that you'll notice changes because of the first failure, and then see the modified files in git.
`...`	Passed on to `waldo::compare()`.
`info`	Extra information to be included in the message. This argument is soft-deprecated and should not be used in new code. Instead see alternatives in quasi_label.
`label`	Used to customise failure messages. For expert use only.
`print`	If `TRUE` and the result of evaluating `code` is visible, print the result using `testthat_print()`.
`width`	Number of characters per line of output. This does not inherit from `getOption("width")` so that tests always use the same output width, minimising spurious differences.
`version`	The serialization format version to use. The default, 2, was the default format from R 1.4.0 to 3.5.3. Version 3 became the default from R 3.6.0 and can only be read by R versions 3.5.0 and higher.
`hash`	Known hash value. Leave empty and you'll be informed what to use in the test output.

Details

These expectations should be used in conjunction with git, as otherwise there is no way to revert to previous values. Git is particularly useful in conjunction with expect_known_output() as the diffs will show you exactly what has changed.

Note that known values updates will only be updated when running tests interactively. R CMD check clones the package source so any changes to the reference files will occur in a temporary directory, and will not be synchronised back to the source package.

3rd edition

expect_known_output() and friends are deprecated in the 3rd edition; please use expect_snapshot_output() and friends instead.

Examples

tmp <- tempfile()

# The first run always succeeds
expect_known_output(mtcars[1:10, ], tmp, print = TRUE)

# Subsequent runs will succeed only if the file is unchanged
# This will succeed:
expect_known_output(mtcars[1:10, ], tmp, print = TRUE)

## Not run: 
# This will fail
expect_known_output(mtcars[1:9, ], tmp, print = TRUE)

## End(Not run)

testthat

Unit Testing for R

v3.0.2

MIT + file LICENSE

Authors

Hadley Wickham [aut, cre], RStudio [cph, fnd], R Core team [ctb] (Implementation of utils::recover())

Initial release