Merge branch 'main' into issue_2106

Author: mcol

.Rbuildignore

@@ -20,3 +20,8 @@
 ^\.github/workflows/R\.yaml$
 ^\.github/workflows/pr-commands\.yaml$
 ^CRAN-SUBMISSION$
+^[\.]?air\.toml$
+^\.vscode$
+^\.git-blame-ignore-rev$
+^CLAUDE\.md$
+^\.claude$

.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(find:*)",
+      "Bash(R:*)"
+    ],
+    "deny": []
+  },
+  "$schema": "https://json.schemastore.org/claude-code-settings.json"
+}

.git-blame-ignore-rev

@@ -0,0 +1,8 @@
+# This file lists revisions of large-scale formatting/style changes so that
+# they can be excluded from git blame results.
+#
+# To set this file as the default ignore file for git blame, run:
+#   $ git config blame.ignoreRevsFile .git-blame-ignore-revs
+
+# https://github.com/r-lib/testthat/pull/2121
+13d17788e5d3a54fa83beed25e325703608f8b9f

.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+    "recommendations": [
+        "Posit.air-vscode"
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "[r]": {
+        "editor.formatOnSave": true,
+        "editor.defaultFormatter": "Posit.air-vscode"
+    }
+}

CLAUDE.md

@@ -0,0 +1,89 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## About This Project
+
+testthat is R's most popular unit testing framework, used by thousands of CRAN packages. It provides functions to make testing R code as fun and addictive as possible, with clear expectations, visual progress indicators, and seamless integration with R package development workflows.
+
+## Key Development Commands
+
+General advice:
+* When running R from the console, always run it with `--quiet --vanilla`
+* Always run `air format .` after generating code
+
+### Development tools
+
+- `devtools::test()` - Run all tests
+- `devtools::test_file("tests/testthat/test-filename.R")` - Run tests in a specific file
+- `devtools::load_all()` - Load package for development
+- `devtools::document()` - Generate documentation
+- `devtools::check()` - Run R CMD check
+- `devtools::install()` - Install package locally
+
+## Core Architecture
+
+### Main Components
+
+1. **Core Testing Functions** (`R/test-that.R`, `R/test-package.R`):
+   - `test_that()` - The fundamental testing function
+   - `test_local()`, `test_package()`, `test_check()` - Different ways to run test suites
+
+2. **Expectations** (`R/expect-*.R`):
+   - Modular expectation functions (equality, conditions, types, etc.)
+   - Each expectation type has its own file following the pattern `expect-[type].R`
+
+3. **Reporters** (`R/reporter*.R`):
+   - Different output formats for test results
+   - Object-oriented design with base `Reporter` class
+   - Includes check, debug, progress, summary, JUnit, TAP formats
+
+4. **Snapshot Testing** (`R/snapshot*.R`):
+   - Value snapshots, file snapshots, output snapshots
+   - Automatic management and comparison of expected outputs
+
+5. **Parallel Testing** (`R/parallel*.R`):
+   - Multi-core test execution
+   - Configuration via `Config/testthat/parallel: true` in DESCRIPTION
+
+6. **Mocking** (`R/mock*.R`, `R/mock2*.R`):
+   - Function mocking capabilities
+   - Both legacy (`mock.R`) and modern (`mock2*.R`) implementations
+
+### Key Design Patterns
+
+- **Editions**: testthat has different "editions" with varying behavior, controlled by `Config/testthat/edition`
+- **Reporters**: Extensible reporting system using R6 classes
+- **Lazy Evaluation**: Expectations use substitute() and lazy evaluation for better error messages
+- **C++ Integration**: Core functionality implemented in C++ for performance
+
+### File Organization
+
+- `R/` - All R source code, organized by functionality
+- `src/` - C++ source code and Makevars
+- `inst/include/testthat/` - C++ headers for other packages to use
+- `tests/testthat/` - Package's own comprehensive test suite
+- `vignettes/` - Documentation on testing concepts and workflows
+
+### Important Configuration
+
+The package uses several DESCRIPTION fields for configuration:
+- `Config/testthat/edition: 3` - Sets testthat edition
+- `Config/testthat/parallel: true` - Enables parallel testing
+- `Config/testthat/start-first` - Tests to run first in parallel mode
+
+### C++ Testing Infrastructure
+
+testthat provides C++ testing capabilities via Catch framework:
+- Headers in `inst/include/testthat/`
+- Test runner infrastructure in `src/test-runner.cpp`
+- Integration with R's testing system
+
+### Snapshot Testing Workflow
+
+- Snapshots stored in `tests/testthat/_snaps/`
+- Different snapshot types: values, files, output
+- Version-specific snapshots for different R versions
+- Use `testthat::snapshot_accept()` to update snapshots
+
+This codebase prioritizes backward compatibility, comprehensive testing, and clear, descriptive error messages to help R developers write better tests.

