test_snapshots_mocks.qmd

# Mocks and snapshots {#sec-tests-mocks-snapshots}

```{r}
#| eval: true 
#| echo: false 
#| include: false
source("_common.R")
library(rlang)
```

:::: {.callout-tip collapse='true' appearance='simple'}

## [Accessing applications]{style='font-weight: bold; font-size: 1.15em;'}

::: {style='font-size: 0.95em; color: #282b2d;'}

I've created the [`shinypak` R package](https://mjfrigaard.github.io/shinypak/) In an effort to make each section accessible and easy to follow:
  
Install `shinypak` using `pak` (or `remotes`):

```{r}
#| code-fold: false 
#| message: false
#| warning: false
#| eval: false
# install.packages('pak')
pak::pak('mjfrigaard/shinypak')
```

Review the chapters in each section:
  
```{r}
#| code-fold: false 
#| message: false
#| warning: false
#| collapse: true
library(shinypak)
list_apps(regex = '^A')
```

Launch the app with `launch()`

```{r}
#| code-fold: false 
#| eval: false
launch(app = "A.E_mocks-snapshots")
```

Download the app with `get()`

```{r}
#| code-fold: false 
#| eval: false
get_app(app = "A.E_mocks-snapshots")
```


::: 

::::

## Snapshots {#sec-tests-snapshots-vdiffr}

