Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Run Clojure tests and view concise exceptions and diffs for test failures

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 public
Octocat-spinner-32 server
Octocat-spinner-32 src
Octocat-spinner-32 test
Octocat-spinner-32 .cljrc.clj
Octocat-spinner-32 .gitignore
Octocat-spinner-32 COPYING
Octocat-spinner-32 README.textile
Octocat-spinner-32 project.clj
README.textile

Deview

Deview is a development tool for Clojure and clojure.test which allows developers to run tests and then view the results in a format that better communicates the reason for test failures. It does this in two ways:

  1. when a test fails because two data structures are not equal, it will display the diff of the data structures
  2. when an exception occurs, during compile time or within a test, a much simpler stack trace is displayed

More generally, deview is an attempt to bring some of the tools that are common to IDEs to those of us using command line tools for development. It is currently designed to work very well with Leiningen projects, but could easily be modified to work with other types of projects.

In order to prevent numerous jars from being added to your project, deview has a client/server architecture. The client is a Compojure application which has many dependencies. The server, which you add as a dependency to your project, depends only on Clojure and clj-stacktrace. Throughout the rest of this document, these will be referred to as the server and client. The server is responsible for interacting with your project; including, reading your Leiningen project file, running tests and reading source files.

If you just want a simple command line tool to run tests and show diffs then see lein-difftest.

Motivation

It takes a little work to get this running so I would like to motivate you with an example of why it is worth your time to do this. clojure.test provides basic reporting facilities which may be easily extended but most of us are using the default text output. Most of the time this is good enough, but sometimes you get output like that shown below.


actual: (not (= {:remote-addr "0:0:0:0:0:0:0:1%0", :scheme :http, :query-params {}, :session {:sandbar.stateful-
session/session {:project {:host "localhost", :name "deview/deview-server", :port 9000, :_id 1, :_v 1, :_type :projects}}},
:form-params {}, :request-method :get, :query-string nil, :route-params {"*" "/deview/deview-server"}, :content-type nil,
:cookies {"ring-session" {:value "0bcoa4e4-a852-4976-b2e9-a697a48f1ed6"}}, :server-name "localhost", :params {"*" "/deview
/deview-server"}} {:remote-addr "0:0:0:0:0:0:0:1%0", :scheme :http, :query-params {}, :session {:sandbar.stateful-
session/session {:project {:host "localhost", :name "deview/deview-server", :port 9000, :_id 1, :_v 1, :_type :projects}}},
:form-params {}, :request-method :get, :query-string nil, :route-params {"*" "/deview/deview-server"}, :content-type nil,
:cookies {"ring-session" {:value "0bcca4e4-a852-4976-b2e9-a697a48f1ed6"}}, :uri "/stats/deview/deview-server", :server-name
"localhost", :params {"*" "/deview/deview-server"}}))

For the same test result, deview will show the difference between the two maps.

Deview Diff

There are two changes in the map and it is easy to see what they are. In the Ring session value, c was removed and o was added. Additionally, the :uri key has been removed.

We have all seen the screens full of stacktrace that you get when encountering an exception. When deview encounters an exception it will display a much more concise stacktrace.

Deview Diff

This alone is worth the time to set up and use deview, but that is not all that it does. It also allows the developer to easily navigate and run tests and, under metrics, displays lines of code per file type. In the future it will do much more. See the TODO section below for details about future plans.

Usage

The easiest way to get started is to follow the instructions below, but once you understand how it all works you will be able to come up with your own custom way to start the client and server.

Install and Run the Server

The simplest way to run the server is to use the lein-deview plugin. Add the following to your Leiningen :dev-dependencies:


[deview/lein-deview "1.0.5"]

The version number for lein-deview will always be the same as the corresponding deview-server version. If the client indicates that you need a specific version of deview-server then you may use the same version of lein-deview.

The port on which the server runs may be configured in your Leiningen project by adding a :deview-server key to the project. For example, :deview-server 9000 will cause the server to run on port 9000.

To start the server:


$ lein deps
$ lein deview &

To stop the server use lein deview stop.

Install and Run the Client

The simplest way to run the client is to clone this repository, start a REPL and run the client.


$ git clone git://github.com/brentonashworth/deview.git
$ cd deview
$ lein deps
$ lein repl
user> (use 'deview.main)
user> (start 8080)

If you followed the above steps, you will have a server running on port 9000 and a client running on port 8080. You may run any number of servers for different projects at the same time as long each one uses a different host and port combination.

Using it

Open the client application in your favorite browser. Click on “Add Project” and enter the port where you started the server. You should now see your project in the project list. Click on the project name and have fun.

Deview is currently focused on testing but also includes a Metrics feature. The only (questionably useful) metric that is implemented is a count of the lines of code by file type for sources, tests and other. You may configure the types of files that are included in this count by adding the :deview-loc-ext key to your project. For example: :deview-loc-ext #{"clj" "html"} will only count lines in Clojure and html files.

Known Problems and Limitations

  1. All tests are run in a separate thread so test code cannot change root bindings for *print-depth* and friends.
  2. Vars that are removed from a source file are still visible to deview until the server is restarted. This will be fixed in a future release.

TODO

  1. Add watchers to run tests with a file is saved
  2. Remove vars from a namespace when they are removed from a test source file
  3. Group tests
  4. Run groups in parallel
  5. Add some useful metrics other than lines of code
  6. Browse source
  7. Add links to source code to test error messages
  8. Create test configurations where bindings may be applied, for example: set a flag to not run the tests that hit the database
  9. When tests are running automatically; when a test fails in a namespace, only run the tests for that namespace until the issue is fixed then go back to running all tests.
  10. Find all usages of a function in one or more projects
  11. Interface with a good code coverage tool once one emerges

License

Copyright © 2010 Brenton Ashworth

Distributed under the Eclipse Public License, the same as Clojure uses. See the file COPYING.

Something went wrong with that request. Please try again.