DESCRIPTION

@@ -17,23 +17,23 @@ BugReports: https://github.com/r-lib/testthat/issues
 Depends:
     R (>= 4.1.0)
 Imports:
-    brio (>= 1.1.3),
-    callr (>= 3.7.3),
-    cli (>= 3.6.1),
-    desc (>= 1.4.2),
-    evaluate (>= 1.0.1),
-    jsonlite (>= 1.8.7),
-    lifecycle (>= 1.0.3),
+    brio (>= 1.1.5),
+    callr (>= 3.7.6),
+    cli (>= 3.6.5),
+    desc (>= 1.4.3),
+    evaluate (>= 1.0.4),
+    jsonlite (>= 2.0.0),
+    lifecycle (>= 1.0.4),
     magrittr (>= 2.0.3),
     methods,
-    pkgload (>= 1.3.2.1),
+    pkgload (>= 1.4.0),
     praise (>= 1.0.0),
-    processx (>= 3.8.2),
-    ps (>= 1.7.5),
-    R6 (>= 2.5.1),
-    rlang (>= 1.1.1),
+    processx (>= 3.8.6),
+    ps (>= 1.9.1),
+    R6 (>= 2.6.1),
+    rlang (>= 1.1.6),
     utils,
-    waldo (>= 0.6.0),
+    waldo (>= 0.6.2),
     withr (>= 3.0.2)
 Suggests:
     covr,

NAMESPACE

@@ -119,6 +119,7 @@ export(expect_s3_class)
 export(expect_s4_class)
 export(expect_s7_class)
 export(expect_setequal)
+export(expect_shape)
 export(expect_silent)
 export(expect_snapshot)
 export(expect_snapshot_error)
@@ -144,29 +145,27 @@ export(is.expectation)
 export(is_a)
 export(is_checking)
 export(is_equivalent_to)
-export(is_false)
 export(is_identical_to)
 export(is_informative_error)
 export(is_less_than)
 export(is_more_than)
-export(is_null)
 export(is_parallel)
 export(is_snapshot)
 export(is_testing)
-export(is_true)
 export(it)
 export(local_edition)
 export(local_mock)
 export(local_mocked_bindings)
+export(local_on_cran)
 export(local_reproducible_output)
 export(local_snapshotter)
 export(local_test_context)
 export(local_test_directory)
 export(make_expectation)
-export(matches)
 export(mock_output_sequence)
 export(new_expectation)
 export(not)
+export(pass)
 export(prints_text)
 export(quasi_label)
 export(run_cpp_tests)
@@ -229,5 +228,6 @@ import(rlang)
 importFrom(R6,R6Class)
 importFrom(brio,readLines)
 importFrom(brio,writeLines)
+importFrom(lifecycle,deprecated)
 importFrom(magrittr,"%>%")
 useDynLib(testthat, .registration = TRUE)

NEWS.md

@@ -1,11 +1,27 @@
 # testthat (development version)
 