If we want to create a graph snapshot test, the [`vdiffr`](https://vdiffr.r-lib.org/) package allows us to perform a 'visual unit test' by capturing the expected output as an `.svg` file that we can compare with future versions.

```{r}
#| label: git_box_A.E-mocks-snapshots
#| echo: false
#| results: asis
#| eval: true
git_margin_box(
  contents = "launch",
  fig_pw = '65%', 
  branch = "A.E-mocks-snapshots", 
  repo = 'sap')
```

The `expect_doppelganger()` function from `vdiffr` is designed specifically to work with ['graphical plots'](https://vdiffr.r-lib.org/reference/expect_doppelganger.html).

```{r}
#| eval: false 
#| code-fold: false
vdiffr::expect_doppelganger(
      title = "name of graph", 
      fig = # ...code to create graph...
  )
```

Another option for using snapshots for testing is the `expect_snapshot_file()` function [^test_tools-12] but `expect_doppelganger()` is probably the better option for comparing graph outputs.

[^test_tools-12]: Follow the `expect_snapshot_file()` example from the [`testthat` documentation](https://testthat.r-lib.org/reference/expect_snapshot_file.html#ref-examples)

### Testing graph outputs

The `Feature` for the initial graph output from `scatter_plot()` might look like: 

```{r}
#| eval: false 
#| code-fold: false
testthat::describe(
  "Feature: Scatter Plot Configuration in Movie Review Application
    As a user who accesses the movie review application,
    I want the initial scatter plot pre-configured with variables and aesthetics,
    So that I can immediately see a meaningful visualization.", code = {
    
})
```


Combining scenarios in the same test file is helpful if we're trying to keep a 1:1 between the `test/testthat/` file names and file names in `R/`.[^test_tools-13]

[^test_tools-13]: matching files names between `R/` and `tests/testthat/` keeps our code organized and ensures the `devtools::test_coverage_active_file()` function [works.](https://testthat.r-lib.org/articles/special-files.html)

```{r}
#| eval: false 
#| code-fold: false
testthat::it( # <1>
  "Scenario: Create scatter plot
      Given I have launched the movie review exploration app,
      When the scatter plot renders,
      Then the points on the x axis should represent 'Ratings'
      And the points on the y axis should represent 'Length'
      And the points should be colored by 'MPAA' rating
      And the opacity of the points should be set to '0.5'
      And the size of the points should be set to '2'
      And the plot title should be set to 'Enter plot title'",
  code = {
    
    test_logger( # <2>
      start = "snap scatter_plot()", 
      msg = "initial x,y,z,size,alpha")  # <2>

    scatter_inputs <- list(  # <3>
      x = "imdb_rating",
      y = "audience_score",
      z = "mpaa_rating",
      alpha = 0.5,
      size = 2,
      plot_title = "Enter plot title"
    ) # <3>

    vdiffr::expect_doppelganger( # <4>
      title = "Initial x y z axes",
      fig = scatter_plot(movies,
        x_var = scatter_inputs$x,
        y_var = scatter_inputs$y,
        col_var = scatter_inputs$z,
        alpha_var = scatter_inputs$alpha,
        size_var = scatter_inputs$size
      ) +
        ggplot2::labs(
          title = scatter_inputs$plot_title,
          x = stringr::str_replace_all(
            tools::toTitleCase(
              scatter_inputs$x
            ), "_", " "
          ),
          y = stringr::str_replace_all(
            tools::toTitleCase(
              scatter_inputs$y
            ), "_", " "
          )
        ) +
        ggplot2::theme_minimal() +
        ggplot2::theme(legend.position = "bottom")
    ) # <4>

    test_logger( # <5>
      end = "snap scatter_plot()", 
      msg = "initial x,y,z,size,alpha") # <5>
    
  }
)# <1>
```
1.  Test scope  
2.  Log start  
3.  Initial `movies` variable inputs for `x`, `y`, and `z` from UI\
4.  Snapshot with initial values\
5.  Log end  

Test results also return the output from `test_logger()` with the context I've added on what's being tested.

### Snapshots

We also see a warning when the snapshot has been saved in the `tests/testthat/_snaps/` folder the first time the test is run:

```{verbatim}
#| eval: false 
#| code-fold: false
── Warning (test-scatter_plot.R:124:9): 
      Scenario: Create scatter plot
          Given I have launched the movie review exploration app,
          When the scatter plot renders,
          Then the points on the x axis should represent 'Ratings'
          And the points on the y axis should represent 'Length'
          And the points should be colored by 'MPAA' rating
          And the size of the points should be set to '2'
          And the opacity of the points should be set to '0.5' ──
Adding new file snapshot: 'tests/testthat/_snaps/initial-x-y-z-axes.svg'

── Warning (test-scatter_plot.R:186:7): 
      Scenario: Change x, y, color values for plotting
        When I launch the Scatter Plot Data Visualization
        And I select the variable 'Audience Score' for the x-axis
        And I select the variable 'IMDB Rating' for the y-axis
        And I select the variable 'Critics Rating' for the color
        Then the scatter plot should show 'Audience Score' on the x-axis
        And the scatter plot should show 'IMDB Rating' on the y-axis
        And the points on the scatter plot should be colored by 'Critics Rating' ──
Adding new file snapshot: 'tests/testthat/_snaps/updated-x-y-color.svg'
[ FAIL 0 | WARN 2 | SKIP 0 | PASS 2 ]
```

On subsequent runs, this warning will disappear (as long as there are no changes to the `.svg` files). 

```{verbatim}
#| eval: false 
#| code-fold: false
INFO [2023-10-27 10:58:25] [ START snap scatter_plot() = initial x,y,z,size,alpha]
[ FAIL 0 | WARN 1 | SKIP 0 | PASS 3 ]
INFO [2023-10-27 10:58:25] [ END snap scatter_plot() = initial x,y,z,size,alpha]
```

### Comparing graph objects

Below is the output from `diffobj::diffObj()` comparing our custom plotting function (`scatter_plot()`) against a graph built with analogous `ggplot2` code:

```{r}
#| eval: false 
#| code-fold: false
ggp_graph <- ggplot2::ggplot(mtcars, 
              ggplot2::aes(x = mpg, y = disp)) + 
              ggplot2::geom_point(
                ggplot2::aes(color = cyl), 
                             alpha = 0.5, 
                             size = 3)
  
app_graph <- scatter_plot(mtcars, 
                  x_var = "mpg", 
                  y_var = "disp", 
                  col_var = "cyl", 
                  alpha_var = 0.5, 
                  size_var = 3)

diffobj::diffObj(ggp_graph, app_graph)
```

::: column-page-inset-right
::: {#fig-11_tests_diffobj_scatter_plot}
![`diffobj::diffObj()` on graph outputs](img/11_tests_diffobj_scatter_plot.png){width="100%" align="center"}

Graph objects are difficult to use as test objects
:::
:::

The output shows us all the potential points of failure when comparing complex objects like graphs (despite the actual outputs appearing identical), so it's best to limit the number of 'visual unit tests' unless they're absolutely necessary.

I've included additional snapshot tests (`test-text_logo.R`) in the [`A.E-mocks-snapshots` branch of `sap`](https://github.com/mjfrigaard/sap/tree/A.E-mocks-snapshots): 

``` sh
tests/testthat/
    ├── test-scatter_plot.R
    └── test-text_logo.R
```

## Mocks

Test code may rely on external systems, behavior, functions, or objects. To ensure that our unit tests remain fast and focused solely on the functional requirement being tested, it's important to minimize these external dependencies. 

The mocking functions can be used to substitute functions by emulating their behavior within the test scope (in BDD terms, mocks are creating the `Given` conditions).[^tests-mocking-testthat-3e]

[^tests-mocking-testthat-3e]: Test mocking functions are a relatively new addition to `testthat`. Read more in the recent updates to [`testthat`](https://www.tidyverse.org/blog/2023/10/testthat-3-2-0/#mocking)

```{r}
#| label: git_box_A.E-mocks-snapshots2
#| echo: false
#| results: asis
#| eval: true
git_margin_box(
  contents = "launch",
  fig_pw = '65%', 
  branch = "A.E-mocks-snapshots", 
  repo = 'sap')
```

### Example: mocking add-on functions

We'll use `local_mocked_bindings()` from `testthat` to mock the behavior of `rlang::is_installed()`.[^tests-pkg-dev-wrkshp] Instead of real-time computations, mocks return predefined responses to given inputs. Consider the `check_installed()` function below:

[^tests-pkg-dev-wrkshp]: This example comes from the package development masterclass [workshop at `posit::conf(2023)`](https://github.com/posit-conf-2023/pkg-dev-masterclass/tree/main).


```{r}
#| eval: true 
#| code-fold: false
check_installed <- function(package) {
  if (is_installed(package)) {
    return(invisible())
  } else {
    stop("Please install '{package}' before continuing")
  }
}
```

Below is a feature  description for `check_installed()` and two scenarios for each expected behavior:

```{verbatim}
#| eval: false
#| code-fold: false
Feature: Checking if an R package is installed

  Scenario: Checking an installed package
    Given the R package 'base' is installed
    When I call the `check_installed()` function with 'base'
    Then the function should return without any error

  Scenario: Checking an uninstalled package
    Given the R package 'foo' is not installed
    When I call the `check_installed()` function with 'foo'
    Then the function should raise an error with the message
      `Please install 'nonexistent_package' before continuing`
```

The `check_installed()` shouldn't be confused with [`rlang::check_installed()`](https://rlang.r-lib.org/reference/is_installed.html), which checks if a package is installed, and if it isn't, prompts the user install the package using [`pak::pkg_install()`](https://pak.r-lib.org/reference/pkg_install.html). 

Lets review how `is_installed()` behaves with installed and missing packages: 

```{r}
#| code-fold: false
#| collapse: true
rlang::is_installed('foo')
rlang::is_installed('base')
```

The version of `check_installed()` in `sap` will check if a package is installed and return `invisible()` if it is (which, when assigned to an object, evaluates to `NULL`):

```{r}
#| code-fold: false
#| collapse: true
#| error: true
check_installed('base')
```

```{r}
#| code-fold: false
#| collapse: true
#| error: true
x <- check_installed('base')
x
```

If the package is not installed, `check_installed()` prints an error message:

```{r}
#| code-fold: false
#| collapse: true
#| error: true
check_installed('foo')
```

To use mocking with `is_installed()`, we'll use the following syntax: 

```{verbatim}
#| eval: false
#| code-fold: false
local_mocked_bindings(
  {local function} = function(...) {value}
)
```

In this case, `{local function}` is `is_installed()` from `rlang`, and we want to test the two possible `{value}`s (`TRUE`/`FALSE`). 

In the first test, we'll use `expect_error()` to confirm that the error message is returned for an uninstalled package by using `local_mocked_bindings()` and setting the `is_installed()` value to `FALSE`:

```{r}
#| eval: false
#| code-fold: false
describe("Feature: Checking if an R package is installed", {
  
  test_that(
    "Scenario: Checking an uninstalled package
        Given the R package 'foo' is not installed
        When I call the `check_installed()` function with 'foo'
        Then the function should raise an error with the message
        `Please install 'nonexistent_package' before continuing`", {
          
    test_logger(start = "mock is_installed", msg = "FALSE") # <1>
    local_mocked_bindings(is_installed = function(package) FALSE) # <2>
    expect_error(object = check_installed("foo")) # <3>
    test_logger(end = "mock is_installed", msg = "FALSE") # <1>
    
  })
  
})
```
1. Log test `start` and `end`
2. Set `{value}` to `FALSE`   
3. Pass a package we know **is not installed**   


To test installed packages, we'll confirm `check_installed('foo')` with `expect_invisible()`: 

```{r}
#| eval: false
#| code-fold: false
describe("Feature: Checking if an R package is installed", {
  
  test_that(
    "Scenario: Checking an installed package
        Given the R package 'base' is installed
        When I call the `check_installed()` function with 'base'
        Then the function should return without any error", {
          
    test_logger(start = "mock is_installed", msg = "TRUE") # <1>
    local_mocked_bindings(is_installed = function(package) TRUE) # <2>
    expect_invisible(check_installed("base")) # <3>
    test_logger(end = "mock is_installed", msg = "TRUE") # <1>
    
  })
})
```
1. Log test `start` and `end`
2. Set `{value}` to `TRUE`   
3. Pass a package we know **is installed**   

The output from the tests above is provided below: 

```{verbatim}
#| eval: false 
#| code-fold: false
[ FAIL 0 | WARN 0 | SKIP 0 | PASS 0 ]
INFO [2023-10-08 22:59:43] [ START mock is_installed = FALSE]
[ FAIL 0 | WARN 0 | SKIP 0 | PASS 1 ]
INFO [2023-10-08 22:59:43] [ END mock is_installed = FALSE]

INFO [2023-10-08 22:59:43] [ START mock is_installed = TRUE]
[ FAIL 0 | WARN 0 | SKIP 0 | PASS 2 ]
INFO [2023-10-08 22:59:43] [ END mock is_installed = TRUE]
```

### Notes on mocking

The `roxygen2` documentation for `check_installed()` uses the `@importFrom` tag to import `is_installed` and add it to the `sap` namespace (using explicit namespacing alone won't work):

```{r}
#| eval: false 
#| code-fold: false
#' Check if package is installed
#' 
#' @description
#' An example function for demonstrating how to use `testthat`'s
#' mocking functions.
#' 
#' @param package string, name of package
#'
#' @return invisible 
#'
#' @importFrom rlang is_installed # <1>
#'
#' @export
#'
#' @examples
#' check_installed("foo")
#' check_installed("base")
```
1. Fortunately we already included rlang in our `DESCRIPTION` file for `.data` in `scatter_plot()`




```{r}
#| label: co_box_recap_userData
#| echo: false
#| results: asis
#| eval: true
co_box(
  color = "g", 
  look = "default", hsize = "1.10", size = "1.05",
  header = "Recap: test snapshots & mocks",
  contents = "

[**Snapshots**]{style='font-size: 1.30em'}
  
**`vdiffr`**: create graph snapshots with the `expect_doppelganger()` function from [`vdiffr`](https://vdiffr.r-lib.org/reference/)
  
As stated before, snapshots are brittle and can produce false negatives test failures (i.e., due to inconsequential changes in the graph) when comparing a new graph to the baseline image.
  
[**Test mocks**]{style='font-size: 1.30em'}
  
Using `testthat`'s mocking functions allow us to craft unit tests that evaluate a single, specific behavior. Read more about mocking functions on the [`testthat` webite](https://testthat.r-lib.org/reference/local_mocked_bindings.html).
  
  ",
  fold = FALSE
)
```


```{r}
#| label: git_contrib_box
#| echo: false
#| results: asis
#| eval: true
git_contrib_box()
```