Establishing fact wide prerequisites

It's often the case that you have prerequisites that you want to apply to many predictions. As a simple example, consider this:

(fact
  (function-under-test 1 1) => 3
  (provided
    (x-handler 1) => 1                ;; same topic
    (y-handler 1) => 2)               ;; duplicate

  (function-under-test 8 1) => 1
  (provided
    (x-handler 8) => -1               ;; same topic
    (y-handler 1) => 2))              ;; duplicate

Look first at the lines marked "duplicate". They're identical. As such, they distract from what's special about each prediction. So let's "extract" them so that they apply to all predictions in the fact:

(fact
  (prerequisite (y-handler 1) => 2)     ;; <<== new

  (function-under-test 1 1) => 3
  (provided
    (x-handler 1) => 1)
    
  (function-under-test 8 1) => 1
  (provided
    (x-handler 8) => -1))

That helps make it clear that all the predictions in this fact depend on a particular property of y-handler.

There's something more that can be done. This fact is about how function-under-test depends on both x-handler and y-handler. As such, it might be helpful to group the x-handler's different prerequisites together so that, when we code it, its properties (and their regularities) are presented to us as a checklist we have to implement. That could look like this:

(fact
  (prerequisites (y-handler 1) => 2
                 (x-handler 1) => 1     ;; <<== new
                 (x-handler 8) => -1)   ;; <<== new

  (function-under-test 1 1) => 3
  (function-under-test 8 1) => 1)

(Note that you can use either prerequisite or prerequisites. We at MidjeCo are very respectful of grammatical number.

Fact-wide prerequisites do not have to be used

When you create a prerequisite with provided, you predict it will be called at least once. If not, Midje will signal a failure. Prerequisites created with prerequisites do not need to be called. As a motivating example, consider a flight checklist. The plane can take off only if all of the pilot, copilot, and engines are ready:

(fact
  (prerequisites (pilot-ready? ..flight..) => true
                 (copilot-ready? ..flight..) => true
                 (engines-ready? ..flight..) => true)
  
  (flight-ready? ..flight..) => truthy
  (flight-ready? ..flight..) => falsey (provided (pilot-ready? ..flight..) => falsey)
  (flight-ready? ..flight..) => falsey (provided (copilot-ready? ..flight..) => falsey)
  (flight-ready? ..flight..) => falsey (provided (engines-ready? ..flight..) => falsey))

Whether flight-ready? is implemented with and or every-pred, it will stop checking for false values after it finds the first one. One of the three "ready?" prerequisites has to be evaluated first. In the prediction where that one is false, the remaining two default prerequisites will be ignored. It would be annoying if they complained they hadn't been called.

Nesting and ordering

Prerequisites apply to any facts included in the fact where they're defined.

(fact "prerequisites can be nested"
  (prerequisite (x-handler 1) => 8000)
  (fact 
    (prerequisite (y-handler 1) => 80)
    (function-under-test 1 1) => 8080)

  (fact
    (prerequisite (y-handler 1) => -8000)
    (function-under-test 1 1) => 0))

When there are matches for a prerequisite at different nesting levels, the innermost takes precedence. provided prerequisites override any from a prerequisites form.

(fact "prerequisites can be nested"
  (prerequisites (x-handler 1) => 10
                 (y-handler 1) => 8)
  (fact 
    (prerequisite (y-handler 1) => 33)

    (function-under-test 1 1) => (+ 10 33)

    (function-under-test 1 1) => (+ 10 99)
    (provided
      (y-handler 1) => 99)))

When more than one prerequisite at the same nesting level match, it's the latest one that's chosen. That allows for "catch all" or default prerequisites:

(fact "catch-all or default prerequisites"
  (prerequisites (x-handler anything) => 1
                 (y-handler anything) => 2
                 (y-handler 3) => 333)
  (function-under-test 1 1) => (+ 1 2)
  (function-under-test 1 3) => (+ 1 333))

Note that the match is not the most specific. If the order of y-handler prerequisites were switched, y-handler would always return 2.

Lexical scoping

prerequisite expressions have access to lexically-scoped symbols:

(let [my-favorite-argument-value 1
      my-favorite-expected-value 32000]
  (fact "lexical scoping is obeyed"
    (prerequisites (x-handler my-favorite-argument-value) => my-favorite-expected-value
                   (y-handler my-favorite-argument-value) => my-favorite-expected-value)

    (function-under-test my-favorite-argument-value my-favorite-argument-value)
    => (* 2 my-favorite-expected-value)))

There may conceivably be a use for that.