Ready4R (2025-02-19): More about unit testing

Welcome to the Weekly Ready for R mailing list! If you need Ready for R course info, it's here. Past newsletters are available here.

Why I Teach

I've always hated that phrase "Those who can't do, teach". Teaching technical subjects for beginners requires knowledge of the subject matter, but also empathy and a grasp of the cognitive limits of learners.

It is hard but rewarding work - don't let some idiot (sorry, George Bernard Shaw) tell you otherwise.

Unit Testing in R (Part 2)

Last time, we talked about expectations, which is at the heart of unit tests in R. This week, we'll dive a little more into the details.

More Kinds of Expectations

Other expectations that can be really helpful are: expect_null() (for testing when a function should return NULL), expect_type() to test whether the function is returning the right class of object, among others.

Another expectation that can be useful is expect_equal(): Does the function do what we expect? For example, we can use the vector c(1,2,3) as an input:

output <- square(c(1,2,3))
expect_equal(output, c(1,4,6))

Here's another one from my {buttondownr} package, which lets you send draft emails to the buttondown mailing list interface:

  test_that("send image works", {
    response <- send_image("test_pic.png")          #send image

    resp_code <- response |> httr2::resp_status()   #parse response
    expect_equal(resp_code, 201)                    #check response
  })
}

In this test, we send a test image to the API server, and await the response from the server. We are looking for a response from the API server here, which is 201, which is the signal that the API recieved an image, so we use expect_equal() here.

A related kind of testing is known as snapshot testing. In snapshot testing, you store a fragment of data, with a known output (also known as a snapshot), and run the test using the data, comparing the output to your snapshot. This is a good option when you are dealing with inputs that can change, such as when you fetch data from an API. You can update the snapshot when the API changes. The test failing is also a good indication that you need to update your code.

Our Testing Setup

How do we integrate unit tests in our work? We must first start by storing our code in a package. At its simplest, we need only a few things to start our package: a folder that will contain the package, and a few folders. I've found that the easiest way to start a package is to use the usethis package. Specifically, usethis::create_package() will create the proper directory structure:

> usethis::create_package("codebits")
✔ Creating codebits/.
✔ Setting active project to "/Users/tladera2/Code/codebits".
✔ Creating R/.
✔ Writing DESCRIPTION.
Package: codebits
... 
[More Info about Created Package]
...

This will create a package folder with the following structure:

.
├── DESCRIPTION
├── NAMESPACE
├── R
└── codebits.Rproj

Then, to add the folder for tests, we'll use usethis::use_testthat(), which will create the right folder structure.

> usethis::use_testthat()
✔ Setting active project to "/Users/tladera2/Code/codebits".
✔ Adding testthat to Suggests field in DESCRIPTION.
✔ Adding "3" to Config/testthat/edition.
✔ Creating tests/testthat/.
✔ Writing tests/testthat.R.
☐ Call usethis::use_test() to initialize a basic test file and open it for editing.

Which creates the following folder tests in our folder:

└── tests
    ├── testthat
    └── testthat.R

Then in the test/testthat/ folder, we can add our testing code. Now we're all setup to add our tests to our code. We can add a test with usethis::use_test():

> usethis::use_test("test_image_loading.R")
✔ Writing tests/testthat/test-test_image_loading.R.
☐ Modify tests/testthat/test-test_image_loading.R.
> 

And testthat will make a file in tests/testthat called test-image-loading.R:

test_that("multiplication works", {
  expect_equal(2 * 2, 4)
})

And as we program and make modifications to the code, we can load these changes up and then execute our tests. We do that with either the Build tab in RStudio or using the command:

testthat::test_local()

The one other thing you need to know to get started with package building is understanding how namespaces work within packages, so you can refer to functions in other packages. You can read more about this here.

The Philosophy of Testing

I think it's important to define what kinds of expectations we should include in our tests. Expectations are contracts that guarantee the behavior of a function. How do we use this to improve our development? They're the most important when we refactor functions (rewriting a function so that it is easier to maintain, or for other reasons), or when we decide to change the behavior of the function. That way, we can guarantee the function's behavior.

Tests should define what a function should do, but also what it shouldn't do. Functions should degrade gracefully when given unexpected inputs; but also, you shouldn't try to anticipate every user behavior. You need to see people use your code in real life, and adjust the tests to cover the most common behaviors.

Reminder: API workshop for Ukraine on 3/13

On March 13, I will be giving a short workshop on using the {httr2} package for requesting data with APIs. This is a benefit to support Ukrainians. You can participate by donating 20 euro or more at the link below.

Do the words “Web API” sound intimidating to you? This talk is a gentle introduction to what Web APIs are and how to get data out of them using the {httr2}, {jsonlite}. and {tidyjson} packages. You'll learn how to request data from an endpoint and get the data out. We'll do this using an API that gives us facts about cats. By the end of this talk, web APIs will seem much less intimidating and you will be empowered to access data from them.

More information: https://sites.google.com/view/dariia-mykhailyshyna/main/r-workshops-for-ukraine?authuser=0#h.hngu50v1j9mb

Thanks for Reading!

If you've gotten this far, you have my gratitude and I hope this series on unit testing has demystified it for you.

Next time, I'll show some tests from a package I made called {xvhelper} that I wrote during my time at DNAnexus.

Until then, stay safe.

Ted