Improve reporter documentation

Fixes #657

Author: hadley

DESCRIPTION

@@ -50,6 +50,7 @@ Collate:
     'context.R'
     'describe.R'
     'evaluate-promise.R'
+    'example.R'
     'expect-comparison.R'
     'expect-equality.R'
     'expect-inheritance.R'

NAMESPACE

@@ -154,6 +154,8 @@ export(test_path)
 export(test_rd)
 export(test_that)
 export(testing_package)
+export(testthat_example)
+export(testthat_examples)
 export(throws_error)
 export(try_again)
 export(use_catch)

NEWS.md

@@ -1,5 +1,11 @@
 # testthat (development version)
 
+* New `testthat_examples()` and `testthat_example()` make it easy to access
+  new test files bundled with the package. These are used in various examples
+  to make it easier to understand how to use the package in novel ways.
+  
+* Documentation of reporters has been considerably improved (#657).
+
 * Expectation object always contains the failure message, even when succesful 
   (#836)
 

R/example.R

@@ -0,0 +1,24 @@
+#' Retrieve paths to built-in example test files
+#'
+#' `testthat_examples()` retrieves path to directory of test files,
+#' `testthat_example()` retrieves path to a single test file.
+#'
+#' @keywords internal
+#' @param filename Name of test file
+#' @export
+#' @examples
+#' dir(testthat_examples())
+#' testthat_example("success")
+testthat_examples <- function() {
+  system.file("examples", package = "testthat")
+}
+
+#' @export
+#' @rdname testthat_examples
+testthat_example <- function(filename) {
+  system.file(
+    "examples", paste0("test-", filename, ".R"),
+    package = "testthat",
+    mustWork = TRUE
+  )
+}

R/reporter-zzz.R

@@ -1,17 +1,25 @@
 #' @include reporter-stop.R
 NULL
 
-#' Get/set reporter; execute code in specified reporter.
+#' Get and set active reporter.
 #'
-#' Changes global reporter to that specified, runs code and the returns
-#' global reporter back to previous value.
+#' `get_reporter()` and `set_reporter()` access and modify the current "active"
+#' reporter. Generally, these functions should not be called directly; instead
+#' use `with_reporter()` to temporarily change, then reset, the active reporter.
 #'
-#' The `with_reporter()` function returns the reporter that has been used
-#' for running the code.
 #'
+#' @inheritParams test_file
+#' @param reporter Reporter to use to summarise output. Can be supplied
+#'   as a string (e.g. "summary") or as an R6 object
+#'   (e.g. `SummaryReporter$new()`).
+#'
+#'   See [Reporter] for more details and a list of built-in reporters.
+#' @param code Code to execute.
+#' @return `with_reporter()` invisible returns the reporter active when `code`
+#'   was evaluated.
+#' @param start_end_reporter Should the reporters `start_reporter()` and
+#'   `end_reporter()` methods be called? For expert use only.
 #' @keywords internal
-#' @param reporter test reporter to use
-#' @param code code block to execute
 #' @name reporter-accessors
 NULL
 
@@ -36,7 +44,6 @@ get_reporter <- function() {
 }
 
 #' @rdname reporter-accessors
-#' @param start_end_reporter whether to start and end the reporter
 #' @export
 with_reporter <- function(reporter, code, start_end_reporter = TRUE) {
   reporter <- find_reporter(reporter)

R/reporter.R

@@ -1,17 +1,32 @@
-#' Managing test reporting
+#' Manage test reporting
 #'
 #' The job of a reporter is to aggregate the results from files, tests, and
-#' expectations and display in some informative way.
+#' expectations and display them in an informative way. Every testtthat function
+#' that runs multiple tests provides a `reporter` argument which you can
+#' use to override the default (which is selected by [default_reporter()]).
+#' Typically this will
 #'
-#' Do not clone directly from this object - children should implement all
-#' methods.
+#' You only need to use this `Reporter` object directly if you are creating
+#' a new reporter. Currently, creating new Reporters is undocumented,
+#' so if you want to create your own, you'll need to make sure that you're
+#' familiar with [R6](https://adv-r.hadley.nz/R6.html) and then need read the
+#' source code for a few.
 #'
 #' @keywords internal
 #' @export
 #' @export Reporter
 #' @aliases Reporter
 #' @importFrom R6 R6Class
 #' @family reporters
+#' @examples
+#' path <- testthat_example("success")
+#'
+#' # The default reporter - doesn't display well in examples because
+#' # it's designed to work in an interactive console.
+#' test_file(path)
+#'
+#' # Override the default by supplying the name of a reporter
+#' test_file(path, reporter = "minimal")
 Reporter <- R6::R6Class("Reporter",
   public = list(
     start_reporter = function() {},
@@ -72,22 +87,10 @@ Reporter <- R6::R6Class("Reporter",
   )
 )
 
-fancy_line <- function(x) {
-  if (!l10n_info()$`UTF-8`) {
-    return(x)
-  }
-
-  switch(x,
-    "-" = "\u2500",
-    "=" = "\u2550",
-    x
-  )
-}
-
-#' Retrieve the default reporter.
+#' Retrieve the default reporter
 #'
 #' The defaults are:
-#' * [SummaryReporter] for interactive; override with `testthat.default_reporter`
+#' * [ProgressReporter] for interactive; override with `testthat.default_reporter`
 #' * [CheckReporter] for R CMD check; override with `testthat.default_check_reporter`
 #'
 #' @export

R/source.R

@@ -1,14 +1,13 @@
-#' Source a file, directory, or all helpers.
+#' Source a file, directory of files, or various important subsets
 #'
-#' The expectation is that the files can be sourced in alphabetical order.
-#' Helper scripts are R scripts accompanying test scripts but prefixed by
-#' `helper`. These scripts are run once before the tests are run.
+#' These are used by [test_dir()] and friends
 #'
-#' @param path Path to tests
-#' @param pattern Regular expression used to filter files
+#' @inheritSection test_dir Test files
+#' @param path Path to files.
+#' @param pattern Regular expression used to filter files.
 #' @param env Environment in which to evaluate code.
 #' @param chdir Change working directory to `dirname(path)`?
-#' @param encoding Deprecated
+#' @param encoding Deprecated.
 #' @param wrap Automatically wrap all code within [test_that()]? This ensures
 #'   that all expectations are reported, even if outside a test block.
 #' @export

R/test-directory.R

@@ -41,25 +41,26 @@
 #' test_check("yourpackage")
 #' ```
 #'
-#' @param path path to tests
-#' @param package   package name
+#' @param path Path to directory containing tests.
+#' @param package Name of installed package.
 #' @param filter If not `NULL`, only tests with file names matching this
-#'   regular expression will be executed.  Matching will take on the file
+#'   regular expression will be executed. Matching be performed on the file
 #'   name after it has been stripped of `"test-"` and `".R"`.
 #' @param ... Additional arguments passed to [grepl()] to control filtering.
 #' @param stop_on_failure If `TRUE`, throw an error if any tests fail.
 #' @param stop_on_warning If `TRUE`, throw an error if any tests generate
 #'   warnings.
 #' @inheritParams test_file
-#' @return The results of the reporter function on all test results.
-#' @return The results as a "testthat_results" (list)
+#' @return A list of test results.
 #' @export
 #' @examples
-#' \dontrun{test_package("testthat")}
+#' test_dir(testthat_examples(), reporter = "summary")
+#' test_dir(testthat_examples(), reporter = "minimal")
 test_dir <- function(path,
                      filter = NULL,
                      reporter = default_reporter(),
-                     env = test_env(), ...,
+                     env = test_env(),
+                     ...,
                      encoding = "unknown",
                      load_helpers = TRUE,
                      stop_on_failure = FALSE,

R/test-files.R

@@ -81,21 +81,37 @@ find_test_scripts <- function(path, filter = NULL, invert = FALSE, ...) {
   filter_test_scripts(files, filter, invert, ...)
 }
 
-#' Run all tests in specified file.
+#' Run all tests in specified file
 #'
-#' @param path path to file
-#' @param reporter reporter to use
-#' @param env environment in which to execute the tests
+#' Execute code in the specified file, displaying results using a `reporter`.
+#' Use this function when you want to run a single file's worth of tests.
+#' You are responsible for ensuring that the functions to test are available
+#' in the global environment.
+#'
+#' @param path Path to file.
+#' @param env Environment in which to execute the tests. Expert use only.
 #' @param load_helpers Source helper files before running the tests?
-#' @param encoding File encoding, default is "unknown"
-#' `unknown`.
+#'   See [source_test_helpers()] for more details.
+#' @param encoding Deprecated. All files now assumed to be UTF-8.
 #' @inheritParams with_reporter
 #' @inheritParams source_file
-#' @return the results as a "testthat_results" (list)
+#' @return Invisibily, a list with one element for each test.
 #' @export
-test_file <- function(path, reporter = default_reporter(), env = test_env(),
-                      start_end_reporter = TRUE, load_helpers = TRUE,
-                      encoding = "unknown", wrap = TRUE) {
+#' @examples
+#' path <- testthat_example("success")
+#' test_file(path, reporter = "minimal")
+#'
+#' # test_file() invisibly returns a list, with one element for each test.
+#' # This can be useful if you want to compute on your test results.
+#' out <- test_file(path, reporter = "minimal")
+#' str(out[[1]])
+test_file <- function(path,
+                      reporter = default_reporter(),
+                      env = test_env(),
+                      start_end_reporter = TRUE,
+                      load_helpers = TRUE,
+                      encoding = "unknown",
+                      wrap = TRUE) {
   library(testthat)
 
   if (!file.exists(path)) {

inst/examples/test-failure.R

@@ -0,0 +1,9 @@
+plus <- function(x, y) 1 + 1
+
+test_that("one plus one is two", {
+  expect_equal(plus(1, 1), 2)
+})
+
+test_that("two plus two is four", {
+  expect_equal(plus(2, 2), 4)
+})

inst/examples/test-success.R

@@ -0,0 +1,16 @@
+test_that("one plus one is two", {
+  expect_equal(1 + 1, 2)
+})
+
+test_that("you can skip tests if needed", {
+  skip("This tests hasn't been written yet")
+})
+
+test_that("some tests have warnings", {
+  expect_equal(log(-1), NaN)
+})
+
+test_that("some more successes just to pad things out", {
+  expect_true(TRUE)
+  expect_false(FALSE)
+})