+* `expect_*()` functions consistently and rigorously check their inputs (#1754). 
+* `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 placese (#1852, #2032).
+* `try_again()` is now publicised. The first argument is now the number of retries, not tries (#2050).
+* `vignette("custom-expectations)` has been overhauled to make it much clearer how to create high-quality expectations (#2113, #2132, #2072).
+* `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).
+* `expect_snapshot_value()` can now handle expressions that generate `-` (#1678) or zero length atomic vectors (#2042).
+* `expect_matches()` failures should be a little easier to read (#2135).
+* New `local_on_cran(TRUE)` allows you to simulate how your tests will run on CRAN (#2112).
+* `expect_no_*()` now executes the entire code block, rather than stopping at the first message or warning (#1991).
+* `expect_no_failures()` and `expect_no_successes()` are now deprecated as `expect_success()` now test for no failures and `expect_failure()` tests for no successes (#)
+* New `pass()` function to use in place of `succeed()` (#2113).
+* `expectation()` is now a combination of `new_expectation()` and `exp_signal()` (#2125).
+* `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_edition()` now gives a useful error for bad values (#1547).
 * testthat now requires R 4.1.
 * `expect_s4_class()` now supports unquoting (@stibu81, #2064).
 * `it()` now finds the correct evaluation environment in more cases (@averissimo, #2085).
 * Fixed an issue preventing compilation from succeeding due to deprecation / removal of `std::uncaught_exception()` (@kevinushey, #2047).
 * 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)
 * `skip_on_os()` gains an option `"emscripten"` of the `os` argument to skip tests on Emscripten (@eitsupi, #2103).
+* New expectation, `expect_shape()`, for testing the shape (i.e., the `length()`, `nrow()`, `ncol()`, or `dim()`), all in one place (#1423, @michaelchirico).
 
 # testthat 3.2.3
 

R/auto-test.R

@@ -1,24 +1,18 @@
 #' Watches code and tests for changes, rerunning tests as appropriate.
 #'
+#' @description
+#' `r lifecycle::badge("superseded")`
+#'
 #' The idea behind `auto_test()` is that you just leave it running while
 #' you develop your code.  Every time you save a file it will be automatically
 #' tested and you can easily see if your changes have caused any test
-#'  failures.
+#' failures.
 #'
 #' The current strategy for rerunning tests is as follows:
 #'
 #' - if any code has changed, then those files are reloaded and all tests
 #'   rerun
 #' - otherwise, each new or modified test is run
-#'
-#' In the future, `auto_test()` might implement one of the following more
-#' intelligent alternatives:
-#'
-#' - Use codetools to build up dependency tree and then rerun tests only
-#'   when a dependency changes.
-#' - Mimic ruby's autotest and rerun only failing tests until they pass,
-#'   and then rerun all tests.
-#
 #' @seealso [auto_test_package()]
 #' @export
 #' @param code_path path to directory containing code
@@ -27,10 +21,14 @@
 #' @param env environment in which to execute test suite.
 #' @param hash Passed on to [watch()]. When FALSE, uses less accurate
 #'   modification time stamps, but those are faster for large files.
-#' @keywords debugging
-auto_test <- function(code_path, test_path, reporter = default_reporter(),
-                      env = test_env(),
-                      hash = TRUE) {
+#' @keywords internal
+auto_test <- function(
+  code_path,
+  test_path,
+  reporter = default_reporter(),
+  env = test_env(),
+  hash = TRUE
+) {
   reporter <- find_reporter(reporter)
   code_path <- normalizePath(code_path)
   test_path <- normalizePath(test_path)
@@ -63,16 +61,17 @@ auto_test <- function(code_path, test_path, reporter = default_reporter(),
   watch(c(code_path, test_path), watcher, hash = hash)
 }
 
-#' Watches a package for changes, rerunning tests as appropriate.
-#'
 #' @param pkg path to package
 #' @export
 #' @param reporter test reporter to use
 #' @param hash Passed on to [watch()].  When FALSE, uses less accurate
 #'   modification time stamps, but those are faster for large files.
-#' @keywords debugging
-#' @seealso [auto_test()] for details on how method works
-auto_test_package <- function(pkg = ".", reporter = default_reporter(), hash = TRUE) {
+#' @rdname auto_test
+auto_test_package <- function(
+  pkg = ".",
+  reporter = default_reporter(),
+  hash = TRUE
+) {
   reporter <- find_reporter(reporter)
 
   path <- pkgload::pkg_path(pkg)
@@ -86,7 +85,12 @@ auto_test_package <- function(pkg = ".", reporter = default_reporter(), hash = T
   # Start by loading all code and running all tests
   withr::local_envvar("NOT_CRAN" = "true")
   pkgload::load_all(path)
-  test_dir(test_path, package = package, reporter = reporter$clone(deep = TRUE), stop_on_failure = FALSE)
+  test_dir(
+    test_path,
+    package = package,
+    reporter = reporter$clone(deep = TRUE),
+    stop_on_failure = FALSE
+  )
 
   # Next set up watcher to monitor changes
   watcher <- function(added, deleted, modified) {
@@ -106,7 +110,11 @@ auto_test_package <- function(pkg = ".", reporter = default_reporter(), hash = T
       cat("Changed code: ", paste0(basename(code), collapse = ", "), "\n")
       cat("Rerunning all tests\n")
       pkgload::load_all(path, quiet = TRUE)
-      test_dir(test_path, package = package, reporter = reporter$clone(deep = TRUE))
+      test_dir(
+        test_path,
+        package = package,
+        reporter = reporter$clone(deep = TRUE)
+      )
     } else if (length(tests) > 0) {
       # If test changes, rerun just that test
       cat("Rerunning tests: ", paste0(basename(tests), collapse = ", "), "\n")
@@ -115,7 +123,7 @@ auto_test_package <- function(pkg = ".", reporter = default_reporter(), hash = T
         test_dir = test_path,
         test_package = package,
         test_paths = tests,
-        env = env, 
+        env = env,
         reporter = reporter$clone(deep = TRUE)
       )
     }