Test fixtures/undoing temporary file in package documentation

[arangaca]

I'm developing a package that can inject yaml data in the yaml header of a Quarto document. I've some examples of this in the documentation of my package. The examples consist in making a temporary file, injecting the data and printing the output (see below).

I know that making temporary things usually implies destroying or undoing them later. I knew about on.exit() but only recently heard of test fixtures, and although I understand the benefit of using them, I'm not quite sure yet to understand all the disadvantages and consequences of not using them.

From what I understood from Self-cleaning test fixtures, test fixtures are usually meant to be used internally, in function environments, not so much outside of them. And as the name suggests, they are essentially useful for testing.

Does this mean that when creating e.g. a temporary file to serve as an example in the documentation (either vignette or function example), it's not necessary to destroy it after the example?

Here's a simplified version of the example I use in on of the vignettes. Does it make sense to undo the temporary file or use e.g. withr::local_tempfile() here?

```{r, include = FALSE}
# make a temp file assigned to the variable `tmp`
```

Blah blah…

```{r, echo = FALSE, comment = ""}
cat(readr::read_file(tmp))

to_yaml(data, tmp)

cat(readr::read_file(tmp))
```

[maelle]

Yes you should also clean after examples, as otherwise you might get told about this by R CMD check (which can be a big disadvantage if submitting the package to CRAN for example) r-source/check.R at 52a4c579b50e1b5ebb051416be9702f9142dd272 · wch/r-source · GitHub So using withr as you mention, is also a good idea in examples and vignettes, and it doesn't add much work.

withr can also be used for various things in package code (if that link doesn't work for you, it might be linked to not having the GitHub advanced search feature).

[arangaca]

Thanks for the reply.

So if I take my example again, would you do e.g.:

```{r, include = FALSE}
tmp <- withr::local_tempfile(
  lines = "---\ntitle: test\n---\n\nLorem ipsum",
  fileext = ".qmd"
)
```

Blah blah…

```{r, echo = FALSE, comment = ""}
cat(readr::read_file(tmp))

to_yaml(data, tmp)

cat(readr::read_file(tmp))
```

In this case, does the local_tempfile() defer in the global environment?

[maelle]

I'd imagine it will defer to the knit environment (if that's a thing) but it's worth trying (I had never noticed the lines argument of withr::local_tempfile()! Thank you!)

[arangaca]

The thing is that executing withr::local_tempfile() in the global environment throws the following message:

Setting global deferred event(s).
i These will be run:
  * Automatically, when the R session ends.
  * On demand, if you call `withr::deferred_run()`.
i Use `withr::deferred_clear()` to clear them without executing.

I'm not so sure if I should then use the function alone or paired with withr::deferred_run() at the end of my example.

[maelle]

oh you mean in actual @examples in the manual page? Right, in that case you might need to use withr::with_tempfile() instead (or \dontrun{}) -- sorry if I misunderstood your question.

[arangaca]

I actually have it in function examples (@examples), rmarkdown chunks (in README and vignettes) and unit tests. But for the latter, that was fairly obvious to use it here.

Will use with_tempfile() in function examples then. Thanks!

So to recap:

• with_tempfile() in @examples
• local_tempfile() in unit tests and rmarkdown chunks

Got it right?

[maelle]

I'd say so? But let's see if someone else chimes in

Regarding the examples I said with_tempfile() because I saw it's the approach used in withr' docs!

[arangaca]

@maelle

Regarding the examples I said with_tempfile() because I saw it's the approach used in withr' docs!

That's a good enough reason for me. That's how I've been learning programming, by looking at how people who know things do it. Haven't found any examples of this in code chunks though, that's why I'm lost haha.