Chapter 5. Developing with Immutant

Immutant fully embraces the time-honored Lisp tradition of incremental development at a REPL. This effectively puts you inside the application server, with all its integrated services at your fingertips.

It is quite an intimate experience to build your application while it's deployed and running in Immutant, with frictionless access to its services in real-time, running tests against those services immediately, as you edit them. And no mocking, packaging, or deployment steps to interrupt your flow.

At the REPL, you're free to use whichever Clojure testing library you prefer, e.g. clojure.test or Midje. Each has its own way of invoking tests, allowing you to, for example, run one at a time or perhaps run every test in one or more namespaces. These should work fine at the Immutant REPL, and you're free to refer to the integrated Immutant services in your test definitions.

There are some handy reflective functions available in the immutant.util namespace, specifically app-uri, which can be used to construct URL's in the tests for your web apps. This ensures your tests can always "find" your app, regardless of context path or HTTP port, for example.

Immutant provides support for connecting to an application's runtime via nREPL.

Each REPL service runs on a unique port, allowing you to have REPLs into multiple applications within the same Immutant, or multiple REPLs within the same application.

REPL services can be started at application deploy time, or dynamically from application code. REPLs started dynamically can be also be shutdown dynamically. REPLs started at deploy time and any dynamically started REPLs that are not shut down by the application will be shut down when the application is undeployed.

See initialization configuration for a list of configuration options (like :nrepl-port) and how to apply them.

Immutant provides tools to aid interactive REPL-based development via the immutant.dev namespace. Currently, it provides three functions for reloading, updating, and viewing your application's dependencies in container:

• immutant.dev/reload-project! Resets the application's class loader to provide the paths and dependencies in the from the given project. If no project is provided, the project.clj for the appplication is loaded from disk. Also makes any new data readers from the dependencies available. Returns the project map.
• immutant.dev/add-dependencies! Adds the given dependencies into the currently active project's dependency set and resets the application's class loader to provide the paths and dependencies from that project (via reload-project!). Each dep can either be a lein coordinate ('[foo-bar "0.1.0"]) or a path (as a String) to be added to :source-paths. Returns the project map.
• immutant.dev/current-project Returns the map representing the currently active leiningen project. This will be the last project reloaded by reload-project!, or the map read from project.clj if reload-project! has yet to be called.

  Examples:

  ;; assuming we have an app loaded that initially only depends on clojure
  ;; (from its project.clj)
  (require '[immutant.dev :as dev]
           '[clojure.java.io :as io])
  
  (:dependencies (dev/current-project)) ; => #{[org.clojure/clojure "1.4.0"]}
  
  ;; let's add more deps
  (dev/add-dependencies! '[dep-1 "1.0.0"] '[dep/two "0.1.0-SNAPSHOT"] "extra")
  
  (:dependencies (dev/current-project)) ; => #{[org.clojure/clojure "1.4.0"] [dep-1 "1.0.0"] [dep/two "0.1.0-SNAPSHOT"]}
  
  (:source-paths (dev/current-project)) ; => [["/path/to/app/root/src", "/path/to/app/root/extra"]]
  
  ;; now let's reset the deps to those specified in project.clj
  (dev/reload-project!)
  
  (:dependencies (dev/current-project)) ; => #{[org.clojure/clojure "1.4.0"]}
  
  ;; let's add a path to :source-paths directly
  (dev/reload-project! ((dev/current-project) [:source-paths]
                        #(conj % "something")))
  
  (:source-paths (dev/current-project)) ; => [["/path/to/app/root/src", "/path/to/app/root/something"]]