ClojureDocs

Namespaces

clojure.test

Provides basic facilities for unit testing Clojure code.

Vars in clojure.test

*^%

*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.

a

are
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
Returns generic assertion code for any test, including macros, Java method calls, or isolated symbols.
assert-predicate
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...).

c

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

d

deftest
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-
Like deftest but creates a private var.
do-report
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.

f

file-position
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.
function?
Returns true if argument is a function or a symbol that resolves to a function (not a macro).

g

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

i

inc-report-counter
Increments the named counter in *report-counters*, a ref to a map. Does nothing if *report-counters* is nil.
is
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.

j

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

r

report
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
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
Runs all tests in the given namespaces; prints results. Defaults to current namespace if none given. Returns a map summarizing test results.

s

set-test
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?
Returns true if the given test summary indicates all tests were successful, false otherwise.

t

test-all-vars
Calls test-vars on every var interned in the namespace, with fixtures.
test-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 *initial-report-counters*. Returns the final, dereferenced state of *report-counters*.
test-var
If v has a function in its :test metadata, calls that function, with *testing-vars* bound to (conj *testing-vars* v).
test-vars
Groups vars by their namespace and runs test-vars on them with appropriate fixtures applied.
testing
Adds a new string to the list of testing contexts. May be nested, but must occur inside a test function (deftest).
testing-contexts-str
Returns a string representation of the current test context. Joins strings in *testing-contexts* with spaces.
testing-vars-str
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
Used by the 'is' macro to catch unexpected exceptions. You don't call this.

u

use-fixtures
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.

w

with-test
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
Runs body with *out* bound to the value of *test-out*.