[](https://cran.r-project.org/package=testthat)
[](https://github.com/r-lib/testthat/actions)
[](https://app.codecov.io/gh/r-lib/testthat?branch=main)
## Overview
Testing your code can be painful and tedious, but it greatly increases
the quality of your code. **testthat** tries to make testing as fun as
possible, so that you get a visceral satisfaction from writing tests.
Testing should be addictive, so you do it all the time. To make that
happen, testthat:
- Provides functions that make it easy to describe what you expect a
function to do, including catching errors, warnings, and messages.
- Easily integrates in your existing workflow, whether it’s informal
testing on the command line, building test suites, or using R CMD
check.
- Displays test progress visually, showing a pass, fail, or error for
every expectation. If you’re using the terminal or a recent version
of RStudio, it’ll even colour the output.
testthat draws inspiration from the xUnit family of testing packages, as
well as from many of the innovative ruby testing libraries, like
[rspec](https://rspec.info/), [testy](https://github.com/ahoward/testy),
[bacon](https://github.com/leahneukirchen/bacon) and
[cucumber](https://cucumber.io).
testthat is the most popular unit testing package for R and is used by
thousands of CRAN packages.
If you’re not familiar with testthat, the [testing
chapter](https://r-pkgs.org/tests.html) in [R
packages](https://r-pkgs.org) gives a good overview, along with workflow
advice and concrete examples.
## Installation
``` r
# Install the released version from CRAN
install.packages("testthat")
# Or the development version from GitHub:
# install.packages("devtools")
devtools::install_github("r-lib/testthat")
```
## Usage
The easiest way to get started is with
[usethis](https://github.com/r-lib/usethis). Assuming you’re in a
package directory, just run `usethis::use_test("name")` to create a test
file, and set up all the other infrastructure you need. If you’re using
RStudio, press Cmd/Ctrl + Shift + T (or run `devtools::test()` if not)
to run all the tests in a package.
testthat/man/ 0000755 0001762 0000144 00000000000 14172347710 012673 5 ustar ligges users testthat/man/testthat-package.Rd 0000644 0001762 0000144 00000002246 14164710002 016404 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/testthat-package.R
\docType{package}
\name{testthat-package}
\alias{testthat}
\alias{testthat-package}
\title{An R package to make testing fun!}
\description{
Try the example below. Have a look at the references and learn more
from function documentation such as \code{\link[=test_that]{test_that()}}.
}
\section{Options}{
\itemize{
\item \code{testthat.use_colours}: Should the output be coloured? (Default: \code{TRUE}).
\item \code{testthat.summary.max_reports}: The maximum number of detailed test
reports printed for the summary reporter (default: 10).
\item \code{testthat.summary.omit_dots}: Omit progress dots in the summary reporter
(default: \code{FALSE}).
}
}
\seealso{
Useful links:
\itemize{
\item \url{https://testthat.r-lib.org}
\item \url{https://github.com/r-lib/testthat}
\item Report bugs at \url{https://github.com/r-lib/testthat/issues}
}
}
\author{
\strong{Maintainer}: Hadley Wickham \email{hadley@rstudio.com}
Other contributors:
\itemize{
\item RStudio [copyright holder, funder]
\item R Core team (Implementation of utils::recover()) [contributor]
}
}
\keyword{internal}
testthat/man/local_snapshotter.Rd 0000644 0001762 0000144 00000000701 14167646004 016706 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/snapshot-reporter.R
\name{local_snapshotter}
\alias{local_snapshotter}
\title{Instantiate local snapshotting context}
\usage{
local_snapshotter(
snap_dir = NULL,
cleanup = FALSE,
fail_on_new = FALSE,
.env = parent.frame()
)
}
\description{
Needed if you want to run snapshot tests outside of the usual testthat
framework For expert use only.
}
\keyword{internal}
testthat/man/auto_test.Rd 0000644 0001762 0000144 00000003006 14164710002 015155 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/auto-test.R
\name{auto_test}
\alias{auto_test}
\title{Watches code and tests for changes, rerunning tests as appropriate.}
\usage{
auto_test(
code_path,
test_path,
reporter = default_reporter(),
env = test_env(),
hash = TRUE
)
}
\arguments{
\item{code_path}{path to directory containing code}
\item{test_path}{path to directory containing tests}
\item{reporter}{test reporter to use}
\item{env}{environment in which to execute test suite.}
\item{hash}{Passed on to \code{\link[=watch]{watch()}}. When FALSE, uses less accurate
modification time stamps, but those are faster for large files.}
}
\description{
The idea behind \code{auto_test()} is that you just leave it running while
you develop your code. Everytime you save a file it will be automatically
tested and you can easily see if your changes have caused any test
failures.
}
\details{
The current strategy for rerunning tests is as follows:
\itemize{
\item if any code has changed, then those files are reloaded and all tests
rerun
\item otherwise, each new or modified test is run
}
In the future, \code{auto_test()} might implement one of the following more
intelligent alternatives:
\itemize{
\item Use codetools to build up dependency tree and then rerun tests only
when a dependency changes.
\item Mimic ruby's autotest and rerun only failing tests until they pass,
and then rerun all tests.
}
}
\seealso{
\code{\link[=auto_test_package]{auto_test_package()}}
}
\keyword{debugging}
testthat/man/expect_setequal.Rd 0000644 0001762 0000144 00000003012 14164710002 016336 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expect-setequal.R
\name{expect_setequal}
\alias{expect_setequal}
\alias{expect_mapequal}
\title{Does code return a vector containing the expected values?}
\usage{
expect_setequal(object, expected)
expect_mapequal(object, expected)
}
\arguments{
\item{object}{Computation and value to compare it to.
Both arguments supports limited unquoting to make it easier to generate
readable failures within a function or for loop. See \link{quasi_label} for
more details.}
\item{expected}{Computation and value to compare it to.
Both arguments supports limited unquoting to make it easier to generate
readable failures within a function or for loop. See \link{quasi_label} for
more details.}
}
\description{
\itemize{
\item \code{expect_setequal(x, y)} tests that every element of \code{x} occurs in \code{y},
and that every element of \code{y} occurs in \code{x}.
\item \code{expect_mapequal(x, y)} tests that \code{x} and \code{y} have the same names, and
that \code{x[names(y)]} equals \code{y}.
}
}
\details{
Note that \code{expect_setequal()} ignores names, and you will be warned if both
\code{object} and \code{expected} have them.
}
\examples{
expect_setequal(letters, rev(letters))
show_failure(expect_setequal(letters[-1], rev(letters)))
x <- list(b = 2, a = 1)
expect_mapequal(x, list(a = 1, b = 2))
show_failure(expect_mapequal(x, list(a = 1)))
show_failure(expect_mapequal(x, list(a = 1, b = "x")))
show_failure(expect_mapequal(x, list(a = 1, b = 2, c = 3)))
}
testthat/man/reporter-accessors.Rd 0000644 0001762 0000144 00000002175 14164710002 017001 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter-zzz.R
\name{reporter-accessors}
\alias{reporter-accessors}
\alias{set_reporter}
\alias{get_reporter}
\alias{with_reporter}
\title{Get and set active reporter.}
\usage{
set_reporter(reporter)
get_reporter()
with_reporter(reporter, code, start_end_reporter = TRUE)
}
\arguments{
\item{reporter}{Reporter to use to summarise output. Can be supplied
as a string (e.g. "summary") or as an R6 object
(e.g. \code{SummaryReporter$new()}).
See \link{Reporter} for more details and a list of built-in reporters.}
\item{code}{Code to execute.}
\item{start_end_reporter}{Should the reporters \code{start_reporter()} and
\code{end_reporter()} methods be called? For expert use only.}
}
\value{
\code{with_reporter()} invisible returns the reporter active when \code{code}
was evaluated.
}
\description{
\code{get_reporter()} and \code{set_reporter()} access and modify the current "active"
reporter. Generally, these functions should not be called directly; instead
use \code{with_reporter()} to temporarily change, then reset, the active reporter.
}
\keyword{internal}
testthat/man/context_start_file.Rd 0000644 0001762 0000144 00000000502 14164710002 017044 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/context.R
\name{context_start_file}
\alias{context_start_file}
\title{Start test context from a file name}
\usage{
context_start_file(name)
}
\arguments{
\item{name}{file name}
}
\description{
For use in external reporters
}
\keyword{internal}
testthat/man/expect_vector.Rd 0000644 0001762 0000144 00000002315 14164710002 016022 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expect-vector.R
\name{expect_vector}
\alias{expect_vector}
\title{Does code return a vector with the expected size and/or prototype?}
\usage{
expect_vector(object, ptype = NULL, size = NULL)
}
\arguments{
\item{object}{Object to test.
Supports limited unquoting to make it easier to generate readable failures
within a function or for loop. See \link{quasi_label} for more details.}
\item{ptype}{(Optional) Vector prototype to test against. Should be a
size-0 (empty) generalised vector.}
\item{size}{(Optional) Size to check for.}
}
\description{
\code{expect_vector()} is a thin wrapper around \code{\link[vctrs:vec_assert]{vctrs::vec_assert()}}, converting
the results of that function in to the expectations used by testthat. This
means that it used the vctrs of \code{ptype} (prototype) and \code{size}. See
details in \url{https://vctrs.r-lib.org/articles/type-size.html}
}
\examples{
if (requireNamespace("vctrs") && packageVersion("vctrs") > "0.1.0.9002") {
expect_vector(1:10, ptype = integer(), size = 10)
show_failure(expect_vector(1:10, ptype = integer(), size = 5))
show_failure(expect_vector(1:10, ptype = character(), size = 5))
}
}
testthat/man/quasi_label.Rd 0000644 0001762 0000144 00000003315 14164710002 015432 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/quasi-label.R
\name{quasi_label}
\alias{quasi_label}
\title{Quasi-labelling}
\usage{
quasi_label(quo, label = NULL, arg = "quo")
}
\arguments{
\item{quo}{A quosure created by \code{rlang::enquo()}.}
\item{label}{An optional label to override the default. This is
only provided for internal usage. Modern expectations should not
include a \code{label} parameter.}
\item{arg}{Argument name shown in error message if \code{quo} is missing.}
}
\value{
A list containing two elements:
\item{val}{The evaluate value of \code{quo}}
\item{lab}{The quasiquoted label generated from \code{quo}}
}
\description{
The first argument to every \code{expect_} function can use unquoting to
construct better labels. This makes it easy to create informative labels when
expectations are used inside a function or a for loop. \code{quasi_label()} wraps
up the details, returning the expression and label.
}
\section{Limitations}{
Because all \code{expect_} function use unquoting to generate more informative
labels, you can not use unquoting for other purposes. Instead, you'll need
to perform all other unquoting outside of the expectation and only test
the results.
}
\examples{
f <- function(i) if (i > 3) i * 9 else i * 10
i <- 10
# This sort of expression commonly occurs inside a for loop or function
# And the failure isn't helpful because you can't see the value of i
# that caused the problem:
show_failure(expect_equal(f(i), i * 10))
# To overcome this issue, testthat allows you to unquote expressions using
# !!. This causes the failure message to show the value rather than the
# variable name
show_failure(expect_equal(f(!!i), !!(i * 10)))
}
\keyword{internal}
testthat/man/watch.Rd 0000644 0001762 0000144 00000002036 13171137773 014275 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/watcher.R
\name{watch}
\alias{watch}
\title{Watch a directory for changes (additions, deletions & modifications).}
\usage{
watch(path, callback, pattern = NULL, hash = TRUE)
}
\arguments{
\item{path}{character vector of paths to watch. Omit trailing backslash.}
\item{callback}{function called everytime a change occurs. It should
have three parameters: added, deleted, modified, and should return
TRUE to keep watching, or FALSE to stop.}
\item{pattern}{file pattern passed to \code{\link[=dir]{dir()}}}
\item{hash}{hashes are more accurate at detecting changes, but are slower
for large files. When FALSE, uses modification time stamps}
}
\description{
This is used to power the \code{\link[=auto_test]{auto_test()}} and
\code{\link[=auto_test_package]{auto_test_package()}} functions which are used to rerun tests
whenever source code changes.
}
\details{
Use Ctrl + break (windows), Esc (mac gui) or Ctrl + C (command line) to
stop the watcher.
}
\keyword{internal}
testthat/man/auto_test_package.Rd 0000644 0001762 0000144 00000001307 14164710002 016632 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/auto-test.R
\name{auto_test_package}
\alias{auto_test_package}
\title{Watches a package for changes, rerunning tests as appropriate.}
\usage{
auto_test_package(pkg = ".", reporter = default_reporter(), hash = TRUE)
}
\arguments{
\item{pkg}{path to package}
\item{reporter}{test reporter to use}
\item{hash}{Passed on to \code{\link[=watch]{watch()}}. When FALSE, uses less accurate
modification time stamps, but those are faster for large files.}
}
\description{
Watches a package for changes, rerunning tests as appropriate.
}
\seealso{
\code{\link[=auto_test]{auto_test()}} for details on how method works
}
\keyword{debugging}
testthat/man/test_that.Rd 0000644 0001762 0000144 00000002253 14164710002 015150 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/test-that.R
\name{test_that}
\alias{test_that}
\title{Run a test}
\usage{
test_that(desc, code)
}
\arguments{
\item{desc}{Test name. Names should be brief, but evocative. They are
only used by humans, so do you}
\item{code}{Test code containing expectations. Braces (\code{{}}) should always
be used in order to get accurate location data for test failures.}
}
\value{
When run interactively, returns \code{invisible(TRUE)} if all tests
pass, otherwise throws an error.
}
\description{
A test encapsulates a series of expectations about a small, self-contained
set of functionality. Each test lives in a file and contains multiple
expectations, like \code{\link[=expect_equal]{expect_equal()}} or \code{\link[=expect_error]{expect_error()}}.
Tests are evaluated in their own environments, and should not affect
global state.
}
\examples{
test_that("trigonometric functions match identities", {
expect_equal(sin(pi / 4), 1 / sqrt(2))
expect_equal(cos(pi / 4), 1 / sqrt(2))
expect_equal(tan(pi / 4), 1)
})
\dontrun{
test_that("trigonometric functions match identities", {
expect_equal(sin(pi / 4), 1)
})
}
}
testthat/man/expect_equivalent.Rd 0000644 0001762 0000144 00000003411 14164710002 016673 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expect-equality.R
\name{expect_equivalent}
\alias{expect_equivalent}
\title{Is an object equal to the expected value, ignoring attributes?}
\usage{
expect_equivalent(
object,
expected,
...,
info = NULL,
label = NULL,
expected.label = NULL
)
}
\arguments{
\item{object}{Computation and value to compare it to.
Both arguments supports limited unquoting to make it easier to generate
readable failures within a function or for loop. See \link{quasi_label} for
more details.}
\item{expected}{Computation and value to compare it to.
Both arguments supports limited unquoting to make it easier to generate
readable failures within a function or for loop. See \link{quasi_label} for
more details.}
\item{...}{Passed on to \code{\link[=compare]{compare()}}.}
\item{info}{Extra information to be included in the message. This argument
is soft-deprecated and should not be used in new code. Instead see
alternatives in \link{quasi_label}.}
\item{label}{Used to customise failure messages. For expert
use only.}
\item{expected.label}{Used to customise failure messages. For expert
use only.}
}
\description{
Compares \code{object} and \code{expected} using \code{\link[=all.equal]{all.equal()}} and
\code{check.attributes = FALSE}.
}
\section{3rd edition}{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
\code{expect_equivalent()} is deprecated in the 3rd edition. Instead use
\code{expect_equal(ignore_attr = TRUE)}.
}
\examples{
#' # expect_equivalent() ignores attributes
a <- b <- 1:3
names(b) <- letters[1:3]
\dontrun{
expect_equal(a, b)
}
expect_equivalent(a, b)
}
\keyword{internal}
testthat/man/local_edition.Rd 0000644 0001762 0000144 00000001214 14164710002 015752 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/edition.R
\name{local_edition}
\alias{local_edition}
\alias{edition_get}
\title{Temporarily change the active testthat edition}
\usage{
local_edition(x, .env = parent.frame())
edition_get()
}
\arguments{
\item{x}{Edition Should be a single integer.}
\item{.env}{Environment that controls scope of changes. For expert use only.}
}
\description{
\code{local_edition()} allows you to temporarily (within a single test or
a single test file) change the active edition of testthat.
\code{edition_get()} allows you to retrieve the currently active edition.
}
\keyword{internal}
testthat/man/expect_output_file.Rd 0000644 0001762 0000144 00000001533 14164710002 017060 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expect-known.R
\name{expect_output_file}
\alias{expect_output_file}
\title{Expectations: is the output or the value equal to a known good value?}
\usage{
expect_output_file(
object,
file,
update = TRUE,
...,
info = NULL,
label = NULL,
print = FALSE,
width = 80
)
}
\description{
\code{expect_output_file()} behaves identically to \code{\link[=expect_known_output]{expect_known_output()}}.
}
\section{3rd edition}{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
\code{expect_output_file()} is deprecated in the 3rd edition;
please use \code{\link[=expect_snapshot_output]{expect_snapshot_output()}} and friends instead.
}
\keyword{internal}
testthat/man/SummaryReporter.Rd 0000644 0001762 0000144 00000002212 14164710002 016324 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter-summary.R
\name{SummaryReporter}
\alias{SummaryReporter}
\title{Test reporter: summary of errors.}
\description{
This is a reporter designed for interactive usage: it lets you know which
tests have run successfully and as well as fully reporting information about
failures and errors.
}
\details{
You can use the \code{max_reports} field to control the maximum number
of detailed reports produced by this reporter. This is useful when running
with \code{\link[=auto_test]{auto_test()}}
As an additional benefit, this reporter will praise you from time-to-time
if all your tests pass.
}
\seealso{
Other reporters:
\code{\link{CheckReporter}},
\code{\link{DebugReporter}},
\code{\link{FailReporter}},
\code{\link{JunitReporter}},
\code{\link{ListReporter}},
\code{\link{LocationReporter}},
\code{\link{MinimalReporter}},
\code{\link{MultiReporter}},
\code{\link{ProgressReporter}},
\code{\link{RStudioReporter}},
\code{\link{Reporter}},
\code{\link{SilentReporter}},
\code{\link{StopReporter}},
\code{\link{TapReporter}},
\code{\link{TeamcityReporter}}
}
\concept{reporters}
testthat/man/expect_null.Rd 0000644 0001762 0000144 00000002535 14164710002 015476 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expect-constant.R
\name{expect_null}
\alias{expect_null}
\title{Does code return \code{NULL}?}
\usage{
expect_null(object, info = NULL, label = NULL)
}
\arguments{
\item{object}{Object to test.
Supports limited unquoting to make it easier to generate readable failures
within a function or for loop. See \link{quasi_label} for more details.}
\item{info}{Extra information to be included in the message. This argument
is soft-deprecated and should not be used in new code. Instead see
alternatives in \link{quasi_label}.}
\item{label}{Used to customise failure messages. For expert use only.}
}
\description{
This is a special case because \code{NULL} is a singleton so it's possible
check for it either with \code{expect_equal(x, NULL)} or \code{expect_type(x, "NULL")}.
}
\examples{
x <- NULL
y <- 10
expect_null(x)
show_failure(expect_null(y))
}
\seealso{
Other expectations:
\code{\link{comparison-expectations}},
\code{\link{equality-expectations}},
\code{\link{expect_error}()},
\code{\link{expect_length}()},
\code{\link{expect_match}()},
\code{\link{expect_named}()},
\code{\link{expect_output}()},
\code{\link{expect_reference}()},
\code{\link{expect_silent}()},
\code{\link{inheritance-expectations}},
\code{\link{logical-expectations}}
}
\concept{expectations}
\keyword{internal}
testthat/man/expect_known_output.Rd 0000644 0001762 0000144 00000007026 14164710002 017300 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expect-known.R
\name{expect_known_output}
\alias{expect_known_output}
\alias{expect_known_value}
\alias{expect_equal_to_reference}
\alias{expect_known_hash}
\title{Expectations: is the output or the value equal to a known good value?}
\usage{
expect_known_output(
object,
file,
update = TRUE,
...,
info = NULL,
label = NULL,
print = FALSE,
width = 80
)
expect_known_value(
object,
file,
update = TRUE,
...,
info = NULL,
label = NULL,
version = 2
)
expect_known_hash(object, hash = NULL)
}
\arguments{
\item{object}{Computation and value to compare it to.
Both arguments supports limited unquoting to make it easier to generate
readable failures within a function or for loop. See \link{quasi_label} for
more details.}
\item{file}{File path where known value/output will be stored.}
\item{update}{Should the file be updated? Defaults to \code{TRUE}, with
the expectation that you'll notice changes because of the first failure,
and then see the modified files in git.}
\item{...}{Passed on to \code{\link[waldo:compare]{waldo::compare()}}.}
\item{info}{Extra information to be included in the message. This argument
is soft-deprecated and should not be used in new code. Instead see
alternatives in \link{quasi_label}.}
\item{label}{Used to customise failure messages. For expert
use only.}
\item{print}{If \code{TRUE} and the result of evaluating \code{code} is
visible, print the result using \code{testthat_print()}.}
\item{width}{Number of characters per line of output. This does not
inherit from \code{getOption("width")} so that tests always use the same
output width, minimising spurious differences.}
\item{version}{The serialization format version to use. The default, 2, was
the default format from R 1.4.0 to 3.5.3. Version 3 became the default from
R 3.6.0 and can only be read by R versions 3.5.0 and higher.}
\item{hash}{Known hash value. Leave empty and you'll be informed what
to use in the test output.}
}
\description{
For complex printed output and objects, it is often challenging to describe
exactly what you expect to see. \code{expect_known_value()} and
\code{expect_known_output()} provide a slightly weaker guarantee, simply
asserting that the values have not changed since the last time that you ran
them.
}
\details{
These expectations should be used in conjunction with git, as otherwise
there is no way to revert to previous values. Git is particularly useful
in conjunction with \code{expect_known_output()} as the diffs will show you
exactly what has changed.
Note that known values updates will only be updated when running tests
interactively. \verb{R CMD check} clones the package source so any changes to
the reference files will occur in a temporary directory, and will not be
synchronised back to the source package.
}
\section{3rd edition}{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
\code{expect_known_output()} and friends are deprecated in the 3rd edition;
please use \code{\link[=expect_snapshot_output]{expect_snapshot_output()}} and friends instead.
}
\examples{
tmp <- tempfile()
# The first run always succeeds
expect_known_output(mtcars[1:10, ], tmp, print = TRUE)
# Subsequent runs will succeed only if the file is unchanged
# This will succeed:
expect_known_output(mtcars[1:10, ], tmp, print = TRUE)
\dontrun{
# This will fail
expect_known_output(mtcars[1:9, ], tmp, print = TRUE)
}
}
\keyword{internal}
testthat/man/expect_named.Rd 0000644 0001762 0000144 00000003667 14164710002 015617 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expect-named.R
\name{expect_named}
\alias{expect_named}
\title{Does code return a vector with (given) names?}
\usage{
expect_named(
object,
expected,
ignore.order = FALSE,
ignore.case = FALSE,
info = NULL,
label = NULL
)
}
\arguments{
\item{object}{Object to test.
Supports limited unquoting to make it easier to generate readable failures
within a function or for loop. See \link{quasi_label} for more details.}
\item{expected}{Character vector of expected names. Leave missing to
match any names. Use \code{NULL} to check for absence of names.}
\item{ignore.order}{If \code{TRUE}, sorts names before comparing to
ignore the effect of order.}
\item{ignore.case}{If \code{TRUE}, lowercases all names to ignore the
effect of case.}
\item{info}{Extra information to be included in the message. This argument
is soft-deprecated and should not be used in new code. Instead see
alternatives in \link{quasi_label}.}
\item{label}{Used to customise failure messages. For expert use only.}
}
\description{
You can either check for the presence of names (leaving \code{expected}
blank), specific names (by supplying a vector of names), or absence of
names (with \code{NULL}).
}
\examples{
x <- c(a = 1, b = 2, c = 3)
expect_named(x)
expect_named(x, c("a", "b", "c"))
# Use options to control sensitivity
expect_named(x, c("B", "C", "A"), ignore.order = TRUE, ignore.case = TRUE)
# Can also check for the absence of names with NULL
z <- 1:4
expect_named(z, NULL)
}
\seealso{
Other expectations:
\code{\link{comparison-expectations}},
\code{\link{equality-expectations}},
\code{\link{expect_error}()},
\code{\link{expect_length}()},
\code{\link{expect_match}()},
\code{\link{expect_null}()},
\code{\link{expect_output}()},
\code{\link{expect_reference}()},
\code{\link{expect_silent}()},
\code{\link{inheritance-expectations}},
\code{\link{logical-expectations}}
}
\concept{expectations}
testthat/man/fail.Rd 0000644 0001762 0000144 00000002067 14164710002 014067 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expect-that.R
\name{fail}
\alias{fail}
\alias{succeed}
\title{Default expectations that always succeed or fail.}
\usage{
fail(
message = "Failure has been forced",
info = NULL,
trace_env = caller_env()
)
succeed(message = "Success has been forced", info = NULL)
}
\arguments{
\item{message}{a string to display.}
\item{info}{Character vector continuing additional information. Included
for backward compatibility only and new expectations should not use it.}
\item{trace_env}{If \code{is.null(trace)}, this is used to automatically
generate a traceback running from \code{test_code()}/\code{test_file()} to
\code{trace_env}. You'll generally only need to set this if you're wrapping
an expectation inside another function.}
}
\description{
These allow you to manually trigger success or failure. Failure is
particularly useful to a pre-condition or mark a test as not yet
implemented.
}
\examples{
\dontrun{
test_that("this test fails", fail())
test_that("this test succeeds", succeed())
}
}
testthat/man/test_env.Rd 0000644 0001762 0000144 00000001012 14164710002 014770 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/test-env.R
\name{test_env}
\alias{test_env}
\title{Generate default testing environment.}
\usage{
test_env(package = NULL)
}
\description{
We use a new environment which inherits from \code{\link[=globalenv]{globalenv()}} or a package
namespace. In an ideal world, we'd avoid putting the global environment on
the search path for tests, but it's not currently possible without losing
the ability to load packages in tests.
}
\keyword{internal}
testthat/man/LocationReporter.Rd 0000644 0001762 0000144 00000001574 14164710002 016451 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter-location.R
\name{LocationReporter}
\alias{LocationReporter}
\title{Test reporter: location}
\description{
This reporter simply prints the location of every expectation and error.
This is useful if you're trying to figure out the source of a segfault,
or you want to figure out which code triggers a C/C++ breakpoint
}
\seealso{
Other reporters:
\code{\link{CheckReporter}},
\code{\link{DebugReporter}},
\code{\link{FailReporter}},
\code{\link{JunitReporter}},
\code{\link{ListReporter}},
\code{\link{MinimalReporter}},
\code{\link{MultiReporter}},
\code{\link{ProgressReporter}},
\code{\link{RStudioReporter}},
\code{\link{Reporter}},
\code{\link{SilentReporter}},
\code{\link{StopReporter}},
\code{\link{SummaryReporter}},
\code{\link{TapReporter}},
\code{\link{TeamcityReporter}}
}
\concept{reporters}
testthat/man/StopReporter.Rd 0000644 0001762 0000144 00000002156 14164710002 015623 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter-stop.R
\name{StopReporter}
\alias{StopReporter}
\title{Test reporter: stop on error}
\description{
The default reporter used when \code{\link[=expect_that]{expect_that()}} is run interactively.
It responds by \code{\link[=stop]{stop()}}ping on failures and doing nothing otherwise. This
will ensure that a failing test will raise an error.
}
\details{
This should be used when doing a quick and dirty test, or during the final
automated testing of R CMD check. Otherwise, use a reporter that runs all
tests and gives you more context about the problem.
}
\seealso{
Other reporters:
\code{\link{CheckReporter}},
\code{\link{DebugReporter}},
\code{\link{FailReporter}},
\code{\link{JunitReporter}},
\code{\link{ListReporter}},
\code{\link{LocationReporter}},
\code{\link{MinimalReporter}},
\code{\link{MultiReporter}},
\code{\link{ProgressReporter}},
\code{\link{RStudioReporter}},
\code{\link{Reporter}},
\code{\link{SilentReporter}},
\code{\link{SummaryReporter}},
\code{\link{TapReporter}},
\code{\link{TeamcityReporter}}
}
\concept{reporters}
testthat/man/capture_condition.Rd 0000644 0001762 0000144 00000003453 14164710002 016665 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/deprec-condition.R
\name{capture_condition}
\alias{capture_condition}
\alias{capture_error}
\alias{capture_expectation}
\alias{capture_message}
\alias{capture_warning}
\alias{capture_messages}
\alias{capture_warnings}
\title{Capture conditions, including messages, warnings, expectations, and errors.}
\usage{
capture_condition(code, entrace = FALSE)
capture_error(code, entrace = FALSE)
capture_expectation(code, entrace = FALSE)
capture_message(code, entrace = FALSE)
capture_warning(code, entrace = FALSE)
capture_messages(code)
capture_warnings(code)
}
\arguments{
\item{code}{Code to evaluate}
\item{entrace}{Whether to add a \link[rlang:trace_back]{backtrace} to
the captured condition.}
}
\value{
Singular functions (\code{capture_condition}, \code{capture_expectation} etc)
return a condition object. \code{capture_messages()} and \code{capture_warnings}
return a character vector of message text.
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#superseded}{\figure{lifecycle-superseded.svg}{options: alt='[Superseded]'}}}{\strong{[Superseded]}}
These functions allow you to capture the side-effects of a function call
including printed output, messages and warnings. We no longer recommend
that you use these functions, instead relying on the \code{\link[=expect_message]{expect_message()}}
and friends to bubble up unmatched conditions. If you just want to silence
unimportant warnings, use \code{\link[=suppressWarnings]{suppressWarnings()}}.
}
\examples{
f <- function() {
message("First")
warning("Second")
message("Third")
}
capture_message(f())
capture_messages(f())
capture_warning(f())
capture_warnings(f())
# Condition will capture anything
capture_condition(f())
}
\keyword{internal}
testthat/man/is_informative_error.Rd 0000644 0001762 0000144 00000001701 14164710002 017375 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/deprec-condition.R
\name{is_informative_error}
\alias{is_informative_error}
\title{Is an error informative?}
\usage{
is_informative_error(x, ...)
}
\arguments{
\item{x}{An error object.}
\item{...}{These dots are for future extensions and must be empty.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
\code{is_informative_error()} is a generic predicate that indicates
whether testthat users should explicitly test for an error
class. Since we no longer recommend you do that, this generic
has been deprecated.
}
\details{
A few classes are hard-coded as uninformative:
\itemize{
\item \code{simpleError}
\item \code{rlang_error} unless a subclass is detected
\item \code{Rcpp::eval_error}
\item \code{Rcpp::exception}
}
}
\keyword{internal}
testthat/man/oldskool.Rd 0000644 0001762 0000144 00000003073 14164710002 015000 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/old-school.R
\name{oldskool}
\alias{oldskool}
\alias{is_null}
\alias{is_a}
\alias{is_true}
\alias{is_false}
\alias{has_names}
\alias{is_less_than}
\alias{is_more_than}
\alias{equals}
\alias{is_equivalent_to}
\alias{is_identical_to}
\alias{equals_reference}
\alias{shows_message}
\alias{gives_warning}
\alias{prints_text}
\alias{throws_error}
\alias{matches}
\title{Old-style expectations.}
\usage{
is_null()
is_a(class)
is_true()
is_false()
has_names(expected, ignore.order = FALSE, ignore.case = FALSE)
is_less_than(expected, label = NULL, ...)
is_more_than(expected, label = NULL, ...)
equals(expected, label = NULL, ...)
is_equivalent_to(expected, label = NULL)
is_identical_to(expected, label = NULL)
equals_reference(file, label = NULL, ...)
shows_message(regexp = NULL, all = FALSE, ...)
gives_warning(regexp = NULL, all = FALSE, ...)
prints_text(regexp = NULL, ...)
throws_error(regexp = NULL, ...)
matches(regexp, all = TRUE, ...)
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#superseded}{\figure{lifecycle-superseded.svg}{options: alt='[Superseded]'}}}{\strong{[Superseded]}}
Initial testthat used a style of testing that looked like
\verb{expect_that(a, equals(b)))} this allowed expectations to read like
English sentences, but was verbose and a bit too cutesy. This style
will continue to work but has been soft-deprecated - it is no longer
documented, and new expectations will only use the new style
\code{expect_equal(a, b)}.
}
\keyword{internal}
testthat/man/find_reporter.Rd 0000644 0001762 0000144 00000000772 13051613152 016021 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter-zzz.R
\name{find_reporter}
\alias{find_reporter}
\title{Find reporter object given name or object.}
\usage{
find_reporter(reporter)
}
\arguments{
\item{reporter}{name of reporter(s), or reporter object(s)}
}
\description{
If not found, will return informative error message.
Pass a character vector to create a \link{MultiReporter} composed
of individual reporters.
Will return null if given NULL.
}
\keyword{internal}
testthat/man/CheckReporter.Rd 0000644 0001762 0000144 00000001504 14164710002 015707 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter-check.R
\name{CheckReporter}
\alias{CheckReporter}
\title{Check reporter: 13 line summary of problems}
\description{
\verb{R CMD check} displays only the last 13 lines of the result, so this
report is designed to ensure that you see something useful there.
}
\seealso{
Other reporters:
\code{\link{DebugReporter}},
\code{\link{FailReporter}},
\code{\link{JunitReporter}},
\code{\link{ListReporter}},
\code{\link{LocationReporter}},
\code{\link{MinimalReporter}},
\code{\link{MultiReporter}},
\code{\link{ProgressReporter}},
\code{\link{RStudioReporter}},
\code{\link{Reporter}},
\code{\link{SilentReporter}},
\code{\link{StopReporter}},
\code{\link{SummaryReporter}},
\code{\link{TapReporter}},
\code{\link{TeamcityReporter}}
}
\concept{reporters}
testthat/man/test_package.Rd 0000644 0001762 0000144 00000005144 14164710002 015605 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/test-package.R
\name{test_package}
\alias{test_package}
\alias{test_check}
\alias{test_local}
\title{Run all tests in a package}
\usage{
test_package(package, reporter = check_reporter(), ...)
test_check(package, reporter = check_reporter(), ...)
test_local(path = ".", reporter = NULL, ...)
}
\arguments{
\item{package}{If these tests belong to a package, the name of the package.}
\item{reporter}{Reporter to use to summarise output. Can be supplied
as a string (e.g. "summary") or as an R6 object
(e.g. \code{SummaryReporter$new()}).
See \link{Reporter} for more details and a list of built-in reporters.}
\item{...}{Additional arguments passed to \code{\link[=test_dir]{test_dir()}}}
\item{path}{Path to directory containing tests.}
}
\value{
A list (invisibly) containing data about the test results.
}
\description{
\itemize{
\item \code{test_local()} tests a local source package.
\item \code{test_package()} tests an installed package.
\item \code{test_check()} checks a package during \verb{R CMD check}.
}
Tests live in \code{tests/testthat}.
}
\section{\verb{R CMD check}}{
To run testthat automatically from \verb{R CMD check}, make sure you have
a \code{tests/testthat.R} that contains:\preformatted{library(testthat)
library(yourpackage)
test_check("yourpackage")
}
}
\section{Special files}{
There are two types of \code{.R} file that have special behaviour:
\itemize{
\item Test files start with \code{test} and are executed in alphabetical order.
\item Setup files start with \code{setup} and are executed before tests. If
clean up is needed after all tests have been run, you can use
\code{withr::defer(clean_up(), teardown_env())}. See \code{vignette("test-fixtures")}
for more details.
}
There are two other types of special file that we no longer recommend using:
\itemize{
\item Helper files start with \code{helper} and are executed before tests are
run. They're also loaded by \code{devtools::load_all()}, so there's no
real point to them and you should just put your helper code in \verb{R/}.
\item Teardown files start with \code{teardown} and are executed after the tests
are run. Now we recommend interleave setup and cleanup code in \verb{setup-}
files, making it easier to check that you automatically clean up every
mess that you make.
}
All other files are ignored by testthat.
}
\section{Environments}{
Each test is run in a clean environment to keep tests as isolated as
possible. For package tests, that environment that inherits from the
package's namespace environment, so that tests can access internal functions
and objects.
}
testthat/man/expect_match.Rd 0000644 0001762 0000144 00000005424 14164710002 015620 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expectations-matches.R
\name{expect_match}
\alias{expect_match}
\alias{expect_no_match}
\title{Does a string match a regular expression?}
\usage{
expect_match(
object,
regexp,
perl = FALSE,
fixed = FALSE,
...,
all = TRUE,
info = NULL,
label = NULL
)
expect_no_match(
object,
regexp,
perl = FALSE,
fixed = FALSE,
...,
all = TRUE,
info = NULL,
label = NULL
)
}
\arguments{
\item{object}{Object to test.
Supports limited unquoting to make it easier to generate readable failures
within a function or for loop. See \link{quasi_label} for more details.}
\item{regexp}{Regular expression to test against.}
\item{perl}{logical. Should Perl-compatible regexps be used?}
\item{fixed}{logical. If \code{TRUE}, \code{pattern} is a string to be
matched as is. Overrides all conflicting arguments.}
\item{...}{
Arguments passed on to \code{\link[base:grep]{base::grepl}}
\describe{
\item{\code{ignore.case}}{if \code{FALSE}, the pattern matching is \emph{case
sensitive} and if \code{TRUE}, case is ignored during matching.}
\item{\code{useBytes}}{logical. If \code{TRUE} the matching is done
byte-by-byte rather than character-by-character. See
\sQuote{Details}.}
}}
\item{all}{Should all elements of actual value match \code{regexp} (TRUE),
or does only one need to match (FALSE).}
\item{info}{Extra information to be included in the message. This argument
is soft-deprecated and should not be used in new code. Instead see
alternatives in \link{quasi_label}.}
\item{label}{Used to customise failure messages. For expert use only.}
}
\description{
Does a string match a regular expression?
}
\details{
\code{expect_match()} is a wrapper around \code{\link[=grepl]{grepl()}}. See its documentation for
more detail about the individual arguments. \code{expect_no_match()} provides
the complementary case, checking that a string \emph{does not} match a regular
expression.
}
\section{Functions}{
\itemize{
\item \code{expect_no_match}: Check that a string doesn't match a regular
expression.
}}
\examples{
expect_match("Testing is fun", "fun")
expect_match("Testing is fun", "f.n")
expect_no_match("Testing is fun", "horrible")
\dontrun{
expect_match("Testing is fun", "horrible")
# Zero-length inputs always fail
expect_match(character(), ".")
}
}
\seealso{
Other expectations:
\code{\link{comparison-expectations}},
\code{\link{equality-expectations}},
\code{\link{expect_error}()},
\code{\link{expect_length}()},
\code{\link{expect_named}()},
\code{\link{expect_null}()},
\code{\link{expect_output}()},
\code{\link{expect_reference}()},
\code{\link{expect_silent}()},
\code{\link{inheritance-expectations}},
\code{\link{logical-expectations}}
}
\concept{expectations}
\keyword{internal}
testthat/man/MultiReporter.Rd 0000644 0001762 0000144 00000001501 14164710002 015761 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter-multi.R
\name{MultiReporter}
\alias{MultiReporter}
\title{Multi reporter: combine several reporters in one.}
\description{
This reporter is useful to use several reporters at the same time, e.g.
adding a custom reporter without removing the current one.
}
\seealso{
Other reporters:
\code{\link{CheckReporter}},
\code{\link{DebugReporter}},
\code{\link{FailReporter}},
\code{\link{JunitReporter}},
\code{\link{ListReporter}},
\code{\link{LocationReporter}},
\code{\link{MinimalReporter}},
\code{\link{ProgressReporter}},
\code{\link{RStudioReporter}},
\code{\link{Reporter}},
\code{\link{SilentReporter}},
\code{\link{StopReporter}},
\code{\link{SummaryReporter}},
\code{\link{TapReporter}},
\code{\link{TeamcityReporter}}
}
\concept{reporters}
testthat/man/not.Rd 0000644 0001762 0000144 00000000664 13171137773 013774 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expect-that.R
\name{not}
\alias{not}
\title{Negate an expectation}
\usage{
not(f)
}
\arguments{
\item{f}{an existing expectation function}
}
\description{
This negates an expectation, making it possible to express that you
want the opposite of a standard expectation. This function is deprecated
and will be removed in a future version.
}
\keyword{internal}
testthat/man/testthat_examples.Rd 0000644 0001762 0000144 00000001060 14164710002 016702 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/example.R
\name{testthat_examples}
\alias{testthat_examples}
\alias{testthat_example}
\title{Retrieve paths to built-in example test files}
\usage{
testthat_examples()
testthat_example(filename)
}
\arguments{
\item{filename}{Name of test file}
}
\description{
\code{testthat_examples()} retrieves path to directory of test files,
\code{testthat_example()} retrieves path to a single test file.
}
\examples{
dir(testthat_examples())
testthat_example("success")
}
\keyword{internal}
testthat/man/test_file.Rd 0000644 0001762 0000144 00000004274 14164710002 015134 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/test-files.R
\name{test_file}
\alias{test_file}
\title{Run all tests in a single file}
\usage{
test_file(path, reporter = default_compact_reporter(), package = NULL, ...)
}
\arguments{
\item{path}{Path to file.}
\item{reporter}{Reporter to use to summarise output. Can be supplied
as a string (e.g. "summary") or as an R6 object
(e.g. \code{SummaryReporter$new()}).
See \link{Reporter} for more details and a list of built-in reporters.}
\item{package}{If these tests belong to a package, the name of the package.}
\item{...}{Additional parameters passed on to \code{test_dir()}}
}
\value{
A list (invisibly) containing data about the test results.
}
\description{
Helper, setup, and teardown files located in the same directory as the
test will also be run.
}
\section{Special files}{
There are two types of \code{.R} file that have special behaviour:
\itemize{
\item Test files start with \code{test} and are executed in alphabetical order.
\item Setup files start with \code{setup} and are executed before tests. If
clean up is needed after all tests have been run, you can use
\code{withr::defer(clean_up(), teardown_env())}. See \code{vignette("test-fixtures")}
for more details.
}
There are two other types of special file that we no longer recommend using:
\itemize{
\item Helper files start with \code{helper} and are executed before tests are
run. They're also loaded by \code{devtools::load_all()}, so there's no
real point to them and you should just put your helper code in \verb{R/}.
\item Teardown files start with \code{teardown} and are executed after the tests
are run. Now we recommend interleave setup and cleanup code in \verb{setup-}
files, making it easier to check that you automatically clean up every
mess that you make.
}
All other files are ignored by testthat.
}
\section{Environments}{
Each test is run in a clean environment to keep tests as isolated as
possible. For package tests, that environment that inherits from the
package's namespace environment, so that tests can access internal functions
and objects.
}
\examples{
path <- testthat_example("success")
test_file(path)
test_file(path, reporter = "minimal")
}
testthat/man/ProgressReporter.Rd 0000644 0001762 0000144 00000002545 14164710002 016504 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter-progress.R
\name{ProgressReporter}
\alias{ProgressReporter}
\alias{CompactProgressReporter}
\alias{ParallelProgressReporter}
\title{Test reporter: interactive progress bar of errors.}
\description{
\code{ProgressReporter} is designed for interactive use. Its goal is to
give you actionable insights to help you understand the status of your
code. This reporter also praises you from time-to-time if all your tests
pass. It's the default reporter for \code{\link[=test_dir]{test_dir()}}.
\code{ParallelProgressReporter} is very similar to \code{ProgressReporter}, but
works better for packages that want parallel tests.
\code{CompactProgressReporter} is a minimal version of \code{ProgressReporter}
designed for use with single files. It's the default reporter for
\code{\link[=test_file]{test_file()}}.
}
\seealso{
Other reporters:
\code{\link{CheckReporter}},
\code{\link{DebugReporter}},
\code{\link{FailReporter}},
\code{\link{JunitReporter}},
\code{\link{ListReporter}},
\code{\link{LocationReporter}},
\code{\link{MinimalReporter}},
\code{\link{MultiReporter}},
\code{\link{RStudioReporter}},
\code{\link{Reporter}},
\code{\link{SilentReporter}},
\code{\link{StopReporter}},
\code{\link{SummaryReporter}},
\code{\link{TapReporter}},
\code{\link{TeamcityReporter}}
}
\concept{reporters}
testthat/man/source_file.Rd 0000644 0001762 0000144 00000002174 14164710002 015452 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/source.R
\name{source_file}
\alias{source_file}
\alias{source_dir}
\alias{source_test_helpers}
\alias{source_test_setup}
\alias{source_test_teardown}
\title{Source a file, directory of files, or various important subsets}
\usage{
source_file(path, env = test_env(), chdir = TRUE, wrap = TRUE)
source_dir(
path,
pattern = "\\\\.[rR]$",
env = test_env(),
chdir = TRUE,
wrap = TRUE
)
source_test_helpers(path = "tests/testthat", env = test_env())
source_test_setup(path = "tests/testthat", env = test_env())
source_test_teardown(path = "tests/testthat", env = test_env())
}
\arguments{
\item{path}{Path to files.}
\item{env}{Environment in which to evaluate code.}
\item{chdir}{Change working directory to \code{dirname(path)}?}
\item{wrap}{Automatically wrap all code within \code{\link[=test_that]{test_that()}}? This ensures
that all expectations are reported, even if outside a test block.}
\item{pattern}{Regular expression used to filter files.}
}
\description{
These are used by \code{\link[=test_dir]{test_dir()}} and friends
}
\keyword{internal}
testthat/man/capture_output.Rd 0000644 0001762 0000144 00000002603 14164710002 016233 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/capture-output.R
\name{capture_output}
\alias{capture_output}
\alias{capture_output_lines}
\alias{testthat_print}
\title{Capture output to console}
\usage{
capture_output(code, print = FALSE, width = 80)
capture_output_lines(code, print = FALSE, width = 80)
testthat_print(x)
}
\arguments{
\item{code}{Code to evaluate.}
\item{print}{If \code{TRUE} and the result of evaluating \code{code} is
visible, print the result using \code{testthat_print()}.}
\item{width}{Number of characters per line of output. This does not
inherit from \code{getOption("width")} so that tests always use the same
output width, minimising spurious differences.}
}
\value{
\code{capture_output()} returns a single string. \code{capture_output_lines()}
returns a character vector with one entry for each line
}
\description{
Evaluates \code{code} in a special context in which all output is captured,
similar to \code{\link[=capture.output]{capture.output()}}.
}
\details{
Results are printed using the \code{testthat_print()} generic, which defaults
to \code{print()}, giving you the ability to customise the printing of your
object in tests, if needed.
}
\examples{
capture_output({
cat("Hi!\n")
cat("Bye\n")
})
capture_output_lines({
cat("Hi!\n")
cat("Bye\n")
})
capture_output("Hi")
capture_output("Hi", print = TRUE)
}
\keyword{internal}
testthat/man/DebugReporter.Rd 0000644 0001762 0000144 00000001427 14164710002 015724 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter-debug.R
\name{DebugReporter}
\alias{DebugReporter}
\title{Test reporter: start recovery.}
\description{
This reporter will call a modified version of \code{\link[=recover]{recover()}} on all
broken expectations.
}
\seealso{
Other reporters:
\code{\link{CheckReporter}},
\code{\link{FailReporter}},
\code{\link{JunitReporter}},
\code{\link{ListReporter}},
\code{\link{LocationReporter}},
\code{\link{MinimalReporter}},
\code{\link{MultiReporter}},
\code{\link{ProgressReporter}},
\code{\link{RStudioReporter}},
\code{\link{Reporter}},
\code{\link{SilentReporter}},
\code{\link{StopReporter}},
\code{\link{SummaryReporter}},
\code{\link{TapReporter}},
\code{\link{TeamcityReporter}}
}
\concept{reporters}
testthat/man/test_dir.Rd 0000644 0001762 0000144 00000006737 14164710002 015001 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/test-files.R
\name{test_dir}
\alias{test_dir}
\title{Run all tests in a directory}
\usage{
test_dir(
path,
filter = NULL,
reporter = NULL,
env = NULL,
...,
load_helpers = TRUE,
stop_on_failure = TRUE,
stop_on_warning = FALSE,
wrap = lifecycle::deprecated(),
package = NULL,
load_package = c("none", "installed", "source")
)
}
\arguments{
\item{path}{Path to directory containing tests.}
\item{filter}{If not \code{NULL}, only tests with file names matching this
regular expression will be executed. Matching is performed on the file
name after it's stripped of \code{"test-"} and \code{".R"}.}
\item{reporter}{Reporter to use to summarise output. Can be supplied
as a string (e.g. "summary") or as an R6 object
(e.g. \code{SummaryReporter$new()}).
See \link{Reporter} for more details and a list of built-in reporters.}
\item{env}{Environment in which to execute the tests. Expert use only.}
\item{...}{Additional arguments passed to \code{\link[=grepl]{grepl()}} to control filtering.}
\item{load_helpers}{Source helper files before running the tests?
See \code{\link[=source_test_helpers]{source_test_helpers()}} for more details.}
\item{stop_on_failure}{If \code{TRUE}, throw an error if any tests fail.}
\item{stop_on_warning}{If \code{TRUE}, throw an error if any tests generate
warnings.}
\item{wrap}{DEPRECATED}
\item{package}{If these tests belong to a package, the name of the package.}
\item{load_package}{Strategy to use for load package code:
\itemize{
\item "none", the default, doesn't load the package.
\item "installed", uses \code{\link[=library]{library()}} to load an installed package.
\item "source", uses \code{\link[pkgload:load_all]{pkgload::load_all()}} to a source package.
}}
}
\value{
A list (invisibly) containing data about the test results.
}
\description{
This function is the low-level workhorse that powers \code{\link[=test_local]{test_local()}} and
\code{\link[=test_package]{test_package()}}. Generally, you should not call this function directly.
In particular, you are responsible for ensuring that the functions to test
are available in the test \code{env} (e.g. via \code{load_package}).
}
\section{Special files}{
There are two types of \code{.R} file that have special behaviour:
\itemize{
\item Test files start with \code{test} and are executed in alphabetical order.
\item Setup files start with \code{setup} and are executed before tests. If
clean up is needed after all tests have been run, you can use
\code{withr::defer(clean_up(), teardown_env())}. See \code{vignette("test-fixtures")}
for more details.
}
There are two other types of special file that we no longer recommend using:
\itemize{
\item Helper files start with \code{helper} and are executed before tests are
run. They're also loaded by \code{devtools::load_all()}, so there's no
real point to them and you should just put your helper code in \verb{R/}.
\item Teardown files start with \code{teardown} and are executed after the tests
are run. Now we recommend interleave setup and cleanup code in \verb{setup-}
files, making it easier to check that you automatically clean up every
mess that you make.
}
All other files are ignored by testthat.
}
\section{Environments}{
Each test is run in a clean environment to keep tests as isolated as
possible. For package tests, that environment that inherits from the
package's namespace environment, so that tests can access internal functions
and objects.
}
\keyword{internal}
testthat/man/TeamcityReporter.Rd 0000644 0001762 0000144 00000001572 14164710002 016456 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter-teamcity.R
\name{TeamcityReporter}
\alias{TeamcityReporter}
\title{Test reporter: Teamcity format.}
\description{
This reporter will output results in the Teamcity message format.
For more information about Teamcity messages, see
http://confluence.jetbrains.com/display/TCD7/Build+Script+Interaction+with+TeamCity
}
\seealso{
Other reporters:
\code{\link{CheckReporter}},
\code{\link{DebugReporter}},
\code{\link{FailReporter}},
\code{\link{JunitReporter}},
\code{\link{ListReporter}},
\code{\link{LocationReporter}},
\code{\link{MinimalReporter}},
\code{\link{MultiReporter}},
\code{\link{ProgressReporter}},
\code{\link{RStudioReporter}},
\code{\link{Reporter}},
\code{\link{SilentReporter}},
\code{\link{StopReporter}},
\code{\link{SummaryReporter}},
\code{\link{TapReporter}}
}
\concept{reporters}
testthat/man/safe_digest.Rd 0000644 0001762 0000144 00000000716 13051613152 015432 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/watcher.R
\name{safe_digest}
\alias{safe_digest}
\title{Compute a digest of a filename, returning NA if the file doesn't
exist.}
\usage{
safe_digest(path)
}
\arguments{
\item{filename}{filename to compute digest on}
}
\value{
a digest of the file, or NA if it doesn't exist.
}
\description{
Compute a digest of a filename, returning NA if the file doesn't
exist.
}
\keyword{internal}
testthat/man/equality-expectations.Rd 0000644 0001762 0000144 00000006660 14164710002 017520 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expect-equality.R
\name{equality-expectations}
\alias{equality-expectations}
\alias{expect_equal}
\alias{expect_identical}
\title{Does code return the expected value?}
\usage{
expect_equal(
object,
expected,
...,
tolerance = if (edition_get() >= 3) testthat_tolerance(),
info = NULL,
label = NULL,
expected.label = NULL
)
expect_identical(
object,
expected,
info = NULL,
label = NULL,
expected.label = NULL,
...
)
}
\arguments{
\item{object, expected}{Computation and value to compare it to.
Both arguments supports limited unquoting to make it easier to generate
readable failures within a function or for loop. See \link{quasi_label} for
more details.}
\item{...}{\strong{3e}: passed on to \code{\link[waldo:compare]{waldo::compare()}}. See its docs to see other
ways to control comparison.
\strong{2e}: passed on to \code{\link[=compare]{compare()}}/\code{\link[=identical]{identical()}}.}
\item{tolerance}{\strong{3e}: passed on to \code{\link[waldo:compare]{waldo::compare()}}. If non-\code{NULL}, will
ignore small floating point differences. It uses same algorithm as
\code{\link[=all.equal]{all.equal()}} so the tolerance is usually relative (i.e.
\verb{mean(abs(x - y) / mean(abs(y)) < tolerance}), except when the differences
are very small, when it becomes absolute (i.e. \verb{mean(abs(x - y) < tolerance}).
See waldo documentation for more details.
\strong{2e}: passed on to \code{\link[=compare]{compare()}}, if set. It's hard to
reason about exactly what tolerance means because depending on the precise
code path it could be either an absolute or relative tolerance.}
\item{info}{Extra information to be included in the message. This argument
is soft-deprecated and should not be used in new code. Instead see
alternatives in \link{quasi_label}.}
\item{label, expected.label}{Used to customise failure messages. For expert
use only.}
}
\description{
These functions provide two levels of strictness when comparing a
computation to a reference value. \code{expect_identical()} is the baseline;
\code{expect_equal()} relaxes the test to ignore small numeric differences.
In the 2nd edition, \code{expect_identical()} uses \code{\link[=identical]{identical()}} and
\code{expect_equal} uses \code{\link[=all.equal]{all.equal()}}. In the 3rd edition, both functions use
\href{https://github.com/r-lib/waldo}{waldo}. They differ only in that
\code{expect_equal()} sets \code{tolerance = testthat_tolerance()} so that small
floating point differences are ignored; this also implies that (e.g.) \code{1}
and \code{1L} are treated as equal.
}
\examples{
a <- 10
expect_equal(a, 10)
# Use expect_equal() when testing for numeric equality
\dontrun{
expect_identical(sqrt(2) ^ 2, 2)
}
expect_equal(sqrt(2) ^ 2, 2)
}
\seealso{
\itemize{
\item \code{\link[=expect_setequal]{expect_setequal()}}/\code{\link[=expect_mapequal]{expect_mapequal()}} to test for set equality.
\item \code{\link[=expect_reference]{expect_reference()}} to test if two names point to same memory address.
}
Other expectations:
\code{\link{comparison-expectations}},
\code{\link{expect_error}()},
\code{\link{expect_length}()},
\code{\link{expect_match}()},
\code{\link{expect_named}()},
\code{\link{expect_null}()},
\code{\link{expect_output}()},
\code{\link{expect_reference}()},
\code{\link{expect_silent}()},
\code{\link{inheritance-expectations}},
\code{\link{logical-expectations}}
}
\concept{expectations}
testthat/man/inheritance-expectations.Rd 0000644 0001762 0000144 00000005407 14164710002 020152 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expect-inheritance.R
\name{inheritance-expectations}
\alias{inheritance-expectations}
\alias{expect_type}
\alias{expect_s3_class}
\alias{expect_s4_class}
\title{Does code return an object inheriting from the expected base type, S3 class,
or S4 class?}
\usage{
expect_type(object, type)
expect_s3_class(object, class, exact = FALSE)
expect_s4_class(object, class)
}
\arguments{
\item{object}{Object to test.
Supports limited unquoting to make it easier to generate readable failures
within a function or for loop. See \link{quasi_label} for more details.}
\item{type}{String giving base type (as returned by \code{\link[=typeof]{typeof()}}).}
\item{class}{Either a character vector of class names, or
for \code{expect_s3_class()} and \code{expect_s4_class()}, an \code{NA} to assert
that \code{object} isn't an S3 or S4 object.}
\item{exact}{If \code{FALSE}, the default, checks that \code{object} inherits
from \code{class}. If \code{TRUE}, checks that object has a class that's identical
to \code{class}.}
}
\description{
See \url{https://adv-r.hadley.nz/oo.html} for an overview of R's OO systems, and
the vocabulary used here.
\itemize{
\item \code{expect_type(x, type)} checks that \code{typeof(x)} is \code{type}.
\item \code{expect_s3_class(x, class)} checks that \code{x} is an S3 object that
\code{\link[=inherits]{inherits()}} from \code{class}
\item \code{expect_s3_class(x, NA)} checks that \code{x} isn't an S3 object.
\item \code{expect_s4_class(x, class)} checks that \code{x} is an S4 object that
\code{\link[=is]{is()}} \code{class}.
\item \code{expect_s4_class(x, NA)} checks that \code{x} isn't an S4 object.
}
See \code{\link[=expect_vector]{expect_vector()}} for testing properties of objects created by vctrs.
}
\examples{
x <- data.frame(x = 1:10, y = "x", stringsAsFactors = TRUE)
# A data frame is an S3 object with class data.frame
expect_s3_class(x, "data.frame")
show_failure(expect_s4_class(x, "data.frame"))
# A data frame is built from a list:
expect_type(x, "list")
# An integer vector is an atomic vector of type "integer"
expect_type(x$x, "integer")
# It is not an S3 object
show_failure(expect_s3_class(x$x, "integer"))
# Above, we requested data.frame() converts strings to factors:
show_failure(expect_type(x$y, "character"))
expect_s3_class(x$y, "factor")
expect_type(x$y, "integer")
}
\seealso{
Other expectations:
\code{\link{comparison-expectations}},
\code{\link{equality-expectations}},
\code{\link{expect_error}()},
\code{\link{expect_length}()},
\code{\link{expect_match}()},
\code{\link{expect_named}()},
\code{\link{expect_null}()},
\code{\link{expect_output}()},
\code{\link{expect_reference}()},
\code{\link{expect_silent}()},
\code{\link{logical-expectations}}
}
\concept{expectations}
testthat/man/expect_is.Rd 0000644 0001762 0000144 00000002642 14164710002 015136 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expect-inheritance.R
\name{expect_is}
\alias{expect_is}
\title{Does an object inherit from a given class?}
\usage{
expect_is(object, class, info = NULL, label = NULL)
}
\arguments{
\item{object}{Object to test.
Supports limited unquoting to make it easier to generate readable failures
within a function or for loop. See \link{quasi_label} for more details.}
\item{class}{Either a character vector of class names, or
for \code{expect_s3_class()} and \code{expect_s4_class()}, an \code{NA} to assert
that \code{object} isn't an S3 or S4 object.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#superseded}{\figure{lifecycle-superseded.svg}{options: alt='[Superseded]'}}}{\strong{[Superseded]}}
\code{expect_is()} is an older form that uses \code{\link[=inherits]{inherits()}} without checking
whether \code{x} is S3, S4, or neither. Instead, I'd recommend using
\code{\link[=expect_type]{expect_type()}}, \code{\link[=expect_s3_class]{expect_s3_class()}} or \code{\link[=expect_s4_class]{expect_s4_class()}} to more clearly
convey your intent.
}
\section{3rd edition}{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
\code{expect_is()} is formally deprecated in the 3rd edition.
}
\keyword{internal}
testthat/man/snapshot_accept.Rd 0000644 0001762 0000144 00000001575 14166627056 016357 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/snapshot-manage.R
\name{snapshot_accept}
\alias{snapshot_accept}
\alias{snapshot_review}
\title{Snapshot management}
\usage{
snapshot_accept(files = NULL, path = "tests/testthat")
snapshot_review(files = NULL, path = "tests/testthat")
}
\arguments{
\item{files}{Optionally, filter effects to snapshots from specified files.
This can be a snapshot name (e.g. \code{foo} or \code{foo.md}), a snapshot file name
(e.g. \code{testfile/foo.txt}), or a snapshot file directory (e.g. \verb{testfile/}).}
\item{path}{Path to tests.}
}
\description{
\itemize{
\item \code{snapshot_accept()} accepts all modified snapshots.
\item \code{snapshot_review()} opens a Shiny app that shows a visual diff of each
modified snapshot. This is particularly useful for whole file snapshots
created by \code{expect_snapshot_file()}.
}
}
testthat/man/expect_success.Rd 0000644 0001762 0000144 00000001332 14164710002 016166 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expect-self-test.R
\name{expect_success}
\alias{expect_success}
\alias{expect_failure}
\alias{show_failure}
\title{Tools for testing expectations}
\usage{
expect_success(expr)
expect_failure(expr, message = NULL, ...)
show_failure(expr)
}
\arguments{
\item{expr}{Expression that evaluates a single expectation.}
\item{message}{Check that the failure message matches this regexp.}
\item{...}{Other arguments passed on to \code{\link[=expect_match]{expect_match()}}.}
}
\description{
Use these expectations to test other expectations.
Use \code{show_failure()} in examples to print the failure message without
throwing an error.
}
\keyword{internal}
testthat/man/expect_less_than.Rd 0000644 0001762 0000144 00000001046 14164710002 016500 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expect-comparison.R
\name{expect_less_than}
\alias{expect_less_than}
\alias{expect_more_than}
\title{Deprecated numeric comparison functions}
\usage{
expect_less_than(...)
expect_more_than(...)
}
\arguments{
\item{...}{All arguments passed on to \code{expect_lt()}/\code{expect_gt()}.}
}
\description{
These functions have been deprecated in favour of the more concise
\code{\link[=expect_gt]{expect_gt()}} and \code{\link[=expect_lt]{expect_lt()}}.
}
\keyword{internal}
testthat/man/MinimalReporter.Rd 0000644 0001762 0000144 00000001673 14164710002 016267 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter-minimal.R
\name{MinimalReporter}
\alias{MinimalReporter}
\title{Test reporter: minimal.}
\description{
The minimal test reporter provides the absolutely minimum amount of
information: whether each expectation has succeeded, failed or experienced
an error. If you want to find out what the failures and errors actually
were, you'll need to run a more informative test reporter.
}
\seealso{
Other reporters:
\code{\link{CheckReporter}},
\code{\link{DebugReporter}},
\code{\link{FailReporter}},
\code{\link{JunitReporter}},
\code{\link{ListReporter}},
\code{\link{LocationReporter}},
\code{\link{MultiReporter}},
\code{\link{ProgressReporter}},
\code{\link{RStudioReporter}},
\code{\link{Reporter}},
\code{\link{SilentReporter}},
\code{\link{StopReporter}},
\code{\link{SummaryReporter}},
\code{\link{TapReporter}},
\code{\link{TeamcityReporter}}
}
\concept{reporters}
testthat/man/teardown_env.Rd 0000644 0001762 0000144 00000000777 14164710002 015655 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/test-files.R
\name{teardown_env}
\alias{teardown_env}
\title{Run code after all test files}
\usage{
teardown_env()
}
\description{
This environment has no purpose other than as a handle for \code{\link[withr:defer]{withr::defer()}}:
use it when you want to run code after all tests have been run.
Typically, you'll use \code{withr::defer(cleanup(), teardown_env())}
immediately after you've made a mess in a \verb{setup-*.R} file.
}
testthat/man/default_reporter.Rd 0000644 0001762 0000144 00000001573 14164710002 016523 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter.R
\name{default_reporter}
\alias{default_reporter}
\alias{default_parallel_reporter}
\alias{default_compact_reporter}
\alias{check_reporter}
\title{Retrieve the default reporter}
\usage{
default_reporter()
default_parallel_reporter()
default_compact_reporter()
check_reporter()
}
\description{
The defaults are:
\itemize{
\item \link{ProgressReporter} for interactive, non-parallel; override with
\code{testthat.default_reporter}
\item \link{ParallelProgressReporter} for interactive, parallel packages;
override with \code{testthat.default_parallel_reporter}
\item \link{CompactProgressReporter} for single-file interactive; override with
\code{testthat.default_compact_reporter}
\item \link{CheckReporter} for R CMD check; override with \code{testthat.default_check_reporter}
}
}
\keyword{internal}
testthat/man/FailReporter.Rd 0000644 0001762 0000144 00000001472 14164710002 015551 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter-fail.R
\name{FailReporter}
\alias{FailReporter}
\title{Test reporter: fail at end.}
\description{
This reporter will simply throw an error if any of the tests failed. It is
best combined with another reporter, such as the
\link{SummaryReporter}.
}
\seealso{
Other reporters:
\code{\link{CheckReporter}},
\code{\link{DebugReporter}},
\code{\link{JunitReporter}},
\code{\link{ListReporter}},
\code{\link{LocationReporter}},
\code{\link{MinimalReporter}},
\code{\link{MultiReporter}},
\code{\link{ProgressReporter}},
\code{\link{RStudioReporter}},
\code{\link{Reporter}},
\code{\link{SilentReporter}},
\code{\link{StopReporter}},
\code{\link{SummaryReporter}},
\code{\link{TapReporter}},
\code{\link{TeamcityReporter}}
}
\concept{reporters}
testthat/man/expect_that.Rd 0000644 0001762 0000144 00000003176 14164710002 015466 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expect-that.R
\name{expect_that}
\alias{expect_that}
\title{Expect that a condition holds.}
\usage{
expect_that(object, condition, info = NULL, label = NULL)
}
\arguments{
\item{object}{Object to test.
Supports limited unquoting to make it easier to generate readable failures
within a function or for loop. See \link{quasi_label} for more details.}
\item{condition, }{a function that returns whether or not the condition
is met, and if not, an error message to display.}
\item{info}{Extra information to be included in the message. This argument
is soft-deprecated and should not be used in new code. Instead see
alternatives in \link{quasi_label}.}
\item{label}{Used to customise failure messages. For expert use only.}
}
\value{
the (internal) expectation result as an invisible list
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#superseded}{\figure{lifecycle-superseded.svg}{options: alt='[Superseded]'}}}{\strong{[Superseded]}}
An old style of testing that's no longer encouraged.
}
\section{3rd edition}{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
This style of testing is formally deprecated as of the 3rd edition.
Use a more specific \code{expect_} function instead.
}
\examples{
expect_that(5 * 2, equals(10))
expect_that(sqrt(2) ^ 2, equals(2))
\dontrun{
expect_that(sqrt(2) ^ 2, is_identical_to(2))
}
}
\seealso{
\code{\link[=fail]{fail()}} for an expectation that always fails.
}
\keyword{internal}
testthat/man/use_catch.Rd 0000644 0001762 0000144 00000011620 14164710002 015105 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/test-compiled-code.R
\name{use_catch}
\alias{use_catch}
\title{Use Catch for C++ Unit Testing}
\usage{
use_catch(dir = getwd())
}
\arguments{
\item{dir}{The directory containing an \R package.}
}
\description{
Add the necessary infrastructure to enable C++ unit testing
in \R packages with \href{https://github.com/catchorg/Catch2}{Catch} and
\code{testthat}.
}
\details{
Calling \code{use_catch()} will:
\enumerate{
\item Create a file \code{src/test-runner.cpp}, which ensures that the
\code{testthat} package will understand how to run your package's
unit tests,
\item Create an example test file \code{src/test-example.cpp}, which
showcases how you might use Catch to write a unit test,
\item Add a test file \code{tests/testthat/test-cpp.R}, which ensures that
\code{testthat} will run your compiled tests during invocations of
\code{devtools::test()} or \verb{R CMD check}, and
\item Create a file \code{R/catch-routine-registration.R}, which ensures that
\R will automatically register this routine when
\code{tools::package_native_routine_registration_skeleton()} is invoked.
}
You will also need to:
\itemize{
\item Add xml2 to Suggests, with e.g. \code{usethis::use_package("xml2", "Suggests")}
\item Add testthat to LinkingTo, with e.g.
\code{usethis::use_package("testthat", "LinkingTo")}
}
C++ unit tests can be added to C++ source files within the
\code{src} directory of your package, with a format similar
to \R code tested with \code{testthat}. Here's a simple example
of a unit test written with \code{testthat} + Catch:
\preformatted{
context("C++ Unit Test") {
test_that("two plus two is four") {
int result = 2 + 2;
expect_true(result == 4);
}
}
}
When your package is compiled, unit tests alongside a harness
for running these tests will be compiled into your \R package,
with the C entry point \code{run_testthat_tests()}. \code{testthat}
will use that entry point to run your unit tests when detected.
}
\section{Functions}{
All of the functions provided by Catch are
available with the \code{CATCH_} prefix -- see
\href{https://github.com/catchorg/Catch2/blob/master/docs/assertions.md}{here}
for a full list. \code{testthat} provides the
following wrappers, to conform with \code{testthat}'s
\R interface:
\tabular{lll}{
\strong{Function} \tab \strong{Catch} \tab \strong{Description} \cr
\code{context} \tab \code{CATCH_TEST_CASE} \tab The context of a set of tests. \cr
\code{test_that} \tab \code{CATCH_SECTION} \tab A test section. \cr
\code{expect_true} \tab \code{CATCH_CHECK} \tab Test that an expression evaluates to \code{true}. \cr
\code{expect_false} \tab \code{CATCH_CHECK_FALSE} \tab Test that an expression evalutes to \code{false}. \cr
\code{expect_error} \tab \code{CATCH_CHECK_THROWS} \tab Test that evaluation of an expression throws an exception. \cr
\code{expect_error_as} \tab \code{CATCH_CHECK_THROWS_AS} \tab Test that evaluation of an expression throws an exception of a specific class. \cr
}
In general, you should prefer using the \code{testthat}
wrappers, as \code{testthat} also does some work to
ensure that any unit tests within will not be compiled or
run when using the Solaris Studio compilers (as these are
currently unsupported by Catch). This should make it
easier to submit packages to CRAN that use Catch.
}
\section{Symbol Registration}{
If you've opted to disable dynamic symbol lookup in your
package, then you'll need to explicitly export a symbol
in your package that \code{testthat} can use to run your unit
tests. \code{testthat} will look for a routine with one of the names:
\preformatted{
C_run_testthat_tests
c_run_testthat_tests
run_testthat_tests
}
See \href{https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Controlling-visibility}{Controlling Visibility}
and \href{https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Registering-symbols}{Registering Symbols}
in the \strong{Writing R Extensions} manual for more information.
}
\section{Advanced Usage}{
If you'd like to write your own Catch test runner, you can
instead use the \code{testthat::catchSession()} object in a file
with the form:
\preformatted{
#define TESTTHAT_TEST_RUNNER
#include