(diff spec.alpha speculoos)

spec.alpha predicates are tested with s/conform or s/valid?

(require '[clojure.spec.alpha :as s])


(s/conform even? 1000) ;; => 1000

Speculoos specifications are bare, unadorned Clojure predicates.

(even? 1000) ;; => true

(nil? nil) ;; => true

(#(< % 5) 4) ;; => true

spec.alpha provides a special def which stores the spec in a central registry.

(s/def :order/date inst?)

(s/def :deck/suit #{:club :diamond :heart :spade})

Speculoos specifications are plain Clojure functions. They are def-ed and live in our namespace, and are therefore automatically namespace-qualified.

(def date inst?)

(def suit #{:club :diamond :heart :spade})

If you like the idea of a spec registry, toss 'em into your own hashmap; Speculoos specifications are just predicates and can be used anywhere

(import java.util.Date) ;; => java.util.Date


(date (Date.)) ;; => true

(suit :club) ;; => :club

(suit :shovel) ;; => nil

spec.alpha has some slick facilities for automatically creating spec docstrings.

Speculoos specifications do not have any special docstring features beyond what we explicitly add to our function defs.

spec.alpha specs are composed with special functions s/and and s/or.

(s/def :num/big-even
  (s/and int?
         even?
         #(> % 1000)))


(s/valid? :num/big-even :foo) ;; => false
(s/valid? :num/big-even 10) ;; => false
(s/valid? :num/big-even 100000) ;; => true


(s/def :domain/name-or-id
  (s/or :name string?
        :id int?))


(s/valid? :domain/name-or-id "abc") ;; => true
(s/valid? :domain/name-or-id 100) ;; => true
(s/valid? :domain/name-or-id :foo) ;; => false

Speculoos specifications are composed with clojure.core/and and clojure.core/or.

(def big-even #(and (int? %) (even? %) (> % 1000)))


(big-even :foo) ;; => false
(big-even 10) ;; => false
(big-even 10000) ;; => true


(def name-or-id #(or (string? %) (int? %)))


(name-or-id "abc") ;; => true
(name-or-id 100) ;; => true
(name-or-id :foo) ;; => false

spec.alpha annotates branches with keywords (e.g., :name and :id), used to return conformed data.

Speculoos uses a different strategy using paths to refer to datums within an validation report.

spec.alpha provides a helper to include nil as a valid value

(s/valid? string? nil) ;; => false
(s/valid? (s/nilable string?) nil) ;; => true

Simply compose to make a Speculoos predicate nilable.

(#(or (string? %) (nil? %)) nil) ;; => true

spec.alpha's explain provides a nice report for non-conforming simple predicates.

Speculoos returns only true/false for simple predicates. Later, we'll see how Speculoos does produce a detailed report for composite values.

Here is spec.alpha in action.

(def email-regex #"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,63}$")


(s/def :acct/email-type (s/and string? #(re-matches email-regex %)))


(s/def :acct/acctid int?)
(s/def :acct/first-name string?)
(s/def :acct/last-name string?)
(s/def :acct/email :acct/email-type)


(s/def :acct/person
  (s/keys :req [:acct/first-name :acct/last-name :acct/email]
          :opt [:acct/phone]))

Here is the same process in Speculoos, re-using the regex. (The spec Guide does not appear to use :acct/acctid, so I will skip it.)

(def email-spec #(and (string? %) (re-matches email-regex %)))


(def person-spec
  {:first-name string?, :last-name string?, :email email-spec, :phone any?})


(require '[speculoos.core :refer
           [valid-scalars? validate-scalars only-invalid]])


(valid-scalars? {:first-name "Bugs",
                 :last-name "Bunny",
                 :email "bugs@example.com"}
                person-spec)
;; => true

Speculoos checks only keys that are in both the data and the specification. If we don't want to validate a particular entry, we can, on-the-fly, dissociate that key-val from the specification.

(valid-scalars? {:first-name "Bugs",
                 :last-name "Bunny",
                 :email "not@even@close@to@a@valid@email"}
                (dissoc person-spec :email))
;; => true

If we want to merely relax a specification, simply associate a new, more permissive predicate.

(valid-scalars? {:first-name "Bugs",
                 :last-name "Bunny",
                 :email :not-an-email}
                (assoc person-spec
                  :email #(string? %)))
;; => false

Note the function name: Speculoos distinguishes validating scalars (i.e., numbers, strings, characters, etc.) from collections (vectors, lists, maps, sets). Speculoos provides a corresponding group of functions for specifying and validating collection counts, presence of keys, set membership, etc.

(valid-scalars? {:first-name "Bugs",
                 :last-name "Bunny",
                 :email "n/a"}
                person-spec)
;; => false

Instead of using valid…? and friends, Speculoos' validate…* family of functions show the details of the validating each datum.

(validate-scalars {:first-name "Bugs",
                   :last-name "Bunny",
                   :email "n/a"}
                  person-spec)
;; => [{:datum "Bugs",
;;      :path [:first-name],
;;      :predicate string?,
;;      :valid? true}
;;     {:datum "Bunny",
;;      :path [:last-name],
;;      :predicate string?,
;;      :valid? true}
;;     {:datum "n/a",
;;      :path [:email],
;;      :predicate email-spec,
;;      :valid? nil}]

The validation results can grow unwieldy with large data and specifications, so Speculoos provides some helper functions to quickly focus on points of interest, i.e., non-valid datums.

(only-invalid (validate-scalars
                {:first-name "Bugs",
                 :last-name "Bunny",
                 :email "n/a"}
                person-spec))
;; => ({:datum "n/a",
;;      :path [:email],
;;      :predicate email-spec,
;;      :valid? nil})

spec.alpha distinguishes unqualified keys and fully-namespaced keys, and allows us to explicitly declare one or the other.

Speculoos implicitly distinguishes qualified from unqualified keys because (not= :k ::k).

Observe: Qualified keys in data, unqualified keys in specification, no matches…

(validate-scalars {::a 42, ::b "abc", ::c :foo}
                  {:a int?, :b string?, :c keyword?})
;; => []

…qualified keys in both data and specification, validation succeeds…

(valid-scalars? {::a 42, ::b "abc", ::c :foo}
                {::a int?, ::b string?, ::c keyword?})
;; => true

…unqualified keys in both data and specification, validation succeeds.

(valid-scalars? {:a 42, :b "abc", :c :foo}
                {:a int?, :b string?, :c keyword?})
;; => true

spec.alpha has the capability to dispatch validation paths according to an in-band key. Here's the Guide's demo.

(s/def :event/type keyword?)
(s/def :event/timestamp int?)
(s/def :search/url string?)
(s/def :error/message string?)
(s/def :error/code int?)


(defmulti event-type :event/type) ;; => nil


(defmethod event-type :event/search
  [_]
  (s/keys :req [:event/type :event/timestamp :search/url]))
;; => #multifn [event-type 0x7f03f2d]


(defmethod event-type :event/error
  [_]
  (s/keys :req [:event/type :event/timestamp :error/message :error/code]))
;; => #multifn [event-type 0x7f03f2d]


(s/def :event/event (s/multi-spec event-type :event/type))


(s/valid? :event/event
          {:event/type :event/search,
           :event/timestamp 1463970123000,
           :search/url "https://clojure.org"})
;; => true


(s/valid? :event/event
          {:event/type :event/error,
           :event/timestamp 1463970123000,
           :error/message "Invalid host",
           :error/code 500})
;; => true


(s/explain :event/event {:event/type :event/restart}) ;; => nil

Since Speculoos consumes regular old Clojure data structures and functions, they work similarly. Instead of def-ing a series of separate predicates, for brevity, I'll inject them directly into the specification definition, but Speculoos could handle any level of indirection.

(defmulti event-type :event/type) ;; => nil


(defmethod event-type :event/search
  [_]
  {:event/type keyword?, :event/timestamp int?, :search/url string?})
;; => #multifn [event-type 0x7f03f2d]


(defmethod event-type :event/error
  [_]
  {:event/type keyword?,
   :event/timestamp int?,
   :error/message string?,
   :error/code int?})
;; => #multifn [event-type 0x7f03f2d]


(def event-1
  {:event/type :event/search,
   :event/timestamp 1463970123000,
   :event/url "https://clojure.org"})


(valid-scalars? event-1 (event-type event-1)) ;; => true


(def event-2
  {:event/type :event/error,
   :event/timestamp 1463970123000,
   :error/message "Invalid host",
   :code 500})


(valid-scalars? event-2 (event-type event-2)) ;; => true


(def event-3 {:event/type :restart})


(try (valid-scalars? event-3 (event-type event-3))
     (catch Exception e (.getMessage e)))
;; => "No method in multimethod 'event-type' for dispatch value: :restart"


(def event-4 {:event/type :event/search, :search/url 200})


(only-invalid (validate-scalars event-4 (event-type event-4)))
;; => ({:datum 200,
;;      :path [:search/url],
;;      :predicate string?,
;;      :valid? false})

spec.alpha provides a trio of helper functions for collections. First, coll-of.

(s/conform (s/coll-of keyword?) [:a :b :c]) ;; => [:a :b :c]


(s/conform (s/coll-of number?) #{5 10 2}) ;; => #{2 5 10}


(s/def :ex/vnum3
  (s/coll-of number? :kind vector? :count 3 :distinct true :into #{}))


(s/conform :ex/vnum3 [1 2 3]) ;; => #{1 2 3}

Speculoos was designed from the beginning to specify collections. Speculoos validates collections in two different ways: it can validate groupings of scalars, atomic, indivisible values (i.e., numbers, booleans, etc.) and it can separately validate the properties of a collection (i.e., vector, map, list, set, etc.) itself, such as its size, the position of particular elements, and the relationships between elements, etc.

This example could certainly be validated as we've seen before.

(valid-scalars? [:a :b :c]
                [keyword? keyword? keyword?])
;; => true

Speculoos could also consider the vector as a whole with its collection validation facility.

(require '[speculoos.core :refer [valid-collections? validate-collections]])


(valid-collections? [:a :b :c]
                    [#(every? keyword? %)])
;; => true

In a collection specification, the predicate applies to the collection that contains that predicate.

Speculoos collection specifications work on just about any type of collection.

(valid-collections? #{5 10 2}
                    #{#(every? number? %)})
;; => true

Speculoos is not limited in the kinds of predicates we might apply to the collection; any Clojure predicate works.

(def all-vector-entries-distinct? #(apply distinct? %))
(def all-vector-entries-numbers? #(every? number? %))
(def vector-length-3? #(= 3 (count %)))


(def combo-coll-spec
  [all-vector-entries-numbers? vector? vector-length-3?
   all-vector-entries-distinct?])


(valid-collections? [1 2 3] combo-coll-spec) ;; => true


(valid-collections? #{1 2 3} combo-coll-spec) ;; => false


(valid-collections? [1 1 1] combo-coll-spec) ;; => false


(only-invalid (validate-collections [1 2 :a] combo-coll-spec))
;; => ({:datum [1 2 :a],
;;      :ordinal-path-datum [],
;;      :path-datum [],
;;      :path-predicate [0],
;;      :predicate
;;        all-vector-entries-numbers?,
;;      :valid? false})

The last example above highlights how def-ing our predicates with informative names makes the validation results easier understand. Instead of something inscrutable like fn--10774, we'll see the name we gave it, presumably carrying some useful meaning. Helps our future selves understand our present selves' intent, and we just might be able to re-use that specification in other contexts.

Next, spec.alpha's tuple.

(s/def :geom/point (s/tuple double? double? double?))


(s/conform :geom/point [1.5 2.5 -0.5]) ;; => [1.5 2.5 -0.5]

Tuples are Speculoos' bread and butter.

(valid-scalars? [1.5 2.5 -0.5]
                [double? double? double?])
;; => true

or

(valid-collections? [1.5 2.5 -0.5]
                    [#(every? double? %)])
;; => true

Finally, spec.alpha's map-of.

(s/def :game/scores (s/map-of string? int?))


(s/conform :game/scores {"Sally" 1000, "Joe" 500})
;; => {"Joe" 500, "Sally" 1000}

Where Speculoos really takes flight is heterogeneous, arbitrarily-nested collections, but since this document is a comparison to spec.alpha, see the Speculoos recipes for examples.

Speculoos collection validation works on maps, too.

(valid-collections?
  {"Sally" 1000, "Joe" 500}
  {:check-keys #(every? string? (keys %)),
   :check-vals #(every? int? (vals %))})
;; => true

spec.alpha uses regex syntax to describe the structure of sequential data.

(s/def :cook/ingredient
  (s/cat :quantity number?
         :unit keyword?))


(s/valid? :cook/ingredient [2 :teaspoon]) ;; => true

Speculoos uses a literal.

(def ingredient-spec [number? keyword?])


(valid-scalars? [2 :teaspoon] ingredient-spec) ;; => true

Invalid datums are reported like this.

(only-invalid (validate-scalars [11 "peaches"] ingredient-spec))
;; => ({:datum "peaches",
;;      :path [1],
;;      :predicate keyword?,
;;      :valid? false})

Note, 'missing' scalars are not validated as they would be with spec.alpha.

(valid-scalars? [2] ingredient-spec) ;; => true

Speculoos ignores predicates without a corresponding datum. Presence/absence of a datum is a property of the collection, and is therefore handled with a collection specification. Like so…

(def is-second-kw? #(keyword? (get % 1)))


(validate-collections [2] [is-second-kw?])
;; => ({:datum [2],
;;      :ordinal-path-datum [],
;;      :path-datum [],
;;      :path-predicate [0],
;;      :predicate is-second-kw?,
;;      :valid? false})

Let's look at another spec.alpha example.

(s/def :ex/seq-of-keywords (s/* keyword?))


(s/valid? :ex/seq-of-keywords [:a :b :c]) ;; => true


(s/explain :ex/seq-of-keywords [10 20]) ;; => nil

Now, the Speculoos way.

(def inf-seq-of-keywords-spec (repeat keyword?))


(valid-scalars? [:a :b :c]
                inf-seq-of-keywords-spec) ;; => true


(validate-scalars [10 20]
                  inf-seq-of-keywords-spec)
;; => [{:datum 10,
;;      :path [0],
;;      :predicate keyword?,
;;      :valid? false}
;;     {:datum 20,
;;      :path [1],
;;      :predicate keyword?,
;;      :valid? false}]

spec.alpha…

(s/def :ex/odds-then-maybe-even
  (s/cat :odds (s/+ odd?)
         :even (s/? even?)))


(s/valid? :ex/odds-then-maybe-even [1 3 5 100]) ;; => true


(s/valid? :ex/odds-then-maybe-even [1]) ;; => true


(s/explain :ex/odds-then-maybe-even [100]) ;; => nil

Speculoos…

(def odds-then-maybe-even-spec
  #(and (<= 2 (count (partition-by odd? %)))
        (every? odd? (first (partition-by odd? %)))))


(valid-collections?
  [1 3 5 100]
  [odds-then-maybe-even-spec]) ;; => true


(validate-collections
  [1]
  [odds-then-maybe-even-spec])
;; => ({:datum [1],
;;      :ordinal-path-datum [],
;;      :path-datum [],
;;      :path-predicate [0],
;;      :predicate odds-then-maybe-even-spec,
;;      :valid? false})


(validate-collections
  [100]
  [odds-then-maybe-even-spec])
;; => ({:datum [100],
;;      :ordinal-path-datum [],
;;      :path-datum [],
;;      :path-predicate [0],
;;      :predicate odds-then-maybe-even-spec,
;;      :valid? false})

Here's a spec.alpha demonstration of opts that are alternating keywords and booleans.

(s/def :ex/opts
  (s/* (s/cat :opt keyword?
              :val boolean?)))


(s/valid? :ex/opts [:silent? false :verbose true]) ;; => true

Speculoos' way to do the same.

(def alt-kw-bool-spec (cycle [keyword? boolean?]))


(valid-scalars? [:silent false :verbose true]
                alt-kw-bool-spec)
;; => true

Finally, spec.alpha specifies alternatives like this.

(s/def :ex/config
  (s/* (s/cat :prop string?
              :val (s/alt :s string?
                          :b boolean?))))


(s/valid? :ex/config
          ["-server" "foo"
           "-verbose" true
           "-user" "joe"])
;; => true

We'd do this in Speculoos.

(def config-spec (cycle [string? #(or (string? %) (boolean? %))]))


(valid-scalars? ["-server" "foo"
                 "-verbose" true
                 "-user" "joe"]
                config-spec)
;; => true

spec.alpha created a provincial &.

(s/def :ex/even-strings (s/& (s/* string?) #(even? (count %))))


(s/valid? :ex/even-strings ["a"]) ;; => false
(s/valid? :ex/even-strings ["a" "b"]) ;; => true
(s/valid? :ex/even-strings ["a" "b" "c"]) ;; => false
(s/valid? :ex/even-strings ["a" "b" "c" "d"]) ;; => true

Speculoos uses clojure.core/and.

(def even-string-spec #(and (even? (count %)) (every? string? %)))


(valid-collections? ["a"] [even-string-spec]) ;; => false
(valid-collections? ["a" "b"] [even-string-spec]) ;; => true
(valid-collections? ["a" "b" "c"] [even-string-spec]) ;; => false
(valid-collections? ["a" "b" "c" "d"] [even-string-spec]) ;; => true

If I weren't trying closely follow along with the spec.alpha Guide for the sake of a compare-and-constrast, I would have written this.

(valid-scalars? ["a" "b" "c" "d"]
                (repeat string?)) ;; => true


(valid-collections? ["a" "b" "c" "d"]
                    [#(even? (count %))])
;; => true

Because we'll often want to validate both a scalar specification and a collection specification at the same time, Speculoos provides a convenience function that does both. With a single invocation, valid? performs a scalar validation, followed immediately by a collection validation, and then merges the results.

(require '[speculoos.core :refer [valid?]])


(valid? ["a" "b" "c" "d"]
        (repeat string?)
        [#(even? (count %))])
;; => true

To entice people to this mindset, I reserved the shortest and most mnemonic function name, valid?, for specifying and validating scalars separately from collections.

Nested collections provide another nice point of comparison. Quoting the spec Guide:

When [spec.alpha] regex ops are combined, they describe a single sequence. If you need to spec a nested sequential collection, you must use an explicit call to spec to start a new nested regex context.

(s/def :ex/nested
  (s/cat :names-kw #{:names}
         :names (s/spec (s/* string?))
         :nums-kw #{:nums}
         :nums (s/spec (s/* number?))))


(s/valid? :ex/nested
          [:names ["a" "b"] :nums [1 2 3]]) ;; => true

Speculoos was designed from the outset to straightforwardly handle nested collections.

(def scalar-nested-spec [#{:names} (repeat string?) #{:nums} (repeat number?)])


(valid-scalars? [:names ["a" "b"] :nums [1 2 3]]
                scalar-nested-spec)
;; => true

spec.alpha can define specifications for a function, like this example, which I've merged with a later section of the spec Guide, titled Instrumentation and Testing.

(defn ranged-rand
  "Returns random int in range start <= rand < end"
  [start end]
  (+ start (long (rand (- end start)))))


(s/fdef ranged-rand
  :args (s/and (s/cat :start int?
                      :end int?)
               #(< (:start %) (:end %)))
  :ret int?
  :fn (s/and #(>= (:ret %)
                  (-> %
                      :args
                      :start))
             #(< (:ret %)
                 (-> %
                     :args
                     :end))))
;; => diff/ranged-rand


(stest/instrument `ranged-rand) ;; => [diff/ranged-rand]


(try (ranged-rand 8 5) (catch Exception e (.getMessage e)))
;; => "Call to diff/ranged-rand did not conform to spec."


(stest/unstrument `ranged-rand) ;; => [diff/ranged-rand]

Speculoos provides a pair of corresponding utilities for testing functions. First, validate-fn-with wraps a function on-the-fly without mutating the function's var. First, I'll demonstrate a valid invocation.

(require '[speculoos.function-specs :refer [validate-fn-with]])


(def second-is-larger-than-first? #(< (get % 0) (get % 1)))


(validate-fn-with ranged-rand
                  {:speculoos/arg-scalar-spec [int? int?],
                   :speculoos/arg-collection-spec
                     [second-is-larger-than-first?],
                   :speculoos/ret-scalar-spec int?}
                  2
                  12)
;; => 8

Here, we'll intentionally violate the function's argument collection specification by reversing the order of the arguments, and observe the report.

(validate-fn-with ranged-rand
                  {:speculoos/arg-scalar-spec [int? int?],
                   :speculoos/arg-collection-spec
                     [second-is-larger-than-first?],
                   :speculoos/ret-scalar-spec int?}
                  8
                  5)
;; => ({:datum [8 5],
;;      :fn-spec-type :speculoos/argument,
;;      :ordinal-path-datum [],
;;      :path-datum [],
;;      :path-predicate [0],
;;      :predicate
;;        second-is-larger-than-first?,
;;      :valid? false})

For testing with a higher degree of integration, Speculoos' second function validation option mimics spec.alpha/instrument. Instrumented function specifications are gathered from the function's metadata. Speculoos provides a convenience function for injecting specs.

(require '[speculoos.function-specs :refer
           [inject-specs! instrument unstrument]])


(inject-specs! ranged-rand
               {:speculoos/arg-scalar-spec [int? int?],
                :speculoos/arg-collection-spec [second-is-larger-than-first?],
                :speculoos/ret-scalar-spec int?})
;; => nil

Now, we instrument the function…

(instrument ranged-rand)

…and then test it. Valid inputs return as normal.

(ranged-rand 5 8) ;; => 7

Invalid arguments return without halting if the function can successfully complete (as in this scenario), but the invalid message is tossed to *out*.

(with-out-str (ranged-rand 8 5))
;;=> ({:path [0],
       :value second-is-larger-than-first?,
       :datum [8 5],
       :ordinal-parent-path [],
       :valid? false})

Later, we can return the function to it's original state.

(unstrument ranged-rand)

(Compliments to whoever invented the unstrument term to compliment instrument.)

spec.alpha supports validating hofs like this.

(defn adder [x] #(+ x %))


(s/fdef adder
  :args (s/cat :x number?)
  :ret (s/fspec :args (s/cat :y number?)
                :ret number?)
  :fn #(= (-> %
              :args
              :x)
          ((:ret %) 0)))
;; => diff/adder

Speculoos' version looks like this.

(require '[speculoos.function-specs :refer [validate-higher-order-fn]])


(inject-specs! adder
               {:speculoos/arg-scalar-spec number?,
                :speculoos/ret-scalar-spec fn?,
                :speculoos/hof-specs {:speculoos/arg-scalar-spec [int?],
                                      :speculoos/ret-scalar-spec number?}})
;; => nil


(validate-higher-order-fn adder [5] [10]) ;; => 15


(validate-higher-order-fn adder [5] [22/7])
;; => ({:datum 22/7,
;;      :fn-tier :speculoos/argument,
;;      :path [1 0],
;;      :predicate int?,
;;      :valid? false})

Speculoos can specify and validate a higher-order-function's arguments and return values to any depth.

spec.alpha's macro analysis is nicely integrated into Clojure's macroexpander.

(s/fdef clojure.core/declare
  :args (s/cat :names (s/* simple-symbol?))
  :ret any?)
;; => clojure.core/declare


(declare 100)
;; => Call to clojure.core/declare did not conform to spec...

Speculoos is more ad hoc: macro output is tested the same as any other function.

(defmacro silly-macro [f & args] `(~f ~@args))


(silly-macro + 1 2) ;; => 3

Speculoos validates macro expansion like this.

(require '[speculoos.core :refer [valid-macro?]])


(def silly-macro-spec (list symbol? number? number?))


(valid-macro? `(silly-macro + 1 2) silly-macro-spec) ;; => true

(valid-macro? is a placeholder: I've not written enough macros to know if it's of any use.)

The Guide presents a card game to demonstrate spec.alpha.

(def suit? #{:club :diamond :heart :spade})
(def rank? (into #{:jack :queen :king :ace} (range 2 11)))
(def deck (for [suit suit? rank rank?] [rank suit]))


(s/def :game/card (s/tuple rank? suit?))
(s/def :game/hand (s/* :game/card))
(s/def :game/name string?)
(s/def :game/score int?)
(s/def :game/player (s/keys :req [:game/name :game/score :game/hand]))


(s/def :game/players (s/* :game/player))
(s/def :game/deck (s/* :game/card))
(s/def :game/game (s/keys :req [:game/players :game/deck]))


(def kenny {:game/name "Kenny Rogers", :game/score 100, :game/hand []})


(s/valid? :game/player kenny) ;; => true


(s/explain-data :game/game
                {:game/deck deck,
                 :game/players
                   [{:game/name "Kenny Rogers",
                     :game/score 100,
                     :game/hand [[2 :banana]]}]})
;; => #:clojure.spec.alpha{:problems
;;                           ({:in [:game/players 0 :game/hand 0
;;                                  1],
;;                             :path [:game/players :game/hand 1],
;;                             :pred diff/suit?,
;;                             :val :banana,
;;                             :via [:game/game :game/players
;;                                   :game/players :game/player
;;                                   :game/player :game/hand
;;                                   :game/hand :game/card
;;                                   :game/card]}),
;;                         :spec :game/game,
;;                         :value
;;                           #:game{:deck ([7 :spade]
;;                                         [:king :spade]
;;                                         [4 :spade]
;;                                         [:queen :spade]
;;                                         [:ace :spade]
;;                                         [6 :spade]
;;                                         [3 :spade]
;;                                         [2 :spade]
;;                                         [:jack :spade]
;;                                         [9 :spade]
;;                                         [5 :spade]
;;                                         [10 :spade]
;;                                         [8 :spade]
;;                                         [7 :heart]
;;                                         [:king :heart]
;;                                         [4 :heart]
;;                                         [:queen :heart]
;;                                         [:ace :heart]
;;                                         [6 :heart]
;;                                         [3 :heart]
;;                                         [2 :heart]
;;                                         [:jack :heart]
;;                                         [9 :heart]
;;                                         [5 :heart]
;;                                         [10 :heart]
;;                                         [8 :heart]
;;                                         [7 :diamond]
;;                                         [:king :diamond]
;;                                         [4 :diamond]
;;                                         [:queen :diamond]
;;                                         [:ace :diamond]
;;                                         [6 :diamond]
;;                                         [3 :diamond]
;;                                         [2 :diamond]
;;                                         [:jack :diamond]
;;                                         [9 :diamond]
;;                                         [5 :diamond]
;;                                         [10 :diamond]
;;                                         [8 :diamond]
;;                                         [7 :club]
;;                                         [:king :club]
;;                                         [4 :club]
;;                                         [:queen :club]
;;                                         [:ace :club]
;;                                         [6 :club]
;;                                         [3 :club]
;;                                         [2 :club]
;;                                         [:jack :club]
;;                                         [9 :club]
;;                                         [5 :club]
;;                                         [10 :club]
;;                                         [8 :club]),
;;                                  :players
;;                                    [#:game{:hand [[2 :banana]],
;;                                            :name
;;                                              "Kenny Rogers",
;;                                            :score 100}]}}

Let's follow along, methodically building up the equivalent Speculoos specification.

(def suits #{:club :diamond :heart :spade})
(def ranks (into #{:jack :queen :king :ace} (range 2 11)))
(def deck (vec (for [s suits r ranks] [r s])))
(def card-spec [ranks suits])
(def deck-spec (repeat card-spec))


(valid-scalars? deck deck-spec) ;; => true


(def player-spec {:name string?, :score int?, :hand (repeat card-spec)})


(def kenny {:name "Kenny Rogers", :score 100, :hand []})


(valid-scalars? kenny player-spec) ;; => true


(defn draw-hand [] (vec (take 5 (repeatedly #(first (shuffle deck))))))


(def players-spec (repeat player-spec))
(def players
  [kenny {:name "Humphrey Bogart", :score 188, :hand (draw-hand)}
   {:name "Julius Caesar", :score 77, :hand (draw-hand)}])


(validate-scalars (:hand (players 1)) (repeat card-spec)) ;; => lengthy output...


(valid-scalars? (:hand (players 1)) (repeat card-spec)) ;; => true


(valid-scalars? players players-spec) ;; => true


(def game [deck players])
(def game-spec [deck-spec players-spec])


(valid-scalars? game game-spec) ;; => true

What happens when we have bad data?

(def corrupted-game (assoc-in game [1 0 :hand 0] [2 :banana]))


(only-invalid (validate-scalars corrupted-game
                                game-spec))
;; => ({:datum :banana,
;;      :path [1 0 :hand 0 1],
;;      :predicate #{:club :diamond :heart :spade},
;;      :valid? nil})

Speculoos reports an invalid datum :banana according to predicate suits located at path [1 0 :hand 0 1], which we can inspect with get-in* and similar functions.

The spec Guide emphasizes that one of spec.alpha's explicit design goals is to facilitate property-based testing. spec.alpha does this by closely cooperating with test.check, which generates sample data that conforms to the spec. Next, we'll see a few examples of these capabilities by generating sample data from the card game specs.

(gen/sample (s/gen #{:club :diamond :heart :spade}))
;; => (:spade :spade
;;            :diamond :club
;;            :spade :spade
;;            :club :diamond
;;            :diamond :heart)


(gen/sample (s/gen (s/cat :k keyword?
                          :ns (s/+ number?))))
;; => ((:!/- -1.0)
;;      (:+/? 3.0 2.0)
;;      (:e/E 1.0 0)
;;      (:l_/-B 0)
;;      (:K/N2O 0 -1.0 0 1.625)
;;      (:mA/P -2.875 0 0)
;;      (:.Ud/y!6 0 0.75 -1)
;;      (:.*b!/X -29 -3.25 1)
;;      (:-dw-/n.* 41 -1
;;                 -1.30078125 -1
;;                 -3.125 -64)
;;      (:_/M._ 230 -0.359375
;;              -41 -7.5
;;              1 -0.7890625))


(gen/generate (s/gen :game/player))
;; => #:game{:hand ([6 :club]
;;                  [7 :diamond]
;;                  [7 :heart]
;;                  [8 :club]
;;                  [:king :diamond]
;;                  [8 :club]
;;                  [10 :heart]
;;                  [9 :spade]
;;                  [7 :club]
;;                  [9 :diamond]
;;                  [2 :club]
;;                  [2 :spade]
;;                  [7 :diamond]
;;                  [4 :heart]),
;;           :name "UbKwHJO6ufTUjCS6Pqw",
;;           :score -23}

Speculoos provides a rudimentary version that mimics this functionality. Because game-spec is composed of infinitely-repeating sequences, let's create a simplified version that terminates, using the basic test.check generators. Speculoos cannot in all instances automatically pull apart a compound predicate such as #(and (int? %) (< % 10)) in order to compose a generator.

(require '[speculoos.utility :refer [data-from-spec]])


(data-from-spec game-spec :random)
;; => [[[:queen :diamond] [:ace :diamond]
;;      [3 :diamond] [7 :diamond] [6 :spade]]
;;     [{:hand [[5 :diamond] [:queen :diamond]
;;              [:king :club] [10 :diamond]
;;              [10 :heart]],
;;       :name "YS3",
;;       :score -667}
;;      {:hand [[9 :diamond] [4 :spade]
;;              [3 :club] [3 :club]
;;              [:queen :spade]],
;;       :name "4t0p5R1d560zQH",
;;       :score 519}
;;      {:hand [[:jack :spade] [8 :spade]
;;              [3 :club] [:queen :spade]
;;              [:queen :diamond]],
;;       :name "OwXjzPGupS8PqjpY3T79ZPAUNkm",
;;       :score 619}
;;      {:hand [[10 :club] [3 :spade]
;;              [:ace :diamond] [:king :heart]
;;              [3 :diamond]],
;;       :name
;;         "9iJX1eDRlerTGk05l0FK7I1OqM8g00",
;;       :score 673}
;;      {:hand [[:queen :diamond]
;;              [10 :diamond] [:jack :spade]
;;              [2 :spade] [3 :club]],
;;       :name "GDT5c07U60KH7I4IKYCXpe",
;;       :score -151}]]

Automatically setting up generators and property-based testing is the main area where Speculoos lags spec.alpha. I do not yet have a great idea on how to automatically pull apart compound, composed predicates. See the docs, api and a later subsection to see how to manually or semi-automatically add generators into the predicate metadata.

Let's follow along as best as we can…

(data-from-spec [int?] :random) ;; => [758]
(data-from-spec [nil?]) ;; => [nil]


(repeatedly 5 #(data-from-spec [string?] :random))
;; => (["48SWGAHN8827SIWmC4Hx152l"]
;;     ["dRkFt4M89xlBpf9pGzxc7DUf55bc"]
;;     ["3UWO8JP0eSPy9sUrc45k"]
;;     ["505F5tDRS5bE62"]
;;     ["5SmO"])


(repeatedly 3 #(data-from-spec (into [keyword?] (repeat 3 double?)) :random))
;; => ([:P+C -486.0 -2.0 -0.00733668653992936]
;;     [:g?53??U. -0.7576036155223846
;;      -0.12298446893692017
;;      254.53848838806152]
;;     [:V 290.875 -0.007080078125
;;      0.010367144364863634])


(data-from-spec player-spec :random)
;; => {:hand [[7 :diamond] [2 :heart]
;;            [2 :club] [:queen :spade]
;;            [4 :heart]],
;;     :name "341yPJxS446DmS12xWx7z240Sfu6",
;;     :score 400}

The card game specifications refer to earlier sections.

spec.alpha's data-generating capabilities allows us to exercise a function by invoking it with generated arguments.

(s/exercise (s/cat :k keyword?
                   :ns (s/+ number?))
            5)
;; => ([(:O/s -1) {:k :O/s, :ns [-1]}]
;;     [(:I2/g ##-Inf)
;;      {:k :I2/g, :ns [##-Inf]}]
;;     [(:V5/sG -2.5 -1.0)
;;      {:k :V5/sG, :ns [-2.5 -1.0]}]
;;     [(:v9/zn 0 -1 -1 0.5625)
;;      {:k :v9/zn, :ns [0 -1 -1 0.5625]}]
;;     [(:s/*L 0.53125 0 0.5 1)
;;      {:k :s/*L, :ns [0.53125 0 0.5 1]}])


(s/exercise (s/or :k keyword?
                  :s string?
                  :n number?)
            5)
;; => (["" [:s ""]]
;;     [0 [:n 0]]
;;     ["w7" [:s "w7"]]
;;     [:B0/A [:k :B0/A]]
;;     ["jD" [:s "jD"]])


(s/exercise-fn `ranged-rand)
;; => ([(-1 0) -1]
;;     [(-1 0) -1]
;;     [(2 7) 5]
;;     [(-1 0) -1]
;;     [(0 2) 1]
;;     [(-2 4) -1]
;;     [(1 3) 1]
;;     [(-47 14) -31]
;;     [(11 105) 34]
;;     [(-3 25) 17])

Speculoos mimics the exercise function, but (for now) only exercises a scalar specification.

(require '[speculoos.utility :refer [exercise]])


(exercise [int? string? boolean? char?] 5)
;; => ([[-8 "2lTn" true \S] true]
;;     [[-888 "rD" true \Q] true]
;;     [[323 "sTV857947e1liAcl3B" true \H] true]
;;     [[640 "1LR4" false \y] true]
;;     [[198 "ZKnir5uOrtA7ZZogQ78ueMo0h" true \0] true])

Speculoos also mimics spec.alpha's exercise-fn, again only for scalar specifications, on the function's arguments.

(require '[speculoos.function-specs :refer [exercise-fn]])


(inject-specs! ranged-rand {:speculoos/arg-scalar-spec [int? int?]}) ;; => nil


(exercise-fn ranged-rand 5)
;; => ([[999 -368] -330]
;;     [[704 900] 809]
;;     [[-58 -566] -312]
;;     [[756 718] 735]
;;     [[-447 -540] -536])

In certain cases, a spec will require the data to fall within a very small range of possible values, such as an even positive integer, divisible by three, less than 31, greater than 12. The generators are not likely to be able to produce multiple conforming samples using only (s/gen int?), so we construct predicates with spec.alpha's and.

(gen/generate (s/gen (s/and int? even?))) ;; => -264926


(defn divisible-by [n] #(zero? (mod % n)))


(gen/sample (s/gen (s/and int?
                          #(> % 0)
                          (divisible-by 3))))
;; => (3 27 27 222 195 63 3 84 21 234)

Right now, Speculoos cannot automatically dive into a compound predicate such as #(and (int? %) (even? %)) to create a competent generator, but it does offer a few options. First, we could manually compose a random sample generator and attach it the predicate's metadata. We may use whatever generator we prefer; test.check.generators work well.

(require '[speculoos.utility :refer [defpred validate-predicate->generator]]
         '[clojure.test.check.generators :as tc-gen])


(defn gen-int-pos-div-by-3
  []
  (last (tc-gen/sample (tc-gen/fmap #(* % 3) tc-gen/nat) 50)))


(def pred-1
  (with-meta #(and (int? %) (> % 0) ((divisible-by 3) %))
    {:speculoos/predicate->generator gen-int-pos-div-by-3}))

The defpred utility macro does the equivalent when we explicitly supply a sample generator.

(defpred pred-2
         #(and (int? %) (> % 0) ((divisible-by 3) %))
         gen-int-pos-div-by-3)


;; verify that the samples produced by generator satisfy the predicate

(validate-predicate->generator pred-1 5)
;; => ([21 true]
;;     [72 true]
;;     [54 true]
;;     [117 true]
;;     [15 true])


(validate-predicate->generator pred-2 5)
;; => ([72 true]
;;     [51 true]
;;     [90 true]
;;     [84 true]
;;     [84 true])

However, if we write our predicate in a way that conforms to defpred's assumptions, it will compose a generator automatically.

(defpred pred-3 #(and (int? %) (pos? %) ((divisible-by 3) %)))


(validate-predicate->generator pred-3 5)
;; => ([30 true]
;;     [33 true]
;;     [12 true]
;;     [21 true]
;;     [27 true])

This is another area where spec.alpha's approach outclasses Speculoos. Because we write a spec.alpha spec in an already 'pulled-apart' state, it can compose a generator starting with the first branch of that compound predicate and then use the following predicates as filters to refine the generated values.

Speculoos consumes predicates as already-defined functions, and it appears fiendishly involved to inspect the internal structure of a function — whose source may not be available — in order to generically extract individual components to an arbitrary nesting depth.

Three questions:

1. Is this why spec.alpha specs are written that way?
2. Would it be possible at all to decompose a predicate function object without access to the source?
3. If Speculoos never offers fully-automatic sample generation from a given compound predicate, is that deal-breaker for the entire approach?

spec.alpha acknowledges that we may want to generate values by some other means, and thus allows custom generators via with-gen.

(s/def :ex/kws
  (s/with-gen (s/and keyword? #(= (namespace %) "my.domain"))
              #(s/gen #{:my.domain/name :my.domain/occupation :my.domain/id})))


(s/valid? :ex/kws :my.domain/name) ;; => true


(gen/sample (s/gen :ex/kws))
;; => (:my.domain/occupation
;;      :my.domain/id
;;      :my.domain/occupation
;;        :my.domain/occupation
;;      :my.domain/name :my.domain/occupation
;;      :my.domain/id :my.domain/name
;;      :my.domain/name :my.domain/occupation)

Speculoos considers a free-floating set to be a membership predicate. Speculoos generates sample values by randomly selecting from such a set. We can compose an equivalent set to generate qualified keywords.

(def kw-pred
  (into #{} (map #(keyword "my.domain" %) ["name" "occupation" "id"])))


(valid-scalars? [:my.domain/name] [kw-pred]) ;; => true


(exercise [kw-pred] 5)
;; => ([[:my.domain/name] true]
;;     [[:my.domain/occupation] true]
;;     [[:my.domain/id] true]
;;     [[:my.domain/occupation] true]
;;     [[:my.domain/occupation] true])

spec.alpha provides combinators for creating more complicated generators.

(def kw-gen-3
  (gen/fmap #(keyword "my.domain" %)
            (gen/such-that #(not= % "") (gen/string-alphanumeric))))


(gen/sample kw-gen-3 5)
;; => (:my.domain/k
;;     :my.domain/xfm
;;     :my.domain/ey
;;     :my.domain/UkH
;;     :my.domain/UY6)

Speculoos merely relies on clojure.core and test.check.generators for that task.

(def kw-pred-2
  (into #{}
        (map #(keyword "my.domain" %)
          (gen/sample (gen/such-that #(not= % "") (gen/string-alphanumeric))))))


(exercise [kw-pred-2] 5)
;; => ([[:my.domain/9r6] true]
;;     [[:my.domain/djkv9] true]
;;     [[:my.domain/L1i] true]
;;     [[:my.domain/K] true]
;;     [[:my.domain/f] true])

spec.alpha making a hello-string generator.

(s/def :ex/hello
  (s/with-gen #(clojure.string/includes? % "hello")
              #(gen/fmap (fn [[s1 s2]] (str s1 "hello" s2))
                         (gen/tuple (gen/string-alphanumeric)
                                    (gen/string-alphanumeric)))))


(gen/sample (s/gen :ex/hello))
;; => ("hello"
;;     "hello"
;;     "2hello"
;;     "hello7B9"
;;     "hello3i81"
;;     "4a13hello88amc"
;;     "cNhello7G503"
;;     "2U90hello87wy"
;;     "68CZhello5fF8"
;;     "Wu30S5FQPhelloG8")

We could certainly copy-paste that generator and use it as is. Speculoos could also generate a sample string via a regular expression predicate.

(exercise [#"\w{0,3}hello\w{1,5}"])
;; => ([["XHUhello7BFty"] true]
;;     [["Pv3hellox2"] true]
;;     [["khelloG"] true]
;;     [["helloi"] true]
;;     [["pxQhellomwM"] true]
;;     [["ghelloOTu"] true]
;;     [["GhellowS"] true]
;;     [["2helloXc"] true]
;;     [["tThellofzWz"] true]
;;     [["FmchelloaMpl"] true])

Spec-ing and generating a range of integers in spec.alpha.

(s/def :bowling/roll (s/int-in 0 11))


(gen/sample (s/gen :bowling/roll)) ;; => (0 0 2 1 1 2 1 0 0 8)

Similar thing in Speculoos.

(defpred bowling-roll
         #(and (int? %) (<= 0 % 10))
         #(last (gen/sample (gen/large-integer* {:min 0, :max 10}))))


(validate-predicate->generator bowling-roll)
;; => ([1 true]
;;     [5 true]
;;     [1 true]
;;     [7 true]
;;     [5 true]
;;     [8 true]
;;     [1 true])

But for integers, nothing beats the succinctness of rand-int.

(defpred bowling-roll-2 #(and (int? %) (<= 0 % 10)) #(rand-int 11))


(validate-predicate->generator bowling-roll-2)
;; => ([3 true]
;;     [10 true]
;;     [2 true]
;;     [6 true]
;;     [5 true]
;;     [3 true]
;;     [5 true])

For small group sizes, a set-as-predicate might feel more natural.

(exercise [(set (range 11))])
;; => ([[1] true]
;;     [[9] true]
;;     [[0] true]
;;     [[10] true]
;;     [[9] true]
;;     [[5] true]
;;     [[7] true]
;;     [[0] true]
;;     [[10] true]
;;     [[2] true])

spec.alpha does a range of instants.

(s/def :ex/the-aughts (s/inst-in #inst "2000" #inst "2010"))


(drop 50 (gen/sample (s/gen :ex/the-aughts) 55))
;; => (#inst "2000-01-01T00:00:03.377-00:00"
;;     #inst "2000-01-03T09:42:38.095-00:00"
;;     #inst "2006-11-17T23:44:05.345-00:00"
;;     #inst "2006-11-21T22:42:01.154-00:00"
;;     #inst "2000-01-01T00:00:00.002-00:00")

Well, hello. test.check does not provide an instance generator for Speculoos to borrow. Lemme reach over into the left-hand column and steal spec.alpha's.

(defpred the-aughts
         #(instance? java.util.Date %)
         #(last (gen/sample (s/gen :ex/the-aughts) 55)))


(validate-predicate->generator the-aughts 5)
;; => ([#inst "2005-04-18T18:05:10.418-00:00"
;;      true]
;;     [#inst "2007-09-05T20:34:20.031-00:00"
;;      true]
;;     [#inst "2000-01-01T00:00:00.356-00:00"
;;      true]
;;     [#inst "2000-03-02T08:38:12.187-00:00"
;;      true]
;;     [#inst "2000-01-02T01:07:45.912-00:00"
;;      true])

Finally, The spec Guide illustrates generating doubles with specific conditions.

(s/def :ex/dubs
  (s/double-in :min -100.0 :max 100.0 :NaN? false :infinite? false))


(s/valid? :ex/dubs 2.9) ;; => true


(s/valid? :ex/dubs Double/POSITIVE_INFINITY) ;; => false


(gen/sample (s/gen :ex/dubs))
;; => (0.5
;;     -0.5
;;     1.0
;;     -1.0
;;     1.5
;;     -1.0
;;     0.6875
;;     -0.94921875
;;     -5.8125
;;     -1.15625)

Speculoos leans on test.check.generators for that flexibility.

(defpred dubs
         #(and (<= -100 % 100) (not (NaN? %)) (not (infinite? %)))
         #(gen/generate
            (gen/double* {:min -100, :max 100, :infinite? false, "NaN?" true})))


(validate-predicate->generator dubs 10)
;; => ([0.34694984555244446 true]
;;     [-0.49853515625 true]
;;     [0.0711669921875 true]
;;     [-3.0 true]
;;     [-3.0 true]
;;     [0.0076084136962890625 true]
;;     [-20.032506823539734 true]
;;     [-5.111328125 true]
;;     [0.013205077673774213 true]
;;     [61.0 true])