"Custom expectations" vignette should discuss "trace_env"

[MichaelChirico]

In ?expect, we see:

testthat/man/expect.Rd

Lines 32 to 33 in 30f5b11

	\code{trace_env}. You'll generally only need to set this if you're wrapping
	an expectation inside another function.}

That's exactly the situation I'm in -- trying to understand why some tests do, some tests don't give a good $trace in the error report. It looks like it's down to my use of expect() inside another function (expect_lint()).

But there's no hint on how to proceed here -- the page also exhorts us to "See vignette("custom-expectation") for details.", but the supplied vignette does not cover this topic at all:

https://testthat.r-lib.org/articles/custom-expectation.html

[hadley]

You need to set trace_env() if you use a helper function that calls fail()/expect() inside your expect_ function. This ensures that the backtrace on error doesn't include unnecessary calls.

We should document this in the new fail() too.

[hadley]

A few notes:

i.e. use it when you have multiple expectations that share some code, and want to extract out a helper. Helper should take a trace_env = parent.frame() argument.

Open question: Should helper call pass() or assume that the caller will do that? If not, probably should be named starting with fail_ or similar. Or maybe assert() ? If helper does, call will need to return() after calling the helper. See expect_length_impl() for concrete example.

And tie in with discussion of calling pass() once per expectation.