volley.engine — com.kirahowe/volley 0.1.0-alpha.2

The parent's event loop as a pure state machine.

(step state input) returns {:state state' :effects [...]}. Inputs are the flat events the pool puts on the queue (worker events, :output, :worker/exit) and timer ticks {:event :tick :at ms}, which may carry :width, the terminal's current width, for the live view. Effects are data for volley.main to carry out:

{:effect :spawn :worker id}              ; :in-process? true: on a thread of the parent
{:effect :send :worker id :msg m}
{:effect :stop :worker id}               ; ask a worker to shut down
{:effect :kill :worker id}               ; it did not exit in time
{:effect :print :lines [str] :stream :out|:err}
{:effect :print-data :value v :pretty? bool}   ; EDN on stdout
{:effect :redraw :frame {:emit [str] :frame [str]}}
{:effect :save-timings :timings {ns millis}}
{:effect :save-history :run {:in-process? b :wall-ms ms}}
{:effect :write-file :path str :text str}   ; the junit-xml report
{:effect :post-summary :hooks [entry] :result kaocha-result}
{:effect :exit :code n}

step composes volley.schedule (who runs what), volley.run-state (what happened) and volley.render (what to show). It never touches processes or the terminal.

preflight makes the decisions that come before the loop: help, version, config and CLI errors, printing the config or plan, and "no tests found", each with Kaocha's exit code.

done? clj

(done? state)

True once the loop has produced its :exit effect.

exit-codes clj

Kaocha's early-exit codes, as the process sees them.

init clj

(init plan {:keys [durations started-at] :as opts})

Initial loop state.

• plan from volley.select/plan
• opts {:workers n :fail-fast? b :isolate? b :preload? b :capture-output? b :reporter :live|:ci|:documentation|:result :width n :color? b :durations {ns ms} :started-at ms :first-worker-id n}

:first-worker-id (default 1) is where this run's worker ids start. :watchdog-ms (default 10000) is how long a busy worker may stay silent after a protocol line that could not be read before it is killed. :stop-grace-ms (default 1000) is how long a worker fail-fast interrupted may take to exit after it is asked to stop before it is killed. :configure is a {:op :configure} message sent to each worker right after it is spawned (volley.hooks/configure-message). :post-summary is {:hooks [entry] :config normalized-config}: the hooks to run in the parent after the summary. :junit-xml is the config's :junit-xml plus :timestamp and :cwd: the report is written after the summary. :bindings ({var-sym value}, Kaocha's :kaocha/bindings) goes to the workers with every run message, and so does :seed, the run seed of a randomized run, which the summary of a failed run prints. :config is the normalized config, for the Kaocha-shaped result --print-result prints. :compact-summary? (watch mode) ends the run with the counts line alone: no slowest tests, and no rerun command, which f does there. :in-process? (volley.runtime/worker-plan) runs the first worker on a thread of the parent: its spawn effect says so, and the run starts no other worker until it has gone on for :scale-out-ms with at least as much work still waiting, by :durations (a namespace without a timing counts as that much), when it may start worker processes up to :workers. :record-history? ends a run that ran every planned namespace with a :save-history effect, its mode and wall time for the next plan. Events from any worker this run did not spawn are dropped.

Returns {:state s :effects [...]}: the first spawns, and the load errors of unreadable test files, which are printed in CI mode at the end.

next-worker-id clj

(next-worker-id state)

The first worker id a later run should use, so ids stay unique across runs.

preflight clj

(preflight {:keys [cli config read-error plugin-error config-missing?
                   config-file plan help version]})

Decide what happens before any worker starts. Takes {:cli parsed-args :config normalized :read-error str-or-nil :plugin-error {:error kw :message str}-or-nil :config-missing? bool :config-file path :plan plan-or-nil :help str :version str} (the plan may be absent when it is not needed yet).

Returns {:effects [...]}; when the effects end with an :exit the run is over, otherwise the caller goes on to init. Follows the order of kaocha.runner: config errors (Kaocha validates while loading, before it looks at the flags), then CLI errors, help, version, print-config, print-test-plan, unknown suites, and finally the kaocha.api/run check for an empty plan.

start clj

(start state)

The first step: spawn workers, or finish at once for an empty plan.

step clj

(step state {:keys [event at] :as input})

Fold one input into the loop state. Returns {:state :effects}. Once an :exit effect has been returned the state is :done and further inputs are ignored, as are events from workers this run did not spawn.