Description of major unitizer
option settings. Once unitizer
is loaded, you can see a full list of unitizer
options with
grep("^unitizer", options(), value=TRUE)
.
Basic state options:
unitizer.state
: default state tracking setting (see
unitizerState
)
unitizer.seed
: default seed to use when random seed tracking
is enabled; this is of type "Wichman-Hill" because it is a lot more
compact than the default R random seed, and should be adequate for most
unit testing purposes.
Additionally, when tracking option state we set options to what you would
find in a freshly loaded vanilla R session, except for systems specific
options which we leave unchanged (e.g. getOption("papersize")
).
If you want to add default option values or options to leave unchanged, you
can use:
unitizer.opts.init
: named list, where names are options, and
the associated value is the value to use as the default value for that
option when a unitizer
is launched with options tracking enabled.
unitizer.opts.asis
: character, containing regular expressions
to match options to leave unchanged (e.g "^unitizer\."
)
We also provide options to limit what elements can be removed from
the search path and/or have their namespaces unloaded when unitizer
tracks the search path state. For example, we use this mechanism to prevent
removal of the unitizer
package itself as well as the default
R vanilla session packages.
unitizer.namespace.keep
: character, names of namespaces to
keep loaded (e.g. "utils"
); note that any imported namespaces
imported by namespaces listed here will also remain loaded
unitizer.search.path.keep
: character, names of objects to
keep on search path (e.g. "package:utils"
, note the
"package:"
); associated namespaces will also be kept loaded
IMPORTANT: There is a dependency between options tracking and search
path / namespace exceptions that stems from most packages setting their
default options when they are loaded. As a result, if you add any packages
or namespaces to these options and options state tracking is enabled, then
you must also add their options to unitizer.opts.init
or
unitizer.opts.asis
to ensure those options remain loaded or at least
set to reasonable values. If you do not do this the packages risk having
their options unset.
Some packages cannot be easily loaded and unloaded. For example
data.table
(<= 1.9.5) cannot be unloaded without causing a segfault
(see issue #990).
For this reason data.table
is included in
getOption("unitizer.namespace.keep")
by default.
The following options hold the default system values for the search path / namespace and options state tracking options:
unitizer.namespace.keep.base
: namespaces that are known to
cause problems when unloaded (as of this writing includes
data.table
)
unitizer.search.path.keep.base
: vanilla R session packages,
plus "package:unitizer"
and "tools:rstudio"
, the latter
because its implementation prevents re-attaching it if it is detached.
unitizer.opts.asis.base
: system specific options that should
not affect test evaluation (e.g. getOption("editor")
).
unitizer.opts.init.base
: base options (e.g.
getOption("width")
that will be set to what we believe are the
factory settings for them.
These are kept separate from the user specified ones to limit the possibility
of inadvertent modification. They are exposed as options to allow the user to
unset single values if required, though this is intended to be rare.
unitizer
runs with the union of user options and the system versions
described here. For unitizer.opts.init
, any options set that are
also present in unitizer.opts.init.base
will overrule the base
version.
These options control how unitizer
displays data such as diffs, test
results, etc.
unitizer.test.out.lines
: integer(2L), where first values is
maximum number of lines of screen output to show for each test, and
second value is the number of lines to show if there are more lines than
allowed by the first value
unitizer.test.msg.lines
: like unitizer.test.out.lines
,
but for stderr output
unitizer.test.fail.context.lines
: integer(2L), used
exclusively when comparing new to references tests when test faile; first
values is maximum number of lines of context to show around a test,
centered on differences if there are any, and second value is the number
of context lines to show if using the first value is not sufficient to
fully display the test results
unitizer.show.output
: TRUE or FALSE, whether to display test
stdout
and stderr
output as it is evaluated.
unitizer.disable.capt
: logical(2L), not NA, with names
c("output", "message")
where each value indicates whether the
corresponding stream should be captured or not. For stdout
the
stream is still captured but setting the value to FALSE tees it.
unitizer.max.capture.chars
: integer(1L) maximum number of
characters to allow capture of per test
unitizer.color
whether to use ANSI color escape sequences,
set to TRUE to force, FALSE to force off, or NULL to attempt to auto
detect (based on code from package:crayon, thanks Gabor Csardi)
unitizer.history.file
character(1L) location of file to use
to store history of command entered by user in in interactive
unitizer
prompt; ""
is interpreted as tempfile()
unitizer.prompt.b4.quit.time
integer(1L) unitizers
that
take more seconds than this to evaluate will post a confirmation prompt
before quitting; this is to avoid accidentally quitting after running a
unitizer
with many slow running tests and having to re-run them
again.