More news polishing

Author: hadley

NEWS.md

@@ -3,86 +3,61 @@
 ## Lifecycle changes
 
 * testthat now requires R 4.1.
-* `expect_snapshot(binary)` is now fully deprecated; it was soft deprecated in v3.0.3.
-* `is_null()`/`matches()` deprecated in 2.0.0 (2017-12-19) and `is_true()`/`is_false()` deprecated in 2.1.0 (2019-04-23) have been removed (#2109).
- * `local_mock()` and `with_mock()` have been made defunct because they are no longer permitted in R 4.5.
-* `test_files(wrap)` has now been removed; it was deprecated in v3.0.0.
-
-## New expectations
-
-* The failure messages for all `expect_` functions have been rewritten to first state what was expected and then what was actually received (#2142). They also functions consistently and rigorously check their inputs (#1754).
-* Expectations now consistently return the value of the first argument, regardless of whether the expectation succeeds or fails (the only exception is `expect_message()` and friends which will return the condition). This shouldn't affect existing tests, but will make failures clearer when you chain together multiple expectations (#2246).
-* When running a test interactively, testthat now reports the number of successes. The results should also be more useful if you are using nested tests.
-
-* New `expect_all_equal()`, `expect_all_true()`, and `expect_all_false()` are a family of expectations that checks that every element of a vector has the same value. Compared to using `expect_true(all(...))` they give better failure messages (#1836, #2235).
-* New `expect_disjoint()` to check for the absence of values (@stibu81, #1851).
-* New `expect_r6_class()` (#2030).
-* New `expect_shape()` for testing the shape (i.e., the `nrow()`, `ncol()`, or `dim()`) (#1423, @michaelchirico).
-
-* `test_that()`, `describe()`, and `it()` can now be arbitrarily nested. Each component will skip only if it and its subtests don't contain any expectations. The interactive stop reporter has been fixed so it doesn't duplicate failures. (#2063, #2188). `describe()`, `it()`, and `test_that()` now have a shared stack of descriptions so that if you nest any inside of each other, any resulting failures will show you the full path.
-
-* `vignette("custom-expectations")` has been overhauled to make it much clearer how to create high-quality expectations (#2113, #2132, #2072).
-  * New `pass()` function to use in place of `succeed()` (#2113).
-  * `expectation()` is now a combination of `new_expectation()` and `exp_signal()` (#2125).
-  * `expect_no_failures()` and `expect_no_successes()` are now deprecated as `expect_success()` also tests for the absence of failures and `expect_failure()` tests for the absence of successes.
-
-* On CRAN, `test_that()` now automatically skips if a package is not installed (#1585). Practically, this means that you no longer need to check that suggested packages are installed. (We don't check the installation of suggested packages in the tidyverse because we think it has limited payoff, but other styles advise differently.)
+* `expect_snapshot(binary)`, soft deprecated in 3.0.3 (2021-06-16), is now fully deprecated.
+* `is_null()`/`matches()`, deprecated in 2.0.0 (2017-12-19), and `is_true()`/`is_false()`, deprecated in 2.1.0 (2019-04-23), have been removed (#2109).
+* `local_mock()` and `with_mock()`, deprecated in 3.0.0 (2020-10-31), are now defunct. They technique that made them work is no longer permitted in R 4.5.0.
+* `test_files(wrap)`, deprecated in 3.0.0 (2020-10-31) has now been removed.
+
+## Expectations and tests
+
+* All `expect_` functions have had their failure messages rewritten. They now all state what was expected, what was actually received, and, if possible, clearly illustrate the difference (#2142). They also consistently check that their inputs are the correct type (#1754). They consistently return the value of the first argument, regardless of whether the expectation succeeds or fails (the only exception is `expect_message()` and friends which return the condition). This shouldn't affect existing tests, but will make failures clearer when you chain together multiple expectations (#2246).
+* It's now much easier to create custom expectations, thanks to an overhauled `vignette("custom-expectations")` (#2113, #2132, #2072), a new `pass()` function to use in place of `succeed()` (#2113), and revisions to how `expectation()` works (#2125). `expect_no_failures()` and `expect_no_successes()` are now deprecated as now `expect_success()` also tests for the absence of failures and `expect_failure()` tests for the absence of successes.
+* Tests (i.e. `test_that()`, `describe()`, and `it()` calls) can now be arbitrarily nested with a shared stack of descriptions so that the failures can show the full path through all subtests. Skips in subtests are now correctly scoped (#2007), and each subtest and will skip if and only if it and its subtests don't contain any expectations.
+* On CRAN, `test_that()` will automatically skips if a package is not installed (#1585). Practically, this means that you no longer need to check that suggested packages are installed. (We already didn't check the installation of suggested packages in the tidyverse because we think it has limited payoff, but other styles advise differently.)
+* When running a test interactively, testthat now reports the number of successes and failures. If you're using nested tests, the results should be more useful and you will no longer see duplicated failures (#2063, #2188). 
+* New `expect_all_equal()`, `expect_all_true()`, and `expect_all_false()` check that every element of a vector has the same value (#1836, #2235), giving better error messages than `expect_true(all(...))`.
+* New `expect_disjoint()` expects values to to be absent (@stibu81, #1851).
+* New `expect_r6_class()` expects an R6 objects (#2030).
+* New `expect_shape()` expects a specific shape (i.e., `nrow()`, `ncol()`, or `dim()`) (#1423, @michaelchirico).
 
 ## Other new features
 
 * New `local_mocked_s3_method()`, `local_mocked_s4_method()`, and `local_mocked_r6_class()` allow you to mock S3 and S4 methods and R6 classes (#1892, #1916)
 * New `local_on_cran(TRUE)` allows you to simulate how your tests will run on CRAN (#2112).
 * `test_dir()`, `test_file()`, `test_package()`, `test_check()`, `test_local()`, `source_file()` gain a `shuffle` argument that uses `sample()` to randomly reorder the top-level expressions in each test file (#1942). This random reordering surfaces dependencies between tests and code outside of any test, as well as dependencies between tests. This helps you find and eliminate unintentional dependencies.
-* `try_again()` is now publicised. The first argument is now the number of retries, not tries (#2050).
-* New `skip_unless_r()` to skip running tests on unsuitable versions of R, e.g. `skip_unless_r(">= 4.1.0")` to skip tests that require, say, `...names` (@MichaelChirico, #2022)
-* New `SlowReporter` makes it easier to find the slowest tests in your package. The easiest way to run it is with `devtools::test(reporter = "slow")` (#1466).
-* New `vignette("mocking")` explains mocking in detail (#1265).
-* New `vignette("challenging-functions")` provides an index to other documentation organised by testing challenges (#1265).
-
-## Snapshotting
-
-New features:
-
-* `snapshot_reject()` rejects all modified snapshots by deleting the `.new` variants (#1923).
-* `snapshot_download_gh()` makes it easy to get snapshots off GitHub and into your local package (#1779).
-
-Behaviour changes:
-
-* `expect_snapshot()` no longer skips on CRAN, as that skips the rest of the test. Instead it just returns, neither succeeding nor failing (#1585).
+* `try_again()` is now publicised, making it easier to test flaky code. We changed the first argument to represent the number of retries, not tries (#2050).
+* New `skip_unless_r()` skip tests on unsuitable versions of R. It has a convenient sytnax so you can use, e.g., `skip_unless_r(">= 4.1.0")` to skip tests that require `...names()` (@MichaelChirico, #2022).
+* New `snapshot_reject()` rejects all modified snapshots by deleting the `.new` variants (#1923), and `snapshot_download_gh()` makes it easy to get snapshots off GitHub and into your local package (#1779).
 * `expect_snapshot()` and friends will now fail when creating a new snapshot on CI. This is usually a signal that you've forgotten to run it locally before committing (#1461).
-* In `R CMD check`, snapshots now only advise on how to resolve failures once (#2207).
-
-Bug fixes:
-
-* The last snapshot is no longer lost if the snapshot file is missing the final newline (#2092). It's easy to accidentally remove this because there are two trailing new lines in snapshot files and many editors will automatically remove if you touch the file.
-* `snapshot_accept(test)` now works when the test file name contains `.` (#1669).
-* `expect_snapshot_file()` now clearly errors if the `path` doesn't exist (#2191), or has been used alreaday (#1592) considers `.json` to be a text file (#1593), and shows differences for text files (#1593).
-* `expect_snapshot()` and `expect_snapshot_file()` hints now include the path to the package, if it's not the current working directory (#1577).
-* `expect_snapshot_value()` can now handle expressions that generate `-` (#1678) or zero length atomic vectors (#2042).
-* `snapshot_review()` includes a reject button and only displays the file navigation and the skip button if there are multiple files to review (#2025). It now passes `...` on to `shiny::runApp()` (#1928).
+* New `SlowReporter` makes it easier to find the slowest tests in your package. You can run it with `devtools::test(reporter = "slow")` (#1466).
+* New `vignette("mocking")` explains mocking in detail (#1265).
+* New `vignette("challenging-functions")` provides an index to other documentation organised by various challenges (#1265).
 
 ## Minor improvements and bug fixes
 
 * Interrupting a test now prints the test name. This makes it easier to tell where a very slow test might be hanging (#1464).
-* Parallel testing:
-  * `ParallelProgressReporter` now respects `max_failures` (#1162)
-  * Test files with syntax errors are no longer silently ignored (#1360).
-* BDD:
-  * `it()` now finds the correct evaluation environment in more cases (@averissimo, #2085).
-  * `describe()` now correctly scopes `skip()` (#2007).
 * Fixed an issue preventing compilation from succeeding due to deprecation / removal of `std::uncaught_exception()` (@kevinushey, #2047).
 * `expect_lt()`, `expect_gt()`, and friends have a refined display that is more likely to display the correct number of digits and shows you the actual values compared (#2006). They have a better display for non-numeric data (@stibu81, #2268).
 * `expect_matches()` failures should be a little easier to read (#2135, #2181).
 * `expect_no_*()` now executes the entire code block, rather than stopping at the first message or warning (#1991).
 * `expect_named()` now gives more informative errors (#2091).
 * `expect_s4_class()` now supports unquoting (@stibu81, #2064).
+* `expect_snapshot()` no longer loses the last snapshot if file is missing the final newline (#2092). It's easy to accidentally remove this because there are two trailing new lines in snapshot files and many editors will automatically remove one if you touch the file.
+* `expect_snapshot()` on reports how to resolve failures once when running inside `R CMD check`.
+* `expect_snapshot()` no longer skips on CRAN, as that skips the rest of the test. Instead it just returns, neither succeeding nor failing (#1585).
+* `expect_snapshot()` and `expect_snapshot_file()` hints now include the path to the package, if it's not the current working directory (#1577).
+* `expect_snapshot_file()` now clearly errors if the `path` doesn't exist (#2191), or has been used alreaday (#1592). It now considers `.json` to be a text file (#1593), and shows differences for text files in the console (#1593).
+* `expect_snapshot_value()` can now handle expressions that generate `-` (#1678) or zero length atomic vectors (#2042).
 * `expect_vector()` fails, instead of erroring, if `object` is not a vector (@plietar, #2224).
-* `JunitReporter()` no longer fails with `"no applicable method for xml_add_child"` for warnings outside of tests (#1913). Additionally, warnings now save their backtraces. `JunitReporter()` strips ANSI escapes in more places (#1852, #2032).
+* `JunitReporter()` no longer fails with `"no applicable method for xml_add_child"` for warnings outside of tests (#1913). Additionally, warnings now save their backtraces and `JunitReporter()` strips ANSI escapes in more places (#1852, #2032).
 * `local_edition()` now gives a useful error for bad values (#1547).
-* `set_state_inspector()` gains `tolerance` argument and ignores minor FP differences by default (@mcol, #2237).
+* `ParallelProgressReporter` now respects `max_failures` (#1162), and test files with syntax errors are no longer silently ignored (#1360).
 * `test_file(desc = ...)` (i.e. test filtering) no longer loses snapshot results (#2066), works with `it()`, and can now be character vector in order to recursively filter subtests (#2118).
 * `test_that()` no longer warns about the absence of `{}` since it no longer seems to be necessary.
+* `set_state_inspector()` gains `tolerance` argument and ignores minor FP differences by default (@mcol, #2237).
 * `skip_on_os()` gains an option `"emscripten"` of the `os` argument to skip tests on Emscripten (@eitsupi, #2103).
+* `snapshot_accept(test)` now works when the test file name contains `.` (#1669).
+* `snapshot_review()` includes a reject button and only displays the file navigation and the skip button if there are multiple files to review (#2025). It now passes `...` on to `shiny::runApp()` (#1928).
 
 # testthat 3.2.3