test

test/*testing-contexts*#

Stack of testing context strings, most recent first.

test/add-reporter!#

(add-reporter! reporter-fn)

Appends reporter-fn to the active reporter set. Returns the updated reporter list.

Example:

(add-reporter! tap-reporter)

test/are#

(are argv expr & args)

Checks multiple assertions with a template expression. argv is a vector of template variables, expr is the assertion template, and the remaining args are partitioned by (count argv) to fill the template. Template variables are substituted lexically at macro-expansion time, so literal collection cells (e.g. (), [], {}) are preserved as data and are not evaluated as code.

Example:

(are [x y] (= x y)
  2 (+ 1 1)
  4 (* 2 2))

test/assert-expr#

(assert-expr & args)

Public extension point for the is macro: an open multimethod dispatched on the first symbol of the asserted form (or :default for non-list forms and for lists not starting with a symbol).

Extend it with (defmethod phel.test/assert-expr 'my-form [message form] ...), returning a quoted form for is to evaluate. Methods must be loaded before any is form using their dispatch value is expanded.

test/assert-expr-methods#

Dispatch table for the assert-expr multimethod: a map of dispatch value to implementing function. Registered through defmethod; not meant to be written directly.

test/assert-expr-prefers#

Preference table for the assert-expr multimethod, resolving ambiguity between two matching dispatch values. Registered through prefer-method; not meant to be written directly.

test/clear-reporters!#

(clear-reporters!)

Removes every registered reporter. Returns an empty vector.

Example:

(clear-reporters!)

test/deftest#

(deftest test-name & body)

Defines a test function.

Metadata attached to test-name is forwarded to the defined function so selectors can inspect it at runtime. ^:integration (shorthand for {:integration true}) and ^{:tags [:integration :slow]} multi-tag maps are both honoured.

Example:

(deftest test-add)

test/do-report#

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

Example:

(do-report {:state :pass :type :any :message "ok"})

test/get-failed-tests#

(get-failed-tests)

Returns the names (ns/test-name) of tests that failed or errored in the last run. Used by --parallel orchestration to aggregate last-failed lists across worker processes.

Example:

(get-failed-tests) ; => ["my-app/foo-test"]

test/get-reporters#

(get-reporters)

Returns the currently registered reporter functions as a vector.

Example:

(get-reporters)

test/get-stats#

(get-stats)

Returns the current test statistics as a hash-map with :failed and :counts keys.

Example:

(get-stats) ; => {:failed [], :skipped [], :counts {:failed 0, :error 0, :pass 0, :skipped 0, :total 0}}

test/is#

(is form & [message])

Asserts that an expression is true.

Example:

(is (= 4 (+ 2 2)))

test/register-reporter!#

(register-reporter! name reporter-fn)

Registers a custom reporter function under name (keyword or keyword-castable string). Returns name.

Example:

(register-reporter! :my-reporter (fn [event] ...))

test/report#

(report & args)

Records a test-framework event and dispatches it to the active reporters. data must contain a :type key (:pass, :failed, :error, :begin-test-ns, :end-test-ns, :begin-test-run, :summary, or a user-defined event). The default methods for assertion outcomes update the internal stats and invoke every registered reporter. Other event types flow straight through to the reporter set. Extend by registering (defmethod report :custom-type [event] ...).

test/report-methods#

Dispatch table for the report multimethod: a map of dispatch value to implementing function. Registered through defmethod; not meant to be written directly.

test/report-prefers#

Preference table for the report multimethod, resolving ambiguity between two matching dispatch values. Registered through prefer-method; not meant to be written directly.

test/reset-stats#

(reset-stats)

Resets the test statistics to their initial state. Call this before running a new batch of tests to get fresh results.

Example:

(reset-stats)

test/resolve-reporter#

(resolve-reporter name)

Returns the reporter function registered for name (keyword or string). Checks user-registered reporters before the built-in set. Returns nil if the name is unknown.

Example:

(resolve-reporter :junit-xml)

test/restore-stats#

(restore-stats saved)

Restores test statistics from a previously saved state.

Example:

(restore-stats saved)

test/run-tests#

(run-tests options & namespaces)

Runs all tests in the given namespaces. When :list-only is true, prints the discovered tests and skips execution.

Recognized option keys include :filter, :filters, :include, :exclude, :ns-patterns, :fail-fast, :stack-trace, :reporters, :junit-output, :list-only, :only-tests, :last-failed-file, :slowest, :repeat (run the selected tests N times), :seed (integer seed for the order RNG), and :random-order (shuffle tests per namespace).

Example:

(run-tests {} 'my-app\test)

test/set-junit-output!#

(set-junit-output! path)

Configures the output path the JUnit reporter writes to. When nil, the XML is printed to stdout.

Example:

(set-junit-output! "build/junit.xml")

test/set-reporters!#

(set-reporters! reporters)

Replaces the active reporter set with reporters (a sequence of single-argument functions). Returns the new reporter list.

Example:

(set-reporters! [my-reporter-fn])

test/successful?#

(successful?)

Checks if all tests passed.

Example:

(successful?) # => true

test/testing#

(testing context & body)

Adds a testing context string. Used inside deftest to describe a group of assertions. The context string is prepended to failure messages for better diagnostics.

Example:

(deftest test-math
  (testing "addition"
    (is (= 2 (+ 1 1)))))

test/use-fixtures#

(use-fixtures fixture-type & fns)

Registers fixture functions for the current namespace.

fixture-type is either :each (wraps every individual test) or :once (wraps the whole run in a single function). Each fixture is a function of one argument, a thunk (fn []) representing the tests to run, and is expected to invoke that thunk somewhere in its body.

Calling use-fixtures with no fixture functions removes all fixtures of that type previously registered on the namespace.

Example:

(use-fixtures :once (fn [t] (setup) (t) (teardown)))

test/with-isolated-reporters#

(with-isolated-reporters reporters & body)

Installs reporters as the only active reporter set while body runs, then restores the previously registered reporters. Returns the value of the last form in body. Use it to capture the events a piece of code emits without permanently replacing the reporters the surrounding run relies on. The previous reporter set is restored even when body throws.

Example:

(let [events (atom [])]
  (with-isolated-reporters [(fn [event] (swap! events conj (:type event)))]
    (report {:type :pass :state :pass}))
  (deref events)) ; => [:pass]

test/with-isolated-stats#

(with-isolated-stats & body)

Runs body against a freshly reset statistics accumulator and returns the stats map that body produced, then restores the statistics the caller had before. Use it when asserting on the outcome of assertions under test, so their pass/fail counts never leak into the surrounding run. Wrap body in with-output-buffer to swallow the reporter output those assertions emit. The caller's statistics are restored even when body throws.

Example:

(:counts (with-isolated-stats (with-output-buffer (is (= 1 2))))) ; => {:failed 1, :error 0, :pass 0, :skipped 0, :total 1}