com.fulcrologic.statecharts.testing — com.fulcrologic/statecharts 1.0.0-RC1

Utility functions to help with testing state charts.

Clearable clj/s protocol

clear! clj/s

(clear! this)

Clear the recordings of the given mock

configuration-for-states clj/s

(configuration-for-states {:keys [statechart]} states)

Returns a set of states that should represent a valid configuration of statechart in the testing env AS LONG AS you list a valid set of leaf states. For example, if you have a top-level parallel state, then states MUST contain a valid atomic state for each sub-region.

Another way to express this is that this function returns the union of the set of states and their proper ancestors.

data clj/s

(data {:keys [session-id]
       {:com.fulcrologic.statecharts/keys [data-model working-memory-store]
        :as env}
         :env})

Returns the current data of the active data model. Ensures that working memory data models will function properly.

ExecutionChecks clj/s protocol

ran-in-order? clj/s

(ran-in-order? execution-model frefs)

Returns true if there was an attempt to run every function reference frefs (a vector), in the order listed. Note, this only requires the functions be called in that relative order, and is fine if there are other calls to (other) things in between.

ran? clj/s

(ran? execution-model fref)

Returns true if there was an attempt to run the function with reference fref

goto-configuration! clj/s

(goto-configuration! {:keys [session-id]
                      {:com.fulcrologic.statecharts/keys [data-model
                                                          working-memory-store]
                       :keys [statechart configuration-validator]
                       :as env}
                        :env}
                     data-ops
                     leaf-states)

Runs the given data-ops on the data model, then sets the working memory configuration to a configuration that contains the given leaf-states. This attempts to include parent states, but you can still generate an invalid configuration be listing too few leaves in a parallel system.

NOTE: You can see the full configuration by directly calling configuration-for-states on your own leaf-states.

Previously recorded state history (via history nodes) is UNAFFECTED.

Throws if the configuration validator returns a non-empty problems list.

in? clj/s

(in? {:keys [session-id]
      {:com.fulcrologic.statecharts/keys [working-memory-store] :as env} :env}
     state-name)

Check to see that the machine in the testing-env is in the given state.

MockEventQueue clj/s

MockExecutionModel clj/s

MockInvocations cljs

new-mock-execution clj/s

(new-mock-execution data-model)

(new-mock-execution data-model mocks)

Create a mock exection model. Records the expressions seen. If the expression has an entry in the supplied mocks map, then if it is a fn, it will be called with env which will contain the normal stuff along with :ncalls (how many times that expression has been called). Otherwise the value in the map is returned.

You can use ran?, ran-in-order? and other ExecutionChecks to do verifications.

new-mock-invocations clj/s

(new-mock-invocations)

new-mock-queue clj/s

(new-mock-queue)

Create an event queue that simply records what it sees. Use sent? and cancelled? to check these whenever you want.

new-testing-env clj/s

(new-testing-env
  {:keys [statechart processor-factory data-model-factory validator session-id]
   :or {data-model-factory new-flat-model validator configuration-problems}}
  mocks)

Returns a new testing env that can be used to run events against a state chart or otherwise manipulate it for tests.

mocks is a map from expression value (e.g. fn ref) to either a literal value or a (fn [env]), where env will be the testing env with :ncalls set to the ordinal (from 1) number of times that expression has been run.

validator is a (fn [machine working-memory] vector?) that returns a list of problems with the state machine's configuration (if any). These problems indicate either a bug in the underlying implementation, or with your initial setup of working memory.

The default data model is the flat working memory model, the default processor is the v20150901 version, and the validator checks things according to that same version.

run-events! clj/s

(run-events!
  {:keys [session-id]
   {:com.fulcrologic.statecharts/keys [processor working-memory-store] :as env}
     :env}
  &
  events)

Run the given sequence of events (names or maps) against the testing runtime. Returns the updated working memory (side effects against testing runtime, so you can run this multiple times to progressively walk the machine)

SendChecks clj/s protocol

cancelled? clj/s

(cancelled? _ session-id send-id)

Checks that an attempt was made to cancel the send with the given id.

sent? clj/s

(sent? _ required-elements-of-send-request)

Checks that a send request was submitted that had at LEAST the elements of required-elements-of-send-request in it. If the value of an element in the required elelments is a fn?, then it will be treated as a predicate.

start! clj/s

(start! {:keys [session-id]
         {:com.fulcrologic.statecharts/keys [working-memory-store processor]
          :as env}
           :env})

Start the machine in the testing env.

TestingEnv clj/s

will-send clj/s

(will-send {{:com.fulcrologic.statecharts/keys [event-queue]} :env}
           event
           delay-ms)

Test assertions. Find event-name on the sends seen, and verify it will be sent after the given delay-ms. Also ensures it only occurs ONCE.