From 403d72b89c997a9944e42f9ccf653485f3fc1401 Mon Sep 17 00:00:00 2001 From: simon Date: Thu, 3 Apr 2014 08:21:26 +0100 Subject: [PATCH] Fuller documentation in README.md --- README.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f0cde6c..60dfdcb 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,14 @@ A Clojure library designed to generate charaterisation tests. +## What are 'characterisation tests'? + +Characterisation tests are a suite of tests which characterise the behaviour of a corpus of code. That is to say, they describe, and test, what it does now, whether that's correct or not. Otherwise, they are like unit tests. In fact, they are unit tests - except that unit tests are normally written to describe the desired behaviour of a corpus of code; these describe the actual behaviour. + +## Why use charaterisation tests? + +When modifying a corpus of legacy code, one wants to make only the desired change to its behaviour, and not introduce any 'regressions' (undesired behaviour changes). One way to do this is to start by writing (or generating) a set of tests which fully exercise the code, and all pass. Then, change only the test which describes the particular aspect of the behaviour that you want to change. That test (presumably) now fails, but all the others continue to pass. Now change the code under test until all tests pass again. The behaviour change is made, and no regressions have been introduced. + ## Usage At this stage, try @@ -11,7 +19,7 @@ At this stage, try It will attempt to generate as Clojure source a set of clojure.test test definitions for the code passed. For example: - user=> (pprint (testgen '(defn testgen [fndef] + user=> (pprint (testgen '(defn testgen [fndef] #_=> (cond (= (first fndef) 'defn) #_=> (let [name (first (rest fndef))] #_=> (list 'deftest (symbol (str "test-" name)) @@ -36,6 +44,14 @@ for the code passed. For example: Note, however, that it only works if the function for which tests are being generated already exists in the environment. +## Where this is going + +What I intend to end up with is a function + + (generate-tests ) + +which will read the file at , presumed to be Clojure source, and write a new file containing a complete test suite for that source file, which should exercise every branch and find as many as possible of the interesting corner cases. This does not work yet! + ## License Copyright © 2014 FIXME