Skip to content


Subversion checkout URL

You can clone with
Download ZIP
executable file 308 lines (268 sloc) 9.7 KB
# [r5]: roundup.5.html
# [r1t]:
# [r5t]:
# _(c) 2010 Blake Mizerany - MIT License_
# Spray **roundup** on your shells to eliminate weeds and bugs. If your shells
# survive **roundup**'s deathly toxic properties, they are considered
# roundup-ready.
# **roundup** reads shell scripts to form test plans. Each
# test plan is sourced into a sandbox where each test is executed.
# See [][r1t] or [][r5t] for example
# test plans.
# __Install__
# git clone
# cd roundup
# make
# sudo make install
# # Alternatively, copy `roundup` wherever you like.
# __NOTE__: Because test plans are sourced into roundup, roundup prefixes its
# variable and function names with `roundup_` to avoid name collisions. See
# "Sandbox Test Runs" below for more insight.
# Usage and Prerequisites
# -----------------------
# Exit if any following command exits with a non-zero status.
set -e
# The current version is set during `make version`. Do not modify this line in
# anyway unless you know what you're doing.
# Usage is defined in a specific comment syntax. It is `grep`ed out of this file
# when needed (i.e. The Tomayko Method). See
# [shocco]( for more detail.
#/ usage: roundup [--help|-h] [--version|-v] [plan ...]
roundup_usage() {
grep '^#/' <"$0" | cut -c4-
while test "$#" -gt 0
case "$1" in
exit 0
echo "roundup version $ROUNDUP_VERSION"
exit 0
echo >&2 "roundup: unknown switch $1"
exit 1
# Consider all scripts with names matching `*` the plans to run unless
# otherwise specified as arguments.
if [ "$#" -gt "0" ]
roundup_plans="$(ls *"
: ${color:="auto"}
# Create a temporary storage place for test output to be retrieved for display
# after failing tests.
mkdir -p "$roundup_tmp"
trap "rm -rf \"$roundup_tmp\"" EXIT INT
# __Tracing failures__
roundup_trace() {
# Delete the first two lines that represent roundups execution of the
# test function. They are useless to the user.
sed '1d' |
# Delete the last line which is the "set +x" of the error trap
sed '$d' |
# Replace the rc=$? of the error trap with an verbose string appended
# to the failing command trace line.
sed '$s/.*rc=/exit code /' |
# Trim the two left most `+` signs. They represent the depth at which
# roundup executed the function. They also, are useless and confusing.
sed 's/^++//' |
# Indent the output by 4 spaces to align under the test name in the
# summary.
sed 's/^/ /' |
# Highlight the last line in front of the exit code to bring notice to
# where the error occurred.
# The sed magic puts every line into the hold buffer first, then
# substitutes in the previous hold buffer content, prints that and starts
# with the next cycle. At the end the last line (in the hold buffer)
# is printed without substitution.
sed -n "x;1!{ \$s/\(.*\)/$mag\1$clr/; };1!p;\$x;\$p"
# __Other helpers__
# Track the test stats while outputting a real-time report. This takes input on
# **stdin**. Each input line must come in the format of:
# # The plan description to be displayed
# d <plan description>
# # A passing test
# p <test name>
# # A failed test
# f <test name>
roundup_summarize() {
set -e
# __Colors for output__
# Use colors if we are writing to a tty device.
if (test -t 1) || (test $color = always)
red=$(printf "\033[31m")
grn=$(printf "\033[32m")
mag=$(printf "\033[35m")
clr=$(printf "\033[m")
cols=$(tput cols)
# Make these available to `roundup_trace`.
export red grn mag clr
: ${cols:=10}
while read status name
case $status in
ntests=$(expr $ntests + 1)
passed=$(expr $passed + 1)
printf " %-48s " "$name:"
printf "$grn[PASS]$clr\n"
ntests=$(expr $ntests + 1)
failed=$(expr $failed + 1)
printf " %-48s " "$name:"
printf "$red[FAIL]$clr\n"
roundup_trace < "$roundup_tmp/$name"
printf "%s\n" "$name"
# __Test Summary__
# Display the summary now that all tests are finished.
yes = | head -n 57 | tr -d '\n'
printf "\n"
printf "Tests: %3d | " $ntests
printf "Passed: %3d | " $passed
printf "Failed: %3d" $failed
printf "\n"
# Exit with an error if any tests failed
test $failed -eq 0 || exit 2
# Sandbox Test Runs
# -----------------
# The above checks guarantee we have at least one test. We can now move through
# each specified test plan, determine its test plan, and administer each test
# listed in a isolated sandbox.
for roundup_p in $roundup_plans
# Create a sandbox, source the test plan, run the tests, then leave
# without a trace.
# Consider the description to be the `basename` of the plan minus the
# tailing
roundup_desc=$(basename "$roundup_p"
# Define functions for
# [roundup(5)][r5]
# A custom description is recommended, but optional. Use `describe` to
# set the description to something more meaningful.
# TODO: reimplement this.
describe() {
# Provide default `before` and `after` functions that run only `:`, a
# no-op. They may or may not be redefined by the test plan.
before() { :; }
after() { :; }
# Seek test methods and aggregate their names, forming a test plan.
# This is done before populating the sandbox with tests to avoid odd
# conflicts.
# TODO: I want to do this with sed only. Please send a patch if you
# know a cleaner way.
grep "^it_.*()" $roundup_p |
sed "s/\(it_[a-zA-Z0-9_]*\).*$/\1/g"
# We have the test plan and are in our sandbox with [roundup(5)][r5]
# defined. Now we source the plan to bring its tests into scope.
. ./$roundup_p
# Output the description signal
printf "d %s" "$roundup_desc" | tr "\n" " "
printf "\n"
for roundup_test_name in $roundup_plan
# Any number of things are possible in `before`, `after`, and the
# test. Drop into an subshell to contain operations that may throw
# off roundup; such as `cd`.
# Output `before` trace to temporary file. If `before` runs cleanly,
# the trace will be overwritten by the actual test case below.
# redirect tracing output of `before` into file.
set -x
# If `before` wasn't redefined, then this is `:`.
} &>"$roundup_tmp/$roundup_test_name"
# disable tracing again. Its trace output goes to /dev/null.
set +x
} &>/dev/null
# exit subshell with return code of last failing command. This
# is needed to see the return code 253 on failed assumptions.
# But, only do this if the error handling is activated.
set -E
trap 'rc=$?; set +x; set -o | grep "errexit.*on" >/dev/null && exit $rc' ERR
# If `before` wasn't redefined, then this is `:`.
# Momentarily turn off auto-fail to give us access to the tests
# exit status in `$?` for capturing.
set +e
# Set `-xe` before the test in the subshell. We want the
# test to fail fast to allow for more accurate output of
# where things went wrong but not in _our_ process because a
# failed test should not immediately fail roundup. Each
# tests trace output is saved in temporary storage.
set -xe
) >"$roundup_tmp/$roundup_test_name" 2>&1
# We need to capture the exit status before returning the `set
# -e` mode. Returning with `set -e` before we capture the exit
# status will result in `$?` being set with `set`'s status
# instead.
# It's safe to return to normal operation.
set -e
# If `after` wasn't redefined, then this runs `:`.
# This is the final step of a test. Print its pass/fail signal
# and name.
if [ "$roundup_result" -ne 0 ]
then printf "f"
else printf "p"
printf " $roundup_test_name\n"
done |
# All signals are piped to this for summary.
Jump to Line
Something went wrong with that request. Please try again.