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.
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"))path contains $PKG, the value of pkg.dir
will be substituted for $PKG, otherwise the value of
pkg.dir will be appended to pkg.dir to give the
location of the pacakge. path can be semi-colon
separated list of paths.pattern and file should be supplied.TRUE run in full testing environment: create directory for
tests; copy tests to that directory; chdir to directory; run each
test file in a newly created R session. full: if full=FALSE the
default value is paste(pkg.dir, ".tests", sep=""; if full=TRUE the
default value is paste(pkg.dir, ".Rcheck/tests", sep="".
Supply dir=FALSE to run tests in the current directory.TRUE, output from the test will be written
as output from this function. The default is FALSE for
runtests() and TRUE for dumprout().console (specify just
console=TRUE or file=TRUE)FALSE. For
runtests(), if the dir already exists, clobber=TRUE
will result in replacing that directory, clobber=FALSE will
result in stopping with an error if the directory already exists. runtests,
meaning no files written), if output.suffix==TRUE, uses suffix .Rout.tmp runScripTests(). Only
relevant when full=TRUE. (Ignored
with a warning message otherwise.)"package:::" is
removed from test code. Supply subst=FALSE to prevent any
substitution. The default value will remove "package:::"
when appropriate. runtests(). 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
/home/tap/R/packages/mynewpkg/DESCRIPTION /home/tap/R/packages/mynewpkg/R /home/tap/R/packages/mynewpkg/tests ... etc ...and the working directory for the R session is
/home/tap/R/packagesTo read package R code and run some tests, do:
> 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
> dumprout(res)The default is to print transcripts only of tests that had warnings or errors. To write the transcripts to files, do:
> dumprout(res, file=T)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.:
> 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
/home/tap/R/packages/mynewpkg/DESCRIPTION /home/tap/R/packages/mynewpkg/R /home/tap/R/packages/mynewpkg/tests ... etc ...and the working directory for the R session is
/home/tap/R/sandboxTo read package R code and run some tests, do:
> 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
/home/tap/R/rforge/projectname/pkg/DESCRIPTION /home/tap/R/rforge/projectname/pkg/R/ /home/tap/R/rforge/projectname/pkg/tests/ ... etc ...and the working directory could be
/home/tap/R/rforge/projectnameTo conveniently source R code and run tests in this directory organization, do this
> 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
/home/tap/R/rforge/projectname/projectname.tests
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
R CMD check --no-codoc --no-examples --no-tests --no-vignettes --no-latexin 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.
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.
## 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)
Run the code above in your browser using DataLab