Test and talk about why id is awesome

R/deprecate.R

@@ -43,11 +43,14 @@
 #'   which will be converted to a [bulleted list][cli::cli_bullets].
 #'   By default, info bullets are used. Provide a named vectors to
 #'   override.
-#' @param id The id of the deprecation. A warning is issued only once
-#'   for each `id`. Defaults to the generated message, but you should
-#'   give a unique ID when the message in `details` is built
-#'   programmatically and depends on inputs, or when you'd like to
-#'   deprecate multiple functions but warn only once for all of them.
+#' @param id The id of the deprecation. A warning is issued only once for each
+#'   `id`. Defaults to the generated message, but you should provide a unique
+#'   `id` when the message in `details` is built programmatically and depends on
+#'   inputs, or when you'd like to deprecate multiple functions but warn only
+#'   once for all of them. Repeated calls to `deprecate_soft()` and
+#'   `deprecate_warn()` are also much faster if you supply an `id` because it
+#'   avoids spending time generating the message only to immediately exit if the
+#'   once per session warning has already been thrown before.
 #' @param env,user_env Pair of environments that define where `deprecate_*()`
 #'   was called (used to determine the package name) and where the function
 #'   called the deprecating function was called (used to determine if

tests/testthat/_snaps/deprecate.md

@@ -186,6 +186,18 @@
       Error:
       ! `details` must be a character vector, not a number.
 
+# lifecycle message is never generated when an `id` is supplied and we've already warned
+
+    Code
+      deprecate_soft(when = stop("when"), what = I("needed by signal_stage()"), with = stop(
+        "with"), details = stop("details"), env = stop("env"), id = "test")
+
+---
+
+    Code
+      deprecate_warn(when = stop("when"), what = I("needed by signal_stage()"), with = stop(
+        "with"), details = stop("details"), env = stop("env"), id = "test")
+
 # needs_warning works as expected
 
     Code

tests/testthat/test-deprecate.R

@@ -213,6 +213,41 @@ test_that("checks input types", {
   expect_snapshot(lifecycle_message("1", details = 1), error = TRUE)
 })
 
+test_that("lifecycle message is never generated when an `id` is supplied and we've already warned", {
+  # This is an important test for performance reasons. Supplying an `id` makes
+  # repeated calls to `deprecate_soft()` and `deprecate_warn()` much faster by
+  # avoiding message generation via `lifecycle_message()`.
+
+  on.exit(env_unbind(deprecation_env, c("test")))
+  local_options(lifecycle_verbosity = "default")
+
+  # Mock having already warned this session
+  env_poke(deprecation_env, "test", TRUE)
+
+  # These arguments are never touched again if we supply an `id`,
+  # we expect silence in the snapshot
+  expect_snapshot({
+    deprecate_soft(
+      when = stop("when"),
+      what = I("needed by signal_stage()"),
+      with = stop("with"),
+      details = stop("details"),
+      env = stop("env"),
+      id = "test"
+    )
+  })
+  expect_snapshot({
+    deprecate_warn(
+      when = stop("when"),
+      what = I("needed by signal_stage()"),
+      with = stop("with"),
+      details = stop("details"),
+      env = stop("env"),
+      id = "test"
+    )
+  })
+})
+
 # helpers -----------------------------------------------------------------
 
 test_that("env_inherits_global works for simple cases", {