Worker process: reads assignments on stdin, runs test namespaces with clojure.test, writes protocol events on the original stdout.
Portable Clojure. It runs on babashka and on the JVM, so it uses no babashka.* namespaces.
The protocol channel is the process's original stdout. At startup -main
points System/out and the root *out* at stderr, so anything a test
prints, even through (.println System/out ...), arrives as stray output
and can never interleave with a protocol line.
Worker process: reads assignments on stdin, runs test namespaces with clojure.test, writes protocol events on the original stdout. Portable Clojure. It runs on babashka and on the JVM, so it uses no babashka.* namespaces. The protocol channel is the process's original stdout. At startup `-main` points `System/out` and the root `*out*` at stderr, so anything a test prints, even through `(.println System/out ...)`, arrives as stray output and can never interleave with a protocol line.
(-main & [nonce])Worker entry point. Protocol events go to the original stdout; everything
else a test prints goes to stderr. The one argument, when given, is the
nonce of the protocol prefix (volley.protocol/prefix-for).
Worker entry point. Protocol events go to the original stdout; everything else a test prints goes to stderr. The one argument, when given, is the nonce of the protocol prefix (`volley.protocol/prefix-for`).
(assertion-event ns-sym v contexts m)Event for a failing or erroring clojure.test report map m, raised
inside var v (nil outside any var) with contexts outermost first.
Kaocha's zero-assertions report is a failure with its message and no
expected or actual value.
Event for a failing or erroring clojure.test report map `m`, raised inside var `v` (nil outside any var) with `contexts` outermost first. Kaocha's zero-assertions report is a failure with its message and no expected or actual value.
(configure command)Hook state for a {:op :configure} message: volley.shell.hooks/init,
with that namespace's functions under ::hooks in place of
without-hooks. A state made by volley.shell.hooks/init alone lacks
them, so the worker would run it without hooks.
Hook state for a `{:op :configure}` message: `volley.shell.hooks/init`,
with that namespace's functions under `::hooks` in place of
`without-hooks`. A state made by `volley.shell.hooks/init` alone lacks
them, so the worker would run it without hooks.(duration-ms start-ns end-ns)Milliseconds between two System/nanoTime readings.
Milliseconds between two `System/nanoTime` readings.
(encode-throwable e)Wire form of a Throwable a test raised. On babashka the JVM stack trace
is nothing but interpreter frames, so the trace comes from the
interpreter's own call stack (sci.core/stacktrace), which names the
user's functions with file and line: e's, or else that of the first
wrapper in its cause chain that names one of them. The interpreter's wrappers are left out of
the cause chain wherever they are. The JVM keeps its stack trace.
Wire form of a Throwable a test raised. On babashka the JVM stack trace is nothing but interpreter frames, so the trace comes from the interpreter's own call stack (`sci.core/stacktrace`), which names the user's functions with file and line: `e`'s, or else that of the first wrapper in its cause chain that names one of them. The interpreter's wrappers are left out of the cause chain wherever they are. The JVM keeps its stack trace.
(make-emit out prefix)Emit function writing whole protocol lines with prefix to out,
atomically, each framed by newlines (volley.protocol/frame-event).
Emit function writing whole protocol lines with `prefix` to `out`, atomically, each framed by newlines (`volley.protocol/frame-event`).
(partition-vars decide select ns-sym ns-meta vars)Ask decide (the 5-arity of volley.filters/decide) about each var, with
the namespace's metadata ns-meta. Returns {:run [var ...] :skipped [[var reason] ...]}, both in input order.
Ask `decide` (the 5-arity of `volley.filters/decide`) about each var, with
the namespace's metadata `ns-meta`. Returns `{:run [var ...] :skipped
[[var reason] ...]}`, both in input order.(project-file? dir bb? rf)True when report file rf can be shown as the place of a failure: a
file under directory dir (relative to it or absolute), or, on the JVM
(bb? false), a bare file name from a stack frame of compiled code. On
babashka a bare name or a path outside the project comes from the
interpreter (a file such as reflector.cljc that a stack-walking
assertion like test.check's picked up), not from the user's code.
True when report file `rf` can be shown as the place of a failure: a file under directory `dir` (relative to it or absolute), or, on the JVM (`bb?` false), a bare file name from a stack frame of compiled code. On babashka a bare name or a path outside the project comes from the interpreter (a file such as `reflector.cljc` that a stack-walking assertion like test.check's picked up), not from the user's code.
(project-path dir file)file as the project sees it, relative to directory dir: babashka's
var metadata already holds test/p/a_test.clj; the JVM's holds the
classpath-relative p/a_test.clj, which is looked up on the classpath.
Anything else comes back as it was.
`file` as the project sees it, relative to directory `dir`: babashka's var metadata already holds `test/p/a_test.clj`; the JVM's holds the classpath-relative `p/a_test.clj`, which is looked up on the classpath. Anything else comes back as it was.
(relative-path dir file)file relative to directory dir when it lies inside it, else as is.
`file` relative to directory `dir` when it lies inside it, else as is.
(run-assignment! emit! decide cmd)(run-assignment! emit! decide hs {:keys [ns run-id] :as cmd})Run one {:op :run} message. emit! receives each event map. decide is
(fn [select ns-sym ns-meta var-sym var-meta] {:run? bool :reason kw}),
normally volley.filters/decide; it gets the namespace's real metadata.
hs is the worker's hook state ({}, or what configure made); the 3-arity
runs without hooks. Returns the next hook state.
Emits :ns/start, then :ns/error if setup, loading or a fixture
fails, the :var/* and :assertion events, and always a final
:ns/end. With :fail-fast? the vars after the first failing one are
not run and get no events. Does not exit the JVM and does not throw.
Run one `{:op :run}` message. `emit!` receives each event map. `decide` is
`(fn [select ns-sym ns-meta var-sym var-meta] {:run? bool :reason kw})`,
normally `volley.filters/decide`; it gets the namespace's real metadata.
`hs` is the worker's hook state (`{}`, or what `configure` made); the 3-arity
runs without hooks. Returns the next hook state.
Emits `:ns/start`, then `:ns/error` if setup, loading or a fixture
fails, the `:var/*` and `:assertion` events, and always a final
`:ns/end`. With `:fail-fast?` the vars after the first failing one are
not run and get no events. Does not exit the JVM and does not throw.(run-everything _select _ns-sym _ns-meta _var-sym _var-meta)A decide that selects every var, for running a namespace whole.
A `decide` that selects every var, for running a namespace whole.
(safely f)Call f with the print vars bound to volley.protocol/safe-print-bindings.
Events are printed inside the user's dynamic scope (a report from an is,
a fixture that bound *print-length*, a namespace that set! it at load
time), so without this a protocol line could come out truncated or in a
form EDN cannot read.
Call `f` with the print vars bound to `volley.protocol/safe-print-bindings`. Events are printed inside the user's dynamic scope (a report from an `is`, a fixture that bound `*print-length*`, a namespace that `set!` it at load time), so without this a protocol line could come out truncated or in a form EDN cannot read.
(serve emit! decide next-line)(serve emit! decide next-line flush!)(serve emit! decide next-line flush! stop-requested?)Handle the parent's commands, a line from (next-line) at a time, until
{:op :shutdown} or the end of input (nil), calling (flush!) (by
default flush) after each. A running namespace starts no further var
once (stop-requested?) (by default never) holds. Returns the final
hook state. Tests get an empty *in*, so a test that reads it cannot
block on or swallow a command.
Handle the parent's commands, a line from `(next-line)` at a time, until
`{:op :shutdown}` or the end of input (nil), calling `(flush!)` (by
default `flush`) after each. A running namespace starts no further var
once `(stop-requested?)` (by default never) holds. Returns the final
hook state. Tests get an empty `*in*`, so a test that reads it cannot
block on or swallow a command.(serve! emit! read-line stray)(serve! emit! read-line stray killed?)The worker's command loop: send :worker/ready, then serve the lines
(read-line) returns, read on a thread of their own so that a
:shutdown stops a running namespace, until it returns nil or a
:shutdown arrives; then run the shutdown hooks. emit! sends an event
(make-emit); stray is the writer for what tests print outside a
capture, flushed after each command. Returns the exit code: 1 when a
shutdown hook threw, else 0. -main serves the process's stdin;
volley.shell.in-process serves a queue inside the parent, so the
stop flag belongs to this call alone: a :shutdown to one loop never
stops another in the same process. A worker inside the parent cannot be
killed as a process can, so it passes killed?: once that holds, the
loop starts no further var, as after a :shutdown, and runs no
shutdown hook, and the call returns 1.
The worker's command loop: send `:worker/ready`, then `serve` the lines `(read-line)` returns, read on a thread of their own so that a `:shutdown` stops a running namespace, until it returns nil or a `:shutdown` arrives; then run the shutdown hooks. `emit!` sends an event (`make-emit`); `stray` is the writer for what tests print outside a capture, flushed after each command. Returns the exit code: 1 when a shutdown hook threw, else 0. `-main` serves the process's stdin; `volley.shell.in-process` serves a queue inside the parent, so the stop flag belongs to this call alone: a `:shutdown` to one loop never stops another in the same process. A worker inside the parent cannot be killed as a process can, so it passes `killed?`: once that holds, the loop starts no further var, as after a `:shutdown`, and runs no shutdown hook, and the call returns 1.
Held while a var takes System/out and System/err or puts them back,
and by volley.shell.in-process while a kill gives the parent its own
streams back, so the kill cannot land between the var's check and what
it does to the streams.
Held while a var takes `System/out` and `System/err` or puts them back, and by `volley.shell.in-process` while a kill gives the parent its own streams back, so the kill cannot land between the var's check and what it does to the streams.
(test-vars-of ns-obj)(test-vars-of ns-obj seed)Interned vars of ns-obj that carry :test, ordered by name like
Kaocha's kaocha.type.ns/load, or with a run seed in the random order
volley.order picks for the namespace.
Interned vars of `ns-obj` that carry `:test`, ordered by name like Kaocha's `kaocha.type.ns/load`, or with a run `seed` in the random order `volley.order` picks for the namespace.
What Kaocha reports for a test var that made no assertion
(kaocha.type.var, report type :kaocha.type.var/zero-assertions).
What Kaocha reports for a test var that made no assertion (`kaocha.type.var`, report type `:kaocha.type.var/zero-assertions`).
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |