Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ThinkR-open/testdown
Turn your 'testthat' results into a Bookdown.
https://github.com/ThinkR-open/testdown
Last synced: 9 days ago
JSON representation
Turn your 'testthat' results into a Bookdown.
- Host: GitHub
- URL: https://github.com/ThinkR-open/testdown
- Owner: ThinkR-open
- License: other
- Created: 2018-12-06T20:38:04.000Z (about 6 years ago)
- Default Branch: main
- Last Pushed: 2023-04-11T06:58:27.000Z (over 1 year ago)
- Last Synced: 2024-11-28T21:53:04.184Z (14 days ago)
- Language: R
- Homepage: https://thinkr-open.github.io/testdown/
- Size: 2.5 MB
- Stars: 25
- Watchers: 4
- Forks: 1
- Open Issues: 6
-
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- jimsghstars - ThinkR-open/testdown - Turn your 'testthat' results into a Bookdown. (R)
README
---
output: github_document
---
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "",
fig.path = "man/figures/README-",
out.width = "100%",
eval = FALSE
)
# Copy reference/images to man/images
# reference folder is required to work with pkgdown
if (!dir.exists("man/figures")) {dir.create("man/figures")}
file.copy(list.files("reference/figures", full.names = TRUE),
"man/figures", overwrite = TRUE)
```
# testdown 
[](https://www.tidyverse.org/lifecycle/#maturing)
[](https://github.com/ThinkR-open/testdown/actions/workflows/R-CMD-check.yaml)
The goal of `{testdown}` is to generate a bookdown report of `{testthat}` results
## Installation
You can install the dev version of `{testdown}`
- from r-universe
```r
# Enable universe(s) by thinkr-open
options(repos = c(
thinkropen = 'https://thinkr-open.r-universe.dev',
CRAN = 'https://cloud.r-project.org'))
# Install some packages
install.packages('testdown')
```
- from GitHub with:
``` r
remotes::install_github("ThinkR-open/testdown")
```
## About
This package has two exported functions:
### `test_down()`
This function turns the `{testthat}` results into a `{bookdown}` report.
It takes:
+ A `project_name`, which is the name you want to give to the project.
The default is `NULL`, which will then be converted to `basename(here::here())`.
+ An `author`, if you want your report to be have an author name.
Default is NULL, and then the report won't have any name on it.
+ `pkg`, the path to the package that will be documented.
Default is `here::here()`
+ `environment`, a name for the testing environment.
Default is `here::here()`
+ `book_path`, the folder where you want the `{bookdown}` report to be created.
Default is `"tests/testdown"`.
+ `with_help` Should the help appendix be added?
Default is `TRUE`.
+ `open` Should the report be opened once compiled?
Default is `interactive()`.
### `test_down_example()`
This function will compile the report for an example package contained inside `{testdown}`.
## Custom `{testdown}` roxygen tags
You can add a `description` to your tests using the roxygen tag `@description`.
Note that this test __must__ be on the line just before the expectation.
Here is an example:
```{r eval = FALSE}
test_that("hello_world() works", {
#' @description Testing that hello_world("colin") returns "Hello world, my name is colin!"
expect_equal(hello_world("colin"), "Hello world, my name is colin!")
#' @description Testing that hello_world("colin") returns a character vector
expect_is(hello_world("colin"), "character")
#' @description Testing that hello_world("colin") has World in it
expect_match(hello_world("colin"), "World")
#' @description Testing that hello_world("colin") has Hello in it
expect_match(hello_world("colin"), "Hello")
})
```
```{r child = "inst/testdownhelp.md", eval = TRUE}
```
## Writing custom expectation
For reliable results, all expectations should start by `expect`, notably if you need to count the skipped tests.
In other words, the skipped expectations count relies on counting all the functions starting with `expect`, so naming custom expectation differently will prevent this count from being correct.
## Known limitations
`{testdown}` report relies on `{testthat}` and the results are based on these outputs.
Here are known example of results that will be discarded by `{testthat}` and hence will make `{testdown}` behave in a weird way.
+ Using `{withr}`
```{r}
test_that("Files exist", {
with_dir(
"new/dir",
{
#' @description Checking that style.css is created
expect_file_exists("tests/testdown/style.css")
#' @description Checking that _bookdown.yml is created
expect_file_exists("tests/testdown/_bookdown.yml")
#' @description Checking that _output.yml is created
expect_file_exists("tests/testdown/_output.yml")
}
)
})
```
As testthat doesn't count the expectations from `with_dir`, this will make the `{testdown}` result weird.
Always add the expectations at the top level of your test_that.
+ Loops
Same goes with for loops:
```{r eval = FALSE}
for (i in names(df)){
#' @description Checking the names of the output are correct
expect_true(
i %in% c(
"context",
"test",
"expectation",
"description",
"location",
"test_time",
"result",
"file",
"message"
)
)
}
```
If ever you use this format, `{testthat}` won't catch the tests, so they won't be reported.
+ HTML expectations
As testdown render the text straight in html, if your expecatation contains html, it will break the rendering.
For example, the following test will break the rendering:
```{r}
expect_match(
tag,
"
this
"
)
```
## Sponsor
The development of this package has been sponsored by:
## CoC
Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md).
By participating in this project you agree to abide by its terms.