Following the first post I published about how to write your first R package using modern tools, we continue our adventures with R packages and touch upon the topic of writing tests. Tests are essential to ensure your package is robust and that any modification you ever make has no impact on its key features.

Unit tests are like insurance. You hope you never have to use them, but you're glad you have them when you do.

Martin Fowler

Why Write Tests?

Writing tests is not the most exciting task. Most developers would rather spend time developing new features than new tests. But the more complex your code becomes, the more likely you will see bugs pop up everywhere. You can't plan to cover the whole surface of issues that can arise, and Unit Testing is the first thing that helps to ensure that independent parts of your code (typically, functions), behave as they should, even in corner cases.

How to write tests in the context of a R package?

You've come here for that!

Let's go back to our packagedfun package. It has a unique function that does not much right now:

#' Saying Hello is polite
#'
#' @description
#' `hello_fun` says hello and uses the name of the person as an argument.
#'
#' @importFrom glue glue
#'
#' @details
#' This is a generic function that can be used to say hello/
#'
#' @param name the name of the person you want to send a Hello message to
#' @export
hello_fun <- function(name) {

  print(glue::glue("Hello {name}"))

}

First, we will make this function a little more elaborate, and do a few more things, such as:

• having a default name value if the function is run as is, without any parameter
• refuse empty names if entered, by throwing an error
• accept multiple names if given in the form of a vector of characters

#' Saying Hello is polite
#'
#' @description
#' `hello_fun` says hello and uses the name of the person(s) as an argument. y
#'
#' @importFrom glue glue
#'
#' @details
#' This is a generic function that can be used to say hello/
#'
#' @param name the name of the person(s) you want to send a Hello message to - you can enter a vector of names. By default is no name is entered, it takes the value of "Person with no name"
#' @export
hello_fun <- function(name="Person with no name") {

  if (length(name)==1) {
  if (is.na(name) | name=="") {
    stop("I'd like you to enter a name. not an empty string!")
  } else {
  return(glue::glue("Hello {name}"))
  }
  }

  if (length(name)>1) {
   names_string <- paste(name,collapse=" and ")
   return(glue::glue("Hello {names_string}!"))
  }
}

Now that we can do several things with this function, let's write some tests for it.

Go into the main folder of your package, and create a folder called tests and inside that folder testthat

In there, you can create one or several R files that will contain your tests. We will create a first file called test-hello.R.

Here's the first test we write for our function in test-hello.R:

test_that("Confirm that the function works with John", {
  expect_equal(hello_fun(name="John"), "Hello John")
})

It's a positive test. We confirm that the function will be returning "Hello John" in case we give "John" as a parameter. Makes sense right? We use the expect_equal function from the testthat package, which will in its first argument secure a function call, and compare it with its second argument to confirm that they are identical.

You can then go in RStudio and hit to "Test Package" menu:

You should see something showing up in the environment pane:

The key info to pick up here is that I am a coding rockstar your test was successful, and there was only one of them coming from the "hello" test file.

Let's write a few more tests! This is now what I have in my tests/testthat/test-hello.R file:

test_that("Confirm that the function works with John", {
  expect_equal(hello_fun(name="John"), "Hello John")
})

test_that("Confirm that the function works when no parameter is given", {
  expect_equal(hello_fun(), "Hello Person with no name")
})

test_that("Confirm that the function works when two names are given", {
  expect_equal(hello_fun(name=c("Joan","Liz")), "Hello Joan and Liz!")
})

test_that("Confirm that the function returns an error when given an empty string", {
  expect_error(hello_fun(name=""), "I'd like you to enter a name. not an empty string!")
})

