speclj.core

Speclj's API. It contains nothing but macros, so that it can be used
in both Clojure and ClojureScript.

-fail

macro

(-fail message)
Useful for making custom assertions.

after

macro

(after & body)
Declares a function that is invoked after each characteristic in the containing describe scope is evaluated. The body
may consist of any forms, presumably ones that perform side effects.

after-all

macro

(after-all & body)
Declares a function that is invoked once after all the characteristics in the containing describe scope have been
evaluated.  The body may consist of any forms, presumably ones that perform side effects.

around

macro

(around binding & body)
Declares a function that will be invoked around each characteristic of the containing describe scope.
The characteristic will be passed in and the around function is responsible for invoking it.

(around [it] (binding [*out* new-out] (it)))

Note that if you have cleanup that must run, use a 'finally' block:

(around [it] (try (it) (finally :clean-up)))

around-all

macro

(around-all context & body)
Declares a function that is invoked once around all characteristics of the containing describe scope.

before

macro

(before & body)
Declares a function that is invoked before each characteristic in the containing describe scope is evaluated. The body
may consist of any forms, presumably ones that perform side effects.

before-all

macro

(before-all & body)
Declares a function that is invoked once before any characteristic in the containing describe scope is evaluated. The
body may consist of any forms, presumably ones that perform side effects.

cljs-munge

context

macro

(context name & components)
Same as describe, but should be used to nest testing contexts inside the outer describe.
Contexts can be nested any number of times.

describe

macro

(describe name & components)
body => & spec-components

Declares a new spec.  The body can contain any forms that evaluate to spec components (it, before, after, with ...).

focus-context

macro

(focus-context name & components)
Same as 'context', but it is meant to facilitate temporary debugging.
Components defined with this macro will be fully executed along with any
other components thus defined, but all other sibling components defined
with 'context' will be ignored.

focus-describe

macro

(focus-describe name & components)
Same as 'describe', but it is meant to facilitate temporary debugging.
Components defined with this macro will be fully executed along with any
other components thus defined, but all other sibling components defined
with 'describe' will be ignored.

focus-it

macro

(focus-it name & body)
Same as 'it', but it is meant to facilitate temporary debugging.
Characteristics defined with this macro will be executed along with any
other characteristics thus defined, but all other characteristic defined
with 'it' will be ignored.

it

macro

(it name & body)
body => any forms, but should contain at least one assertion (should)

Declares a new characteristic (example in rspec).

pending

macro

(pending)(pending message)
When added to a characteristic, it is marked as pending.  If a message is provided it will be printed
in the run report

run-specs

macro

(run-specs)

should

macro

(should form)
Asserts the truthy-ness of a form

should-be

macro

(should-be f-form actual-form)
Asserts that a form satisfies a function.

should-be-a

macro

(should-be-a expected-type actual-form)
Asserts that the type of the given form derives from or equals the expected type

should-be-nil

macro

(should-be-nil form)
Asserts that the form evaluates to nil

should-be-same

macro

(should-be-same expected-form actual-form)
Asserts that two forms evaluate to the same object, with the expected value as the first parameter.

should-contain

macro

(should-contain expected actual)
Multi-purpose assertion of containment.  Works on strings, regular expressions, sequences, and maps.

