Table of Contents

*load-tests*

True by default.  If set to false, no test functions will
be created by deftest, set-test, or with-test.  Use this to omit
tests when compiling or loading production code.

*stack-trace-depth*

The maximum depth of stack traces to print when an Exception
is thrown during a test.  Defaults to nil, which means print the
complete stack trace.

apply-template

Usage: (apply-template expr values)

Replaces _1, _2, _3, etc. in expr with corresponding elements of
values.  Returns the modified expression.  For use in macros.

are

Usage: (are expr & args)

Checks multiple assertions with a template expression.
See clojure.contrib.template/do-template for an explanation of
templates.

Example: (are (= _1 _2)
              2 (+ 1 1)
              4 (* 2 2))
Expands to:
         (do (is (= 2 (+ 1 1)))
             (is (= 4 (* 2 2))))

Note: This breaks some reporting features, such as line numbers.

assert-any

Usage: (assert-any msg form)

Returns generic assertion code for any test, including macros, Java
method calls, or isolated symbols.

assert-predicate

Usage: (assert-predicate msg form)

Returns generic assertion code for any functional predicate.  The
'expected' argument to 'report' will contains the original form, the
'actual' argument will contain the form with all its sub-forms
evaluated.  If the predicate returns false, the 'actual' form will
be wrapped in (not...).

compose-fixtures

Usage: (compose-fixtures f1 f2)

Composes two fixture functions, creating a new fixture function
that combines their behavior.

deftest

Usage: (deftest name & body)

Defines a test function with no arguments.  Test functions may call
other tests, so tests may be composed.  If you compose tests, you
should also define a function named test-ns-hook; run-tests will
call test-ns-hook instead of testing all vars.

Note: Actually, the test body goes in the :test metadata on the var,
and the real function (the value of the var) calls test-var on
itself.

When *load-tests* is false, deftest is ignored.

deftest-

Usage: (deftest- name & body)

Like deftest but creates a private var.

do-report

Usage: (do-report m)

Add file and line information to a test result and call report.
If you are writing a custom assert-expr method, call this function
to pass test results to report.

do-template

Usage: (do-template expr & args)

Repeatedly evaluates template expr (in a do block) using values in
args.  args are grouped by the number of holes in the template.
Example: (do-template (check _1 _2) :a :b :c :d)
expands to (do (check :a :b) (check :c :d))

file-position

Usage: (file-position n)

Returns a vector [filename line-number] for the nth call up the
stack.

Deprecated in 1.2: The information needed for test reporting is
now on :file and :line keys in the result map.

find-holes

Usage: (find-holes form)

Recursively finds all symbols starting with _ in form.

find-pure-exprs

Usage: (find-pure-exprs form)

Recursively finds all sub-expressions in form that do not contain
any symbols starting with _

find-symbols

Usage: (find-symbols form)

Recursively finds all symbols in form.

flatten-map

Usage: (flatten-map m)

Transforms a map into a vector like [key value key value].

function?

Usage: (function? x)

Returns true if argument is a function or a symbol that resolves to
a function (not a macro).

get-possibly-unbound-var

Usage: (get-possibly-unbound-var v)

Like var-get but returns nil if the var is unbound.

inc-report-counter

Usage: (inc-report-counter name)

Increments the named counter in *report-counters*, a ref to a map.
Does nothing if *report-counters* is nil.

is

Usage: (is form)
       (is form msg)

Generic assertion macro.  'form' is any predicate test.
'msg' is an optional message to attach to the assertion.

Example: (is (= 4 (+ 2 2)) "Two plus two should be 4")

Special forms:

(is (thrown? c body)) checks that an instance of c is thrown from
body, fails if not; then returns the thing thrown.

(is (thrown-with-msg? c re body)) checks that an instance of c is
thrown AND that the message on the exception matches (with
re-find) the regular expression re.

join-fixtures

Usage: (join-fixtures fixtures)

Composes a collection of fixtures, in order.  Always returns a valid
fixture function, even if the collection is empty.

report

No usage documentation available

Generic reporting function, may be overridden to plug in
different report formats (e.g., TAP, JUnit).  Assertions such as
'is' call 'report' to indicate results.  The argument given to
'report' will be a map with a :type key.  See the documentation at
the top of test_is.clj for more information on the types of
arguments for 'report'.

run-all-tests

Usage: (run-all-tests)
       (run-all-tests re)

Runs all tests in all namespaces; prints results.
Optional argument is a regular expression; only namespaces with
names matching the regular expression (with re-matches) will be
tested.

run-tests

Usage: (run-tests)
       (run-tests & namespaces)

Runs all tests in the given namespaces; prints results.
Defaults to current namespace if none given.  Returns a map
summarizing test results.

set-test

Usage: (set-test name & body)

Experimental.
Sets :test metadata of the named var to a fn with the given body.
The var must already exist.  Does not modify the value of the var.

When *load-tests* is false, set-test is ignored.

successful?

Usage: (successful? summary)

Returns true if the given test summary indicates all tests
were successful, false otherwise.

template?

Usage: (template? form)

Returns true if form is a valid template expression.

test-all-vars

Usage: (test-all-vars ns)

Calls test-var on every var interned in the namespace, with fixtures.

test-ns

Usage: (test-ns ns)

If the namespace defines a function named test-ns-hook, calls that.
Otherwise, calls test-all-vars on the namespace.  'ns' is a
namespace object or a symbol.

Internally binds *report-counters* to a ref initialized to
*inital-report-counters*.  Returns the final, dereferenced state of
*report-counters*.

test-var

Usage: (test-var v)

If v has a function in its :test metadata, calls that function,
with *testing-vars* bound to (conj *testing-vars* v).

testing

Usage: (testing string & body)

Adds a new string to the list of testing contexts.  May be nested,
but must occur inside a test function (deftest).

testing-contexts-str

Usage: (testing-contexts-str)

Returns a string representation of the current test context. Joins
strings in *testing-contexts* with spaces.

testing-vars-str

Usage: (testing-vars-str m)

Returns a string representation of the current test.  Renders names
in *testing-vars* as a list, then the source file and line of
current assertion.

try-expr

Usage: (try-expr msg form)

Used by the 'is' macro to catch unexpected exceptions.
You don't call this.

use-fixtures

No usage documentation available

Wrap test runs in a fixture function to perform setup and
teardown. Using a fixture-type of :each wraps every test
individually, while:once wraps the whole run in a single function.

with-test

Usage: (with-test definition & body)

Takes any definition form (that returns a Var) as the first argument.
Remaining body goes in the :test metadata function for that Var.

When *load-tests* is false, only evaluates the definition, ignoring
the tests.

with-test-out

Usage: (with-test-out & body)

Runs body with *out* bound to the value of *test-out*.