Liking cljdoc? Tell your friends :D

fulcro-spec

End Of Maintenance Notice

Fulcro Spec was created at a time when other alternatives with similar support did not exist for Clojurescript. Those days have reached an end and the Fulcro team would rather devote our limited resources to maintaining a smaller core set of libraries. As a result Fulcro Spec will no longer be maintained. If a maintainer would like to step forward, we would gladly consider redirecting people to a fork of this library.

There are a few useful macros in this library that do not yet have great cljc equivalents: particularly the when-mocking and assertions. These will either be pulled into the main Fulcro library, or released as a small stand-alone library.

1. Recommended Alternatives

For CLJS, we highly recommend using Wilker Lucio’s new workspaces library. Not only does it do a great job at giving you a cljs test UI, it is also has some improvements over devcards.

As for CLJ testing: the IDE support for running Clojure tests in Emacs and Cursive is already quite good against clojure.test. You should learn how to use those tools instead of this library. Use the testing macro there as a replacement for behavior (behavior is really just an alias for that, with nesting).

2. Porting away from Fulcro Spec

The specification macro is really just deftest. If you’re porting to workspaces, then just use ws/deftest and change your string to a symbol (hyphenate your test name?). behavior/component can be testing. We’ll release the assertions/when-mocking to a smaller library soon, so you should not need to port away from those (leave fulcro-spec in your deps until that happens).

Workspaces ws/deftest works in CLJC, so you can still do single tests for shared target code.

2.1. Porting and CI

Since all of the tests are just deftest (and always have been), the story for CI should be no different than it was.

3. Super Quick Start

Use the fulcro lein template to get a project with CLJ tests, CLJS tests, and CI testing already configured and set to go with:

lein new fulcro my-project

The resulting project’s README has instructions for running the parts.

4. Usage

  • Make sure your clojure(script) versions are at or above "1.9.x".

  • Add [fulcrologic/fulcro-spec "x.y.z"] to your :dependencies.

  • Make sure you have at least one test file, eg: test/your-ns/arithmetic_spec.cljc, that uses fulcro-spec.core:

(ns your-ns.arithmetic-spec
  (:require
    [fulcro-spec.core :refer [specification behavior component assertions]]))

(specification "arithmetic"
  (component "addition"
    (behavior "is commutative"
      (assertions
        (+ 13 42) => (+ 42 13)))))

4.1. Clojure In The Terminal

  • Add [com.jakemccrary/lein-test-refresh "x.y.z"] to your :plugins.

  • Add the following to your project.clj configuration:

    :test-refresh {:report fulcro-spec.reporters.terminal/fulcro-report}

Other configuration options are available, take a look at:

  • Run lein test-refresh in your command-line, et voila! You should see something like:

Using reporter: fulcro-spec.reporters.terminal/fulcro-report
*********************************************
*************** Running tests ***************
:reloading (your-ns.arithmetic-spec)
Running tests for: (your-ns.arithmetic-spec)

Testing your-ns.arithmetic-spec
   addition
     is commutative

Ran 1 tests containing 1 assertions.
0 failures, 0 errors.

Failed 0 of 1 assertions
Finished at 17:32:43.925 (run time: 0.01s)
Make sure you make the test fail to check that error reporting is working before moving on to another section. 
Error refreshing environment: java.io.FileNotFoundException: Could not locate clojure/spec__init.class or clojure/spec.clj on classpath.

Make sure you have clojure(script) versions above "1.9.x".

Error refreshing environment: java.lang.IllegalAccessError: clj does not exist, compiling:(fulcro_spec/watch.clj:1:1)

Add an :exclusions [org.clojure/tools.namespace] for tools.namespace on lein-test-refresh
(and any other projects that use it, which you can check using lein deps :tree or boot -pd),
as fulcro-spec requires "0.3.x" for clojurescript support, but lein-test-refresh doesn’t need that itself.

4.2. Clojure In The Browser

  • Create a dev/clj/user.clj file that contains:

