runExamplesWrapper

Barry Zeeberg [aut, cre]

2025-02-21

Wrapper for run_examples()
Capture, Process, and Archive Errors in Package Examples

 

 

Barry Zeeberg



Motivation

The function run_examples() within the devtools package allows batch execution of all of the examples within a given package. This is much more convenient than testing each example manually. However, a major inconvenience is that if an error is encountered, the program stops and does not complete testing the remaining examples. Also, there is not a systematic record of the results, namely which package functions had no examples, which had examples that failed, and which had examples that succeeded.

The goal of the current package runExamplesWrapper is to provide the missing functionality.

The key is that run_examples() processes examples in alphabetical order, so if we can detect the most recent failure, we know the name of the next one that still needs to be tested.

The detailed strategy involves embedding run_examples() within a loop that

executes *run_examples()* within a *try()* statement

captures the output of *run_examples()*

parses the output to determine the name of the failing function example (if any)

restarting *run_examples()* with the *start* parameter set to the alphabetically next function example

The return value is a vector specifying each function example as either “GOOD”, “BAD”, or “MIA” (Figure 1).

Figure 1. Result of running RunExamples()
Figure 1. Result of running RunExamples()


RunExamples() is used in conjunction with my upcoming (expected Feb/March 2025) package retrieveFunctionsExamples to provide the information on which package function examples are still missing or incorrect, and need to be supplied. That package simplifies and partially automates management of manual page examples in multi-package projects.