Add fail() from bats-assert

5 files changed, 90 insertions, 0 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8f89bb1..c57df7c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ### Added
 
 - `npm` support
+- Reporting arbitrary failures with `fail()` (moved from `bats-assert`)
 
 ### Changed
 
diff --git a/README.md b/README.md
index bb8fcc1..cd3fee1 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,7 @@ them. Version numbering continues where `bats-core` left off.*
 test helper libraries written for [Bats][bats].
 
 Features:
+- [error reporting](#error-reporting)
 - [output formatting](#output-formatting)
 
 See the [shared documentation][bats-docs] to learn how to install and
@@ -27,6 +28,36 @@ learn about its internals see the developer documentation in the [source
 files](src).
 
 
+## Error reporting
+
+### `fail`
+
+Display an error message and fail. This function provides a convenient
+way to report failure in arbitrary situations. You can use it to
+implement your own helpers when the ones available do not meet your
+needs. Other functions use it internally as well.
+
+```bash
+@test 'fail()' {
+  fail 'this test always fails'
+}
+```
+
+The message can also be specified on the standard input.
+
+```bash
+@test 'fail() with pipe' {
+  echo 'this test always fails' | fail
+}
+```
+
+This function always fails and simply outputs the given message.
+
+```
+this test always fails
+```
+
+
 ## Output formatting
 
 Many test helpers need to produce human readable output. This library
diff --git a/load.bash b/load.bash
index 325c5b1..0d4a5ac 100644
--- a/load.bash
+++ b/load.bash
@@ -1 +1,2 @@
 source "$(dirname "${BASH_SOURCE[0]}")/src/output.bash"
+source "$(dirname "${BASH_SOURCE[0]}")/src/error.bash"
diff --git a/src/error.bash b/src/error.bash
new file mode 100644
index 0000000..e5d9791
--- /dev/null
+++ b/src/error.bash
@@ -0,0 +1,41 @@
+#
+# bats-support - Supporting library for Bats test helpers
+#
+# Written in 2016 by Zoltan Tombol <zoltan dot tombol at gmail dot com>
+#
+# To the extent possible under law, the author(s) have dedicated all
+# copyright and related and neighboring rights to this software to the
+# public domain worldwide. This software is distributed without any
+# warranty.
+#
+# You should have received a copy of the CC0 Public Domain Dedication
+# along with this software. If not, see
+# <http://creativecommons.org/publicdomain/zero/1.0/>.
+#
+
+#
+# error.bash
+# ----------
+#
+# Functions implementing error reporting. Used by public helper
+# functions or test suits directly.
+#
+
+# Fail and display a message. When no parameters are specified, the
+# message is read from the standard input. Other functions use this to
+# report failure.
+#
+# Globals:
+#   none
+# Arguments:
+#   $@ - [=STDIN] message
+# Returns:
+#   1 - always
+# Inputs:
+#   STDIN - [=$@] message
+# Outputs:
+#   STDERR - message
+fail() {
+  (( $# == 0 )) && batslib_err || batslib_err "$@"
+  return 1
+}
diff --git a/test/51-error-10-fail.bats b/test/51-error-10-fail.bats
new file mode 100755
index 0000000..1d8691a
--- /dev/null
+++ b/test/51-error-10-fail.bats
@@ -0,0 +1,16 @@
+#!/usr/bin/env bats
+
+load test_helper
+
+@test 'fail() <message>: returns 1 and displays <message>' {
+  run fail 'message'
+  [ "$status" -eq 1 ]
+  [ "$output" == 'message' ]
+}
+
+@test 'fail(): reads <message> from STDIN' {
+  run bash -c "source '${TEST_MAIN_DIR}/load.bash'
+               echo 'message' | fail"
+  [ "$status" -eq 1 ]
+  [ "$output" == 'message' ]
+}