Provides support for running Jepsen tests in Antithesis. Provides an RNG, lifecycle hooks, and assertions.
You should wrap your entire program in (with-rng ...). This does nothing in
ordinary environments, but in Antithesis, it replaces the jepsen.random RNG
with one powered by Antithesis.
Call setup-complete! once the test is ready to begin--for instance, at the
end of Client/setup. Call event! to signal interesting things have
happened.
Assertions begin with assert-, and take an expression, a message, and data
to include if the assertion fails. For instance:
(assert-always! (not (db-corrupted?)) "DB corrupted" {:db "foo"})
Wrap your test map in (a/test test-map). This wraps both the client and
checkers with Antithesis instrumentation. You can also do this selectively
using checker and client.
Provides support for running Jepsen tests in Antithesis. Provides an RNG,
lifecycle hooks, and assertions.
## Randomness
You should wrap your entire program in `(with-rng ...)`. This does nothing in
ordinary environments, but in Antithesis, it replaces the jepsen.random RNG
with one powered by Antithesis.
## Lifecycle
Call `setup-complete!` once the test is ready to begin--for instance, at the
end of Client/setup. Call `event!` to signal interesting things have
happened.
## Assertions
Assertions begin with `assert-`, and take an expression, a message, and data
to include if the assertion fails. For instance:
(assert-always! (not (db-corrupted?)) "DB corrupted" {:db "foo"})
## Wrappers
Wrap your test map in `(a/test test-map)`. This wraps both the client and
checkers with Antithesis instrumentation. You can also do this selectively
using `checker` and `client`.(antithesis?)Are we running in an Antithesis environment?
Are we running in an Antithesis environment?
(assert-always expr message data)Asserts that expr is true every time, and that it's called at least once. Takes a map of data which is serialized to JSON.
Asserts that expr is true every time, and that it's called at least once. Takes a map of data which is serialized to JSON.
(assert-always-or-unreachable expr message data)Asserts that expr is true every time. Passes even if the assertion never triggers.
Asserts that expr is true every time. Passes even if the assertion never triggers.
(assert-reachable message data)Asserts that this line of code is reached at least once.
Asserts that this line of code is reached at least once.
(assert-sometimes expr message data)Asserts that expr is true at least once, and that this assertion is reached.
Asserts that expr is true at least once, and that this assertion is reached.
(assert-unreachable message data)Asserts that this line of code is never reached.
Asserts that this line of code is never reached.
This protocol marks checker types which perform their own Antithesis
assertions. The checker+ wrapper skips over any checkers which satisfy this
protocol, as well as their children.
This protocol marks checker types which perform their own Antithesis assertions. The `checker+` wrapper skips over any checkers which satisfy this protocol, as well as their children.
(checker checker-)(checker name checker)Wraps a Jepsen Checker in one which asserts the results of the underlying checker are always valid. Takes a string name, which defaults to "checker"; this is used for the Antithesis assertion.
Wraps a Jepsen Checker in one which asserts the results of the underlying checker are always valid. Takes a string name, which defaults to "checker"; this is used for the Antithesis assertion.
(checker+ c)(checker+ path c)Rewrites a Jepsen Checker, wrapping every Checker in its own Antithesis Checker, which asserts validity of that specific checker. Each checker gets a name derived from the path into that data structure it took to get there.
Ignores any object which satisfies the Checker protocol. You can use this to flag checkers you don't want to add assertions for, or which implement their own assertions.
Rewrites a Jepsen Checker, wrapping every Checker in its own Antithesis Checker, which asserts validity of that specific checker. Each checker gets a name derived from the path into that data structure it took to get there. Ignores any object which satisfies the Checker protocol. You can use this to flag checkers you don't want to add assertions for, or which implement their own assertions.
When selecting long values, we consider something an Antithesis "choice" if it asks for at most this many elements.
When selecting long values, we consider something an Antithesis "choice" if it asks for at most this many elements.
(client client)Wraps a Jepsen Client in one which performs some simple Antithesis
instrumentation. Calls setup-complete! after the client's setup is done,
and issues a pair of assertions for every operation--once on invocation, and
once on completion.
Wraps a Jepsen Client in one which performs some simple Antithesis instrumentation. Calls `setup-complete!` after the client's setup is done, and issues a pair of assertions for every operation--once on invocation, and once on completion.
(dir)The Antithesis SDK directory, if present, or nil.
The Antithesis SDK directory, if present, or nil.
(early-termination-generator {:keys [interval probability]} gen)Wraps a Jepsen generator in one which, every so often, asks Jepsen's random source whether it ought to terminate. This allows Antithesis to perform a sort of weak 'online checking', as opposed to always running for the full (e.g.) time limit. Options are a map of:
:interval How many operations to emit before flipping a coin :probability The probability of early termination at each interval. This is only useful for extremely low/high probabilities; everything in the moderate range (see choice-cardinality) winds up being a coin toss.
Wraps a Jepsen generator in one which, every so often, asks Jepsen's random source whether it ought to terminate. This allows Antithesis to perform a sort of weak 'online checking', as opposed to always running for the full (e.g.) time limit. Options are a map of: :interval How many operations to emit before flipping a coin :probability The probability of early termination at each interval. This is only useful for extremely low/high probabilities; everything in the moderate range (see choice-cardinality) winds up being a coin toss.
(event! name)(event! name details)Logs that we've reached a specific event. Takes a string name and an optional JSON-coerceable details map.
Logs that we've reached a specific event. Takes a string name and an optional JSON-coerceable details map.
(log-file)The Antithesis log file we write JSON to, or nil.
The Antithesis log file we write JSON to, or nil.
(replacement-bool)(replacement-bool p)Antithesis replacement for jepsen.random/bool. Uses Antithesis choices
when probabilities are closer to chance than choice-cardinality.
Antithesis replacement for `jepsen.random/bool`. Uses Antithesis choices when probabilities are closer to chance than choice-cardinality.
(replacement-double-weighted-index weights)(replacement-double-weighted-index total-weight weights)Antithesis replacement for jepsen.random/double-weighted-index. Takes a double array, and picks a random index into it.
Antithesis replacement for jepsen.random/double-weighted-index. Takes a double array, and picks a random index into it.
(replacement-long)(replacement-long upper)(replacement-long lower upper)Antithesis replacement for jepsen.random/long. Mostly equivalent to the
original, but when there are less than choice-cardinality options, hints to
Antithesis that we're making a specific choice.
Antithesis replacement for `jepsen.random/long`. Mostly equivalent to the original, but when there are less than `choice-cardinality` options, hints to Antithesis that we're making a specific choice.
(setup-complete!)(setup-complete! details)Logs that we've started up. Only emits once per JVM run. Optionally takes a JSON-coerceable structure with details.
Logs that we've started up. Only emits once per JVM run. Optionally takes a JSON-coerceable structure with details.
(test test)Prepares a Jepsen test for running in Antithesis. When running inside Antithesis, this:
You likely also want to wrap the client in client, parts of the checker in
checker, and possibly the generator in early-termination-generator.
Prepares a Jepsen test for running in Antithesis. When running inside Antithesis, this: 1. Replaces the OS with a no-op 2. Repaces the DB with a no-op 3. Replaces the SSH system with a stub. You likely also want to wrap the client in `client`, parts of the checker in `checker`, and possibly the generator in `early-termination-generator`.
(->json-node x)Coerces x to a Jackson JsonNode.
Coerces x to a Jackson JsonNode.
(with-rng & body)When running in an Antithesis environment, replaces Jepsen's random source with an Antithesis-controlled source. You should wrap your top-level program in this.
When running in an Antithesis environment, replaces Jepsen's random source with an Antithesis-controlled source. You should wrap your top-level program in this.
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 |