comparisons.qmd

# Comparisons 

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

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

Comparisons are the backbone of testing. Exploring the mechanics of how tests perform these comparisons (i.e., the underlying package(s)) can save you from surprising results. 

For example, `expect_equal()` compares whatever is passed to the `observed` and `expected` arguments with the [`waldo` package](https://www.tidyverse.org/blog/2021/08/waldo-0-3-0/), with some help from [`diffobj`](https://github.com/brodieG/diffobj).

```{r}
#| eval: true 
#| code-fold: false
#| collapse: true 
#| message: false 
#| warning: false
library(waldo)
library(diffobj)
library(tibble)
```

### [`waldo::compare()`]{style="font-size: 1.05em;"}

If you'd like a preview of a comparison before writing a formal test, you can pass the your `observed` and `expected` objects to `compare()`[^waldo-compare-args] 

[^waldo-compare-args]: Be mindful of the difference in arguments between expectation functions (i.e., `expect_equal()`) and `compare()`

```{r}
#| eval: true 
#| include: false
old <- tibble(
  chr = LETTERS[2:4],
  num = as.double(c(1.0, 2.0, 3.0)),
  fct = factor(c("low", "med", "high"), 
        levels = c("low", "med", "high"), 
        labels = c("L", "M", "H"),
        ordered = TRUE)
)
new <- data.frame(
  CHR = LETTERS[2:4],
  num = as.integer(c(1, 2, 3)),
  fct = factor(c("low", "med", "high"),
        levels = c("low", "med", "high"),
        labels = c("low", "med", "high"))
)
```


For example, suppose we have two objects: 

::::{layout="[50, 50]"}

```r
old
## # A tibble: 3 × 3
##   chr     num fct  
##   <chr> <dbl> <ord>
## 1 B         1 L    
## 2 C         2 M    
## 3 D         3 H
```

```r
new
## # A tibble: 3 × 3
##   CHR     num fct  
##   <chr> <int> <fct>
## 1 B         1 low  
## 2 C         2 med  
## 3 D         3 high
```

::::

The outputs below are example outputs from `waldo::compare()`:


```{r}
#| eval: true 
#| code-fold: false
#| collapse: true
compare(
  x = old, # <1>
  y = old) # <1> 
```
1. Comparing identical objects


```{r}
#| eval: true 
#| code-fold: false
#| collapse: true
compare(
  x = old, # <1>
  y = new) # <1>
```
1. Comparing different objects


`compare()` displays the differences in classes, names, and any individual value differences. 

### [`diffobj::diffObj()`]{style="font-size: 1.05em;"}

If you're using Posit Workbench, the [`diffobj` package](https://github.com/brodieG/diffobj) has a colorful display for making comparisons in the IDE. 

The differences can be displayed vertically with `diffobj::diffObj()`:

:::: {layout="[30, 70]"}

```r
diffObj(
  old, 
  new)
```

![Viewer ouput from `diffobj::diffObj()`](img/08_tests_diffobj.png){#fig-08_tests_diffobj width='100%' align='left'}

::::

If you want to view the structure (`str()`) differences, you can use `diffobj::diffStr()`:

:::: {layout="[30, 70]"}

```r
diffStr(
  old, 
  new)
```

![Viewer ouput from `diffobj::diffStr()`](img/08_tests_diffstr.png){#fig-08_tests_diffobj width='100%' align='center'}

::::

After viewing the `old` vs `new` comparisons with `waldo` and `diffobj`, you should notice similarities and differences in the results from `testthat`[^compare-tolerance]

[^compare-tolerance]: The results from `testthat` don't include the differences between `old$num` and `new$num`. This is due to the `tolerance` argument, which can be adjusted in both functions.

```{verbatim}
#| eval: false 
#| code-fold: false
[ FAIL 1 | WARN 0 | SKIP 0 | PASS 0 ]

── Failure (test-old_vs_new.R:17:3): old vs. new ───────────────────────────────
`new` (`actual`) not equal to `old` (`expected`).

`class(actual)`:   "data.frame"                   
`class(expected)`: "tbl_df"     "tbl" "data.frame"

`names(actual)`:   "CHR" "num" "fct"
`names(expected)`: "chr" "num" "fct"

`actual$CHR` is a character vector ('B', 'C', 'D')
`expected$CHR` is absent

`class(actual$fct)`:   "factor"          
`class(expected$fct)`: "ordered" "factor"

`levels(actual$fct)`:   "low" "med" "high"
`levels(expected$fct)`: "L"   "M"   "H"   

`actual$chr` is absent
`expected$chr` is a character vector ('B', 'C', 'D')
[ FAIL 1 | WARN 0 | SKIP 0 | PASS 0 ]
```