Home

/

CRAN

/

scriptests

/

runtests: Interactively run some Rt test files in a package

runtests: Interactively run some Rt test files in a package
In scriptests: Transcript-Based Unit Tests that are Easy to Create and Maintain

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.

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 `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`	A regular expression pattern of test files to be run. Only one of `pattern` and `file` should be supplied.
`file`	The name of the file(s) containing tests to be run.
`full`	If `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.
`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 `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.
`console`	If `TRUE`, output from the test will be written as output from this function. The default is `FALSE` for `runtests()` and `TRUE` for `dumprout()`.
`files`	Opposite of `console` (specify just `console=TRUE` or `file=TRUE`)
`clobber`	Should existing output files or directories be clobbered? For safety, the default is `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.
`output.suffix`	File suffix for actual output transcript files (default NULL for `runtests`, meaning no files written), if `output.suffix==TRUE`, uses suffix `.Rout.tmp`
`level`	Skip files unless they have notifications at the specified level or above.
`...`	Arguments to pass on to `runScripTests()`. Only relevant when `full=TRUE`. (Ignored with a warning message otherwise.)
`verbose`	Should progress indications be printed?
`envir`	The environment in which to run the tests.
`subst`	Provides control over whether the string `"package:::"` is removed from test code. Supply `subst=FALSE` to prevent any substitution. The default value will remove `"package:::"` when appropriate.
`res`	A value returned from `runtests()`.

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	R CMD check --no-codoc --no-examples --no-tests --no-vignettes --no-latex <pkg.dir>

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

  /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

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	> 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.:

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

  /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

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

  /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

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.

## 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)