hegel-clj.core — com.aphyr/hegel-clj 0.1.1

The main API for hegel-clj.

*test-case* clj

It's convenient to have an implicitly bound test case, so one can simply call (draw! generator) instead of threading the test case through.

assume! clj

(assume! condition)

(assume! test-case condition)

Rejects the current test case unless the given condition holds.

draw! clj

(draw! gen)

(draw! label gen)

(draw! test-case label gen)

Given a generator, draws a randomly selected value. Optionally takes a label, which will be used to describe the value in the final output. For example:

(draw! (g/float))
(draw! "bools" (g/vector (g/boolean)))
(draw! test-case "names" (g/set (g/string)))

failure->map clj

(failure->map f)

Converts a Hegel test case Failure to a Clojure map of the form:

{:draws :exception :reproduce-blob :caveat}

final? clj

(final?)

(final? test-case)

Is Hegel in the final phase of a test?

finfo clj macro

(finfo & args)

Wrapper for (when (final?) (info ...))

fpp clj

(fpp x)

Wrapper for (when (final?) (pprint x))

fprn clj

(fprn & args)

Wrapper for (when (final?) (prn ...))

label clj

(label label)

Takes a keyword and returns a long label for a span. These tell Hegel the kind of structure represented by the span. There are several built-in labels from Hegel.label. Using any other label will generate a fresh one.

let clj macro

(let binding-forms & body)

Like Clojure's let, but when a right-hand side is a Generator, draws a value using hegel-clj.core/draw!. This lets you mix generators and regular values. For example:

(h/let [a (gen/integer) ; Drawn randomly by hegel-clj
        b (+ a 2)]      ; Evaluated as normal
  ...)

note! clj

(note! msg)

(note! test-case msg)

Records a debug message which is shown only on the final replay of a failing case.

run-stateful! clj

(run-stateful! state)

(run-stateful! test-case state)

Within a test case, asks Hegel to run a stateful test over the given object. See hegel.dev.Stateful for details.

sample clj

(sample n-or-opts gen)

Samples up to n values from the provided generator. Helpful for debugging generators. Can either take a number of values, or a map passed to test!, which is helpful if you want to pass a deterministic seed etc.

span! clj macro

(span! & args)

Opens a span, evaluates body, then closes it. Spans denote a series of draws which belong together, so that Hegel can shrink them as a unit. Takes a literal keyword label, which can either be a built-in Hegel label or a custom one; see label for details.

Can take an optional test case as the first argument, or just a span, in which case test-case is used.

(span :list-element
  (draw! (g/integer)))

(span my-test-case :list-element
  (draw! my-test-case (g/integer)))

target! clj

(target! value)

(target! value label)

(target! test-case value label)

Guides Hegel by reporting that something interesting has happened during this test case. Higher numbers are more interesting. Takes an optional label; either a string, or any object, which will be converted to a string with pr-str.

test! clj macro

(test! opts & body)

Main entry point for running tests. This is the macro form of test-fn!; takes a body, rather than a function.

test-fn! clj

(test-fn! {:keys [database derandomize? health-checks name phases
                  report-multiple-failures? seed suppress-health-checks
                  test-cases verbosity]}
          case-fn)

Runs a test. This version is more functional; see run! for the macro form. Options are:

:database       A hegel.Database
:derandomize?   Whether to force deterministic (or not) input selection.
:name           The string name of the property being tested.

:reproduce-failure
                A string blob (e.g. the :reproduce-blob from one of
                the :failures returned by an earlier call to
                test-fn!) which has Hegel run just that failure,
                instead of searching and shrinking in general.

:report-multiple-failures?
                If set, Hegel will keep searching for additional distinct
                failures after the first.

:seed           A Long random seed

:suppress-health-checks
                A collection of health check keywords to
                suppress: any of :test-cases-too-large, :filter-too-much,
                :too-slow, :large-initial-test-case

:test-cases     The number of test cases to run

:verbosity      One of :debug, :normal, :quiet, or :verbose.

Takes a function (case-fn) which will be invoked approximately test-cases times, with a TestCase argument. This case will also be bound to test-case for the duration of the function. This function can call (draw gen) to generate values. As a side effect, it should either return a value, or throw.

Returns a map describing the results of the test, of the form:

:passed?                Did all tests pass?
:status                 Either :passed, :failed, or :error (if a health
                        check failed or the engine crashed)
:statistics             A map of the :total, :valid, :invalid, :overrun,
                        and :interesting test case counts.
:error                  A string error message, present iff the status
                        was :error.
:flaky?                 Hegel thought this test was non-deterministic
:health-check-failed?   Did a health check fail during the test?
:failures               A sequence of failure maps which describe each
                        failing test case--see failure->map for details.