custom-expectation vignette: `is.expectation` and `new_expectation` unexplained and unused

[math-mcshane]

I'm currently working on some custom expectations for autogradeR at Jenny's recommendation during her workshop a few weeks ago, which involved taking a look at vignette("custom-expecatation") and then remembering it was actually in development.

I noticed that while R/expectations.R starts by pointing to vignette("custom-expecatation") for more explanation, is.expectation and new_expecation (which exist in the released version, 3.2.3), are not mentioned in the under-construction vignette (feels like a good time to mention?).

Out of curiosity, I wanted to see whether anything is currently an expectation (I had written some expectations and wanted to try it as a self-check, spooked myself for a minute, and then took a deeper look). From a regex assuming consistent naming in testthat, it looks like no expectations in testthat are currently "considered" expectations. Reprex using testthat v3.2.3 (sorry if in dev version):

library(testthat)
# Example expectation (ish) isn't an expectation:
expect_length |> is.expectation()
#> [1] FALSE

# testthat expectations (at least, most-ish)
expectations_testthat = ls("package:testthat") |> 
  stringr::str_subset(pattern = "expect") |>
  as.list() |> 
  purrr::set_names() |> 
  lapply(FUN = \(x) paste0("testthat::", x) |> str2expression() |> eval())

# They're all functions (sanity check)
are_functions = sapply(X = expectations_testthat, FUN = is.function)
all(are_functions)
#> [1] TRUE

# But none are of class "expectation"
are_expectations = sapply(X = expectations_testthat, FUN = is.expectation)
any(are_expectations)
#> [1] FALSE

^{Created on 2025-10-08 with reprex v2.1.1}

Relatedly, it looks like testing the class of an expectation is not useful ATM (but might be if class applied)

library(testthat)
# won't work, although is.expectation uses inherits?
try(expect_s3_class(expect_length, class = "expectation"))
#> Error : `expect_length` is not an S3 object

# only base type ATM, so can't test class
sloop::otype(expect_length)
#> [1] "base"
test_that("Can test this", expect_type(expect_length, type = "closure"))
#> Test passed 😀

^{Created on 2025-10-08 with reprex v2.1.1}

Tagging @hadley because he's been writing this vignette.

[hadley]

new_expectation(), expectation(), and is.expectation() are all internal implementation details that you shouldn't need to know about to write your own expectation. Do you think there's a way to make that more clear in their docs? The first paragraph is supposed to suggest "you don't need to know this, instead read the vignette".

[math-mcshane]

I think I would replace "For advanced use only" with "Internal implementation details that you shouldn't need to know about to write your own expectation." The former suggests the reader could, with enough study, figure out how to use those functions to write a self-check for their expectations. You could also just substitute "advanced" with "internal" if users aren't meant to use it, ever.

Is is.expectation currently used in the testthat? I see that it's briefly defined, but no published expectations resolve as TRUE (see initial comment).

If I'm at the R console typing testthat::expect (and skimming through the object options that match), these are functions that I and many other users would be drawn to. is. functions are some of my favorite. If it's not in use, lifecycle "experimental" or whichever tag y'all have for this? Is there a lifecycle "internal" tag?

[hadley]

is.expectation() and new_expectation() is about expectation conditions, not expectation functions. Neither are used very frequently, but equally don't seem to cause much confusion, so I don't think it's worth removing. (Especially since my capacity for more revdep breaks is now very low). I'll improve the starting paragraph along the lines you suggest.

[math-mcshane]

Hi @hadley -- changes in 558c788 do clear it up for me, personally! Thanks!