(ns clj.user
  (:require
    [fulcro-spec.selectors :as sel]
    [fulcro-spec.suite :as suite])

(suite/def-test-suite my-test-suite
  {:config {:port 8888} (2)
   :test-paths ["test"]
   :source-paths ["src"]}
  {:available #{:focused :unit :integration}
   :default #{::sel/none :focused :unit}})

(my-test-suite) (1)
1Starts the test suite, note that it will stop any pre-existing test suite first, so it’s safe to call this whenever (eg: hot code reload).
2You can now goto localhost:8888/fulcro-spec-server-tests.html

  • Make sure the "dev" folder is in your :source-paths, if you are using lein that’s probably just a :profiles {:dev {:source-paths ["dev"]}}.

  • Add clj.user to your :repl-options {:init-ns clj.user}, which again if using lein probably goes in your :profiles {:dev #_…​}

4.3. CLJS In The Browser

  • Add [figwheel-sidecar "x.y.z"] to your dev time dependencies (latest releases).

    • Add [com.cemerick/piggieback "x.y.z"] to your dev time dependencies (latest version).

    • Add :nrepl-middleware [cemerick.piggieback/wrap-cljs-repl] to your :repl-options.

  • Add [org.clojure/clojurescript "x.y.z"] as a normal dependencies (latest releases).

  • Add to your /dev/clj/user.clj:

(:require
  [com.stuartsierra.component :as cp]
  [figwheel-sidecar.system :as fsys]
  #_...)

(defn start-figwheel [build-ids]
  (-> (fsys/fetch-config)
    (assoc-in [:data :build-ids] build-ids)
    fsys/figwheel-system cp/start fsys/cljs-repl))

  • Create a /dev/cljs/user.cljs

(ns cljs.user
  (:require
    your-ns.arithmetic-spec (1)
    [fulcro-spec.selectors :as sel]
    [fulcro-spec.suite :as suite]))

(suite/def-test-suite on-load {:ns-regex #"your-ns\..*-spec"} (2)
  {:default #{::sel/none :focused}
   :available #{:focused :should-fail}})
1Ensures your tests are loaded so the test suite can find them
2Regex for finding just your tests from all the loaded namespaces.

  • (Optional) Create an HTML file for loading your tests in your resources/public folder. If you’re using the standard figwheel config, then you can also choose to load one that is provided in the JAR of Fulcro Spec.

<!DOCTYPE html>
<html>
    <head>
        <link href="css/fulcro-spec-styles.css" rel="stylesheet" type="text/css">
        <link href="css/fulcro-ui.css" rel="stylesheet" type="text/css">
        <link id="favicon" rel="shortcut icon" type="image/png" href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAIElEQVQ4T2NMS0v7z0ABYBw1gGE0DBhGwwCYh4ZBOgAAcQUjIUXh8RYAAAAASUVORK5CYII="/>
        <meta content="text/html;charset=utf-8" http-equiv="Content-Type">
    </head>
    <body>
        <div id="fulcro-spec-report">Loading "js/test/test.js", if you need to name that something else (conflicts?) make your own test html file</div>
        <script src="js/test/test.js" type="text/javascript"></script>
    </body>
</html>

The HTML above is exactly the content of the built-in file fulcro-spec-client-tests.html.

:cljsbuild {:builds [

{:id "test"
 :source-paths ["src" "dev" "test"]
 :figwheel     {:on-jsload cljs.user/on-load}
 :compiler     {:main          cljs.user
                :output-to     "resources/public/js/test/test.js"
                :output-dir    "resources/public/js/test/out"
                :asset-path    "js/test/out"
                :optimizations :none}}

]}
lein repl
#_=> (start-figwheel ["test"])
java.lang.RuntimeException: No such var: om/dispatch, compiling:(fulcro/client/mutations.cljc:8:1)

Means you have a conflicting org.omcljs/om versions, either resolve them by looking at lein deps :tree or bood -pd, or pin your version to the latest version or whatever version fulcro-spec is using.

  • Run the tests by loading your HTML file (or the one provided in the Fulcro Spec JAR). The default figwheel port is 3449, so the URL that should always work by default if you’ve named your javascript output js/test/test.js would be: http://localhost:3449/fulcro-spec-client-tests.html

5. Focusing in on Tests

Fulcro Spec allows you to tag specifications with arbitrary keywords that you define, and allows you to specify which of those are in your "default" set. This can allow you to separate integration tests, or simply focus in on the test you’re working on.

(specification "My Test" :focused
   ...)

The selectors configuration shown earlier (:default and :available) are where you define which ones you start out with. The special keyword ::sel/none is for tests that have no tag. The browser-based UI will let you choose the selectors to run from the pull out menu in the upper-left corner.

5.1. For CI

  • Add lein-doo as both a test dependency and a plugin

    :dependencies [#_... [lein-doo "0.1.6" :scope "test"] #_...]
:plugins [#_... [lein-doo "0.1.6"] #_...]

  • Add a :doo section to your project.clj

    :doo {:build "automated-tests"
      :paths {:karma "node_modules/karma/bin/karma"}}

  • Add a top level package.json containing at least:

    {
  "devDependencies": {
    "karma": "^2.0.0",
    "karma-chrome-launcher": "^2.2.0",
    "karma-firefox-launcher": "^1.1.0",
    "karma-cljs-test": "^0.1.0"
  }
}

  • Add a :cljsbuild for your CI tests, eg:

:cljsbuild {:builds [

{:id "automated-tests"
 :source-paths ["src" "test"]
 :compiler     {:output-to     "resources/private/js/unit-tests.js"
                :output-dir    "resources/private/js/unit-tests"
                :asset-path    "js/unit-tests"
                :main          fulcro-spec.all-tests
                :optimizations :none}}

]}

  • Add a file that runs your tests

(ns your-ns.all-tests
  (:require
    your-ns.arithmetic-spec ;; ensures tests are loaded so doo can find them
    [doo.runner :refer-macros [doo-all-tests]]))

(doo-all-tests #"fulcro-spec\..*-spec")

  • Run npm install & then lein doo chrome automated-tests once,

If you put the automated-tests build in a lein profile (eg: test),
you will have to prepend a with-profile test …​ in your command.

  • See doo itself for further details & as a fallback if this information is somehow out of date.

6. Learn More

7. Development

This section is for the development of fulcro-spec itself.
If you wanted instructions on how to use fulcro-spec in your app/library, see Usage

7.1. CLJS In The Browser

lein repl
#_user=> (start-figwheel ["test"])

& http://localhost:3457/fulcro-spec-client-tests.html

7.2. Clojure In The Terminal

lein test-refresh

7.3. Clojure In The Browser

lein repl
#_user=> (start)

& http://localhost:8778/fulcro-spec-server-tests.html

7.4. CI Testing

To run the CLJ and CLJS tests on a CI server, it must have chrome, node, and npm installed.
Then you can simply use the Makefile:

make tests

or manually run:

npm install
lein test-cljs
lein test-clj

8. License

MIT License Copyright © 2015 NAVIS

Can you improve this documentation?Edit on GitHub

cljdoc is a website building & hosting documentation for Clojure/Script libraries

Keyboard shortcutsReport a problemcljdoc on GitHub
× close