When and when not to use \donttest and \dontrun in R package development?

Question

So I'm submitting my package to CRAN and I am confused about when to wrap examples in \donttest or \dontrun. I have a few different cases:

1. Examples that return data frames, etc.
2. Examples that return static figures generated via ggplot2
3. Examples that return JavaScript figures generated via plotly
4. Examples that read or write to the file system (e.g. importing data, and writing spreadsheets)
5. Examples that run Shiny apps

I have worked out that for (1) I should never wrap in \donttest or \dontrun. For (5) I should wrap the whole function in if(interactive()){}.

That still leaves cases 2-5 where I am not sure if I should leave the examples wrapped or un-wrapped. I am guessing that plots are ok but not sure about reading/writing files. Any hints or directing me to somewhere where it is clearly explained is much appreciated. Thanks.

Answer 1

Generally speaking you should avoid those markers unless you need them. You'll need one of them if the example does something that is likely to fail, because CRAN will see the failure as an error in your package. You would also use them if they do something that is dangerous (e.g. creating files in a user's home directory, deleting files other than tempfiles you've created, sending email, etc.)

The \dontrun marker is stronger. In the past examples wrapped in that didn't even need to be syntactically correct, though I think that might have changed. If a user runs the example() function, they won't run that code.

Use \donttest on examples that take too long to run and violate CRAN's 5 second limit. A user running example() will run those, but the basic tests of your package won't. Sometimes CRAN will test the \donttest code, so it has to work. (Generally if you can it's better to give examples that run quickly and don't hit the 5 second limit.)

For your specific examples, none need any wrapping as long as they are fast enough and you can arrange that all file system changes happen in the R session temp directory.