---
title: "runExamplesWrapper"
author: Barry Zeeberg [aut, cre]
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{runExamplesWrapper}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
Wrapper for *run_examples()*
Capture, Process, and Archive Errors in Package Examples
Barry
Zeeberg
barryz2013@gmail.com
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).
{width=100%}
*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.