distributing R package containing unit tests

Question

so I decided I would put my few R functions into a package and I'm reading/learning Writing R Extension.

it obviously complains about an amount of things I'm not doing right.

after enough googling, I'm firing a few questions here, this one is about testing style: I am using RUnit and I like having tests as close possible to the code being tested. this way I won't forget about the tests and I use the tests as part of the technical documentation.

for example:

fillInTheBlanks <- function(S) {
  ## NA in S are replaced with observed values

  ## accepts a vector possibly holding NA values and returns a vector
  ## where all observed values are carried forward and the first is
  ## carried backward.  cfr na.locf from zoo library.
  L <- !is.na(S)
  c(S[L][1], S[L])[1 + cumsum(L)]
}

test.fillInTheBlanks <- function() {
  checkEquals(fillInTheBlanks(c(1, NA, NA, 2, 3, NA, 4)), c(1, 1, 1, 2, 3, 3, 4))
  checkEquals(fillInTheBlanks(c(1, 2, 3, 4)), c(1, 2, 3, 4))
  checkEquals(fillInTheBlanks(c(NA, NA, 2, 3, NA, 4)), c(2, 2, 2, 3, 3, 4))
}

but R CMD check issues NOTE lines, like this one:

test.fillInTheBlanks: no visible global function definition for
  ‘checkEquals’

and it complains about me not documenting the test functions.

I don't really want to add documentation for the test functions and I definitely would prefer not having to add a dependency to the RUnit package.

how do you think I should look at this issue?

Answer 1

Did you load the RUnit package?

Your best bet is probably to look at a package containing existing code using RUnit.

Answer 2

Where are you putting your unit tests? You may not want to put them into the R directory. A more standard approach is to put them under inst\unitTests. Have a look at this R-wiki page regarding the configuration.

Alternatively, you can specify what files will be exported in your NAMESPACE, and by extension, what functions should and should not be documented.

Beyond that, ideally you should have your tests run when R CMD CHECK is called; that's part of the design. In which case, you should create a test script to call your tests in a separate tests directory. And you will need to load the RUnit package in that script (but you don't need to make it a dependency of your package).

Edit 1:

Regarding your failure because it can't find the checkEquals function: I would change you function to be like this:

test.fillInTheBlanks <- function() {
  require(RUnit)
  checkEquals(fillInTheBlanks(c(1, NA, NA, 2, 3, NA, 4)), c(1, 1, 1, 2, 3, 3, 4))
  checkEquals(fillInTheBlanks(c(1, 2, 3, 4)), c(1, 2, 3, 4))
  checkEquals(fillInTheBlanks(c(NA, NA, 2, 3, NA, 4)), c(2, 2, 2, 3, 3, 4))
}

That way the package is loaded when the function is called or it will inform the user that the package is required.

Edit 2:

From "Writing R Extensions":

Note that all user-level objects in a package should be documented; if a package pkg contains user-level objects which are for “internal” use only, it should provide a file pkg-internal.Rd which documents all such objects, and clearly states that these are not meant to be called by the user. See e.g. the sources for package grid in the R distribution for an example. Note that packages which use internal objects extensively should hide those objects in a name space, when they do not need to be documented (see Package name spaces).

You can use the pkg-internal.Rd file as one option, but if you intend on having many hidden objects, this is usually handled in the declarations in the NAMESPACE.