R: Expectations: is the output or the value equal to a known...

expect_known_output {testthat} | R Documentation

## 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.
`...` | For `expect_equal()` and `expect_equivalent()`, passed on `compare()`, for `expect_identical()` passed on to `identical()`. Used to control the details of the comparison.
`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 this will print the result, ensuring that the output of printing the object is included in the overall output
`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.

### 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)

[Package testthat version 2.3.2 Index]