<div style="text-align:center;">

```{r, echo = F}

</div>

What you’ll have learned by the end of the chapter: what unit tests are, how to write them, and how

to test your package thoroughly.

It might not have seemed like it, but developing our own package was actually the first step in

writing reproducible code. Packaged code is easy to share, and much easier to run than code that

lives inside scripts. When you share code, be it with future you or others, you have a

responsibility to ship high quality code. Unit tests are one way to ensure that your code works as

intented, but it is not a panacea. But if you write short, well-documented functions, and you

package them, and test them thoroughly, you are on the right track for success.

But what are unit tests? Unit tests are pieces of code that test other pieces of code (called units

in this context). It turns out that functions are units of code, and that makes testing them quite

easy. I hope that you are starting to see the pieces coming all together: I introduced you to

functional programming and insisted that you write your code as a sequence of functions calls,

because it makes it easier to package and document everything. And now that your code lives inside

a package, as a series of functions, it will be very easy to test these functions (or units of

code).

To make sure that each one of us starts with the exact same package and code, you will first of all

fork the following repository [that you can find here](https://github.com/b-rodrigues/unemp_lux_r4m).

```{r, echo = F}

Forking the repository will add a copy of the repository to your github account. You can now clone your fork

of the repo (make sure you clone using the ssh link!) and start working!

Because our code is packaged, starting to write unit tests will be very easy. For this, open RStudio

and make sure your package’s project is opened:

```{r, echo = F}

In order to set up the required files and folders for unit testing, run the following line in the R

console:

```{r, eval = F}

You should see a folder called `tests` appear inside the package. Inside `tests`, there is another

folder called `testthat`, and inside this folder you should find a file called

`test-clean_unemp.R`. This file should contain an example:

```{r, eval = F}

This is quite self-explanatory; `test_that()` is the function that we are going to use to write

tests. It takes a string as an argument, and a test. For the string write an explanatory name. This

will make it easier to find the test if it fails. `expect_equal()` is a function that tests the

equality between its arguments. On one side we have `2 * 2`, and on the other, `4`. All our tests

will look somewhat like this. There are many `expect_` functions, that allow you to test for many

conditions. You can take a look at `{testthat}`’s [function

reference](https://testthat.r-lib.org/reference/index.html) for a complete list.

So, what should we test? Well, here are several ideas:

- Is the function returning an expected value for a given input?

- Can the function deal with all kinds of input? What happens if an unexpected input is provided?

- Is the function failing as expected for certain inputs?

- Is the function dealing with corner cases as intended?

Let’s try to write some tests for our `clean_unemp()` function now, and start to consider each of these questions.

Let’s start by testing if our function actually returns data for the Grand-Duchy of Luxembourg if

the user provides a correct regular expression. Add these lines to the script (and remove the

example test while you're at it):

```{r, eval = F}

So what’s going on here? First, I need to get the data. I load the data outside of the test, so

it’ll be available to every test afterwards as well. Then, inside the test, I need to define two

more variables: the actual value returned by the function, and the value that we expect. I need to

create this value by hand, and I do so using the `tibble::as_tibble()` function. This function

takes a list as an argument and converts it to a tibble. I did not explain what tibbles are yet:

tibbles are basically the same as a data frame, but have a nicer print method, and other niceties.

In practice, you don’t need to think about tibbles too much, but here you need to be careful:

`clean_unemp()` returns a tibble, because that’s what `{dplyr}` functions return by default. So if

in your test you compare a tibble to a data.frame, your test will fail, because their classes are

not equal. So I need to define my expected value as a tibble for the test to pass.

You can now save the script, and press `CTRL-SHIFT-T` to run the test. The test should pass, if

not, there’s either something wrong with your function, with the inputs you provided to it, or with

the expected value. You can keep adding tests to this script, to cover every possible use case:

```{r, eval = F}

In the test above, I cannot write the expected value by hand. So what I did instead was run my

function in a terminal, and save the output in a csv file. I used the following code for this:

```{r, eval = F}

I inspected this output to make sure everything was correct. I can now keep this csv file and test

my function against it. Should my function fail when tested against it, I know that something is