(should-contain "foo" "foobar")            ; looks for sub-string
(should-contain #"hello.*" "hello, world") ; looks for regular expression
(should-contain :foo {:foo :bar})          ; looks for a key in a map
(should-contain 3 [1 2 3 4])               ; looks for an object in a collection

should-end-with

macro

(should-end-with suffix whole)
Assertion of suffix in strings and sequences.

(should-end-with "foo" "foobar")            ; looks for string suffix
(should-end-with [1 2] [1 2 3 4])               ; looks for a subset at end of collection

should-fail

macro

(should-fail)(should-fail message)
Forces a failure. An optional message may be passed in.

should-have-invoked

macro

(should-have-invoked name)(should-have-invoked name options)
Checks for invocations of the specified stub.

Options:
  :times - the number of times the stub should have been invoked. nil means at least once. (default: nil)
  :with - a list of arguments that the stubs should have been invoked with.
    If not specified, anything goes.  Special expected arguments include:
     :* - matches anything
     a fn - matches when the actual is the same fn or calling fn with the actual argument returns true

Example:
(let [foo (stub :foo)]
  (should-have-invoked :foo {:with [1] :times 3}) ; fail
  (foo 1)
  (foo 2)
  (should-have-invoked :foo {:with [1] :times 3}) ; fail
  (should-have-invoked :foo {:with [1] :times 1}) ; pass
  (should-have-invoked :foo {:with [2] :times 1}) ; pass
  (should-have-invoked :foo {:times 3}) ; fail
  (should-have-invoked :foo {:times 2}) ; pass
  (should-have-invoked :foo {:times 1}) ; fail
  (should-have-invoked :foo {:with [1]}) ; pass
  (should-have-invoked :foo {:with [2]}) ; pass
  )

should-invoke

macro

(should-invoke var options & body)
Creates a stub, and binds it to the specified var, evaluates the body, and checks the invocations.

(should-invoke reverse {:with [1 2 3] :return []} (reverse [1 2 3]))

See stub and should-have-invoked for valid options.

should-not

macro

(should-not form)
Asserts the falsy-ness of a form

should-not-be

macro

(should-not-be f-form actual-form)
Asserts that a form does not satisfy a function.

should-not-be-a

macro

(should-not-be-a expected-type actual-form)
Asserts that the type of the given form does not derived from or equals the expected type

should-not-be-nil

macro

(should-not-be-nil form)
Asserts that the form evaluates to a non-nil value

should-not-be-same

macro

(should-not-be-same expected-form actual-form)
Asserts that two forms evaluate to different objects, with the unexpected value as the first parameter.

should-not-contain

macro

(should-not-contain expected actual)
Multi-purpose assertion of non-containment.  See should-contain as an example of opposite behavior.

should-not-end-with

macro

(should-not-end-with prefix whole)
The inverse of should-end-with.

should-not-have-invoked

macro

(should-not-have-invoked name)(should-not-have-invoked name options)
Inverse of should-have-invoked.

Options:
  :times - the number of times the stub should not have been invoked. nil means never. (default: nil)
  :with - a list of arguments that the stubs should not have been invoked with.
    If not specified, anything goes. Special expected arguments include:
     :* - matches anything
     a fn - matches when the actual is the same fn or calling fn with the actual argument returns true

Example:
(let [foo (stub :foo)]
  (should-not-have-invoked :foo {:with [1] :times 3}) ; pass
  (foo 1)
  (should-not-have-invoked :foo {:with [1] :times 3}) ; pass
  (should-not-have-invoked :foo {:with [1] :times 1}) ; fail
  (should-not-have-invoked :foo {:times 3}) ; pass
  (should-not-have-invoked :foo {:times 1}) ; fail
  (should-not-have-invoked :foo {:with [1]}) ; fail
  )

should-not-invoke

macro

(should-not-invoke var options & body)
Creates a stub, and binds it to the specified var, evaluates the body, and checks that is was NOT invoked.

(should-not-invoke reverse {:with [1 2 3] :return [] :times 2} (reverse [1 2 3])) ; pass
(should-not-invoke reverse {:with [1 2 3] :return []} (reverse [1 2 3])) ; fail

See stub and should-not-have-invoked for valid options.

should-not-start-with

macro

(should-not-start-with prefix whole)
The inverse of should-start-with.

should-not-throw

macro

(should-not-throw form)
Asserts that nothing is thrown by the evaluation of a form.

should-not=

macro

(should-not= expected-form actual-form)
Asserts that two forms evaluate to unequal values, with the unexpected value as the first parameter.

should-not==

macro

(should-not== expected actual)
Asserts 'non-equivalency'.
When passed collections it will check that they do NOT have the same contents.
For anything else it will assert that clojure.core/== returns false.

should-start-with

macro

(should-start-with prefix whole)
Assertion of prefix in strings and sequences.

(should-start-with "foo" "foobar")            ; looks for string prefix
(should-start-with [1 2] [1 2 3 4])               ; looks for a subset at start of collection

should-throw

macro

(should-throw form)(should-throw throwable-type form)(should-throw throwable-type predicate form)
Asserts that a Throwable is throws by the evaluation of a form.
When an class is passed, it asserts that the thrown Exception is an instance of the class.
There are three options for passing different kinds of predicates:
  - If a string, assert that the message of the Exception is equal to the string.
  - If a regex, asserts that the message of the Exception matches the regex.
  - If a function, assert that calling the function on the Exception returns a truthy value.

should<

macro

(should< a b)
Asserts that the first numeric form is less than the second numeric form, using the built-in < function.

should<=

macro

(should<= a b)
Asserts that the first numeric form is less than or equal to the second numeric form, using the built-in <= function.

should=

macro

(should= expected-form actual-form)(should= expected-form actual-form delta-form)
Asserts that two forms evaluate to equal values, with the expected value as the first parameter.

should==

macro

(should== expected actual)
Asserts 'equivalency'.
When passed collections it will check that they have the same contents.
For anything else it will assert that clojure.core/== returns true.

should>

macro

(should> a b)
Asserts that the first numeric form is greater than the second numeric form, using the built-in > function.

should>=

macro

(should>= a b)
Asserts that the first numeric form is greater than or equal to the second numeric form, using the built-in >= function.

stub

macro

(stub name)(stub name options)
Creates a stub function.  Each call to the stub will be recorded and can later be looked up using the specified name.

Options:
  :invoke - a function that will be invoked when the stub is invoked.  All the arguments passed to the stub will
    be passed to the :invoke value and its return value returned by the stub.
  :return - a value that will be returned by the stub.  This overrides the result of the :invoke value, if specified.
  :throw - an exception that will be thrown by the stub.

tags

macro

(tags & values)
Add tags to the containing context.  All values passed will be converted into keywords.  Contexts can be filtered
at runtime by their tags.

(tags :one :two)

with

macro

(with name & body)
Declares a reference-able symbol that will be lazily evaluated once per characteristic of the containing
describe scope.  The body may contain any forms, the last of which will be the value of the dereferenced symbol.

(with meaning 42)
(it "knows the meaning of life" (should= @meaning (the-meaning-of :life)))

with!

macro

(with! name & body)
Declares a reference-able symbol that will be evaluated immediately and reset once per characteristic of the containing
describe scope.  The body may contain any forms, the last of which will be the value of the dereferenced symbol.

(def my-num (atom 0))
(with! my-with! (swap! my-num inc))
(it "increments my-num before being accessed" (should= 1 @my-num) (should= 2 @my-with!))

with-all

macro

(with-all name & body)
Declares a reference-able symbol that will be lazily evaluated once per context. The body may contain any forms,
 the last of which will be the value of the dereferenced symbol.

(with-all meaning 42)
(it "knows the meaning of life" (should= @meaning (the-meaning-of :life)))

with-all!

macro

(with-all! name & body)
Declares a reference-able symbol that will be immediately evaluated once per context. The body may contain any forms,
 the last of which will be the value of the dereferenced symbol.

(def my-num (atom 0))
(with-all! my-with-all! (swap! my-num inc))
(it "increments my-num before being accessed"
  (should= 1 @my-num)
  (should= 2 @my-with!))
(it "only increments my-num once per context"
  (should= 1 @my-num)
  (should= 2 @my-with!))

with-stubs

macro

(with-stubs)
Add this to describe/context blocks that use stubs.  It will setup a clean recording environment.

xit

macro

(xit name & body)
Syntactic shortcut to make the characteristic pending.