[](https://cran.r-project.org/package=testthat)
[](https://travis-ci.org/r-lib/testthat)
[](https://codecov.io/gh/r-lib/testthat?branch=master)
## 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](http://rspec.info/), [testy](https://github.com/ahoward/testy),
[bacon](https://github.com/chneukirchen/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](http://r-pkgs.had.co.nz/tests.html) in [R
packages](http://r-pkgs.had.co.nz/) 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 13564563701 012677 5 ustar ligges users testthat/man/testthat-package.Rd 0000644 0001762 0000144 00000002737 13216707011 016414 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/test-that.R
\docType{package}
\name{testthat-package}
\alias{testthat}
\alias{testthat-package}
\title{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[=expect_that]{expect_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}).
}
}
\examples{
library(testthat)
a <- 9
expect_that(a, is_less_than(10))
expect_lt(a, 10)
}
\references{
Wickham, H (2011). testthat: Get Started with Testing.
\strong{The R Journal} \emph{3/1} 5-10.
\url{https://journal.r-project.org/archive/2011-1/RJournal_2011-1_Wickham.pdf}
\url{http://adv-r.had.co.nz/Testing.html}
}
\seealso{
Useful links:
\itemize{
\item \url{http://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/auto_test.Rd 0000644 0001762 0000144 00000002774 13165405551 015202 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 00000003005 13456034771 016357 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{Expectation: do two vectors contain the same 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{x}.
}
}
\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 13456034771 017020 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/expect_vector.Rd 0000644 0001762 0000144 00000002275 13456034771 016046 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{Expectation: does the object have vctr properties?}
\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 13564563701 015451 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 13173076020 014262 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 00000001311 13456034771 016644 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 00000002040 13164532741 015155 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{Create a test.}
\usage{
test_that(desc, code)
}
\arguments{
\item{desc}{test name. Names should be kept as brief as possible, as they
are often used as line prefixes.}
\item{code}{test code containing expectations}
}
\description{
A test encapsulates a series of expectations about small, self-contained
set of functionality. Each test is contained in a \link{context} and
contains multiple expectations.
}
\details{
Tests are evaluated in their own environments, and should not affect
global state.
When run from the command line, tests return \code{NULL} if all
expectations are met, otherwise it raises an error.
}
\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)
})
# Failing test:
\dontrun{
test_that("trigonometric functions match identities", {
expect_equal(sin(pi / 4), 1)
})
}
}
testthat/man/SummaryReporter.Rd 0000644 0001762 0000144 00000002374 13564523315 016351 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter-summary.R
\docType{data}
\name{SummaryReporter}
\alias{SummaryReporter}
\title{Test reporter: summary of errors.}
\format{An object of class \code{R6ClassGenerator} of length 24.}
\usage{
SummaryReporter
}
\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{ListReporter}},
\code{\link{LocationReporter}},
\code{\link{MinimalReporter}},
\code{\link{MultiReporter}},
\code{\link{ProgressReporter}}, \code{\link{Reporter}},
\code{\link{RstudioReporter}},
\code{\link{SilentReporter}}, \code{\link{StopReporter}},
\code{\link{TapReporter}}, \code{\link{TeamcityReporter}}
}
\concept{reporters}
\keyword{datasets}
testthat/man/expect_null.Rd 0000644 0001762 0000144 00000002514 13564563701 015512 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expect-null.R
\name{expect_null}
\alias{expect_null}
\title{Expectation: is an object \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_message}},
\code{\link{expect_named}}, \code{\link{expect_output}},
\code{\link{expect_silent}},
\code{\link{inheritance-expectations}},
\code{\link{logical-expectations}}
}
\concept{expectations}
testthat/man/expect_known_output.Rd 0000644 0001762 0000144 00000006613 13564563701 017320 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_output_file}
\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{...}{For \code{expect_equal()} and \code{expect_equivalent()}, passed on
\code{\link[=compare]{compare()}}, for \code{expect_identical()} passed on to \code{\link[=identical]{identical()}}.
Used to control the details of the comparison.}
\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 this will print the result, ensuring that the output of printing
the object is included in the overall output}
\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. \code{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.
}
\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 00000003757 13564563701 015636 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{Expectation: does object have 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.}
\item{...}{Other arguments passed on to \code{\link[=has_names]{has_names()}}.}
}
\description{
You can either check for the presence of names (leaving \code{expected}
blank), specific names (by suppling 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_message}},
\code{\link{expect_null}}, \code{\link{expect_output}},
\code{\link{expect_silent}},
\code{\link{inheritance-expectations}},
\code{\link{logical-expectations}}
}
\concept{expectations}
testthat/man/fail.Rd 0000644 0001762 0000144 00000001413 13521025554 014070 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)
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.}
}
\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 00000000747 13164532741 015021 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/test-files.R
\name{test_env}
\alias{test_env}
\title{Generate default testing environment.}
\usage{
test_env()
}
\description{
We use a new environment which inherits from \code{\link[=globalenv]{globalenv()}}.
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 00000001757 13564523315 016470 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter-location.R
\docType{data}
\name{LocationReporter}
\alias{LocationReporter}
\title{Test reporter: location}
\format{An object of class \code{R6ClassGenerator} of length 24.}
\usage{
LocationReporter
}
\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{ListReporter}},
\code{\link{MinimalReporter}},
\code{\link{MultiReporter}},
\code{\link{ProgressReporter}}, \code{\link{Reporter}},
\code{\link{RstudioReporter}},
\code{\link{SilentReporter}}, \code{\link{StopReporter}},
\code{\link{SummaryReporter}}, \code{\link{TapReporter}},
\code{\link{TeamcityReporter}}
}
\concept{reporters}
\keyword{datasets}
testthat/man/StopReporter.Rd 0000644 0001762 0000144 00000002316 13564523315 015635 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter-stop.R
\docType{data}
\name{StopReporter}
\alias{StopReporter}
\title{Test reporter: stop on error.}
\format{An object of class \code{R6ClassGenerator} of length 24.}
\usage{
StopReporter
}
\description{
The default reporter, executed when \code{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{ListReporter}},
\code{\link{LocationReporter}},
\code{\link{MinimalReporter}},
\code{\link{MultiReporter}},
\code{\link{ProgressReporter}}, \code{\link{Reporter}},
\code{\link{RstudioReporter}},
\code{\link{SilentReporter}},
\code{\link{SummaryReporter}}, \code{\link{TapReporter}},
\code{\link{TeamcityReporter}}
}
\concept{reporters}
\keyword{datasets}
testthat/man/capture_condition.Rd 0000644 0001762 0000144 00000003124 13564563701 016677 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/capture-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 messeages, 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{
These functions allow you to capture the side-effects of a function call
including printed output, messages and warnings. They are used to evaluate
code for \code{\link[=expect_output]{expect_output()}}, \code{\link[=expect_message]{expect_message()}},
\code{\link[=expect_warning]{expect_warning()}}, and \code{\link[=expect_silent]{expect_silent()}}.
}
\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 00000002605 13564563701 017420 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expect-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{
\code{is_informative_error()} is a generic predicate that indicates
whether testthat users should explicitly test for an error
class. When it returns \code{TRUE} (the default), and \code{expect_error()}
does not check for the class, a warning is issued during tests.
You can silence the warning by implementing \code{is_informative_error()}.
The main use case for overriding this method is to introduce an
experimental error class when you need more experience while
developing an error hierarchy for your package. Override
\code{is_informative_error()} to return \code{FALSE} to avoid encouraging
users to depend on the experimental class in their tests.
Since testthat should be a \code{Suggest} dependency, methods for
\code{is_informative_error()} should typically be lazily registered,
e.g. with \code{vctrs::s3_register()}.
}
\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/expect_message.Rd 0000644 0001762 0000144 00000006565 13564563701 016176 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expect-messages.R
\name{expect_message}
\alias{expect_message}
\alias{expect_warning}
\title{Expectation: does code produce warnings or messages?}
\usage{
expect_message(object, regexp = NULL, ..., all = FALSE, info = NULL,
label = NULL)
expect_warning(object, regexp = NULL, ..., all = 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{regexp}{Regular expression to test against.
\itemize{
\item A character vector giving a regular expression that must match the
message/warning
\item If \code{NULL}, the default, asserts that there should be a messsage/warning,
but doesn't test for a specific value.
\item If \code{NA}, asserts that there shouldn't be any messages or warnings.
}}
\item{...}{Arguments passed on to \code{expect_match}
\describe{
\item{all}{Should all elements of actual value match \code{regexp} (TRUE),
or does only one need to match (FALSE)}
\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{all}{Do messages/warnings need to match the \code{regexp} (\code{TRUE}), or
does only one need to match (\code{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.}
}
\value{
The first argument, invisibly.
}
\description{
Use \code{expect_message()} and \code{expect_warning()} to check if the messages or
warnings match the given regular expression.
}
\examples{
# Messages ------------------------------------------------------------------
f <- function(x) {
if (x < 0) {
message("*x* is already negative")
return(x)
}
-x
}
expect_message(f(-1))
expect_message(f(-1), "already negative")
expect_message(f(1), NA)
# To test message and output, store results to a variable
expect_message(out <- f(-1), "already negative")
expect_equal(out, -1)
# You can use the arguments of grepl to control the matching
expect_message(f(-1), "*x*", fixed = TRUE)
expect_message(f(-1), "NEGATIVE", ignore.case = TRUE)
# Warnings ------------------------------------------------------------------
f <- function(x) {
if (x < 0) {
warning("*x* is already negative")
return(x)
}
-x
}
expect_warning(f(-1))
expect_warning(f(-1), "already negative")
expect_warning(f(1), NA)
# To test message and output, store results to a variable
expect_warning(out <- f(-1), "already negative")
expect_equal(out, -1)
# You can use the arguments of grepl to control the matching
expect_warning(f(-1), "*x*", fixed = TRUE)
expect_warning(f(-1), "NEGATIVE", ignore.case = TRUE)
}
\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_silent}},
\code{\link{inheritance-expectations}},
\code{\link{logical-expectations}}
}
\concept{expectations}
testthat/man/oldskool.Rd 0000644 0001762 0000144 00000002621 13164532741 015011 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{
Initial testthat used a style of testing that looked like
\code{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 13164532741 016032 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 00000001662 13564523315 015730 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter-check.R
\docType{data}
\name{CheckReporter}
\alias{CheckReporter}
\title{Check reporter: 13 line summary of problems}
\format{An object of class \code{R6ClassGenerator} of length 24.}
\usage{
CheckReporter
}
\description{
\code{R CMD check} displays only the last 13 lines of the result, so this
report is design to ensure that you see something useful there.
}
\seealso{
Other reporters: \code{\link{DebugReporter}},
\code{\link{FailReporter}}, \code{\link{ListReporter}},
\code{\link{LocationReporter}},
\code{\link{MinimalReporter}},
\code{\link{MultiReporter}},
\code{\link{ProgressReporter}}, \code{\link{Reporter}},
\code{\link{RstudioReporter}},
\code{\link{SilentReporter}}, \code{\link{StopReporter}},
\code{\link{SummaryReporter}}, \code{\link{TapReporter}},
\code{\link{TeamcityReporter}}
}
\concept{reporters}
\keyword{datasets}
testthat/man/expect_match.Rd 0000644 0001762 0000144 00000004440 13564563701 015634 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}
\title{Expectation: does string match a regular expression?}
\usage{
expect_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{base::grepl}
\describe{
\item{ignore.case}{if \code{FALSE}, the pattern matching is \emph{case
sensitive} and if \code{TRUE}, case is ignored during matching.}
\item{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{
Expectation: does 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.
}
\examples{
expect_match("Testing is fun", "fun")
expect_match("Testing is fun", "f.n")
\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_message}}, \code{\link{expect_named}},
\code{\link{expect_null}}, \code{\link{expect_output}},
\code{\link{expect_silent}},
\code{\link{inheritance-expectations}},
\code{\link{logical-expectations}}
}
\concept{expectations}
testthat/man/MultiReporter.Rd 0000644 0001762 0000144 00000001661 13564523315 016004 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter-multi.R
\docType{data}
\name{MultiReporter}
\alias{MultiReporter}
\title{Multi reporter: combine several reporters in one.}
\format{An object of class \code{R6ClassGenerator} of length 24.}
\usage{
MultiReporter
}
\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{ListReporter}},
\code{\link{LocationReporter}},
\code{\link{MinimalReporter}},
\code{\link{ProgressReporter}}, \code{\link{Reporter}},
\code{\link{RstudioReporter}},
\code{\link{SilentReporter}}, \code{\link{StopReporter}},
\code{\link{SummaryReporter}}, \code{\link{TapReporter}},
\code{\link{TeamcityReporter}}
}
\concept{reporters}
\keyword{datasets}
testthat/man/not.Rd 0000644 0001762 0000144 00000000664 13173076020 013761 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 13456034771 016721 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 00000003637 13564563701 015155 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 specified file}
\usage{
test_file(path, reporter = default_reporter(), env = test_env(),
start_end_reporter = TRUE, load_helpers = TRUE,
encoding = "unknown", wrap = TRUE)
}
\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{env}{Environment in which to execute the tests. Expert use only.}
\item{start_end_reporter}{Should the reporters \code{start_reporter()} and
\code{end_reporter()} methods be called? For expert use only.}
\item{load_helpers}{Source helper files before running the tests?
See \code{\link[=source_test_helpers]{source_test_helpers()}} for more details.}
\item{encoding}{Deprecated. All files now assumed to be UTF-8.}
\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.}
}
\value{
Invisibily, a list with one element for each test.
}
\description{
Execute code in the specified file, displaying results using a \code{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.
}
\details{
Any errors that occur in code run outside of \code{test_that()} will generate
a test failure and terminate execution of that test file.
}
\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]])
}
testthat/man/ProgressReporter.Rd 0000644 0001762 0000144 00000002271 13564523315 016514 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter-progress.R
\docType{data}
\name{ProgressReporter}
\alias{ProgressReporter}
\title{Test reporter: interactive progress bar of errors.}
\format{An object of class \code{R6ClassGenerator} of length 24.}
\usage{
ProgressReporter
}
\description{
This reporter is a reimagining of \link{SummaryReporter} desgined to make the
most information available up front, while taking up less space overall. It
is the default reporting reporter used by \code{\link[=test_dir]{test_dir()}} and \code{\link[=test_file]{test_file()}}.
}
\details{
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{ListReporter}},
\code{\link{LocationReporter}},
\code{\link{MinimalReporter}},
\code{\link{MultiReporter}}, \code{\link{Reporter}},
\code{\link{RstudioReporter}},
\code{\link{SilentReporter}}, \code{\link{StopReporter}},
\code{\link{SummaryReporter}}, \code{\link{TapReporter}},
\code{\link{TeamcityReporter}}
}
\concept{reporters}
\keyword{datasets}
testthat/man/source_file.Rd 0000644 0001762 0000144 00000003353 13456034771 015471 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,
encoding = "unknown", 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{encoding}{Deprecated.}
\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
}
\section{Test files}{
For package code, tests should live in \code{tests/testthat}.
There are four classes of \code{.R} files that have special behaviour:
\itemize{
\item Test files start with \code{test} and are executed in alphabetical order.
\item Helper files start with \code{helper} and are executed before tests are
run and from \code{devtools::load_all()}.
\item Setup files start with \code{setup} and are executed before tests, but not
during \code{devtools::load_all()}.
\item Teardown files start with \code{teardown} and are executed after the tests
are run.
}
}
\keyword{internal}
testthat/man/capture_output.Rd 0000644 0001762 0000144 00000002330 13456034771 016247 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}
\title{Capture output to console}
\usage{
capture_output(code, print = FALSE, width = 80)
capture_output_lines(code, print = FALSE, width = 80)
}
\arguments{
\item{code}{Code to evaluate.}
\item{print}{If \code{TRUE} and the result of evaluating \code{code} is
visible this will print the result, ensuring that the output of printing
the object is included in the overall output}
\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()}}.
}
\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 00000001607 13564523315 015740 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter-debug.R
\docType{data}
\name{DebugReporter}
\alias{DebugReporter}
\title{Test reporter: start recovery.}
\format{An object of class \code{R6ClassGenerator} of length 24.}
\usage{
DebugReporter
}
\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{ListReporter}},
\code{\link{LocationReporter}},
\code{\link{MinimalReporter}},
\code{\link{MultiReporter}},
\code{\link{ProgressReporter}}, \code{\link{Reporter}},
\code{\link{RstudioReporter}},
\code{\link{SilentReporter}}, \code{\link{StopReporter}},
\code{\link{SummaryReporter}}, \code{\link{TapReporter}},
\code{\link{TeamcityReporter}}
}
\concept{reporters}
\keyword{datasets}
testthat/man/test_dir.Rd 0000644 0001762 0000144 00000007713 13564563701 015013 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/test-directory.R
\name{test_dir}
\alias{test_dir}
\alias{test_package}
\alias{test_check}
\alias{is_testing}
\alias{testing_package}
\title{Run all tests in directory or package}
\usage{
test_dir(path, filter = NULL, reporter = default_reporter(),
env = test_env(), ..., encoding = "unknown", load_helpers = TRUE,
stop_on_failure = FALSE, stop_on_warning = FALSE, wrap = TRUE)
test_package(package, filter = NULL, reporter = check_reporter(), ...,
stop_on_failure = TRUE, stop_on_warning = FALSE)
test_check(package, filter = NULL, reporter = check_reporter(), ...,
stop_on_failure = TRUE, stop_on_warning = FALSE, wrap = TRUE)
is_testing()
testing_package()
}
\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 be performed on the file
name after it has been 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{encoding}{Deprecated. All files now assumed to be UTF-8.}
\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.
For historical reasons, the default value of \code{stop_on_failure} is \code{TRUE}
for \code{test_package()} and \code{test_check()} but \code{FALSE} for \code{test_dir()}, so
if you're calling \code{test_dir()} you may want to consider explicitly setting
\code{stop_on_failure = TRUE}.}
\item{stop_on_warning}{If \code{TRUE}, throw an error if any tests generate
warnings.}
\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{package}{Name of installed package.}
}
\value{
A list of test results.
}
\description{
Use \code{test_dir()} for a collection of tests in a directory; use
\code{test_package()} interactively at the console, and \code{test_check()}
inside of \code{R CMD check}.
In your own code, you can use \code{is_testing()} to determine if code is being
run as part of a test and \code{testing_package()} to retrieve the name of the
package being tested. You can also check the underlying env var directly
\code{identical(Sys.getenv("TESTTHAT"), "true")} to avoid creating a run-time
dependency on testthat.
}
\section{Test files}{
For package code, tests should live in \code{tests/testthat}.
There are four classes of \code{.R} files that have special behaviour:
\itemize{
\item Test files start with \code{test} and are executed in alphabetical order.
\item Helper files start with \code{helper} and are executed before tests are
run and from \code{devtools::load_all()}.
\item Setup files start with \code{setup} and are executed before tests, but not
during \code{devtools::load_all()}.
\item Teardown files start with \code{teardown} and are executed after the tests
are run.
}
}
\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.
}
\section{\code{R CMD check}}{
To run testthat automatically from \code{R CMD check}, make sure you have
a \code{tests/testthat.R} that contains:\preformatted{library(testthat)
library(yourpackage)
test_check("yourpackage")
}
}
\examples{
test_dir(testthat_examples(), reporter = "summary")
test_dir(testthat_examples(), reporter = "minimal")
}
testthat/man/TeamcityReporter.Rd 0000644 0001762 0000144 00000001755 13564523315 016475 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter-teamcity.R
\docType{data}
\name{TeamcityReporter}
\alias{TeamcityReporter}
\title{Test reporter: Teamcity format.}
\format{An object of class \code{R6ClassGenerator} of length 24.}
\usage{
TeamcityReporter
}
\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{ListReporter}},
\code{\link{LocationReporter}},
\code{\link{MinimalReporter}},
\code{\link{MultiReporter}},
\code{\link{ProgressReporter}}, \code{\link{Reporter}},
\code{\link{RstudioReporter}},
\code{\link{SilentReporter}}, \code{\link{StopReporter}},
\code{\link{SummaryReporter}}, \code{\link{TapReporter}}
}
\concept{reporters}
\keyword{datasets}
testthat/man/safe_digest.Rd 0000644 0001762 0000144 00000000716 13164532741 015443 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 00000005656 13564563701 017543 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_equivalent}
\alias{expect_identical}
\alias{expect_reference}
\title{Expectation: is the object equal to a value?}
\usage{
expect_equal(object, expected, ..., info = NULL, label = NULL,
expected.label = NULL)
expect_equivalent(object, expected, ..., info = NULL, label = NULL,
expected.label = NULL)
expect_identical(object, expected, info = NULL, label = NULL,
expected.label = NULL, ...)
expect_reference(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{...}{For \code{expect_equal()} and \code{expect_equivalent()}, passed on
\code{\link[=compare]{compare()}}, for \code{expect_identical()} passed on to \code{\link[=identical]{identical()}}.
Used to control the details of the comparison.}
\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{
\itemize{
\item \code{expect_identical()} compares values with \code{\link[=identical]{identical()}}.
\item \code{expect_equal()} compares values with \code{\link[=all.equal]{all.equal()}}
\item \code{expect_equivalent()} compares values with \code{\link[=all.equal]{all.equal()}} and
\code{check.attributes = FALSE}
\item \code{expect_reference()} compares the underlying memory addresses.
}
}
\examples{
a <- 10
expect_equal(a, 10)
# Use expect_equal() when testing for numeric equality
sqrt(2) ^ 2 - 1
expect_equal(sqrt(2) ^ 2, 2)
# Neither of these forms take floating point representation errors into
# account
\dontrun{
expect_true(sqrt(2) ^ 2 == 2)
expect_identical(sqrt(2) ^ 2, 2)
}
# You can pass on additional arguments to all.equal:
\dontrun{
# Test the ABSOLUTE difference is within .002
expect_equal(10.01, 10, tolerance = .002, scale = 1)
}
# Test the RELATIVE difference is within .002
x <- 10
expect_equal(10.01, expected = x, tolerance = 0.002, scale = x)
# expect_equivalent ignores attributes
a <- b <- 1:3
names(b) <- letters[1:3]
expect_equivalent(a, b)
}
\seealso{
\code{expect_setequal()} to test for set equality.
Other expectations: \code{\link{comparison-expectations}},
\code{\link{expect_error}}, \code{\link{expect_length}},
\code{\link{expect_match}}, \code{\link{expect_message}},
\code{\link{expect_named}}, \code{\link{expect_null}},
\code{\link{expect_output}}, \code{\link{expect_silent}},
\code{\link{inheritance-expectations}},
\code{\link{logical-expectations}}
}
\concept{expectations}
testthat/man/inheritance-expectations.Rd 0000644 0001762 0000144 00000004514 13564563701 020167 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{Expectation: does the object inherit from a S3 or S4 class, or is it a base type?}
\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}{character vector of class names}
\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_s4_class(x, class)} checks that \code{x} is an S4 object that
\code{\link[=is]{is()}} \code{class}.
}
}
\examples{
x <- data.frame(x = 1:10, y = "x")
# 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"))
# By default data.frame() converts characters 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_message}},
\code{\link{expect_named}}, \code{\link{expect_null}},
\code{\link{expect_output}}, \code{\link{expect_silent}},
\code{\link{logical-expectations}}
}
\concept{expectations}
testthat/man/expect_is.Rd 0000644 0001762 0000144 00000001566 13456034771 015161 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{Expectation: does the 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}{character vector of class names}
}
\description{
\code{expect_is()} is an older form that uses \code{\link[=inherits]{inherits()}} without checking
whether \code{x} is S3, S4, or neither. Intead, 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.
}
\keyword{internal}
testthat/man/expect_success.Rd 0000644 0001762 0000144 00000001503 13456034771 016205 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}
\alias{expect_known_failure}
\title{Tools for testing expectations}
\usage{
expect_success(expr)
expect_failure(expr, message = NULL, ...)
show_failure(expr)
expect_known_failure(path, 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()}}.}
\item{path}{Path to save failure output}
}
\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/MinimalReporter.Rd 0000644 0001762 0000144 00000002055 13564523315 016276 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter-minimal.R
\docType{data}
\name{MinimalReporter}
\alias{MinimalReporter}
\title{Test reporter: minimal.}
\format{An object of class \code{R6ClassGenerator} of length 24.}
\usage{
MinimalReporter
}
\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{ListReporter}},
\code{\link{LocationReporter}},
\code{\link{MultiReporter}},
\code{\link{ProgressReporter}}, \code{\link{Reporter}},
\code{\link{RstudioReporter}},
\code{\link{SilentReporter}}, \code{\link{StopReporter}},
\code{\link{SummaryReporter}}, \code{\link{TapReporter}},
\code{\link{TeamcityReporter}}
}
\concept{reporters}
\keyword{datasets}
testthat/man/default_reporter.Rd 0000644 0001762 0000144 00000000766 13456034771 016545 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{check_reporter}
\title{Retrieve the default reporter}
\usage{
default_reporter()
check_reporter()
}
\description{
The defaults are:
\itemize{
\item \link{ProgressReporter} for interactive; override with \code{testthat.default_reporter}
\item \link{CheckReporter} for R CMD check; override with \code{testthat.default_check_reporter}
}
}
\keyword{internal}
testthat/man/FailReporter.Rd 0000644 0001762 0000144 00000001651 13564523315 015564 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reporter-fail.R
\docType{data}
\name{FailReporter}
\alias{FailReporter}
\title{Test reporter: fail at end.}
\format{An object of class \code{R6ClassGenerator} of length 24.}
\usage{
FailReporter
}
\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{ListReporter}},
\code{\link{LocationReporter}},
\code{\link{MinimalReporter}},
\code{\link{MultiReporter}},
\code{\link{ProgressReporter}}, \code{\link{Reporter}},
\code{\link{RstudioReporter}},
\code{\link{SilentReporter}}, \code{\link{StopReporter}},
\code{\link{SummaryReporter}}, \code{\link{TapReporter}},
\code{\link{TeamcityReporter}}
}
\concept{reporters}
\keyword{datasets}
testthat/man/expect_that.Rd 0000644 0001762 0000144 00000002226 13456034771 015500 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{
An old style of testing that's no longer encouraged.
}
\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 00000011235 13173076020 015113 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/philsquared/Catch}{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 \code{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.
}
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/philsquared/Catch/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 This vignette shows you how to create custom expectations that work identically to the built-in expect_ functions.
There are three main parts to writing an expectation, as illustrated by expect_length():
expect_length <- function(object, n) {
# 1. Capture object and label
act <- quasi_label(rlang::enquo(object), arg = "object")
# 2. Call expect()
act$n <- length(act$val)
expect(
act$n == n,
sprintf("%s has length %i, not length %i.", act$lab, act$n, n)
)
# 3. Invisibly return the value
invisible(act$val)
}The first step in any expectation is to capture the actual object, and generate a label for it to use if a failure occur. All testthat expectations support quasiquotation so that you can unquote variables. This makes it easier to generate good labels when the expectation is called from a function or within a for loop.
By convention, the first argument to every expect_ function is called object, and you capture it’s value (val) and label (lab) with act <- quasi_label(enquo(object)), where act is short for actual.
Next, you should verify the expectation. This often involves a little computation (here just figuring out the length), and you should typically store the results back into the act object.
Next you call expect(). This has two arguments:
ok: was the expectation successful? This is usually easy to write
failure_message: What informative error message should be reported to the user so that they can diagnose the problem. This is often hard to write!
For historical reasons, most built-in expectations generate these with sprintf(), but today I’d recommend using the glue package
succeed() and fail()For expectations with more complex logic governing when success or failure occurs, you can use succeed() and fail(). These are simple wrappers around expect() that allow you to write code that looks like this:
Use the expectations expect_success() and expect_failure() to test your expectation.