net.lewisship.test-pipeline — io.github.hlship/test-pipeline v0.1

Per-test pipeline of composable steps, including simple mocks and capturing of logging events.

A test is implemented as series of step functions; each step receives a context map, does work, and passes the (sometimes modified) context map to the next step.

The goal is to make tests flatter (fewer nested scopes), more readable, and to make various kinds of steps more composable.

add-halt-check clj

(add-halt-check context check-fn)

Adds a halt check function to the context, for use by continue.

Returns the updated context, which should then be passed to continue.

assoc-in-context clj

(assoc-in-context ks v)

Returns a step function that performs an assoc-in on the context during execution.

calls clj macro

(calls context spy-var)

Returns calls to-date of the given spy, clearing the list of calls as a side effect.

capture-logging clj

(capture-logging context)

A step function that captures logging events from clojure.tools.logging.

Replaces the *logger-factory* with one that enables logging for all loggers and levels, and captures all log events to an atom. These events can be accessed via log-events.

Each captured logging event is a map with the following keys:

• :thread-name - String name of current thread
• :logger - String name of logger, e.g., "com.example.myapp.worker"
• :level - keyword of log level (:debug, :error, etc.)
• :throwable - instance of Throwable, or nil
• :message - String message

Note that only logging events from clojure.tools.logging are captured; logging to other frameworks (such logging from referenced Java libraries) are logged normally and not captured.

continue clj

(continue context)

Called from a step function to pass the context to the next step function in the pipeline. Does nothing if there are no more steps to execute.

continue is responsible for halt checks; each added halt check function is passed the context, and if any of them return a truthy value, the pipeline is halted, as with halt.

execute clj

(execute & step-fns)

The main entrypoint: executes a sequence of step functions as a pipeline.

A step function is responsible for one portion of setting up the test environment, and may perform part of the test execution as well. Generally, the final step function is the most specific to a particular test, and will be where most assertions occur.

A step function is passed a context; the step function's job is to modify the context before passing the context to continue; this call is often wrapped in a try (to clean up resources) and/or with-redefs (to override functions for testing).

Note that nils are allowed as no-op steps to make it easier to conditionally include steps using when. The provided seq of step functions is flattened and nils are removed before constructing the final pipeline.

Each step function must call continue (except the final step function, for which the call to continue is optional and does nothing); however this check is skipped if the execution pipeline is halted.

halt clj

(halt context)

Called instead of continue to immediately halt the execution of the pipeline without executing any further steps. This is used when an error has been detected that will invalidate behavior checks in later steps.

When execution is halted, the check that ensures all steps executed is disabled.

halt-on-failure clj

(halt-on-failure context)

Adds a halt check that terminates the pipeline if any test errors or test failures are subsequently reported.

log-events clj

(log-events context)

Returns all captured logging events, while clearing the list as a side effect.

mock clj macro

(mock mock-var mock-fn)

Expands to a step function that mocks the var with the corresponding function (as with clojure.core/with-redefs).

reporting clj macro

(reporting k)

Expands to a step function based on com.walmartlabs.test-reporting/reporting that extracts a value from the context and reports its value if a test fails.

split clj

(split step-fns)

Splits the execution pipeline. Returns a step function that will sequence through the provided seq of step fns and pass the context to each in turn.

Thus, any steps further down the pipeline will be invoked multiple times.

spy clj macro

(spy spy-var)

(spy spy-var mock-fn)

Expands to a step function that mocks a function with a spy.

The spy records into an atom each set of arguments it is passed, before passing the arguments to the spied function.

Optionally, a mock function (as with mock) can be supplied to replace the spied function.

Usage:

  (spy db/put-row (fn [_ row-data] ...))

The calls macro retrieves the calls made to the spy.

update-in-context clj

(update-in-context ks f & args)

Returns a step function that performs an update-in on the context during execution.