lucid.unit metadata through unit tests

Author: Chris Zheng  (z@caudate.me)
Date: 29 June 2017
Repository: https://www.github.com/zcaudate/lucidity
Version: 1.3.13

1    Introduction

lucid.unit allows for management of unit tests as well as docstrings and function meta data. It works by analysing source and test code to manage all related information to a function within the test file.

1.1    Installation

Add to project.clj dependencies:

[im.chit/lucid.unit "1.3.13"]

All functionality is in the lucid.unit namespace:

(require '[lucid.unit :as unit])

2    API



arrange ^

arranges tests so that vars are in correct order

v 1.2
(defn arrange
  ([] (arrange *ns*))
  ([ns] (arrange ns (project/project)))
  ([ns project] (scaffold/arrange ns (project/file-lookup project) project)))
link
;; arranges tests for current namespace (arrange) ;; arranges tests for specific namespace (arrange 'lucid.unit)

import ^

imports unit tests as docstrings

v 1.2
(defn import
  ([] (import *ns*))
  ([ns] (import ns (project/project)))
  ([ns project] (import ns (project/file-lookup project) project))
  ([ns lookup project]
   (cond (= ns :all)
         (doseq [ns (keys (project/all-files (:source-paths project) {} project))]
           (import ns lookup project))
         
         :else
         (let [ns (code/source-namespace ns)
               src-file  (lookup ns)
               test-file (lookup (symbol (str ns "-test")))
               import-fn (fn [nsp refers]
                           (fn [zloc]
                             (zipper/insert zloc nsp refers)))
               refers (if test-file
                        (code/analyse-file :test test-file)
                        {})]
           (if src-file
             (zipper/walk-file src-file nil refers import-fn))))))
link
;; import docstrings for the current namespace (import) ;; import docstrings for a given namespace (import 'lucid.unit) ;; import docstrings for the entire project (import :all)

in-order? ^

checks vars in the test file is in correct order

v 1.2
(defn in-order?
  ([] (in-order? *ns*))
  ([ns] (in-order? ns (project/project)))
  ([ns project] (scaffold/in-order? ns (project/file-lookup project) project)))
link
;; checks ordering for current namespace (in-order?) ;; checks ordering for specific namespace (in-order? 'lucid.unit)

missing ^

checks functions that are missing in a given namespace

v 1.2
(defn missing
  ([] (missing *ns*))
  ([ns] (missing ns (project/project)))
  ([ns project] (missing ns (project/file-lookup project) project))
  ([ns lookup project]
   (let [ns (code/source-namespace ns)
         src-file (lookup ns)
         test-file (lookup (symbol (str ns "-test")))
         src-vars (if src-file (code/all-source-vars src-file))
         test-vars (if test-file (code/all-test-vars test-file))]
     {ns (set/difference (set src-vars) (set test-vars))})))
link
;; lists missing tests for current namespace (missing) ;; lists missing tests for specific namespace (missing 'lucid.unit)

orphaned ^

finds all unit tests that do not have functions

v 1.2
(defn orphaned
  ([] (orphaned *ns*))
  ([ns] (orphaned ns (project/project)))
  ([ns project] (orphaned ns (project/file-lookup project) project))
  ([ns lookup project]
   (let [ns (code/source-namespace ns)
         src-file (lookup ns)
         test-file (lookup (symbol (str ns "-test")))
         src-vars (if src-file (code/all-source-vars src-file))
         test-vars (if test-file (code/all-test-vars test-file))]
     {ns (set/difference (set test-vars) (set src-vars))})))
link
;; lists orphaned tests for current namespace (orphaned) ;; lists orphaned tests for specific namespace (orphaned 'lucid.unit)

purge ^

purge docstrings and meta from file

v 1.2
(defn purge
  ([] (purge *ns*))
  ([ns] (purge ns (project/project)))
  ([ns project] (purge ns (project/file-lookup project) project))
  ([ns lookup project]
   (cond (= ns :all)
         (doseq [ns (keys (project/all-files (:source-paths project) {} project))]
           (purge ns lookup project))

         :else
         (let [ns (code/source-namespace ns)
               src-file (lookup ns)
               purge-fn (fn [nsp references] identity)]
           (if src-file
             (zipper/walk-file src-file nil nil purge-fn))))))
link
;; removes docstrings for the current namespace (purge) ;; removes docstrings for a given namespace (purge 'lucid.unit) ;; removes docstrings for the entire project (purge :all)

scaffold ^

builds the unit test scaffolding for the source

v 1.2
(defn scaffold
  ([] (scaffold *ns*))
  ([ns] (scaffold ns (project/project)))
  ([ns project] (scaffold/scaffold ns (project/file-lookup project) project)))
link
;; generates test scaffolding for current namespace (scaffold) ;; generates test scaffolding for specific namespace (scaffold 'lucid.unit)

unwatch ^

removes the automatic watching and importing of tests

v 1.2
(defn unwatch
  ([] (unwatch (project/project)))
  ([{:keys [root] :as project}]
   (when-let [watcher (get *watchers* root)]
     (alter-var-root #'*watchers* dissoc root)
     (watch/stop-watcher watcher))))
link
(unwatch)

watch ^

automatic imports tests when files change

v 1.2
(defn watch
  ([] (watch {} (project/project)))
  ([opts {:keys [root test-paths] :as project}]
   (unwatch project)
   (let [lookup    (project/file-lookup project)
         ns-lookup (zipmap (vals lookup) (keys lookup))
         watcher   (-> (watch/watcher test-paths
                                      (fn [_ file]
                                        (let [ns (ns-lookup (str file))]
                                          (import ns lookup project)))
                                      {:recursive true
                                       :filter ["*.clj"]})
                       (watch/start-watcher))]
     (alter-var-root #'*watchers* assoc root watcher)
     watcher)))
link
(watch)