Description Usage Arguments Details Value Running tests Author(s) See Also Examples
Run some Rt test files in a package from within an interactive R
session.
There are two major modes in which runtests()
can be used:
full=FALSE
: Running tests within the current R session,
which can change existing R variables, and create new ones.
full=TRUE
: Running tests by creating a new R session
for each test file. This is safer, but slower, and also requires an
installed version of the package in a local directory, such as one
created by running R CMD check
at the command line.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | runtests(pkg.dir = getOption("scriptests.pkg.dir", "pkg"),
pattern = ".*",
file = NULL,
full = FALSE,
dir = TRUE,
clobber = FALSE,
output.suffix = NULL,
console = FALSE,
...,
verbose = TRUE,
envir = globalenv(),
subst = NULL,
path = getOption("scriptests.pkg.path", default=getwd()))
dumprout(res = .Last.value,
output.suffix = ".Rout.tmp",
verbose = TRUE,
console = FALSE,
files = !console,
clobber = identical(output.suffix, ".Rout.tmp"),
level=c("error", "all", "info", "warning"))
|
pkg.dir |
The directory in which the package code and tests reside. |
path |
The path to the package in which the tests reside. If
|
pattern |
A regular expression pattern of test files to be run.
Only one of |
file |
The name of the file(s) containing tests to be run. |
full |
If |
dir |
Directory where tests will be run. The default is usually
satisfactory. This can be important if
the files access and/or create any files or directories. The
default value depends on |
console |
If |
files |
Opposite of |
clobber |
Should existing output files or directories be
clobbered? For safety, the default is |
output.suffix |
File suffix for actual output transcript files (default NULL for |
level |
Skip files unless they have notifications at the specified level or above. |
... |
Arguments to pass on to |
verbose |
Should progress indications be printed? |
envir |
The environment in which to run the tests. |
subst |
Provides control over whether the string |
res |
A value returned from |
runtests()
runs some or all of the tests (in .Rt
files)
found in the tests
directory of a package. The arguments
pkg.dir
and path
are used to specify the location of the
package (see the section Running tests below for further
details). runtests()
is designed to be used in conjunction
with source.pkg()
, which reads all the R code in a package into
a special environment on the search path. With the default argument
full=FALSE
, runtests()
will run the tests in the same R
session, though it will create a special directory which will be used
as the working directory while running the tests. In this mode of
operation, output from tests is not is not written to files (unless
output.suffix
is supplied with a value), though tests may
create or modify files themselves.
Supplying runtests(..., full=TRUE)
will run each test file in a new
R session - the way tests are run under R CMD check
. When run
like this, the package must be installed in the
location <pkg.dir>.Rcheck
or or <pkg.name>.Rcheck
,
relative to the working directory of the current R session. This can
be accomplished by running the shell command
1 |
in the same directory as the R session is running in.
For working with a package in a different location relative to the
working directory of the R session, supply the path to the package
directory as path
(can be either a relative or absolute path.)
After either of the package or path has been specified once, it is
remembered and will be used as the default value next time either of
runtests()
or source.pkg()
is called.
dumprout()
writes actual R output to the console or to files.
It creates one file for each test run. Specifying level=
skips
files that have no notification at the given level or above. With a
missing first argument, dumprout()
uses the value of the
previously run command, which allows it to be meaningfully used
directly after a runtests()
command.
runtests()
returns an invisible list of RtTestSetResults
objects (each element of
the list is the result of running and checking the test in one file.)
This result can be given to dumprout()
to write actual R output
to temporary files for test debugging and development purposes.
dumprout()
returns its first argument (whose default value is
.Last.value
), allowing it to be run several times in a row
without having to supply any arguments
runtests()
is intended to be used in an R session while
developing and/or maintaining code and/or tests. It is designed to
work together with source.pkg()
, which rapidly reads the
R code in a package.. The arguments given to runtests()
will
depend on how package directories are organized, and the working
directory for the R session used for code and test development.
Scenario 1: working directory of R session contains the package source code
The package source code
mynewpkg
is in
1 2 3 4 |
and the working directory for the R session is
1 | /home/tap/R/packages
|
To read package R code and run some tests, do:
1 2 | > source.pkg(pkg.dir="mynewpkg")
> res <- runtests(pkg.dir="mynewpkg", pattern="testfile1", clobber=T)
|
This will create a directory /home/tap/R/packages/mynewpkg.tests
,
copy all tests to it, and run the tests whose name matches
testfile1
(to run all the tests, omit the argument
pattern=
).
Test files (ending in .Rt
) will be looked for in the directory
mynewpkg/tests/
, and various output files could be created in
/home/tap/R/packages
(such as those created by the tests, and
also some created by runtests).
If there are errors or warnings in matching actual and desired output, a
brief description and summary will be printed. A transcript of the
actual output from running the tests can be printed by
1 | > dumprout(res)
|
The default is to print transcripts only of tests that had warnings or errors. To write the transcripts to files, do:
1 |
This will create files like testfile1.Rout.tmp
in the working
directory of the R session.
These functions remember the most recent pkg.dir
argument, and
dumprout()
will use a .Last.value
left by
runtests()
, so it is possible to omit various arguments in the
above commands, e.g.:
1 2 3 | > source.pkg(pkg.dir="mynewpkg")
> runtests(pattern="testfile1", clobber=T)
> dumprout(file=T)
|
Note that the name of the directory where the package lives (here
mynewpkg
) may be the same as or different from the name of the package.
Scenario 2: working directory of R session is in a different filesystem branch to package source code
The package code
mynewpkg
is in
1 2 3 4 |
and the working directory for the R session is
1 | /home/tap/R/sandbox
|
To read package R code and run some tests, do:
1 2 | > source.pkg(pkg.dir="mynewpkg", path="/home/tap/R/packages")
> res <- runtests(pkg.dir="mynewpkg", pattern="testfile1", clobber=T)
|
and proceed as above. The directory
/home/tap/R/sandbox/mynewpkg.tests
will be created and used as
the working directory for running tests.
Scenario 3: deeper directory structure for package source code
In an R-forge-like directory structure, the package files and directories may be in
1 2 3 4 |
and the working directory could be
1 | /home/tap/R/rforge/projectname
|
To conveniently source R code and run tests in this directory organization, do this
1 2 | > source.pkg(pkg.dir="projectname", path="/home/tap/R/rforge/$DIR/pkg")
> res <- runtests(pkg.dir="projectname", pattern="testfile1", clobber=T)
|
Tests will be run in the directory
1 | /home/tap/R/rforge/projectname/projectname.tests
|
Tony Plate tplate@acm.org
source.pkg()
shares the options
scriptests.pkg.dir
and scriptests.pkg.path
that provide
defaults for the pkg.dir
and path
arguments.
For running tests in under R CMD check
, use the function
runScripTests()
in the file tests/runtests.R
in
the package.
For an overview and for more details of how tests are run, inlcuding how to make test output matching more flexible, see scriptests.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | ## Not run:
> # To run like this example, set the current working directory
> # to where the package code lives.
> # source.pkg() reads in the functions -- could just as well
> # load the library, but source.pkg() can be more convenient
> # when developing a package.
> source.pkg("scriptests")
Reading 5 .R files into env at pos 2: 'pkgcode:scriptests'
Sourcing scriptests/R/createRfromRt.R
Sourcing scriptests/R/interactive.R
Sourcing scriptests/R/oldcode.R
Sourcing scriptests/R/plus.R
Sourcing scriptests/R/rttests.R
list()
> runtests("simple1")
Running tests in scriptests/tests/simple1.Rt (read 4 chunks)
....
Ran 4 tests with 0 errors and 0 warnings from scriptests/tests/simple1.Rt
> runtests("simple2")
Running tests in scriptests/tests/simple2.Rt (read 5 chunks)
.....
Ran 5 tests with 0 errors and 0 warnings from scriptests/tests/simple2.Rt
> runtests("simple")
Running tests in scriptests/tests/simple1.Rt (read 4 chunks)
....
Ran 4 tests with 0 errors and 0 warnings from scriptests/tests/simple1.Rt
Running tests in scriptests/tests/simple2.Rt (read 5 chunks)
.....
Ran 5 tests with 0 errors and 0 warnings from scriptests/tests/simple2.Rt
>
## End(Not run)
|
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.