cljs.test

since v0.0-2496

*current-env* - dynamic var

are - macro
(are argv expr & args)
Checks multiple assertions with a template expression.
See clojure.template/do-template for an explanation of
templates.

Example: (are [x y] (= x y)  
              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 - function
(assert-any msg form)
Returns generic assertion code for any test, including macros, Java
method calls, or isolated symbols.

assert-expr - multimethod
(assert-expr menv msg form)

assert-predicate - function
(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...).

async - macro
(async done & body)
Wraps body as a CPS function that can be returned from a test to
continue asynchronously.  Binds done to a function that must be
invoked once and from an async context after any assertions.

(deftest example-with-timeout
  (async done
    (js/setTimeout (fn []
                     ;; make assertions in async context...
                     (done) ;; ...then call done
                     )
                   0)))

async? - function
(async? x)
Returns whether x implements IAsyncTest.

block - function
(block fns)
Tag a seq of fns to be picked up by run-block as injected
continuation.  See run-block.

clear-env! - function
(clear-env!)

compose-fixtures - function
(compose-fixtures f1 f2)
Composes two fixture functions, creating a new fixture function
that combines their behavior.

NOTE: Incompatible with map fixtures.

deftest - macro
(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 cljs.analyzer/*load-tests* is false, deftest is ignored.

do-report - function
(do-report m)

empty-env - function
(empty-env)
(empty-env reporter)
Generates a testing environment with a reporter.
(empty-env) - uses the :cljs.test/default reporter.
(empty-env :cljs.test/pprint) - pretty prints all data structures. 
(empty-env reporter) - uses a reporter of your choosing.

To create your own reporter see cljs.test/report

file-and-line - function
(file-and-line exception depth)

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

get-and-clear-env! - function
(get-and-clear-env!)

get-current-env - function
(get-current-env)

inc-report-counter! - function
(inc-report-counter! name)
Increments the named counter in *report-counters*, a ref to a map.
Does nothing if *report-counters* is nil.

is - macro
(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 - function
(join-fixtures fixtures)
Composes a collection of fixtures, in order.  Always returns a valid
fixture function, even if the collection is empty.

NOTE: Incompatible with map fixtures.

js-filename - function
(js-filename stack-element)

js-line-and-column - function
(js-line-and-column stack-element)

mapped-line-and-column - function
(mapped-line-and-column filename line column)

ns? - function
(ns? x)

report - multimethod
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.

run-all-tests - macro
(run-all-tests)
(run-all-tests re)
(run-all-tests re env)
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-block - function
(run-block fns)
Invoke all functions in fns with no arguments. A fn can optionally
return

an async test - is invoked with a continuation running left fns

a seq of fns tagged per block - are invoked immediately after fn

run-test - macro
(run-test test-symbol)
Runs a single test.

Because the intent is to run a single test, there is no check for the namespace test-ns-hook.

run-tests - macro
(run-tests)
(run-tests env-or-ns)
(run-tests env-or-ns & namespaces)
Runs all tests in the given namespaces; prints results.
Defaults to current namespace if none given. Does not return a meaningful
value due to the possiblity of asynchronous execution. To detect test
completion add a :end-run-tests method case to the cljs.test/report
multimethod.

run-tests-block - macro
(run-tests-block env-or-ns & namespaces)
Like test-vars, but returns a block for further composition and
later execution.

set-env! - function
(set-env! new-env)

successful? - function
(successful? summary)
Returns true if the given test summary indicates all tests
were successful, false otherwise.

test-all-vars - macro
(test-all-vars [quote ns :as form])
Calls test-vars on every var with :test metadata interned in the
namespace, with fixtures.

test-all-vars-block - macro
(test-all-vars-block [quote ns])

test-ns - macro
(test-ns ns)
(test-ns env [quote ns :as form])
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
*initial-report-counters*.  

test-ns-block - macro
(test-ns-block env [quote ns :as form])
Like test-ns, but returns a block for further composition and
later execution.  Does not clear the current env.

test-var - function
(test-var v)
If v has a function in its :test metadata, calls that function,
add v to :testing-vars property of env.

test-var-block - function
(test-var-block v)
Like test-var, but returns a block for further composition and
later execution.

test-vars - function
(test-vars vars)
Groups vars by their namespace and runs test-var on them with
appropriate fixtures assuming they are present in the current
testing environment.

test-vars-block - function
(test-vars-block vars)
Like test-vars, but returns a block for further composition and
later execution.

testing - macro
(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 - function
(testing-contexts-str)
Returns a string representation of the current test context. Joins
strings in *testing-contexts* with spaces.

testing-vars-str - function
(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 - macro
(try-expr msg form)
Used by the 'is' macro to catch unexpected exceptions.
You don't call this.

update-current-env! - function
(update-current-env! ks f & args)

use-fixtures - macro
(use-fixtures type & fns)

Types and Protocols

IAsyncTest - protocol
Marker protocol denoting CPS function to begin asynchronous
  testing.