RCF turns your Rich Comment Forms into tests (in the same file as your functions). Send form or file to REPL to run tests and it squirts dopamine ✅✅✅. It's good, try it!
Features
- Clojure/Script
- async tests
- zero boilerplate
- natural REPL workflow
- one key-chord to run tests, no hotkey configuring
- same-file tests (examples are better than docstrings)
- no file watchers, no extra windows, no beeping, no latency
- notebook support – example NextJournal notebook
- it's fun! ✅✅✅
RCF is specifically engineered to support Electric Clojure, which we test, document and teach with RCF.
Hype quotes:
- "RCF has changed my habits with regards to tests. It is so much easier than flipping back and forth between files, you get my preferred work habits - work in a comment block until something works. But before RCF I never took the time to turn comment blocks into an automated test"
- "I use RCF to do leetcode style questions as 'fun practice.' It certainly didn't feel fun before!"
- "I think people make the mistake of comparing this with other methods of inlining tests near their function definitions. The integration with the REPL, low syntax/interface, reduces friction and makes testing more attractive as a language of communication and verification."
- "I used RCF in a successful interview. RCF was a massive help in communication and a fast tool for thought whilst under the conditions of technical interview."
Project maturity: CLJ is stable, CLJS is experimental, bb is experimental.
{:deps {com.hyperfiddle/rcf {:mvn/version "20220926-202227"}}}Changelog
- :throws
- babashka support (experimental)
- breaking don't return final result return nil like comment
20220926-202227!is deprecated, usetapinstead20220827-151056async test forms no longer guaranteed return final result20220405maven group-id renamed fromhyperfiddletocom.hyperfiddlefor security- 2021 Dec 18: clojurescript dependency is now under the :cljs alias, see #25
- 2021 Oct 20: custom reporters now dispatch on qualified keywords, see #19
Current dev priority is improving complex async tests in ClojureScript.
(tests) blocks erase by default (macroexpanding to nothing), which avoids a startup time performance penalty as well as keeps tests out of prod.
It's an easy one-liner to turn on tests in your dev entrypoint:
(ns user ; user ns is loaded by REPL startup (:require [hyperfiddle.rcf])) (hyperfiddle.rcf/enable!)
Tests are run when you send a file or form to your Clojure/Script REPL.
(ns example (:require [hyperfiddle.rcf :refer [tests tap %]])) (tests "equality" (inc 1) := 2 "wildcards" {:a :b, :b [2 :b]} := {:a _, _ [2 _]} "unification" {:a :b, :b [2 :b]} := {:a ?b, ?b [2 ?b]} "unification on reference types" (def x (atom nil)) {:a x, :b x} := {:a ?x, :b ?x} "multiple tests on one value" (def xs [:a :b :c]) (count xs) := 3 (last xs) := :c (let [xs (map identity xs)] (last xs) := :c (let [] (last xs) := :c)) "exceptions" (assert false "boom") :throws java.lang.AssertionError (tests "nested tests (is there a strong use case?)" 1 := 1) (tests "REPL bindings work" (keyword "a") := :a (keyword "b") := :b (keyword "c") := :c *1 := :c *2 := :b *3 := :a *1 := :c ; inspecting history does not affect history (keyword "d") := :d *1 := :d *2 := :c *3 := :b (symbol *2) := 'c ; this does affect history (symbol *2) := 'd))
Loading src/example.cljc...
✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅✅Loaded
(ns example (:require [clojure.core.async :refer [chan >! go go-loop <! timeout close!]] [hyperfiddle.electric :as e] [hyperfiddle.rcf :as rcf :refer [tests tap % with]] [missionary.core :as m])) (rcf/set-timeout! 100) (tests "async tests" #?(:clj (tests (future (tap 1) (Thread/sleep 10) ; tap value to queue (tap 2) (Thread/sleep 200) (tap 3)) % := 1 ; pop queue % := 2 % := ::rcf/timeout) :cljs (tests (defn setTimeout [f ms] (js/setTimeout ms f)) (tap 1) (setTimeout 10 (fn [] (tap 2) (setTimeout 200 (fn [] (tap 3))))) % := 1 % := 2 % := ::rcf/timeout))) (tests "electric" (def !x (atom 0)) (def dispose (e/run (let [x (e/watch !x) a (inc x) b (inc x)] (tap (+ a b))))) % := 2 (swap! !x inc) % := 4 (swap! !x inc) % := 6 (dispose)) (tests "core.async" (def c (chan)) (go-loop [x (<! c)] (when x (<! (timeout 10)) (tap x) (recur (<! c)))) (go (>! c :hello) (>! c :world)) % := :hello % := :world (close! c)) (tests "missionary" (def !x (atom 0)) (def dispose ((m/reactor (m/stream! (m/ap (! (inc (m/?< (m/watch !x))))))) (fn [_] #_(prn ::done)) #(prn ::crash %))) % := 1 (swap! !x inc) (swap! !x inc) % := 2 % := 3 (dispose)))
To run in CI, configure a JVM flag for RCF to generate clojure.test deftests, and then run them with clojure.test. Github actions example.
; deps.edn {:aliases {:test {:jvm-opts ["-Dhyperfiddle.rcf.generate-tests=true"]}}}
% clj -M:test -e "(require 'example)(clojure.test/run-tests 'example)"
Testing example
✅✅✅✅✅✅✅✅
Ran 1 tests containing 8 assertions.
0 failures, 0 errors.
{:test 1, :pass 8, :fail 0, :error 0, :type :summary}For CLJS tests to run, rcf/enable! must be true in both CLJ (shadow-cljs macroexpansion time) and CLJS (JS runtime). Reports may be printed to browser console instead of the REPL, because browser REPLs donn't intercept the async println.
(ns dev-entrypoint (:require [example] ; transitive inline tests will erase [hyperfiddle.rcf :refer [tests]])) ; wait to enable tests until after app namespaces are loaded (hyperfiddle.rcf/enable!) ; subsequent REPL interactions will run tests ; prevent test execution during cljs hot code reload #?(:cljs (defn ^:dev/before-load stop [] (hyperfiddle.rcf/enable! false))) #?(:cljs (defn ^:dev/after-load start [] (hyperfiddle.rcf/enable!)))
One of my tests threw an exception, but the stack trace is empty? — you want {:jvm-opts ["-XX:-OmitStackTraceInFastThrow"]} explanation (this may be JVM specific)
I see no output — RCF is off by default, run (hyperfiddle.rcf/enable!)
Emacs has no output and tests are enabled — check if your emacs supports emojis
How do I customize what’s printed at the REPL? — see reporters.clj, reporters.cljs
#hyperfiddle @ clojurians.net