The new thing that I introduced here is the expect_error function. It will not look for equality, but instead confirm that the execution was stopped, and that an error message was returned (and checks that it's the right one).

Let's hit the "Test Package" menu one more time.

Good! We have now 4 tests, and all of them were passed. Are we done?

Let me add one more test!

test_that("Confirm that the function works when two names are given but one is empty", {
  expect_equal(hello_fun(name=c("Joan","")), "Hello Joan")
})

I would expect that the function ignores names that are empty... let's test one more time!

Ouch! Look like we met with our first failed test! Looking at my original code, it's not supposed to handle things this way, and will instead return something like "Hello Joan and !" if the second name is an empty string.

This is to show you that writing tests is not just about writing obvious statements like checking that 1+1=2, but rather checking expected behavior that should occur in fairly typical scenarios.

You may not always think about how to deal with empty values, NA values, or other strange things like -Inf or +Inf when dealing with numeric values.

Writing tests is about thinking what can go wrong. Considering "what if...?" stories. And checking if your code can handle them.

In the meantime, let's fix our function!

Whack-a-Mole

Fixing this issue? Just 1 minute work, I thought. Here's my fix:

#' Saying Hello is polite
#'
#' @description
#' `hello_fun` says hello and uses the name of the person(s) as an argument. y
#'
#' @importFrom glue glue
#'
#' @details
#' This is a generic function that can be used to say hello/
#'
#' @param name the name of the person(s) you want to send a Hello message to - you can enter a vector of names. By default is no name is entered, it takes the value of "Person with no name"
#' @export
hello_fun <- function(name="Person with no name") {

  is_empty_string_vector <- name == ""
  name <- name[!is_empty_string_vector]

  is_na_vector <- is.na(name)
  name <- name[!is_na_vector]

  if (length(name)==1) {
  if (is.na(name) | name=="") {
    stop("I'd like you to enter a name. not an empty string!")
  } else {
  return(glue::glue("Hello {name}"))
  }
  }

  if (length(name)>1) {
   names_string <- paste(name,collapse=" and ")
   return(glue::glue("Hello {names_string}!"))
  }
}

The new bits are there to sanitize and remove the empty strings or NA values from the name parameter, if given, and it works no matter how long the vector is!

Let's enjoy the final, successful test, while I go and grab a cup of tea:

The tea will have to wait. What's happening here?

Oh, I fixed one issue, but I created a new one!? Now, when someone enters an empty string as an argument, it will stop throwing an error since my new additions will completely remove them.

When you end up here, there's two ways to proceed:

• First would be to fix the function to restore the older behavior. It's as simple as doing a condition to check if the length of the vector is 1 first before applying our couple of lines that were made mainly for longer vectors.
• The other approach is... well, that test we had does not make sense anymore. I ended up with a generalization that's more correct, and I could just as well get rid of that test.

My choice here is to take the second approach. And this is where this quote feels just right at home:

"Unit testing is a conversation between the developer and the code."

Martin Fowler (yes, again)

So my final test-hello.R file will be like that:

test_that("Confirm that the function works with John", {
  expect_equal(hello_fun(name="John"), "Hello John")
})

test_that("Confirm that the function works when no parameter is given", {
  expect_equal(hello_fun(), "Hello Person with no name")
})

test_that("Confirm that the function works when two names are given", {
  expect_equal(hello_fun(name=c("Joan","Liz")), "Hello Joan and Liz!")
})

test_that("Confirm that the function works when two names are given but one is empty", {
  expect_equal(hello_fun(name=c("Joan","")), "Hello Joan")
})

And this time, all tests are passed:

And apparently, I'm not a rockstar anymore :-(

But I get to enjoy my tea, before it got cold. All's good.

Is that it?

For simple tests, yes. But there are many other tests you can plan, and different ways to write them, too. Next time, I will bring a more complex example on this topic - there's a lot to cover.

Stay tuned!

A short post this time. If you use {reticulate} (the excellent library to bridge together Python and R code) you will sometimes end up with a complete system crash (R session aborted) when loading specific Python functions using a reticulate environment.

Since the error gives you no insight as to what is actually happening, this is a hard one to debug. Nobody likes to meet face-to-face with a "Segmentation Fault".

In my case, I have ultimately found that this error occurs when I use a Python environment with Numpy installed. As soon as the environment is loaded with Numpy, this leads to this kind of crash.

This happens (on Linux) when I install Numpy this way in a virtualenv:

reticulate::virtualenv_install(envname = "python-env-for-analysis",packages = "numpy")

To make this error go away, this is what actually works - you need to let pip know that you don't want to fetch a binary for numpy, but actually recompile it from sources on your local machine.

reticulate::virtualenv_install(envname = "python-env-for-analysis",packages = "numpy", pip_options = "--no-binary='numpy'",ignore_installed = TRUE)

It will take a little longer to install, but it's worth it.

If you ever get some weird, unexpected crashes with reticulate, keep this is in mind (or in a bookmark). It might save you many, many precious hours.

I will not be using {fusen} here while it's often being advertised these days. I find it a bit confusing and much prefer the typical way of building packages.

You need to install the following:

• devtools (necessary to build your package)
• usethis (helper functions to take shortcuts)
• roxygen2 (simplifies package creation)
• testthat (to incorporate standard testing as part of your package build)

You can install them all with a one liner:

install.packages(c("devtools", "roxygen2","usethis", "testthat"))

Setting You on the Right Path

First you need to setup the path that you are working with, and where a new folder will be created for you. (don't create a folder for your package!)

setwd("/path/to/your/main/folder/")

Now you can use a helper function to create the main structure of your package:

usethis::create_package("packagedfun")

note that are limits to what kind of characters you can use when you name a package. If you get an error this probably means that you tried to use some of them that are not allowed.

When you execute the above command in RStudio, it will directly reload the environment to put you inside the newly created project.

Your environment will have the following files:

• .gitignore
• .Rbuildignore
• DESCRIPTION
• NAMESPACE
• packagedfun.Rproj
• R (folder)

The DESCRIPTION file generates meta data about your project. You will have to edit it by yourself to reflect the actual information about your package.

The NAMESPACE file is automatically generated (and is read-only) in our workflow so you should not edit it manually.

The R folder is where you will put your R scripts which will contain your functions and scripts.

Licensing: Just a Few Seconds of Work

First I'd recommend you set the license of your package. You can use the helper functions from usethis for this purpose. Let's say we want to use the MIT license, you can simply write in the console:

usethis::use_mit_license()

This will automatically modify the DESCRIPTION file to include the MIT license and add a separate license file (actually two, LICENSE and LICENSE.md) in the working folder with the MIT license text. Practical!

Of course this is not limited to MIT, you can add AGPL, GPL, or even proprietary licenses directly from usethis.

Versioning: Easy!

You probably want to start enumerating the version of your package as well. Once again, usethis comes to the rescue when you run it in the console:

usethis::use_version()

This will ask you to choose how to increment your package's version number:

If you are still in early days of developing your package, you may want to start with a minor version (option 2). Type 2, and the DESCRIPTION will be automatically updated.

Your Package's First Function

Let's proceed by creating a simple function:

usethis::use_r("hello")

This creates a hello.R file inside the R folder, as you can imagine.

The new file is completely empty and you can start creating your function. Let's do a simple hello world, but with a twist.

hello_fun <- function(name) {
  
  print(glue::glue("Hello {name}"))
  
}

As you can see, I am including an external dependency on purpose here. Most of the tutorials on the net consider that you make functions that depend on nothing at all, which is far from being the typical use case.

Now let's see what happens if we check the package in its current state.

Learning from Failure(s)

Assuming you use RStudio, you can use the "Check Package" menu from the Rstudio interface in the Build menu:

You will get a long list of checks happening in the environment tab on the upper right corner, and at the end it will issue a warning about the fact that you did not declare a dependency.

You can actually still build your package - and it will work and load, but when you call the hello_fun() function it will complain that the function glue is not available, which is less than ideal.

In order to fix it, you can follow the style used by roxygen2 to add meta data to your functions:

#' Saying Hello is polite
#' 
#' @description
#' `hello_fun` says hello and uses the name of the person as an argument.
#'
#' @import glue
#'
#' @details
#' This is a generic function that can be used to say hello/
hello_fun <- function(name) {

  print(glue::glue("Hello {name}"))

}

The key statement here is the @import. Here by specify "glue", which means it will import the whole glue library along with all of its functions. While that would work, that's completely overkill, and incurs the risk of functions with the same name causing conflicts. The better approach if a more specific import statement:

#' Saying Hello is polite
#' 
#' @description
#' `hello_fun` says hello and uses the name of the person as an argument.
#'
#' @importFrom glue glue
#'
#' @details
#' This is a generic function that can be used to say hello/
hello_fun <- function(name) {

  print(glue::glue("Hello {name}"))

}

Since it's not obvious from the example above, the @importFrom follows the syntax:

@importFrom <package> <function>

So if you import the function write_feather from the library arrow, it would look like:

@importFrom arrow write_feather

Are we done now?

Let's "check" the package again.

When you run the checks, it will also modify the NAMESPACE file - and if you open it, you will see it now contains the dependency declaration:

# Generated by roxygen2: do not edit by hand

importFrom(glue,glue)

... which is great, but alas! this is not enough to pass the checks yet!

Now we get an actual error, because our dependency is not declared in the DESCRIPTION file!

It's an easy fix - this is the DESCRIPTION before the import statement:

Package: packagedfun
Title: Enjoy a proper Hello World with a customized message!
Version: 0.1.0
Authors@R: 
    person("Alisa", "Wazrak", , "alisa.wazrak@example.com", role = c("aut", "cre"))
Description: This package provides the valuable hello_fun function that nobody has ever created before.
License: MIT + file LICENSE
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.2.3

and after:

Package: packagedfun
Title: Enjoy a proper Hello World with a customized message!
Version: 0.1.0
Authors@R: 
    person("Alisa", "Wazrak", , "alisa.wazrak@example.com", role = c("aut", "cre"))
Description: This package provides the valuable hello_fun function that nobody has ever created before.
Imports: glue
License: MIT + file LICENSE
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.2.3

Are we there yet?

Let's see...

Almost!

Now we are notified that we have forgotten to document the argument in our function.

We can just modify it in the hello.R file to include a @param statement as well as an @export statement to ensure that the function is available once you load the package later on: (functions without @export flags are ignored)

#' Saying Hello is polite
#'
#' @description
#' `hello_fun` says hello and uses the name of the person as an argument.
#'
#' @importFrom glue glue
#'
#' @details
#' This is a generic function that can be used to say hello/
#'
#' @param name the name of the person you want to send a Hello message to
#' @export
hello_fun <- function(name) {

  print(glue::glue("Hello {name}"))

}

And we are done! The last check works:

Building, Installing and Testing the Package

Now you can go ahead and build a binary package, for example, once the checks are successful:

This will build a packagedfun_0.1.0_R_x86_64-pc-linux-gnu.tar.gz (if you run this on Linux) in the parent folder of your package.

To check if it works, you can exit the current Rstudio session, and reload a clean one. Then you try installing the package (of course, adapt the path to your system's):

install.packages("/path/to/your/package/binary/packagedfun_0.1.0_R_x86_64-pc-linux-gnu.tar.gz")

It should succeed.

Now you can load it:

library(packagedfun)

and try it out:

hello_fun("You!")

and you should see a glorious answer in your console:

Hello You!

We are done!

I hope you enjoyed this post. We will come back with a few more details on how to make packages in R. This time we focused on how to do it correctly with the minimal effort - next, we will see how we can add some more polish.

This is my first post, just to say Hi! I'm Alisa, and I love to play around with data in my spare time. I will be sharing with you some of the things I do once in a while! Stay tuned!