testthat v2.0.1

• Fix failing tests with devtools 2.0.0

testthat 2.0.0

Breaking API changes

• "Can't mock functions in base packages": You can no longer use with_mock()
  to mock functions in base packages, because this no longer works in
  R-devel due to changes with the byte code compiler. I recommend using
  mockery or mockr instead.

• The order of arguments to expect_equivalent() and expect_error() has
  changed slightly as both now pass ... on another function. This reveals
  itself with a number of different errors, like:

  • 'what' must be a character vector
  • 'check.attributes' must be logical
  • 'tolerance' should be numeric
  • argument is not interpretable as logical
  • threw an error with unexpected class
  • argument "quo" is missing, with no default
  • argument is missing, with no default

  If you see one of these errors, check the number, order, and names of
  arguments to the expectation.

• "Failure: (unknown)". The last release mistakenly failed to test
  bare expectations not wrapped inside test_that(). If you see "(unknown)"
  in a failure message, this is a failing expectation that you previously
  weren't seeing. As well as fixing the failure, please also wrap inside
  a test_that() with an informative name.

• "Error: the argument has already been evaluated": the way in which
  expectations now need create labels has changed, which caused a couple
  of failures with unusual usage when combined with Reduce, lapply(),
  and Map(). Avoid these functions in favour of for loops. I also recommend
  reading the section below on quasiquotation support in order to create more
  informative failure messages.

Expectations

New and improved expectations

