API forclojure.test -Clojurev1.13.0 (in development)

Overview

A unit testing framework.ASSERTIONSThe core of the library is the "is" macro, which lets you makeassertions of any arbitrary expression:(is (= 4 (+ 2 2)))(is (instance? Integer 256))(is (.startsWith "abcde" "ab"))You can type an "is" expression directly at the REPL, which willprint a message if it fails.    user> (is (= 5 (+ 2 2)))    FAIL in  (:1)    expected: (= 5 (+ 2 2))      actual: (not (= 5 4))    falseThe "expected:" line shows you the original expression, and the"actual:" shows you what actually happened.  In this case, itshows that (+ 2 2) returned 4, which is not = to 5.  Finally, the"false" on the last line is the value returned from theexpression.  The "is" macro always returns the result of theinner expression.There are two special assertions for testing exceptions.  The"(is (thrown? c ...))" form tests if an exception of class c isthrown:(is (thrown? ArithmeticException (/ 1 0))) "(is (thrown-with-msg? c re ...))" does the same thing and alsotests that the message on the exception matches the regularexpression re:(is (thrown-with-msg? ArithmeticException #"Divide by zero"                      (/ 1 0)))DOCUMENTING TESTS"is" takes an optional second argument, a string describing theassertion.  This message will be included in the error report.(is (= 5 (+ 2 2)) "Crazy arithmetic")In addition, you can document groups of assertions with the"testing" macro, which takes a string followed by any number ofassertions.  The string will be included in failure reports.Calls to "testing" may be nested, and all of the strings will bejoined together with spaces in the final report, in a stylesimilar to RSpec <http://rspec.info/>(testing "Arithmetic"  (testing "with positive integers"    (is (= 4 (+ 2 2)))    (is (= 7 (+ 3 4))))  (testing "with negative integers"    (is (= -4 (+ -2 -2)))    (is (= -1 (+ 3 -4)))))Note that, unlike RSpec, the "testing" macro may only be usedINSIDE a "deftest" or "with-test" form (see below).DEFINING TESTSThere are two ways to define tests.  The "with-test" macro takesa defn or def form as its first argument, followed by any numberof assertions.  The tests will be stored as metadata on thedefinition.(with-test    (defn my-function [x y]      (+ x y))  (is (= 4 (my-function 2 2)))  (is (= 7 (my-function 3 4))))As of Clojure SVN rev. 1221, this does not work with defmacro.Seehttp://code.google.com/p/clojure/issues/detail?id=51The other way lets you define tests separately from the rest ofyour code, even in a different namespace:(deftest addition  (is (= 4 (+ 2 2)))  (is (= 7 (+ 3 4))))(deftest subtraction  (is (= 1 (- 4 3)))  (is (= 3 (- 7 4))))This creates functions named "addition" and "subtraction", whichcan be called like any other function.  Therefore, tests can begrouped and composed, in a style similar to the test framework inPeter Seibel's "Practical Common Lisp"<http://www.gigamonkeys.com/book/practical-building-a-unit-test-framework.html>(deftest arithmetic  (addition)  (subtraction))The names of the nested tests will be joined in a list, like"(arithmetic addition)", in failure reports.  You can use nestedtests to set up a context shared by several tests.RUNNING TESTSRun tests with the function "(run-tests namespaces...)":(run-tests 'your.namespace 'some.other.namespace)If you don't specify any namespaces, the current namespace isused.  To run all tests in all namespaces, use "(run-all-tests)".By default, these functions will search for all tests defined ina namespace and run them in an undefined order.  However, if youare composing tests, as in the "arithmetic" example above, youprobably do not want the "addition" and "subtraction" tests runseparately.  In that case, you must define a special functionnamed "test-ns-hook" that runs your tests in the correct order:(defn test-ns-hook []  (arithmetic))Note: test-ns-hook prevents execution of fixtures (see below).OMITTING TESTS FROM PRODUCTION CODEYou can bind the variable "*load-tests*" to false when loading orcompiling code in production.  This will prevent any tests frombeing created by "with-test" or "deftest".FIXTURESFixtures allow you to run code before and after tests, to set upthe context in which tests should be run.A fixture is just a function that calls another function passed asan argument.  It looks like this:(defn my-fixture [f]   Perform setup, establish bindings, whatever.  (f)  Then call the function we were passed.   Tear-down / clean-up code here. )Fixtures are attached to namespaces in one of two ways.  "each"fixtures are run repeatedly, once for each test function createdwith "deftest" or "with-test".  "each" fixtures are useful forestablishing a consistent before/after state for each test, likeclearing out database tables."each" fixtures can be attached to the current namespace like this:(use-fixtures :each fixture1 fixture2 ...)The fixture1, fixture2 are just functions like the example above.They can also be anonymous functions, like this:(use-fixtures :each (fn [f] setup... (f) cleanup...))The other kind of fixture, a "once" fixture, is only run once,around ALL the tests in the namespace.  "once" fixtures are usefulfor tasks that only need to be performed once, like establishingdatabase connections, or for time-consuming tasks.Attach "once" fixtures to the current namespace like this:(use-fixtures :once fixture1 fixture2 ...)Note: Fixtures and test-ns-hook are mutually incompatible.  If youare using test-ns-hook, fixture functions will *never* be run.SAVING TEST OUTPUT TO A FILEAll the test reporting functions write to the var *test-out*.  Bydefault, this is the same as *out*, but you can rebind it to anyPrintWriter.  For example, it could be a file opened withclojure.java.io/writer.EXTENDING TEST-IS (ADVANCED)You can extend the behavior of the "is" macro by defining newmethods for the "assert-expr" multimethod.  These methods arecalled during expansion of the "is" macro, so they should returnquoted forms to be evaluated.You can plug in your own test-reporting framework by rebindingthe "report" function: (report event)The 'event' argument is a map.  It will always have a :type key,whose value will be a keyword signaling the type of event beingreported.  Standard events with :type value of :pass, :fail, and:error are called when an assertion passes, fails, and throws anexception, respectively.  In that case, the event will also havethe following keys:  :expected   The form that was expected to be true  :actual     A form representing what actually occurred  :message    The string message given as an argument to 'is'The "testing" strings will be a list in "*testing-contexts*", andthe vars being tested will be a list in "*testing-vars*".Your "report" function should wrap any printing calls in the"with-test-out" macro, which rebinds *out* to the current valueof *test-out*.For additional event types, see the examples in the code.

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

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

Usage: (are argv expr & args)

Checks multiple assertions with a template expression.See clojure.template/do-template for an explanation oftemplates.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.

Usage: (assert-any msg form)

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

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-formsevaluated.  If the predicate returns false, the 'actual' form willbe wrapped in (not...).

Usage: (compose-fixtures f1 f2)

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

Usage: (deftest name & body)

Defines a test function with no arguments.  Test functions may callother tests, so tests may be composed.  If you compose tests, youshould also define a function named test-ns-hook; run-tests willcall 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 onitself.When *load-tests* is false, deftest is ignored.

Usage: (deftest- name & body)

Like deftest but creates a private var.

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 functionto pass test results to report.

Usage: (file-position n)

Returns a vector [filename line-number] for the nth call up thestack.Deprecated in 1.2: The information needed for test reporting isnow on :file and :line keys in the result map.

Usage: (function? x)

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

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

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

Usage: (inc-report-counter name)

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

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 frombody, fails if not; then returns the thing thrown.(is (thrown-with-msg? c re body)) checks that an instance of c isthrown AND that the message on the exception matches (withre-find) the regular expression re.

Usage: (join-fixtures fixtures)

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

No usage documentation available

Generic reporting function, may be overridden to plug indifferent 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 atthe top of test_is.clj for more information on the types ofarguments for 'report'.

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

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

Usage: (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.

Usage: (run-test-var v)

Runs the tests for a single Var, with fixtures executed around the test, and summary output after.

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

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

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.

Usage: (successful? summary)

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

Usage: (test-all-vars ns)

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

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 anamespace object or a symbol.Internally binds *report-counters* to a ref initialized to*initial-report-counters*.  Returns the final, dereferenced state of*report-counters*.

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

Usage: (test-vars vars)

Groups vars by their namespace and runs test-var on them withappropriate fixtures applied.

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

Usage: (testing-contexts-str)

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

Usage: (testing-vars-str m)

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

Usage: (try-expr msg form)

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

No usage documentation available

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

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, ignoringthe tests.

Usage: (with-test-out & body)

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

clojure.test.junit

clojure.test extension for JUnit-compatible XML output.JUnit (http://junit.org/) is the most popular unit-testing libraryfor Java.  As such, tool support for JUnit output formats iscommon.  By producing compatible output from tests, this toolsupport can be exploited.To use, wrap any calls to clojure.test/run-tests in thewith-junit-output macro, like this:  (use 'clojure.test)  (use 'clojure.test.junit)  (with-junit-output    (run-tests 'my.cool.library))To write the output to a file, rebind clojure.test/*test-out* toyour own PrintWriter (perhaps opened usingclojure.java.io/writer).

Usage: (with-junit-output & body)

Execute body with modified test-is reporting functions that writeJUnit-compatible XML output.

clojure.test.tap

clojure.test extensions for the Test Anything Protocol (TAP)TAP is a simple text-based syntax for reporting test results.  TAPwas originally developed for Perl, and now has implementations inseveral languages.  For more information on TAP, seehttp://testanything.org/ andhttp://search.cpan.org/~petdance/TAP-1.0.0/TAP.pmTo use this library, wrap any calls toclojure.test/run-tests in the with-tap-output macro,like this:  (use 'clojure.test)  (use 'clojure.test.tap)  (with-tap-output   (run-tests 'my.cool.library))

Usage: (print-tap-diagnostic data)

Prints a TAP diagnostic line.  data is a (possibly multi-line)string.

Usage: (print-tap-fail msg)

Prints a TAP 'not ok' line.  msg is a string, with no line breaks

Usage: (print-tap-pass msg)

Prints a TAP 'ok' line.  msg is a string, with no line breaks

Usage: (print-tap-plan n)

Prints a TAP plan line like '1..n'.  n is the number of tests

Usage: (with-tap-output & body)

Execute body with modified test reporting functions that produceTAP output