unitize
Unitize an R Test Script
Turn standard R scripts into unit tests by storing the expressions therein along with the results of their evaluation.
Usage
unitize(test.file = NULL, store.id = NULL,
state = getOption("unitizer.state"), pre = NULL, post = NULL,
history = getOption("unitizer.history.file"),
interactive.mode = interactive(), force.update = FALSE,
auto.accept = character(0L))review(store.id = NULL)
unitize_dir(test.dir = NULL, store.ids = filename_to_storeid,
pattern = "^[^.].*\\.[Rr]$", state = getOption("unitizer.state"),
pre = NULL, post = NULL, history = getOption("unitizer.history.file"),
interactive.mode = interactive(), force.update = FALSE,
auto.accept = character(0L))
Arguments
- test.file
path to the file containing tests, if supplied path does not match an actual system path,
unitizer
will try to infer a possible path. If NULL, will look for a file in the “tests/unitizer” package folder if it exists, or in “.” if it does not. Seeinfer_unitizer_location
) for details.- store.id
if NULL (default),
unitizer
will select a directory based on thetest.file
name by replacing.[rR]
with.unitizer
. You can also specify a directory name, or pass any object that has a definedget_unitizer
method which allows you to specify non-standardunitizer
storage mechanisms (seeget_unitizer
). Finally, you can pass an actualunitizer
object if you are usingreview
; seestore.ids
forunitize_dir
- state
character(1L) one of
c("prisitine", "default", "basic", "off", "safe")
, an environment, or a state object produced bystate
orin_pkg
; modifies howunitizer
manages aspects of session state that could affect test evaluation, including the parent evaluation environment. For more details seeunitizerState
documentation andvignette("unitizer_reproducible_tests")
- pre
NULL, or a character vector pointing to files and/or directories. If a character vector, then any files referenced therein will be sourced, and any directories referenced therein will be scanned non-recursively for visible files ending in ".r" or ".R", which are then also sourced. If NULL, then
unitizer
will look for a directory named "_pre" in the directory containing the first test file and will treat it as if you had specified it inpre
. Any objects created by those scripts will be put into a parent environment for all tests. This provides a mechanism for creating objects that are shared across different test files, as well as loading shared packages. Unlike objects created during test evaluation, any objects created here will not be stored in theunitizer
so you will have not direct way to check whether these objects changed acrossunitizer
runs. Additionally, typingls
from the review prompt will not list these objects.- post
NULL, or a character vector pointing to files and/or directories. See
pre
. If NULL will look for a directory named "_post" in the directory containing the first test file. Scripts are run just prior to exitingunitizer
.post
code will be run in an environment with the environment used to runpre
as the parent. This means that any objects created inpre
will be available topost
, which you can use to your advantage if there are some things you do inpre
you wish to undo inpost
. Keep in mind thatunitizer
can manage most aspects of global state, so you should not need to use this parameter to unload packages, remove objects, etc. See details.- history
character(1L) path to file to use to store history generated during interactive unitizer session; the default is an empty string, which leads to
unitizer
using a temporary file, set to NULL to disable history capture.- interactive.mode
logical(1L) whether to run in interactive mode ( request user input when needed) or not (error if user input is required, e.g. if all tests do not pass).
- force.update
logical(1L) if TRUE will give the option to re-store a unitizer after re-evaluating all the tests even if all tests passed. you can also toggle this option from the unitizer prompt by typing
O
, thoughforce.update=TRUE
will force update irrespective of what you do withO
at the prompt- auto.accept
character(X) ADVANCED USE ONLY: YOU CAN EASILY DESTROY YOUR
unitizer
WITH THIS; whether to auto-accept tests without prompting, use values inc("new", "failed", "deleted", "error")
to specify which type(s) of test you wish to auto accept (i.e. same as typing"Y"
at theunitizer
prompt) or empty character vector to turn off (default)- test.dir
the directory to run the tests on; if NULL will use the “tests/unitizer” package folder if it exists, or “.” if it does not. See
infer_unitizer_location
) for details.- store.ids
one of
a function that converts test file names to
unitizer
ids; ifunitize
ing multiple files will belapply
ed over each filea character vector with
unitizer
ids, must be the same length as the number of test files being reviewed (seestore.id
)a list of unitizer ids, must be the same length as the number of test files being reviewed; useful when you implement special storage mechanisms for the
unitizers
(seeget_unitizer
)
- pattern
a regular expression used to match what subset of files in
test.dir
tounitize
Details
unitize
creates unit tests from a single R file, and
unitize_dir
creates tests from all the R files in the specified
directory (analogous to testthat::test_dir
).
unitizer
stores are identified by unitizer
ids, which by
default are character strings containing the location of the folder the
unitizer
RDS files are kept in. unitize
and
friends will create a unitizer
id for you based on the test file
name and location, but you can specify your own location as an id, or even
use a completely different mechanism to store the unitizer
data by
implementing S3 methods for get_unitizer
and
set_unitizer
.
review
allows you to review existing unitizer
s and modify them
by dropping tests from them. Tests are not evaluated in this mode; you are
just allowed to review the results of previous evaluations of the tests
Because of this, no effort is made to create reproducible state in the
browsing environments, unlike with unitize
or unitize_dir
(see state
parameter).
You are strongly encouraged to read through vignette("unitizer")
for details and examples. The demo (demo("unitizer")
) is also a
good introduction to these functions.
Value
unitize
and company are intended to be used primarily for
the interactive environment and side effects. The functions do return
summary data about test outcomes and user input as
unitizer_result
objects, or for unitize_dir
as
unitizer_results
objects, invisbly. See
unitizer_result
.
Default Settings
Many of the default settings are specfied in the form getOption("...")
to allow the user to "permanently" set them to their prefered modes by
setting options in their .Rprofile
file.
See Also
unitizerState
, unitizer.opts
,
get_unitizer
, infer_unitizer_location
,
unitizer_result