src/library/tools/man/assertCondition.Rd

\name{assertCondition}
\alias{assertCondition}
\alias{assertWarning}
\alias{assertError}
\title{Asserting Error Conditions}
\description{
  When testing code, it is not sufficient to check that results are correct,
  but also that errors or warnings are signalled in appropriate
  situations.  The functions described here provide a convenient
  facility for doing so.  The three functions check that evaluating the
  supplied expression produces an error, a warning or one of a
  specified list of conditions, respectively.  If the assertion fails,
  an error is signalled.
}
\usage{
assertError(expr, verbose = FALSE)
assertWarning(expr, verbose = FALSE)
assertCondition(expr, ..., .exprString = , verbose = FALSE)
}
\arguments{
  \item{expr}{an unevaluated \R expression which will be evaluated via
    \code{\link{tryCatch}(expr, ..)}.}
  \item{\dots}{\code{\link{character}} strings corresponding to the
    classes of the conditions that would satisfy the assertion; e.g., \code{"error"} or
    \code{"warning"}. If none are specified, any condition will
    satisfy the assertion.  See the details section. }
  \item{.exprString}{The string to be printed corresponding to
    \code{expr}. By default, the actual \code{expr} will be
    deparsed.  Will be omitted if the function is supplied with the
    actual expression to be tested.  If \code{assertCondition()} is
    called from another function, with the actual expression passed as
    an argument to that function, supply the deparsed version.}
  \item{verbose}{If \code{TRUE}, a message is printed when the
    condition is satisfied.}
}
\details{
  \code{assertCondition()} uses the general condition mechanism to
  check all the conditions generated in evaluating \code{expr}.  The
  occurrence of any of the supplied condition classes among these satisfies the
  assertion regardless of what other conditions may be signalled.

  \code{assertError()} is a convenience function for asserting errors;
  it calls \code{assertCondition()}.

  \code{assertWarning()} asserts that a warning will be signalled, but
  \emph{not} an error, whereas \code{assertCondition(expr, "warning")}
  will be satisfied even if an error follows the warning.  See the examples.
 }
\value{
  If the assertion is satisfied, a list of all the condition objects
  signalled is returned, invisibly. See \code{\link{conditionMessage}} for the
  interpretation of these objects.  Note that \emph{all} conditions
  signalled during the evaluation are returned, whether or not they
  were among the requirements.
}
\author{John Chambers and Martin Maechler}
\seealso{
  \code{\link{stop}}, \code{\link{warning}};
  \code{\link{signalCondition}}, \code{\link{tryCatch}}.
}
\examples{
  assertError(sqrt("abc"))
  assertWarning(matrix(1:8, 4,3))

  assertCondition( ""-1 ) # ok, any condition would satisfy this

try( assertCondition(sqrt(2), "warning") )
## .. Failed to get warning in evaluating sqrt(2)
     assertCondition(sqrt("abc"), "error")   # ok
try( assertCondition(sqrt("abc"), "warning") )# -> error: had no warning
     assertCondition(sqrt("abc"), "error")
  ## identical to assertError() call above

assertCondition(matrix(1:5, 2,3), "warning")
try( assertCondition(matrix(1:8, 4,3), "error") )
## .. Failed to get expected error ....

## either warning or worse:
assertCondition(matrix(1:8, 4,3), "error","warning") # OK
assertCondition(matrix(1:8, 4, 3), "warning") # OK

## when both are signalled:
ff <- function() { warning("my warning"); stop("my error") }
    assertCondition(ff(), "warning")
## but assertWarning does not allow an error to follow
try(assertWarning(ff()))
    assertCondition(ff(), "error")          # ok
assertCondition(ff(), "error", "warning") # ok (quietly, catching warning)

## assert that assertC..() does not assert [and use *one* argument only]
assertCondition( assertCondition(sqrt( 2   ), "warning") )
assertCondition( assertCondition(sqrt("abc"), "warning"), "error")
assertCondition( assertCondition(matrix(1:8, 4,3), "error"),
                "error")
}
\keyword{programming}
\keyword{error}