• expect_condition() works like expect_error() but captures any
  condition, not just error conditions (#621).

• expect_error() gains a class argument that allows you to make an
  assertion about the class of the error object (#530).

• expect_reference() checks if two names point to the same object (#622).

• expect_setequal() compares two sets (stored in vectors), ignoring
  duplicates and differences in order (#528).

New and improved skips

• skip_if() makes it easy to skip a test when a condition is true (#571).
  For example, use skip_if(getRversion() <= 3.1) to skip a test in older
  R versions.

• skip_if_translated() skips tests if you're running in an locale
  where translations are likely to occur (#565). Use this to avoid
  spurious failures when checking the text of error messages in non-English
  locales.

• skip_if_not_installed() gains new minimum_version argument (#487, #499).

Known good values

We have identified a useful family of expectations that compares the results of an expression to a known good value stored in a file. They are designed to be use in conjunction with git so that you can see what precisely has changed, and revert it if needed.

• expect_known_output() replaces expect_output_file(), which has
  been soft-deprecated. It now defaults to update = TRUE and warn, rather
  than failing on the first run. It gains a print argument to automatically
  print the input (#627). It also sets the width option to 80 to ensure
  consistent output across environments (#514)

• expect_known_value() replaces expect_equal_to_reference(), which
  has been soft-deprecated. It gains an update argument defaulting to TRUE.
  This changes behaviour from the previous version, and soft-deprecated
  expect_equal_to_reference() gets update = FALSE.

• expect_known_failure() stored and compares the failure message from
  an expectation. It's a useful regression test when developing informative
  failure messges for your own expectations.

Quasiquotation support

All expectations can now use unquoting (#626). This makes it much easier to generate informative failure messages when running tests in a for loop.

For example take this test:

f <- function(i) if (i > 3) i * 9 else i * 10

for (i in 1:5) {
  expect_equal(f(i), i * 10)
}

When it fails, you'll see the message Error: `f(i)` not equal to `i * 10` .
That's hard to diagnose because you don't know which iteration caused the problem!

for (i in 1:5) {
  expect_equal(f(!!i), !!(i * 10))
}

If you unquote the values using !!, you get the failure message `f(4L)` not equal to 40.. This is much easier to diagnose! See ?quasi_label() for more details.

(Note that this is not tidy evaluation per se, but is closely related. At this time you can not unquote quosures.)

New features

Setup and teardown

• New setup() and teardown() functions allow you to run at the start and
  end of each test file. This is useful if you want to pair cleanup code
  with the code that messes up state (#536).

• Two new prefixes are recognised in the test/ directory. Files starting
  with setup are run before tests (but unlike helpers are not run in
  devtools::load_all()). Files starting with teardown are run after all
  tests are completed (#589).

Other new features

• All files are now read and written as UTF-8 (#510, #605).

• is_testing() allows you to tell if your code is being run inside a
  testing environment (#631). Rather than taking a run-time dependency on testthat
  you may want to inline the function into your own package:

  is_testing <- function() {
    identical(Sys.getenv("TESTTHAT"), "true")
  }

  It's frequently useful to combine with interactive().

New default reporter

A new default reporter, ReporterProgress, produces more aesthetically pleasing output and makes the most important information available upfront (#529). You can return to the previous default by setting option(testthat.default_reporter = "summary").

Reporters

• Output colours have been tweaked to be consistent with clang:
  warnings are now in magenta, and skips in blue.

• New default_reporter() and check_reporter() which returns the default
  reporters for interactive and check environments (#504).

• New DebugReporter that calls a better version of recover() in case of
  failures, errors, or warnings (#360, #470).

• New JunitReporter generates reports in JUnit compatible format.
  (#481, @lbartnik; #640, @nealrichardson; #575)

• New LocationReporter which just prints the location of every expectation.
  This is useful for locating segfaults and C/C++ breakpoints (#551).

• SummaryReporter recieved a number of smaller tweaks

  • Aborts testing as soon the limit given by the option
    testthat.summary.max_reports (default 10) is reached (#520).

  • New option testthat.summary.omit_dots = TRUE hides the progress dots
    speeding up tests by a small amount (#502).

  • Bring back random praise and encouragement which I accidentally dropped
    (#478).

• New option testthat.default_check_reporter, defaults to "check".
  Continuous Integration system can set this option before evaluating
  package test sources in order to direct test result details to known
  location.

• All reporters now accept a file argument on initialization. If provided,
  reporters will write the test results to that path. This output destination
  can also be controlled with the option testthat.output_file
  (#635, @nealrichardson).

Deprecated functions

• is_null() and matches() have been deprecated because they conflict
  with other functions in the tidyverse (#523).

Minor improvements and bug fixes

• Updated Catch to 1.9.6. testthat now understands and makes use of the package
  routine registration mechanism required by CRAN with R >= 3.4.0.
  (@kevinushey)

• Better reporting for deeply nested failures, limiting the stack trace to the
  first and last 10 entries (#474).

• Bare expectations notify the reporter once again. This is achieved by running
  all tests inside test_code() by default (#427, #498). This behaviour can be
  overridden by setting wrap = FALSE in test_dir() and friends (#586).

• auto_test() and auto_test_package() provide hash parameter to enable
  switching to faster, time-stamp-based modification detection
  (#598, @katrinleinweber). auto_test_package() works correctly on windows
  (#465).

• capture_output_lines() is now exported (#504).

• compare.character() works correctly for vectors of length > 5 (#513, @brodieG)

• compare.default() gains a max_diffs argument and defaults to printing
  out only the first 9 differences (#538).

• compare.numeric() respects check.attributes() so expect_equivalent()
  correctly ignores attributes of numeric vectors (#485).

• Output expectations (expect_output(), expect_message(),
  expect_warning(), and expect_silent()) all invisibly return the first
  argument to be consistent with the other expectations (#615).

• expect_length() works with any object that has a length method, not
  just vectors (#564, @nealrichardson)

• expect_match() now accepts explicit perl and fixed arguments, and adapts
  the failure message to the value of fixed. This also affects other expectations
  that forward to expect_match(), like expect_output(), expect_message(),
  expect_warning(), and expect_error().

• expect_match() escapes special regular expression characters when printing
  (#522, @jimhester).

• expect_message(), expect_warning() and expect_error() produce clearer
  failure messages.

• find_test_scripts() only looks for \.[rR] in the extension
  (#492, @brodieG)

• test_dir(), test_package(), test_check() unset the R_TESTS env var
  (#603)

• test_examples() now works ...

testthat 1.0.2

• Ensure 'std::logic_error()' constructed with 'std::string()'
  argument, to avoid build errors on Solaris.

testthat 1.0.1

• New expect_output_file() to compare output of a function
  with a text file, and optionally update it (#443, @krlmlr).
• Properly scoped use + compilation of C++ unit testing code using
  Catch to gcc and clang only, as Catch includes code that does
  not strictly conform to the C++98 standard. (@kevinushey)
• Fixed an out-of-bounds memory access when routing Catch output
  through Rprintf(). (@kevinushey)
• Ensure that unit tests run on R-oldrel (remove use of dir.exists()).
  (@kevinushey)
• Improved overriding of calls to exit() within Catch, to ensure
  compatibility with GCC 6.0. (@krlmlr)
• Hardened formatting of difference messages, previously the presence of %
  characters could affect the output (#446, @krlmlr).
• Fixed errors in expect_equal() when comparing numeric vectors with and
  without attributes (#453, @krlmlr).
• auto_test() and auto_test_package() show only the results of the
  current test run and not of previously failed runs (#456, @krlmlr).

testthat 1.0.0

Breaking changes

The expectation() function now expects an expectation type (one of "success", "failure", "error", "skip", "warning") as first argument. If you're creating your own expectations, you'll need to use expect() instead (#437).

New expectations

The expectation system got a thorough overhaul (#217). This primarily makes it easier to add new expectations in the future, but also included a thorough review of the documentation, ensuring that related expectations are documented together, and have evocative names.

One useful change is that most expectations invisibly return the input object. This makes it possible to chain together expectations with magrittr:

factor("a") %>% 
  expect_type("integer") %>% 
  expect_s3_class("factor") %>% 
  expect_length(1)

(And to make this style even easier, testthat now re-exports the pipe, #412).

The exception to this rule are the expectations that evaluate (i.e.
for messages, warnings, errors, output etc), which invisibly return NULL. These functions are now more consistent: using NA will cause a failure if there is a errors/warnings/mesages/output (i.e. they're not missing), and will NULL fail if there aren't any errors/warnings/mesages/output. This previously didn't work for expect_output() (#323), and the error messages were confusing with expect_error(..., NA) (#342, @nealrichardson + @krlmlr, #317).

Another change is that expect_output() now requires you to explicitly print the output if you want to test a print method: expect_output("a", "a") will fail, expect_output(print("a"), "a") will succeed.

There are six new expectations:

• expect_type() checks the type of the object (#316),
  expect_s3_class() tests that an object is S3 with given class,
  expect_s4_class() tests that an object is S4 with given class (#373).
  I recommend using these more specific expectations instead of the
  more general expect_is().
• expect_length() checks that an object has expected length.
• expect_success() and expect_failure() are new expectations designed
  specifically for testing other expectations (#368).

A number of older features have been deprecated:

• expect_more_than() and expect_less_than() have been deprecated. Please
  use expect_gt() and expect_lt() instead.
• takes_less_than() has been deprecated.
• not() has been deprecated. Please use the explicit individual forms
  expect_error(..., NA) , expect_warning(.., NA) and so on.

Expectations are conditions

Now all expectations are also conditions, and R's condition system is used to signal failures and successes (#360, @krlmlr). All known conditions (currently, "error", "warning", "message", "failure", and "success") are converted to expectations using the new as.expectation(). This allows third-party test packages (such as assertthat, testit, ensurer, checkmate, assertive) to seamlessly establish testthat compatibility by issuing custom error conditions (e.g., structure(list(message = "Error message"), class = c("customError", "error", "condition"))) and then implementing as.expectation.customError(). The assertthat package contains an example.

Reporters

The reporters system class has been considerably refactored to make existing reporters simpler and to make it easier to write new reporters. There are two main changes:

• Reporters classes are now R6 classes instead of Reference Classes.
• Each callbacks receive the full context:
  • add_results() is passed context and test as well as the expectation.
  • test_start() and test_end() both get the context and test.
  • context_start() and context_end() get the context.
• Warnings are now captured and reported in most reporters.
• The reporter output goes to the original standard output and is not affected by sink() and expect_output() (#420, @krlmlr).
• The default summary reporter lists all warnings (#310), and all skipped
  tests (@krlmlr, #343). New option testthat.summary.max_reports limits
  the number of reports printed by the summary reporter. The default is 15
  (@krlmlr, #354).
• MinimalReporter correct labels errors with E and failures with F (#311).
• New FailReporter to stop in case of failures or errors after all tests
  (#308, @krlmlr).

Other

• New functions capture_output(), capture_message(), and
  capture_warnings() selectively capture function output. These are
  used in expect_output(), expect_message() and expect_warning()
  to allow other types out output to percolate up (#410).
• try_again() allows you to retry code multiple times until it succeeds
  (#240).
• test_file(), test_check(), and test_package() now attach testthat so
  all testing functions are available.
• source_test_helpers() gets a useful default path: the testthat tests
  directory. It defaults to the test_env() to be consistent with the
  other source functions (#415).
• test_file() now loads helpers in the test directory before running
  the tests (#350).
• test_path() makes it possible to create paths to files in tests/testthat
  that work interactively and when called from tests (#345).
• Add skip_if_not() helper.
• Add skip_on_bioc() helper (@thomasp85).
• make_expectation() uses expect_equal().
• setup_test_dir() has been removed. If you used it previously, instead use
  source_test_helpers() and find_test_scripts().
• source_file() exports the function testthat uses to load files from disk.
• test_that() returns a logical that indicates if all tests were successful
  (#360, @krlmlr).
• find_reporter() (and also all high-level testing functions) support a vector
  of reporters. For more than one reporter, a MultiReporter is created
  (#307, @krlmlr).
• with_reporter() is used internally and gains new argument
  start_end_reporter = TRUE (@krlmlr, 355).
• set_reporter() returns old reporter invisibly (#358, @krlmlr).
• Comparing integers to non-numbers doesn't raise errors anymore, and falls
  back to string comparison if objects have different lengths. Complex numbers
  are compared using the same routine (#309, @krlmlr).
• compare.numeric() and compare.chacter() recieved another overhaul. This
  should improve behaviour of edge cases, and provides a strong foundation for
  further work. Added compare.POSIXt() for better reporting of datetime
  differences.
• expect_identical() and is_identical_to() now use compare() for more
  detailed output of differences (#319, @krlmlr).
• Added Catch v1.2.1 for unit testing of C++ code.
  See ?use_catch() for more details. (@kevinushey)

testthat 0.11.0

• Handle skipped tests in the TAP reporter (#262).
• New expect_silent() ensures that code produces no output, messages,
  or warnings (#261).
• New expect_lt(), expect_lte(), expect_gt() and expect_gte() for
  comparison with or without equality (#305, @krlmlr).
• expect_output(), expect_message(), expect_warning(), and
  expect_error() now accept NA as the second argument to indicate that
  output, messages, warnings, and errors should be absent (#219).
• Praise gets more diverse thanks to the praise package, and you'll now
  get random encouragment if your tests don't pass.
• testthat no longer muffles warning messages. If you don't want to see them
  in your output, you need to explicitly quiet them, or use an expectation that
  captures them (e.g. expect_warning()). (#254)
• Use of tests in inst/tests is formally deprecated. Please move them into
  tests/testthat instead (#231).
• expect_match() now encodes the match, as well as the output, in the
  expectation message (#232).
• expect_is() gives better failure message when testing multiple inheritance,
  e.g. expect_is(1:10, c("glm", "lm")) (#293).
• Corrected argument order in compare.numeric() (#294).
• comparison() constructure now checks its arguments are the correct type and
  length. This bugs a bug where tests failed with an error like "values must be
  length 1, but FUN(X[[1]]) result is length 2" (#279).
• Added skip_on_os(), to skip tests on specified operating systems
  (@kevinushey).
• Skip test that depends on devtools if it is not installed (#247, @krlmlr)
• Added skip_on_appveyor() to skip tests on Appveyor (@lmullen).
• compare() shows detailed output of differences for character vectors of
  different length (#274, @krlmlr).
• Detailed output from expect_equal() doesn't confuse expected and actual
  values anymore (#274, @krlmlr).

testthat 0.10.0

• Failure locations are now formated as R error locations.
• Deprecated library_if_available() has been removed.
• test (test_dir(), test_file(), test_package(), test_check()) functions
  now return a testthat_results object that contains all results, and can be
  printed or converted to data frame.
• test_dir(), test_package(), and test_check() have an added ...
  argument that allows filtering of test files using, e.g., Perl-style regular
  expressions,or fixed character filtering. Arguments in ... are passed to
  grepl() (@leeper).
• test_check() uses a new reporter specifically designed for R CMD check.
  It displays a summary at the end of the tests, designed to be <13 lines long
  so test failures in R CMD check display something more useful. This will
  hopefully stop BDR from calling testthat a "test obfuscation suite" (#201).
• compare() is now documented and exported. Added a numeric method so when
  long numeric vectors don't match you'll see some examples of where the
  problem is (#177). The line spacing in compare.character() was
  tweaked.
• skip_if_not_installed() skips tests if a package isn't installed (#192).
• expect_that(a, equals(b)) style of testing has been soft-deprecated.
  It will keep working, but it's no longer demonstrated any where, and new
  expectations will only be available in expect_equal(a, b) style. (#172)
• Once again, testthat suppresses messages and warnings in tests (#189)
• New test_examples() lets you run package examples as tests. Each example
  counts as one expectation and it succeeds if the code runs without errors
  (#204).
• New succeed() expectation always succeeds.
• skip_on_travis() allows you to skip tests when run on Travis CI.
  (Thanks to @mllg)
• colourise() was removed. (Colour is still supported, via the crayon
  package.)
• Mocks can now access values local to the call of with_mock (#193, @krlmlr).
• All equality expectations are now documented together (#173); all
  matching expectations are also documented together.

testthat 0.9.1

testthat 0.9.1

• Bump R version dependency

testthat 0.9

testthat 0.9

New features

• BDD: testhat now comes with an initial behaviour driven development (BDD)
  interface. The language is similiar to RSpec for Ruby or Mocha for JavaScript.
  BDD tests read like sentences, so they should make it easier to understand
  the specification of a function. See ?describe() for further information
  and examples.
• It's now possible to skip() a test with an informative message - this is
  useful when tests are only available under certain conditions, as when
  not on CRAN, or when an internet connection is available (#141).
• skip_on_cran() allows you to skip tests when run on CRAN. To take advantage
  of this code, you'll need either to use devtools, or run
  Sys.setenv(NOT_CRAN = "true"))
• Simple mocking: with_mock() makes it easy to temporarily replace
  functions defined in packages. This is useful for testing code that relies
  on functions that are slow, have unintended side effects or access resources
  that may not be available when testing (#159, @krlmlr).
• A new expectation, expect_equal_to_reference() has been added. It
  tests for equality to a reference value stored in a file (#148, @jonclayden).

Minor improvements and bug fixes

• auto_test_package() works once more, and now uses devtools::load_all()
  for higher fidelity loading (#138, #151).
• Bug in compare.character() fixed, as reported by Georgi Boshnakov.
• colourise() now uses option testthat.use_colours (default: TRUE). If it
  is FALSE, output is not colourised (#153, @mbojan).
• is_identical_to() only calls all.equal() to generate an informative
  error message if the two objects are not identical (#165).
• safe_digest() uses a better strategy, and returns NA for directories
  (#138, #146).
• Random praise is renabled by default (again!) (#164).
• Teamcity reporter now correctly escapes output messages (#150, @windelinckx).
  It also uses nested suites to include test names.

Deprecated functions

• library_if_available() has been deprecated.

testthat 0.8.1

• Better default environment for test_check() and test_package() which
  allows S4 class creation in tests
• compare.character() no longer fails when one value is missing.