Use this function in your testthat test files, to test cli output. It requires testthat edition 3, and works best with snapshot tests.

test_that_cli(desc, code, configs = NULL)

Arguments

desc

Test description, passed to testthat::test_that(), after appending the name of the cli configuration to it.

code

Test code, it is modified to set up the cli config, and then passed to testthat::test_that()

configs

cli configurations to test code with. The default is NULL, which includes all possible configurations. It can also be a character vector, to restrict the tests to some configurations only. See available configurations below.

Details

test_that_cli() calls testthat::test_that() multiple times, with different cli configurations. This makes it simple to test cli output with and without ANSI colors, with and without Unicode characters.

Currently available configurations:

  • plain: no ANSI colors, ASCII characters only.

  • ansi: ANSI colors, ASCII characters only.

  • unicode: no ANSI colors, Unicode characters.

  • fancy; ANSI colors, Unicode characters.

See examples below and in cli's own tests, e.g. in https://github.com/cran/cli/blob/master/tests/testthat and the corresponding snapshots at https://github.com/cran/cli/tree/master/tests/testthat/_snaps

Importtant note regarding Windows

Because of base R's limitation to record Unicode characters on Windows, we suggest that you record your snapshots on Unix, or you restrict your tests to ASCII configurations.

Unicode tests on Windows are automatically skipped by testthat currently.

Examples

# testthat cannot record or compare snapshots when you run these # examples interactively, so you might want to copy them into a test # file # Default configurations cli::test_that_cli("success", { expect_snapshot({ cli::cli_alert_success("wow") }) })
#> ── Error (<text>:7:3): success [plain] ───────────────────────────────────────── #> Error: could not find function "expect_snapshot" #> #> ── Error (<text>:7:3): success [ansi] ────────────────────────────────────────── #> Error: could not find function "expect_snapshot" #> #> ── Error (<text>:7:3): success [unicode] ─────────────────────────────────────── #> Error: could not find function "expect_snapshot" #> #> ── Error (<text>:7:3): success [fancy] ───────────────────────────────────────── #> Error: could not find function "expect_snapshot" #>
#> [[1]] #> [1] FALSE #> #> [[2]] #> [1] FALSE #> #> [[3]] #> [1] FALSE #> #> [[4]] #> [1] FALSE #>
# Only use two configurations, because this output does not have colors cli::test_that_cli(configs = c("plain", "unicode"), "cat_bullet", { expect_snapshot({ cli::cat_bullet(letters[1:5]) }) })
#> ── Error (<text>:14:3): cat_bullet [plain] ───────────────────────────────────── #> Error: could not find function "expect_snapshot" #> #> ── Error (<text>:14:3): cat_bullet [unicode] ─────────────────────────────────── #> Error: could not find function "expect_snapshot" #>
#> [[1]] #> [1] FALSE #> #> [[2]] #> NULL #> #> [[3]] #> [1] FALSE #> #> [[4]] #> NULL #>
# You often need to evaluate all cli calls of a test case in the same # environment. Use `local()` to do that: cli::test_that_cli("theming", { expect_snapshot(local({ cli::cli_div(theme = list(".alert" = list(before = "!!! "))) cli::cli_alert("wow") })) })
#> ── Error (<text>:22:3): theming [plain] ──────────────────────────────────────── #> Error: could not find function "expect_snapshot" #> #> ── Error (<text>:22:3): theming [ansi] ───────────────────────────────────────── #> Error: could not find function "expect_snapshot" #> #> ── Error (<text>:22:3): theming [unicode] ────────────────────────────────────── #> Error: could not find function "expect_snapshot" #> #> ── Error (<text>:22:3): theming [fancy] ──────────────────────────────────────── #> Error: could not find function "expect_snapshot" #>
#> [[1]] #> [1] FALSE #> #> [[2]] #> [1] FALSE #> #> [[3]] #> [1] FALSE #> #> [[4]] #> [1] FALSE #>