Merge commit '65f6b64b9c47a3d945b512b6f37321b1d3a8351b' as 'test-utils/bats-support'

Author: hughsaunders

test-utils/bats-support/.travis.yml

@@ -0,0 +1,7 @@
+language: bash
+before_install:
+  - ./script/install-bats.sh
+before_script:
+  - export PATH="${HOME}/.local/bin:${PATH}"
+script:
+  - bats test

test-utils/bats-support/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](http://semver.org/).
+
+
+## [0.3.0] - 2016-11-30
+
+### Added
+
+- Restricting invocation to specific locations with
+  `batslib_is_caller()`
+
+
+## [0.2.0] - 2016-03-22
+
+### Added
+
+- `npm` support
+- Reporting arbitrary failures with `fail()` (moved from `bats-assert`)
+
+### Changed
+
+- Library renamed to `bats-support`
+
+
+## 0.1.0 - 2016-02-16
+
+### Added
+
+- Two-column key-value formatting with `batslib_print_kv_single()`
+- Multi-line key-value formatting with `batslib_print_kv_multi()`
+- Mixed formatting with `batslib_print_kv_single_or_multi()`
+- Header and footer decoration with `batslib_decorate()`
+- Prefixing lines with `batslib_prefix()`
+- Marking lines with `batslib_mark()`
+- Common output function `batslib_err()`
+- Line counting with `batslib_count_lines()`
+- Checking whether a text is one line long with
+  `batslib_is_single_line()`
+- Determining key width for two-column and mixed formatting with
+  `batslib_get_max_single_line_key_width()`
+
+
+[0.3.0]: https://github.com/ztombol/bats-support/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/ztombol/bats-support/compare/v0.1.0...v0.2.0

test-utils/bats-support/LICENSE

@@ -0,0 +1,116 @@
+CC0 1.0 Universal
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator and
+subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for the
+purpose of contributing to a commons of creative, cultural and scientific
+works ("Commons") that the public can reliably and without fear of later
+claims of infringement build upon, modify, incorporate in other works, reuse
+and redistribute as freely as possible in any form whatsoever and for any
+purposes, including without limitation commercial purposes. These owners may
+contribute to the Commons to promote the ideal of a free culture and the
+further production of creative, cultural and scientific works, or to gain
+reputation or greater distribution for their Work in part through the use and
+efforts of others.
+
+For these and/or other purposes and motivations, and without any expectation
+of additional consideration or compensation, the person associating CC0 with a
+Work (the "Affirmer"), to the extent that he or she is an owner of Copyright
+and Related Rights in the Work, voluntarily elects to apply CC0 to the Work
+and publicly distribute the Work under its terms, with knowledge of his or her
+Copyright and Related Rights in the Work and the meaning and intended legal
+effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not limited
+to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display, communicate,
+  and translate a Work;
+
+  ii. moral rights retained by the original author(s) and/or performer(s);
+
+  iii. publicity and privacy rights pertaining to a person's image or likeness
+  depicted in a Work;
+
+  iv. rights protecting against unfair competition in regards to a Work,
+  subject to the limitations in paragraph 4(a), below;
+
+  v. rights protecting the extraction, dissemination, use and reuse of data in
+  a Work;
+
+  vi. database rights (such as those arising under Directive 96/9/EC of the
+  European Parliament and of the Council of 11 March 1996 on the legal
+  protection of databases, and under any national implementation thereof,
+  including any amended or successor version of such directive); and
+
+  vii. other similar, equivalent or corresponding rights throughout the world
+  based on applicable law or treaty, and any national implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention of,
+applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and
+unconditionally waives, abandons, and surrenders all of Affirmer's Copyright
+and Related Rights and associated claims and causes of action, whether now
+known or unknown (including existing as well as future claims and causes of
+action), in the Work (i) in all territories worldwide, (ii) for the maximum
+duration provided by applicable law or treaty (including future time
+extensions), (iii) in any current or future medium and for any number of
+copies, and (iv) for any purpose whatsoever, including without limitation
+commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes
+the Waiver for the benefit of each member of the public at large and to the
+detriment of Affirmer's heirs and successors, fully intending that such Waiver
+shall not be subject to revocation, rescission, cancellation, termination, or
+any other legal or equitable action to disrupt the quiet enjoyment of the Work
+by the public as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason be
+judged legally invalid or ineffective under applicable law, then the Waiver
+shall be preserved to the maximum extent permitted taking into account
+Affirmer's express Statement of Purpose. In addition, to the extent the Waiver
+is so judged Affirmer hereby grants to each affected person a royalty-free,
+non transferable, non sublicensable, non exclusive, irrevocable and
+unconditional license to exercise Affirmer's Copyright and Related Rights in
+the Work (i) in all territories worldwide, (ii) for the maximum duration
+provided by applicable law or treaty (including future time extensions), (iii)
+in any current or future medium and for any number of copies, and (iv) for any
+purpose whatsoever, including without limitation commercial, advertising or
+promotional purposes (the "License"). The License shall be deemed effective as
+of the date CC0 was applied by Affirmer to the Work. Should any part of the
+License for any reason be judged legally invalid or ineffective under
+applicable law, such partial invalidity or ineffectiveness shall not
+invalidate the remainder of the License, and in such case Affirmer hereby
+affirms that he or she will not (i) exercise any of his or her remaining
+Copyright and Related Rights in the Work or (ii) assert any associated claims
+and causes of action with respect to the Work, in either case contrary to
+Affirmer's express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+  a. No trademark or patent rights held by Affirmer are waived, abandoned,
+  surrendered, licensed or otherwise affected by this document.
+
+  b. Affirmer offers the Work as-is and makes no representations or warranties
+  of any kind concerning the Work, express, implied, statutory or otherwise,
+  including without limitation warranties of title, merchantability, fitness
+  for a particular purpose, non infringement, or the absence of latent or
+  other defects, accuracy, or the present or absence of errors, whether or not
+  discoverable, all to the greatest extent permissible under applicable law.
+
+  c. Affirmer disclaims responsibility for clearing rights of other persons
+  that may apply to the Work or any use thereof, including without limitation
+  any person's Copyright and Related Rights in the Work. Further, Affirmer
+  disclaims responsibility for obtaining any necessary consents, permissions
+  or other rights required for any use of the Work.
+
+  d. Affirmer understands and acknowledges that Creative Commons is not a
+  party to this document and has no duty or obligation with respect to this
+  CC0 or use of the Work.
+
+For more information, please see
+<http://creativecommons.org/publicdomain/zero/1.0/>

test-utils/bats-support/README.md

@@ -0,0 +1,189 @@
+*__Important:__ `bats-core` has been renamed to `bats-support`. GitHub
+automatically redirects all references, e.g. submodules and clones will
+continue to work, but you are encouraged to [update][github-rename]
+them. Version numbering continues where `bats-core` left off.*
+
+[github-rename]: https://help.github.com/articles/renaming-a-repository/
+
+- - - - -
+
+# bats-support
+
+[![GitHub license](https://img.shields.io/badge/license-CC0-blue.svg)](https://raw.githubusercontent.com/ztombol/bats-support/master/LICENSE)
+[![GitHub release](https://img.shields.io/github/release/ztombol/bats-support.svg)](https://github.com/ztombol/bats-support/releases/latest)
+[![Build Status](https://travis-ci.org/ztombol/bats-support.svg?branch=master)](https://travis-ci.org/ztombol/bats-support)
+
+`bats-support` is a supporting library providing common functions to
+test helper libraries written for [Bats][bats].
+
+Features:
+- [error reporting](#error-reporting)
+- [output formatting](#output-formatting)
+- [language tools](#language-and-execution)
+
+See the [shared documentation][bats-docs] to learn how to install and
+load this library.
+
+If you want to use this library in your own helpers or just want to
+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
+provides a simple way to format simple messages and key value pairs, and
+display them on the standard error.
+
+
+### Simple message
+
+Simple messages without structure, e.g. one-line error messages, are
+simply wrapped in a header and a footer to help them stand out.
+
+```
+-- ERROR: assert_output --
+`--partial' and `--regexp' are mutually exclusive
+--
+```
+
+
+### Key-Value pairs
+
+Some helpers, e.g. [assertions][bats-assert], structure output as
+key-value pairs. This library provides two ways to format them.
+
+When the value is one line long, a pair can be displayed in a columnar
+fashion called ***two-column*** format.
+
+```
+-- output differs --
+expected : want
+actual   : have
+--
+```
+
+When the value is longer than one line, the key and value must be
+displayed on separate lines. First, the key is displayed along with the
+number of lines in the value. Then, the value, indented by two spaces
+for added readability, starting on the next line. This is called
+***multi-line*** format.
+
+```
+-- command failed --
+status : 1
+output (2 lines):
+  Error! Something went terribly wrong!
+  Our engineers are panicing... \`>`;/
+--
+```
+
+Sometimes, for clarity, it is a good idea to display related values also
+in this format, even if they are just one line long.
+
+```
+-- output differs --
+expected (1 lines):
+  want
+actual (3 lines):
+  have 1
+  have 2
+  have 3
+--
+```
+
+## Language and Execution
+
+### Restricting invocation to specific locations
+
+Sometimes a helper may work properly only when called from a certain
+location. Because it depends on variables to be set or some other side
+effect.
+
+A good example is cleaning up temporary files only if the test has
+succeeded. The outcome of a test is only available in `teardown`. Thus,
+to avoid programming mistakes, it makes sense to restrict such a
+clean-up helper to that function.
+
+`batslib_is_caller` checks the call stack and returns `0` if the caller
+was invoked from a given function, and `1` otherwise. This function
+becomes really useful with the `--indirect` option, which allows calls
+through intermediate functions, e.g. the calling function may be called
+from a function that was called from the given function.
+
+Staying with the example above, the following code snippet implements a
+helper that is restricted to `teardown` or any function called
+indirectly from it.
+
+```shell
+clean_up() {
+  # Check caller.
+  if batslib_is_caller --indirect 'teardown'; then
+    echo "Must be called from \`teardown'" \
+      | batslib_decorate 'ERROR: clean_up' \
+      | fail
+    return $?
+  fi
+
+  # Body goes here...
+}
+```
+
+In some cases a helper may be called from multiple locations. For
+example, a logging function that uses the test name, description or
+number, information only available in `setup`, `@test` or `teardown`, to
+distinguish entries. The following snippet implements this restriction.
+
+```shell
+log_test() {
+  # Check caller.
+  if ! ( batslib_is_caller --indirect 'setup' \
+      || batslib_is_caller --indirect "$BATS_TEST_NAME" \
+      || batslib_is_caller --indirect 'teardown' )
+  then
+    echo "Must be called from \`setup', \`@test' or \`teardown'" \
+      | batslib_decorate 'ERROR: log_test' \
+      | fail
+    return $?
+  fi
+
+  # Body goes here...
+}
+```
+
+
+<!-- REFERENCES -->
+
+[bats]: https://github.com/sstephenson/bats
+[bats-docs]: https://github.com/ztombol/bats-docs
+[bats-assert]: https://github.com/ztombol/bats-assert

test-utils/bats-support/load.bash

@@ -0,0 +1,3 @@
+source "$(dirname "${BASH_SOURCE[0]}")/src/output.bash"
+source "$(dirname "${BASH_SOURCE[0]}")/src/error.bash"
+source "$(dirname "${BASH_SOURCE[0]}")/src/lang.bash"

test-utils/bats-support/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "bats-support",
+  "version": "0.3.0",
+  "private": true
+}

test-utils/bats-support/script/install-bats.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+set -o errexit
+set -o xtrace
+
+git clone --depth 1 https://github.com/sstephenson/bats
+cd bats && ./install.sh "${HOME}/.local" && cd .. && rm -rf bats