Readme — fulcrologic/fulcro-spec 3.1.13

fulcro-spec

1. CHANGE OF SCOPE NOTICE

BREAKING CHANGES as of 3.1. The =throws⇒ clause now just takes either a type or a regex. Not maps/lists.

BREAKING CHANGES as of 3.0. Do NOT upgrade without being prepared to port your test runners.

This library no longer contains browser-based runners.

I recommend the following alternatives:

Clojure Tests: I recommend IntelliJ/Emacs/Vim in-editor testing, or perhaps Clojure Tools Deps with kaocha. The latter renders into a terminal, but can use fulcro-spec’s macros. Here is a sample config file that will use Fulcro spec’s terminal reporting:

#kaocha/v1
    {:tests    [{:id           :unit
                 :ns-patterns  ["-test$" "-spec$"]
                 :test-paths   ["src/test"]
                 :skip-meta    [:integration]
                 :source-paths ["src/main"]}]
     :reporter [fulcro-spec.reporters.terminal/fulcro-report]
     :plugins  [:kaocha.plugin/randomize
                :kaocha.plugin/filter
                :kaocha.plugin/capture-output]}

Clojurescript Tests: I highly recommend using Nubank’s Workspaces. I’ve contributed a shadow-cljs target that can auto-scan for tests if you use their deftest macro. Again, things like the provided macro work within Workspaces. I recommend using shadow-cljs :karma target for running CI tests.

See the docs for more details.

2. Description

A Clojure(scipt) testing library to augment the standard clojure.test.

Release:

It is common to want to run tests in the REPL, but the output of the default runner leaves a lot to be desired. If you’re using IntelliJ you can now add something like this to your REPL commands (and hook it to a keyboard shortcut) for a much better testing experience:

Run Tests with a :focus metadata marker (selector):

(in-ns (.getName *ns*))
(require 'fulcro-spec.reporters.repl)
(fulcro-spec.reporters.repl/run-tests #(:focus (meta %)))

Run all tests:

(in-ns (.getName *ns*))
(require 'fulcro-spec.reporters.repl)
(fulcro-spec.reporters.repl/run-tests)

Be sure to check "Before Executing" → "Load File" on the REPL command.

4. Usage

(ns my-test
  (:require
    [fulcro-spec.core :refer [specification when-mocking provided assertions]]
    [clojure.test :refer [deftest]]
    ...))

(defn f [x] 900)
(defn g [y] (+ y (f y)))

(deftest my-test
  (when-mocking
    (f x) => 22

    (assertions
      "mocking works"
      (g 9) => 31)))

The specification macro is a convenient alternative to deftest that provides enhanced reporting and metadata support:

;; Basic usage
(specification "My feature works correctly"
  (assertions
    "addition works"
    (+ 1 2) => 3))

;; With selector keywords for test filtering (e.g., :focus)
(specification "Debug this test" :focus
  (assertions
    (+ 1 2) => 3))

;; With custom metadata map for advanced test organization
(specification {:integration true :slow true} "Database integration test"
  (assertions
    (db/query ...) => ...))

;; Combining metadata map with selector keywords
(specification {:integration true} "Critical integration test" :focus
  (assertions
    (critical-operation) => expected-result))

The metadata map (when provided) must appear before the test name string. Selector keywords (like :focus) follow the test name and are automatically converted to metadata. Both metadata sources are merged, allowing test runners to filter tests by any metadata key.

See the full documentation for complete details.

`Ctrl`+`k`	Jump to recent docs
`←`	Move to previous article
`→`	Move to next article
`Ctrl`+`/`	Jump to the search field

fulcro-spec

1. CHANGE OF SCOPE NOTICE

2. Description

3. NEW! REPL Runner

4. Usage