Core snapshot testing API for Still.
Provides two main functions:
Core snapshot testing API for Still. Provides two main functions: - snap: Filesystem-based snapshot testing with dual behaviour (test vs REPL) - snap!: Inline snapshot testing with automatic source code editing
(in-repl?)Check if we're currently in an interactive REPL session.
Returns true if running in any REPL (nREPL, socket REPL, clojure.main), but false inside a test context.
REPL detection works by checking if repl is bound, which is true for all standard Clojure REPLs but false when running as a compiled JAR or in test runners.
Check if we're currently in an interactive REPL session. Returns true if running in any REPL (nREPL, socket REPL, clojure.main), but false inside a test context. REPL detection works by checking if *repl* is bound, which is true for all standard Clojure REPLs but false when running as a compiled JAR or in test runners.
(in-test-context?)Check if we're currently inside a deftest context.
Returns true if called within a clojure.test/deftest block, false otherwise.
Check if we're currently inside a deftest context. Returns true if called within a clojure.test/deftest block, false otherwise.
(snap snapshot-key value)Filesystem-based snapshot testing.
Compares a value against a stored snapshot. Behaviour adapts based on context:
Inside deftest (test context):
Outside deftest (REPL context):
Outside deftest and REPL (assertion context):
Arguments:
Enable/Disable:
Configuration:
Examples: ;; In a test (deftest user-creation-test (let [user (create-user {:name "Alice"})] (snap :user-creation user)))
;; In the REPL (snap :api-response (fetch-data)) ;; => ✓ Snapshot matches: :api-response ;; => true
;; Disable snapshots (set! assert false)
Filesystem-based snapshot testing.
Compares a value against a stored snapshot. Behaviour adapts based on context:
Inside deftest (test context):
- Uses clojure.test/is for assertions
- Failures appear in test runner output
- Integrates with CI/CD pipelines
Outside deftest (REPL context):
- Returns boolean (true if match, false if mismatch)
- Prints friendly messages to stdout
- No test framework overhead
Outside deftest and REPL (assertion context):
- Throws AssertionError on mismatch
- Returns true on match
- No output unless there's an error
Arguments:
- snapshot-key: Keyword identifying this snapshot (e.g., :user-creation)
- value: The value to snapshot
Enable/Disable:
- Controlled by *assert* outside of deftest contexts
- Inside deftest: Always enabled (ignores *assert* setting)
- Outside deftest: When *assert* is false, snap returns true (pass-through)
Configuration:
- :auto-update? true: Automatically update mismatched snapshots
- :snapshot-dir: Directory for snapshot files (default: test/still)
Examples:
;; In a test
(deftest user-creation-test
(let [user (create-user {:name "Alice"})]
(snap :user-creation user)))
;; In the REPL
(snap :api-response (fetch-data))
;; => ✓ Snapshot matches: :api-response
;; => true
;; Disable snapshots
(set! *assert* false)(snap! value-expr)(snap! value-expr expected)Inline snapshot testing with automatic source editing.
Like snap, but stores the expected value directly in the source code instead of in a separate file. When called without an expected value, automatically edits the source file to add the value.
Arguments:
Behaviour:
Enable/Disable:
Examples: ;; First run: source file will be edited (snap! (compute-result)) ;; After edit, the line becomes: (snap! (compute-result) {:result 42})
;; Future runs: compares against inline value (snap! (compute-result) {:result 42})
;; Disable at compile time (set! assert false)
Note: This feature requires write access to source files and only works on JVM. It uses rewrite-clj to preserve formatting and comments.
Inline snapshot testing with automatic source editing.
Like snap, but stores the expected value directly in the source code instead
of in a separate file. When called without an expected value, automatically
edits the source file to add the value.
Arguments:
- value-expr: The expression to snapshot
- expected (optional): The expected value (typically added by snap! itself)
Behaviour:
- If expected is provided: compares value against expected
- If expected is not provided: edits source file to add value as expected
- In test context: uses clojure.test/is
- In REPL context: returns boolean and prints messages
- Outside test/REPL: throws AssertionError on mismatch
Enable/Disable:
- Controlled by *assert* outside of deftest contexts
- Inside deftest: Always enabled (ignores *assert* setting)
- Outside deftest: When *assert* is false, snap! returns true (pass-through)
Examples:
;; First run: source file will be edited
(snap! (compute-result))
;; After edit, the line becomes:
(snap! (compute-result) {:result 42})
;; Future runs: compares against inline value
(snap! (compute-result) {:result 42})
;; Disable at compile time
(set! *assert* false)
Note: This feature requires write access to source files and only works on JVM.
It uses rewrite-clj to preserve formatting and comments.Inline snapshot testing (limited ClojureScript support).
Note: Automatic source editing is not available in ClojureScript. You must manually provide the expected value.
Enable/Disable:
Inline snapshot testing (limited ClojureScript support). Note: Automatic source editing is not available in ClojureScript. You must manually provide the expected value. Enable/Disable: - Controlled by *assert* outside of deftest contexts - Inside deftest: Always enabled (ignores *assert* setting) - Outside deftest: When *assert* is false, snap! returns true (pass-through)
(snap!-impl value expected location)Implementation of snap! comparison logic for JVM.
Implementation of snap! comparison logic for JVM.
(try-get-nrepl-file)Attempt to get the file path from nREPL middleware.
When nREPL 1.5.1+ is used with a client that sends the :file parameter, it may be available in the nREPL message map even if file is nil.
Attempt to get the file path from nREPL middleware. When nREPL 1.5.1+ is used with a client that sends the :file parameter, it may be available in the nREPL message map even if *file* is nil.
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 |