Tweak documentation & functionality of new expes

r-lib · Jan 23, 2014 · e76372b · e76372b
1 parent 5d11e65
commit e76372b
Show file tree

Hide file tree

Showing 18 changed files with 208 additions and 249 deletions.
diff --git a/NEWS.md b/NEWS.md
@@ -34,6 +34,10 @@ to include source references so you can see exactly where failures occured.
 
 * `expect_named()` and `has_names()` to check the names of a vector (#79)
 
+* `expect_more_than()`, `is_more_than()`, `expect_less_than()`,
+  `is_less_than()` to check values above or below a threshold.
+  (#77, thanks to @jknowles)
+
 ## Minor improvements and bug fixes
 
 * `expect_that()` (and thus all `expect_*` functions) now invisibly return

diff --git a/R/expectations.r b/R/expectations.r
@@ -626,10 +626,12 @@ normalise_names <- function(x, ignore.order = FALSE, ignore.case = FALSE) {
   x
 }
 
-#' Expectation: is returned value less than specified value?
+#' Expectation: is returned value less or greater than specified value?
 #'
-#' This is useful for ensuring returned value is below a ceiling.
-#
+#' This is useful for ensuring returned value is below a ceiling or above
+#' a floor.
+#'
+#' @inheritParams expect_that
 #' @param expected Expected value
 #' @param label For full form, label of expected object used in error
 #'   messages. Useful to override default (deparsed expected expression) when
@@ -638,34 +640,45 @@ normalise_names <- function(x, ignore.order = FALSE, ignore.case = FALSE) {
 #' @param expected.label Equivalent of \code{label} for shortcut form.
 #' @param ... other values passed to \code{\link{all.equal}}
 #' @family expectations
-#' @export
 #' @examples
 #' a <- 9
 #' expect_that(a, is_less_than(10))
 #' expect_less_than(a, 10)
+#'
+#' \dontrun{
+#' expect_less_than(11, 10)
+#' }
+#'
+#' a <- 11
+#' expect_that(a, is_more_than(10))
+#' expect_more_than(a, 10)
+#' \dontrun{
+#' expect_more_than(9, 10)
+#' }
+#' @name expect-compare
+NULL
+
+#' @rdname expect-compare
+#' @export
 is_less_than <- function(expected, label = NULL, ...) {
   if (is.null(label)) {
     label <- find_expr("expected")
   } else if (!is.character(label) || length(label) != 1) {
     label <- deparse(label)
   }
   function(actual) {
-    less <- actual < expected
     diff <- expected - actual
-    if (isTRUE(less)) {
-      diff <- "Actual is less than expected"
-    } else {
-      diff <- str_c(diff, collapse = "\n")
-    }
+
     expectation(
-      identical(actual, expected),
-      str_c("not less than ", label, ". Difference: \n", diff)
+      diff > 0,
+      paste0("not less than ", label, ". Difference: ", format(diff)),
+      paste0("is less than ", label)
     )
   }
 }
+
 #' @export
-#' @rdname is_less_than
-#' @inheritParams expect_that
+#' @rdname expect-compare
 expect_less_than <- function(object, expected, ..., info = NULL, label = NULL,
                          expected.label = NULL) {
   if (is.null(label)) {
@@ -678,46 +691,26 @@ expect_less_than <- function(object, expected, ..., info = NULL, label = NULL,
               info = info, label = label)
 }
 
-#' Expectation: is returned value more than specified value?
-#'
-#' This is useful for ensuring returned value is above a floor.
-#
-#' @param expected Expected value
-#' @param label For full form, label of expected object used in error
-#'   messages. Useful to override default (deparsed expected expression) when
-#'   doing tests in a loop.  For short cut form, object label. When
-#'   \code{NULL}, computed from deparsed object.
-#' @param expected.label Equivalent of \code{label} for shortcut form.
-#' @param ... other values passed to \code{\link{all.equal}}
-#' @family expectations
+#' @rdname expect-compare
 #' @export
-#' @examples
-#' a <- 11
-#' expect_that(a, is_more_than(10))
-#' expect_more_than(a, 10)
 is_more_than <- function(expected, label = NULL, ...) {
   if (is.null(label)) {
     label <- find_expr("expected")
   } else if (!is.character(label) || length(label) != 1) {
     label <- deparse(label)
   }
   function(actual) {
-    more <- expected < actual
-    diff <- actual - expected
-    if (isTRUE(more)) {
-      diff <- "Actual is greater than expected"
-    } else {
-      diff <- str_c(diff, collapse = "\n")
-    }
+    diff <- expected - actual
+
     expectation(
-      identical(actual, expected),
-      str_c("not more than ", label, ". Difference: \n", diff)
+      diff < 0,
+      paste0("not more than ", label, ". Difference: ", format(diff)),
+      paste0("is more than")
     )
   }
 }
 #' @export
-#' @rdname is_more_than
-#' @inheritParams expect_that
+#' @rdname expect-compare
 expect_more_than <- function(object, expected, ..., info = NULL, label = NULL,
                              expected.label = NULL) {
   if (is.null(label)) {

diff --git a/man/equals.Rd b/man/equals.Rd
@@ -60,21 +60,22 @@ expect_equal(object = 10.01, expected = expectedValue, tolerance = 0.002,
 }
 }
 \seealso{
-Other expectations: \code{\link{expect_equivalent}},
+Other expectations: \code{\link{expect-compare}},
+\code{\link{expect_less_than}},
+\code{\link{expect_more_than}}, \code{\link{is_less_than}},
+\code{\link{is_more_than}};
+\code{\link{expect_equivalent}},
 \code{\link{is_equivalent_to}}; \code{\link{expect_error}},
 \code{\link{throws_error}}; \code{\link{expect_false}},
 \code{\link{is_false}}; \code{\link{expect_identical}},
 \code{\link{is_identical_to}}; \code{\link{expect_is}},
-\code{\link{is_a}}; \code{\link{expect_less_than}},
-\code{\link{is_less_than}}; \code{\link{expect_match}},
+\code{\link{is_a}}; \code{\link{expect_match}},
 \code{\link{matches}}; \code{\link{expect_message}},
-\code{\link{shows_message}};
-\code{\link{expect_more_than}}, \code{\link{is_more_than}};
-\code{\link{expect_named}}, \code{\link{has_names}};
-\code{\link{expect_null}}, \code{\link{is_null}};
-\code{\link{expect_output}}, \code{\link{prints_text}};
-\code{\link{expect_true}}, \code{\link{is_true}};
-\code{\link{expect_warning}}, \code{\link{gives_warning}};
-\code{\link{takes_less_than}}
+\code{\link{shows_message}}; \code{\link{expect_named}},
+\code{\link{has_names}}; \code{\link{expect_null}},
+\code{\link{is_null}}; \code{\link{expect_output}},
+\code{\link{prints_text}}; \code{\link{expect_true}},
+\code{\link{is_true}}; \code{\link{expect_warning}},
+\code{\link{gives_warning}}; \code{\link{takes_less_than}}
 }
 
diff --git a/man/is_more_than.Rd → man/expect-compare.Rd b/man/is_more_than.Rd → man/expect-compare.Rd
@@ -1,8 +1,16 @@
-\name{is_more_than}
+\name{expect-compare}
+\alias{expect-compare}
+\alias{expect_less_than}
 \alias{expect_more_than}
+\alias{is_less_than}
 \alias{is_more_than}
-\title{Expectation: is returned value more than specified value?}
+\title{Expectation: is returned value less or greater than specified value?}
 \usage{
+is_less_than(expected, label = NULL, ...)
+
+expect_less_than(object, expected, ..., info = NULL, label = NULL,
+  expected.label = NULL)
+
 is_more_than(expected, label = NULL, ...)
 
 expect_more_than(object, expected, ..., info = NULL, label = NULL,
@@ -29,13 +37,24 @@ expect_more_than(object, expected, ..., info = NULL, label = NULL,
   message (useful when writing tests in loops).}
 }
 \description{
-This is useful for ensuring returned value is above a
-floor.
+This is useful for ensuring returned value is below a
+ceiling or above a floor.
 }
 \examples{
+a <- 9
+expect_that(a, is_less_than(10))
+expect_less_than(a, 10)
+
+\dontrun{
+expect_less_than(11, 10)
+}
+
 a <- 11
 expect_that(a, is_more_than(10))
 expect_more_than(a, 10)
+\dontrun{
+expect_more_than(9, 10)
+}
 }
 \seealso{
 Other expectations: \code{\link{equals}},
@@ -45,8 +64,7 @@ Other expectations: \code{\link{equals}},
 \code{\link{throws_error}}; \code{\link{expect_false}},
 \code{\link{is_false}}; \code{\link{expect_identical}},
 \code{\link{is_identical_to}}; \code{\link{expect_is}},
-\code{\link{is_a}}; \code{\link{expect_less_than}},
-\code{\link{is_less_than}}; \code{\link{expect_match}},
+\code{\link{is_a}}; \code{\link{expect_match}},
 \code{\link{matches}}; \code{\link{expect_message}},
 \code{\link{shows_message}}; \code{\link{expect_named}},
 \code{\link{has_names}}; \code{\link{expect_null}},

diff --git a/man/gives_warning.Rd b/man/gives_warning.Rd
@@ -50,21 +50,21 @@ expect_warning(f(-1), "NEGATIVE", ignore.case = TRUE)
 }
 \seealso{
 Other expectations: \code{\link{equals}},
-\code{\link{expect_equal}};
+\code{\link{expect_equal}}; \code{\link{expect-compare}},
+\code{\link{expect_less_than}},
+\code{\link{expect_more_than}}, \code{\link{is_less_than}},
+\code{\link{is_more_than}};
 \code{\link{expect_equivalent}},
 \code{\link{is_equivalent_to}}; \code{\link{expect_error}},
 \code{\link{throws_error}}; \code{\link{expect_false}},
 \code{\link{is_false}}; \code{\link{expect_identical}},
 \code{\link{is_identical_to}}; \code{\link{expect_is}},
-\code{\link{is_a}}; \code{\link{expect_less_than}},
-\code{\link{is_less_than}}; \code{\link{expect_match}},
+\code{\link{is_a}}; \code{\link{expect_match}},
 \code{\link{matches}}; \code{\link{expect_message}},
-\code{\link{shows_message}};
-\code{\link{expect_more_than}}, \code{\link{is_more_than}};
-\code{\link{expect_named}}, \code{\link{has_names}};
-\code{\link{expect_null}}, \code{\link{is_null}};
-\code{\link{expect_output}}, \code{\link{prints_text}};
-\code{\link{expect_true}}, \code{\link{is_true}};
-\code{\link{takes_less_than}}
+\code{\link{shows_message}}; \code{\link{expect_named}},
+\code{\link{has_names}}; \code{\link{expect_null}},
+\code{\link{is_null}}; \code{\link{expect_output}},
+\code{\link{prints_text}}; \code{\link{expect_true}},
+\code{\link{is_true}}; \code{\link{takes_less_than}}
 }
 
diff --git a/man/has_names.Rd b/man/has_names.Rd
@@ -51,21 +51,21 @@ expect_named(z, NULL)
 }
 \seealso{
 Other expectations: \code{\link{equals}},
-\code{\link{expect_equal}};
+\code{\link{expect_equal}}; \code{\link{expect-compare}},
+\code{\link{expect_less_than}},
+\code{\link{expect_more_than}}, \code{\link{is_less_than}},
+\code{\link{is_more_than}};
 \code{\link{expect_equivalent}},
 \code{\link{is_equivalent_to}}; \code{\link{expect_error}},
 \code{\link{throws_error}}; \code{\link{expect_false}},
 \code{\link{is_false}}; \code{\link{expect_identical}},
 \code{\link{is_identical_to}}; \code{\link{expect_is}},
-\code{\link{is_a}}; \code{\link{expect_less_than}},
-\code{\link{is_less_than}}; \code{\link{expect_match}},
+\code{\link{is_a}}; \code{\link{expect_match}},
 \code{\link{matches}}; \code{\link{expect_message}},
-\code{\link{shows_message}};
-\code{\link{expect_more_than}}, \code{\link{is_more_than}};
-\code{\link{expect_null}}, \code{\link{is_null}};
-\code{\link{expect_output}}, \code{\link{prints_text}};
-\code{\link{expect_true}}, \code{\link{is_true}};
-\code{\link{expect_warning}}, \code{\link{gives_warning}};
-\code{\link{takes_less_than}}
+\code{\link{shows_message}}; \code{\link{expect_null}},
+\code{\link{is_null}}; \code{\link{expect_output}},
+\code{\link{prints_text}}; \code{\link{expect_true}},
+\code{\link{is_true}}; \code{\link{expect_warning}},
+\code{\link{gives_warning}}; \code{\link{takes_less_than}}
 }
 
diff --git a/man/is_a.Rd b/man/is_a.Rd
@@ -37,21 +37,21 @@ expect_that(is.data.frame(mtcars), is_true())
 \code{\link{inherits}}
 
 Other expectations: \code{\link{equals}},
-\code{\link{expect_equal}};
+\code{\link{expect_equal}}; \code{\link{expect-compare}},
+\code{\link{expect_less_than}},
+\code{\link{expect_more_than}}, \code{\link{is_less_than}},
+\code{\link{is_more_than}};
 \code{\link{expect_equivalent}},
 \code{\link{is_equivalent_to}}; \code{\link{expect_error}},
 \code{\link{throws_error}}; \code{\link{expect_false}},
 \code{\link{is_false}}; \code{\link{expect_identical}},
-\code{\link{is_identical_to}};
-\code{\link{expect_less_than}}, \code{\link{is_less_than}};
-\code{\link{expect_match}}, \code{\link{matches}};
-\code{\link{expect_message}}, \code{\link{shows_message}};
-\code{\link{expect_more_than}}, \code{\link{is_more_than}};
-\code{\link{expect_named}}, \code{\link{has_names}};
-\code{\link{expect_null}}, \code{\link{is_null}};
-\code{\link{expect_output}}, \code{\link{prints_text}};
-\code{\link{expect_true}}, \code{\link{is_true}};
-\code{\link{expect_warning}}, \code{\link{gives_warning}};
-\code{\link{takes_less_than}}
+\code{\link{is_identical_to}}; \code{\link{expect_match}},
+\code{\link{matches}}; \code{\link{expect_message}},
+\code{\link{shows_message}}; \code{\link{expect_named}},
+\code{\link{has_names}}; \code{\link{expect_null}},
+\code{\link{is_null}}; \code{\link{expect_output}},
+\code{\link{prints_text}}; \code{\link{expect_true}},
+\code{\link{is_true}}; \code{\link{expect_warning}},
+\code{\link{gives_warning}}; \code{\link{takes_less_than}}
 }
 
diff --git a/man/is_equivalent_to.Rd b/man/is_equivalent_to.Rd
@@ -40,20 +40,20 @@ expect_equivalent(a, b)
 }
 \seealso{
 Other expectations: \code{\link{equals}},
-\code{\link{expect_equal}}; \code{\link{expect_error}},
+\code{\link{expect_equal}}; \code{\link{expect-compare}},
+\code{\link{expect_less_than}},
+\code{\link{expect_more_than}}, \code{\link{is_less_than}},
+\code{\link{is_more_than}}; \code{\link{expect_error}},
 \code{\link{throws_error}}; \code{\link{expect_false}},
 \code{\link{is_false}}; \code{\link{expect_identical}},
 \code{\link{is_identical_to}}; \code{\link{expect_is}},
-\code{\link{is_a}}; \code{\link{expect_less_than}},
-\code{\link{is_less_than}}; \code{\link{expect_match}},
+\code{\link{is_a}}; \code{\link{expect_match}},
 \code{\link{matches}}; \code{\link{expect_message}},
-\code{\link{shows_message}};
-\code{\link{expect_more_than}}, \code{\link{is_more_than}};
-\code{\link{expect_named}}, \code{\link{has_names}};
-\code{\link{expect_null}}, \code{\link{is_null}};
-\code{\link{expect_output}}, \code{\link{prints_text}};
-\code{\link{expect_true}}, \code{\link{is_true}};
-\code{\link{expect_warning}}, \code{\link{gives_warning}};
-\code{\link{takes_less_than}}
+\code{\link{shows_message}}; \code{\link{expect_named}},
+\code{\link{has_names}}; \code{\link{expect_null}},
+\code{\link{is_null}}; \code{\link{expect_output}},
+\code{\link{prints_text}}; \code{\link{expect_true}},
+\code{\link{is_true}}; \code{\link{expect_warning}},
+\code{\link{gives_warning}}; \code{\link{takes_less_than}}
 }
 
diff --git a/man/is_false.Rd b/man/is_false.Rd
@@ -31,21 +31,21 @@ expect_that(length(a) == 4, is_false())
 }
 \seealso{
 Other expectations: \code{\link{equals}},
-\code{\link{expect_equal}};
+\code{\link{expect_equal}}; \code{\link{expect-compare}},
+\code{\link{expect_less_than}},
+\code{\link{expect_more_than}}, \code{\link{is_less_than}},
+\code{\link{is_more_than}};
 \code{\link{expect_equivalent}},
 \code{\link{is_equivalent_to}}; \code{\link{expect_error}},
 \code{\link{throws_error}}; \code{\link{expect_identical}},
 \code{\link{is_identical_to}}; \code{\link{expect_is}},
-\code{\link{is_a}}; \code{\link{expect_less_than}},
-\code{\link{is_less_than}}; \code{\link{expect_match}},
+\code{\link{is_a}}; \code{\link{expect_match}},
 \code{\link{matches}}; \code{\link{expect_message}},
-\code{\link{shows_message}};
-\code{\link{expect_more_than}}, \code{\link{is_more_than}};
-\code{\link{expect_named}}, \code{\link{has_names}};
-\code{\link{expect_null}}, \code{\link{is_null}};
-\code{\link{expect_output}}, \code{\link{prints_text}};
-\code{\link{expect_true}}, \code{\link{is_true}};
-\code{\link{expect_warning}}, \code{\link{gives_warning}};
-\code{\link{takes_less_than}}
+\code{\link{shows_message}}; \code{\link{expect_named}},
+\code{\link{has_names}}; \code{\link{expect_null}},
+\code{\link{is_null}}; \code{\link{expect_output}},
+\code{\link{prints_text}}; \code{\link{expect_true}},
+\code{\link{is_true}}; \code{\link{expect_warning}},
+\code{\link{gives_warning}}; \code{\link{takes_less_than}}
 }