Truss

Truss allows you to attach execution context to exceptions using a dynamic variable *ctx*. Any truss/ex-info thrown while a context is set will automatically include that context in its ex-data. This is useful for including request information (like Ring requests) in production error logs.

Use set-ctx!, with-ctx, or with-ctx+ (which merges into the existing context) to establish this information.

(defn wrap-ring-ctx
  """Wraps given Ring handler so that the Ring req will be
  included in any thrown `truss/ex-info`s."""
  [ring-handler-fn]
  (fn [ring-req]
    (truss/with-ctx+ {:ring-req ring-req} ; Merge into `truss/*ctx*`
      (ring-handler-fn ring-req))))

To use Truss in your Clojure or ClojureScript project, add the dependency to your build configuration. Replace x-y-z with the latest version of com.taoensso/truss.

;; Leiningen
[com.taoensso/truss "x-y-z"]

;; deps.edn
com.taoensso/truss {:mvn/version "x-y-z"}

After adding the dependency, import the taoensso.truss namespace. It is recommended to alias it as truss and explicitly refer to have and have? for common assertion tasks.

(ns my-ns (:require [taoensso.truss :as truss :refer [have have?]]))

To eliminate the runtime overhead of assertions in production, you can disable them by setting *assert* to false before macro expansion. When elided, Truss assertions pass their arguments through with no predicate checks and zero performance cost.

If using Leiningen, add this to your project.clj:

:global-vars {*assert* false}

By default, Truss throws an exception when an assertion fails. You can customize this behavior by adjusting the *failed-assertion-handler* dynamic var. This is useful for:

• Capturing failures during unit testing using dynamic binding.
• Emitting failures as Telemere signals before throwing.

The primary way to use Truss is the have macro. It takes a predicate and an argument. If the predicate returns truthy for the argument, the assertion succeeds and returns the argument. If the predicate returns falsey, a detailed error is thrown.

Use this to formalize assumptions about function arguments, intermediate values, or application state to prevent undocumented type assumptions from causing silent failures.

(defn greet
  "Given a string username, prints a greeting message."
  [username]
  (println "hello" (have string? username)))

Truss includes utilities to make debugging complex Clojure transducers and reducing functions easier:

• catching-xform: A utility for debugging Clojure transducers.
• catching-rf: A utility for debugging regular reducing functions.

Truss provides utilities to simplify exception handling in code that runs on both Clojure (JVM) and ClojureScript.

• catching: A utility that simply swallows exceptions: (catching (my-code)).
• try*: A cross-platform version of core/try that can catch specific Truss exception classes: :ex-info, :common, :all, or :default.
• error?: A cross-platform predicate to check if something is an error.

When writing unit tests, Truss provides utilities to assert that code throws specific errors. These utilities can check for exception types, messages, and ex-data content. If a match fails on a top-level exception, Truss will attempt to match against its nested causes.

Key functions:

• throws?: Checks if an expression throws an error matching specific criteria.
• throws: Asserts that an expression throws.
• matching-error: Provides advanced matching for errors.

;; Check for any error and a specific message
(is (throws? :any "Divide by zero" (/ 1 0))) ; => true

;; Check for specific ex-info data
(is (throws? :ex-info {:user-name :stu, :user-id pos-int?} ...))

If you have critical checks that must never be disabled (e.g., security assertions), use the have! macro. Unlike have, have! ignores the *assert* setting and will never be elided, ensuring the check always runs in production.

(defn get-restricted-resource [ring-session]
  (let [auth (have! string? (:auth-token ring-session))] ; Never elide!
    ;; Do stuff...
    "Return restricted resource content"))