wrong. We can do the same for communes. First, save the "ground truth" in a csv file:

```{r, eval = F}

Then, we can use this csv file in our tests:

```{r, eval = F}

We could even add a test for a specific commune:

```{r, eval = F}

So your final script would look something like this:

```{r, eval = F}

What *should* happen if your function gets an unexpected input? Let’s write a unit test and then see if it passes.

For example, what if the user enters a commune name that is not in Luxembourg? We expect the data frame to be

empty, so let’s write a test for that

```{r, eval = F}

This test reveals something interesting: your function returns an empty data frame, but the user might not understand

what’s wrong. Maybe we could add a message to inform the user? We could write something like:

```{r, eval = F}

Replace the `clean_unemp()` function from your package with this one, and rerun the tests. The test should

still pass, but a warning will be shown. We can test for this as well; is the warning thrown? Let's write

the required test for it:

```{r, eval = F}

`expect_warning()` needs the expression that should raise the warning, and a regular expression.

I've used the string "This is likely", which appears in the warning. This is to make sure that the

correct warning is raised. Should another warning be thrown, the test will fail, and I'll know that

something's wrong (try to change the regular expression and rerun the test, you see that it'll fail).

Now might be a good time to stop writing tests and think a little bit. While writing these tests,

and filling the shoes of your users, you might have realized that your function might not be that

great. We are asking users to enter a regular expression to filter data, which is really not

great nor user-friendly. And this is because the data we're dealing with is actually not clean,

because the same column mixes three different regional levels. For example, what if the users

wants to take a look at the commune "Luxembourg"?

```{r, eval = F}

So the user gets back three rows; that's because there's the country, the canton and the commune of Luxembourg.

Of course the user can now filter again to just get the commune. But this is not a good interface.

What we should do instead is clean the input data. And while we're at it, we could also provide the

data directly inside the package. This way users get the data "for free" once they install the

package. Let's do exactly that. To package data, we first need to create the `data-raw` folder.

This can be done with the following call:

```{r, eval = F}

There's a script called `DATASET.R` inside the `data-raw` folder. This is the script that we

should edit to clean the data. Let's write the following lines in it:

```{r, eval = F}

Running this code creates a dataset called `unemp`, which users of your package will be able to

load using `data("unemp")` (after having loaded your package). The now contains a new column

called `level` which will make filtering much easier. After `usethis::use_data()` is done,

we can read following message in the R console:

We are invited to document our data. To do so, create and edit a file called `data.R` in the `R`

directory:

```{r, eval = F}

You can now rebuild the document using `CTRL-SHIFT-D` and reload the package using `CRTL-SHIFT-L`. You

should now be able to load the data into your session using `data("unemp")`.

We can now change our function to accommodate this new data format. Let's edit our function like this:

```{r, eval = F}

There's a lot more going on now: if you don't get everything that's going on in this function,

don't worry, it is not that important for what follows. But do try to understand what's happening,

especially the part about the optional arguments.

Running our tests now will obviously fail:

At this stage, it might be a good idea to at least commit. Maybe let's not push yet, and only

push once the tests have been rewritten to pass. Commit from RStudio or from a terminal, the

choice is yours. We now have to rewrite the tests, to make them pass again. We also need

to recreate the csv files for some of the tests, and will probably need to create others. This is

what the script containing the tests could look like once you're done:

```{r, eval = F}

Once you're done, commit and push your changes.

You should now have a pretty good intuition about unit tests. As you can see, unit tests are not just

useful to make sure that changes that get introduced in our functions don't result in regressions in

our code, but also to actually improve our code. Writing unit tests allows us to fill the shoes

of our users and rethink our code.

A little sidenote before continuing; you might want to look into *code coverage* using the `{covr}`

package. This package helps you identify code from your package that is not tested yet. The goal

of course being to improve the coverage as much as possible! Take a look at

[`{cover}`'s website](https://covr.r-lib.org/) to learn more.

Ok, one final thing; let's say that we're happy with our package. To actually use it in other

projects we have to install it to our library. To do so, make sure RStudio is inside the

right project, and press `CTRL-SHIFT-B`. This will install the package to our library.