Encode and decode the messages between the parent and its workers.
Parent to worker: one EDN map per line (encode-command).
Worker to parent: one prefixed EDN map per line (frame-event), the
prefix carrying a nonce the parent gave the worker (prefix-for). Any
other text is stray output.
Pure: printing is bounded by structurally truncating values before they
reach the printer. The printer itself obeys the caller's print vars, so
the shell encodes inside safe-print-bindings.
Encode and decode the messages between the parent and its workers. Parent to worker: one EDN map per line (`encode-command`). Worker to parent: one prefixed EDN map per line (`frame-event`), the prefix carrying a nonce the parent gave the worker (`prefix-for`). Any other text is stray output. Pure: printing is bounded by structurally truncating values before they reach the printer. The printer itself obeys the caller's print vars, so the shell encodes inside `safe-print-bindings`.
(->event message {:keys [worker at stream]})Turn a decoded message into the flat event the parent's loop consumes.
ctx is {:worker id :at millis :stream :stdout|:stderr}.
Events keep their keys and gain :worker and :at. Stray output becomes
{:event :output :text str :stream kw ...} (plus :protocol-error).
Turn a decoded message into the flat event the parent's loop consumes.
`ctx` is `{:worker id :at millis :stream :stdout|:stderr}`.
Events keep their keys and gain `:worker` and `:at`. Stray output becomes
`{:event :output :text str :stream kw ...}` (plus `:protocol-error`).(bound-value v opts)Bounded copy of v: collections keep at most :print-length items and
:print-level levels, with a ... symbol marking each cut. Lazy and
infinite seqs are only realized that far. Returns [bounded exact?].
Bounded copy of `v`: collections keep at most `:print-length` items and `:print-level` levels, with a `...` symbol marking each cut. Lazy and infinite seqs are only realized that far. Returns `[bounded exact?]`.
(check-result? v)True when v looks like the result map of clojure.test.check/quick-check
for a failed property, which is what a failing defspec reports as its
:actual.
True when `v` looks like the result map of `clojure.test.check/quick-check` for a failed property, which is what a failing `defspec` reports as its `:actual`.
(decode-command line)One stdin line -> {:kind :command :command map}, or
{:kind :invalid :text line :error msg}. Never throws.
One stdin line -> `{:kind :command :command map}`, or
`{:kind :invalid :text line :error msg}`. Never throws.(decode-line line)(decode-line prefix line)One line of worker output -> a vector of messages, in order.
{:kind :event :event map} for a well-formed protocol event.{:kind :output :text str} for anything else.The prefix (prefix, default event-prefix) may appear anywhere in the
line: what precedes it is output (a partial line a child process wrote
to the inherited pipe), and so is anything after the event's map. An
empty line gives no message, because the worker frames each event with
newlines on both sides.
A line that starts with the prefix but whose payload is not a map with
an :event keyword stays output, with :protocol-error msg added, so
nothing the worker printed is lost and the parent can flag the breakage.
When the prefix is not at the start of the line, the line is not wholly
the worker's and a payload that does not parse is plain output.
Total: never throws, accepts nil.
One line of worker output -> a vector of messages, in order.
* `{:kind :event :event map}` for a well-formed protocol event.
* `{:kind :output :text str}` for anything else.
The prefix (`prefix`, default `event-prefix`) may appear anywhere in the
line: what precedes it is output (a partial line a child process wrote
to the inherited pipe), and so is anything after the event's map. An
empty line gives no message, because the worker frames each event with
newlines on both sides.
A line that starts with the prefix but whose payload is not a map with
an `:event` keyword stays output, with `:protocol-error msg` added, so
nothing the worker printed is lost and the parent can flag the breakage.
When the prefix is not at the start of the line, the line is not wholly
the worker's and a payload that does not parse is plain output.
Total: never throws, accepts nil.Bounds used when none are passed to encode-value.
Bounds used when none are passed to `encode-value`.
Class-name prefixes of stack frames that belong to the runner, not to the code under test.
Class-name prefixes of stack frames that belong to the runner, not to the code under test.
(encode-check v)(encode-check v opts)The parts of a failed quick-check result worth showing:
{:seed n :num-tests n :failing-size n :smallest value :fail value :result value}, values encoded as by encode-value. :result is left
out when the property simply returned false. nil when v is not a failed
check result.
The parts of a failed quick-check result worth showing:
`{:seed n :num-tests n :failing-size n :smallest value :fail value
:result value}`, values encoded as by `encode-value`. `:result` is left
out when the property simply returned false. nil when `v` is not a failed
check result.(encode-command command)Parent-to-worker message map -> one line, without the trailing newline.
Parent-to-worker message map -> one line, without the trailing newline.
(encode-error tm)(encode-error tm opts)Throwable->map-style data -> {:class :message :data :trace :cause}.
The :via chain becomes nested :causes, outermost first. Throwable->map
carries one stack trace (the root cause's), so it lands on the innermost
error; outer errors get an empty trace. :data is the bounded pr-str of
ex-data, or nil. Runner frames are removed from the trace.
`Throwable->map`-style data -> `{:class :message :data :trace :cause}`.
The `:via` chain becomes nested `:cause`s, outermost first. `Throwable->map`
carries one stack trace (the root cause's), so it lands on the innermost
error; outer errors get an empty trace. `:data` is the bounded `pr-str` of
`ex-data`, or nil. Runner frames are removed from the trace.(encode-event event)(encode-event prefix event)Event map -> one protocol line (prefix included, no trailing newline).
The result never contains a raw newline because pr-str escapes them.
prefix defaults to event-prefix.
Event map -> one protocol line (prefix included, no trailing newline). The result never contains a raw newline because `pr-str` escapes them. `prefix` defaults to `event-prefix`.
(encode-value v)(encode-value v opts)Wire form of a test value: {:str (pr-str value)}, plus :edn value
only when the value survives an EDN round trip untruncated.
opts may carry :print-length, :print-level and :max-chars
(defaults 100, 8 and 10000). Text longer than :max-chars is cut, and
then has no :edn.
Records, regexes, NaN, functions and anything else EDN cannot read back
get :str only. Never throws: a value whose printing throws is reported as
an unprintable placeholder.
Wire form of a test value: `{:str (pr-str value)}`, plus `:edn value`
only when the value survives an EDN round trip untruncated.
`opts` may carry `:print-length`, `:print-level` and `:max-chars`
(defaults 100, 8 and 10000). Text longer than `:max-chars` is cut, and
then has no `:edn`.
Records, regexes, NaN, functions and anything else EDN cannot read back
get `:str` only. Never throws: a value whose printing throws is reported as
an unprintable placeholder.Marks a worker stdout line as a protocol event when the worker was started without a nonce.
Marks a worker stdout line as a protocol event when the worker was started without a nonce.
(frame-event prefix event)What the worker writes for one event: the protocol line between two newlines. The leading newline ends any partial line a child process wrote to the inherited pipe, so it cannot glue onto the event.
What the worker writes for one event: the protocol line between two newlines. The leading newline ends any partial line a child process wrote to the inherited pipe, so it cannot glue onto the event.
(interpreter-trace frames dir)(interpreter-trace frames dir max-frames)Babashka's call stack for an error (sci.core/stacktrace: maps with
:ns :name :file :line, innermost first) as trace lines like
my.app/parse (src/my/app.clj:12). Built-in frames and frames of the
runner (volley, clojure.test, the interpreter) are dropped, as is the
unnamed frame of a call into a built-in, which precedes its fn's. The
interpreter lists each user fn twice, the call site in its body and then
its definition; only the first of consecutive frames of the same fn is
kept. Files under dir are made relative to it. At most max-frames
(default 50).
Babashka's call stack for an error (`sci.core/stacktrace`: maps with `:ns :name :file :line`, innermost first) as trace lines like `my.app/parse (src/my/app.clj:12)`. Built-in frames and frames of the runner (volley, clojure.test, the interpreter) are dropped, as is the unnamed frame of a call into a built-in, which precedes its fn's. The interpreter lists each user fn twice, the call site in its body and then its definition; only the first of consecutive frames of the same fn is kept. Files under `dir` are made relative to it. At most `max-frames` (default 50).
(message t)t's message. An exception built from a cause alone (a future's
ExecutionException, say) takes the cause's toString as its message;
when that cause is an interpreter wrapper, the message would hold the
wrapper's data, call stack included, so it is rebuilt from the
unwrapped cause.
`t`'s message. An exception built from a cause alone (a future's ExecutionException, say) takes the cause's `toString` as its message; when that cause is an interpreter wrapper, the message would hold the wrapper's data, call stack included, so it is rebuilt from the unwrapped cause.
(prefix-for nonce)The protocol prefix of a worker started with nonce (a string the
parent made up for it), or event-prefix when nonce is nil. Children
a test starts inherit the protocol pipe; the nonce keeps what they print
from ever reading as an event, whatever it says.
The protocol prefix of a worker started with `nonce` (a string the parent made up for it), or `event-prefix` when `nonce` is nil. Children a test starts inherit the protocol pipe; the nonce keeps what they print from ever reading as an event, whatever it says.
Print vars and the values the protocol needs, for the shell to bind
around encoding (with-bindings). Messages are printed with pr-str,
and tests often bind or set! these vars: a *print-length* would cut
a message short and *print-dup*, *print-meta*, *print-readably* or
*print-namespace-maps* would print forms the reader on the other side
treats differently.
Print vars and the values the protocol needs, for the shell to bind around encoding (`with-bindings`). Messages are printed with `pr-str`, and tests often bind or `set!` these vars: a `*print-length*` would cut a message short and `*print-dup*`, `*print-meta*`, `*print-readably*` or `*print-namespace-maps*` would print forms the reader on the other side treats differently.
(sci-wrapper? t)True for the ExceptionInfo babashka's interpreter wraps around an
exception that passes an interpreted try, to carry its call stack
(:sci.impl/callstack in its data). The original is its cause.
True for the ExceptionInfo babashka's interpreter wraps around an exception that passes an interpreted `try`, to carry its call stack (`:sci.impl/callstack` in its data). The original is its cause.
(trim-trace trace
{:keys [runner-prefixes max-frames]
:or {runner-prefixes default-runner-prefixes max-frames 50}})Cut a Throwable->map-style frame vector at the first runner frame (the
test machinery that called the user's code, and everything below it) and
render the frames above it as strings. At most :max-frames (default 50)
are kept.
Cut a `Throwable->map`-style frame vector at the first runner frame (the test machinery that called the user's code, and everything below it) and render the frames above it as strings. At most `:max-frames` (default 50) are kept.
(unwrap t)t without the interpreter's wrappers around it: the first exception
in its cause chain that is not one.
`t` without the interpreter's wrappers around it: the first exception in its cause chain that is not one.
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 |