Turn standard R scripts into unit tests by storing the expressions therein along with the results of their evaluation.
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))
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.
See infer_unitizer_location) for details.
if NULL (default), unitizer will select a directory
based on the test.file name by replacing .[rR] with
.unitizer. You can also specify a directory name, or pass any
object that has a defined get_unitizer method which allows
you to specify non-standard unitizer storage mechanisms (see
get_unitizer). Finally, you can pass an actual
unitizer object if you are using review; see store.ids
for unitize_dir
character(1L) one of
c("prisitine", "default", "basic", "off", "safe"), an environment,
or a state object produced by state or in_pkg;
modifies how unitizer manages aspects of session state that could
affect test evaluation, including the parent evaluation environment. For
more details see unitizerState documentation and
vignette("unitizer_reproducible_tests")
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 in pre. 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 the unitizer so you
will have not direct way to check whether these objects changed across
unitizer runs. Additionally, typing ls from the review
prompt will not list these objects.
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
exiting unitizer. post code will be run in an environment
with the environment used to run pre as the parent. This means that
any objects created in pre will be available to post, which
you can use to your advantage if there are some things you do in pre
you wish to undo in post. Keep in mind that unitizer can
manage most aspects of global state, so you should not need to use this
parameter to unload packages, remove objects, etc. See details.
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.
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).
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,
though force.update=TRUE will force update irrespective of what
you do with O at the prompt
character(X) ADVANCED USE ONLY: YOU CAN EASILY DESTROY
YOUR unitizer WITH THIS; whether to auto-accept tests without
prompting, use values in c("new", "failed", "deleted", "error") to
specify which type(s) of test you wish to auto accept (i.e. same as typing
"Y" at the unitizer prompt) or empty character vector to turn
off (default)
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.
one of
a function that converts test file names to unitizer ids; if
unitizeing multiple files will be lapplyed over each file
a character vector with unitizer ids, must be the same
length as the number of test files being reviewed (see store.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 (see get_unitizer)
a regular expression used to match what subset of files in
test.dir to unitize
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.
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.
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 unitizers 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.
unitizerState, unitizer.opts,
get_unitizer, infer_unitizer_location,
unitizer_result