Simple Improvement

_Simple Improvement_
====================

By  Noel Welsh (noelwelsh at yahoo dot com)

This manual documents Simple Improvment version 1.0
Time-stamp: <2006-11-07 12:02:02 nhw>

Keywords: _improvement_, _test_, _testing_, _unit testing_,
          _unit test_, _schemeunit_



Introduction
============

Simple Improvement (SI) is a SchemeUnit add-on that makes
the you, the programmer, aware of the effectiveness of your
development process.

There are two main goals for a software development process:

  - Develop software as quickly as possible

  - Develop software as correctly as possible

Simple Improvement gathers statistics on these two aspects
of software development.  This allows you to see how
effective your process is, and, better yet, tweak your
process to optimise it.

To measure how quickly you are developing software SI
records the number of test cases (and the number of
succcesses, failures, and error) each time you run your
tests.  Assuming you are diligent with your testsing, the
number of tests should be strongly correlated with the
number of features in your software.

To measure how correct your software is SI extends the
SchemeUnit language with a new type of test case called a
'bug-case'.  A bug-case is exactly the same as a test-case,
except it indicates a test for a problem found after a
software release -- in other words, a released bug.  

By observing these two statistics over time you can gain an
idea of the effectiveness of your development process.

To use SI you only need make two changes to your test suites:

  - replace uses of test/text-ui with test/si-text-ui

  - use bug-case instead of test-case when writing a test
    for a bug (a problem found in released code)


Simple Improvement API
======================

All are exported by si.ss


> (test/si-text-ui name test)
test/si-text-ui : symbol test -> natural

Analogous to SchemeUnit's test/text-ui, additionally records
in the SI database the results of running this test

The SI database with be stored in a file in the
current-directory called [name].sidb, where [name] is the
value of name above.


> (bug-case name expr ...)
syntax bug-case : string expression ...

Analogous to SchemeUnit's test-case macro, this macro
constructs a test case that checks for the presence of a
bug.


> (with-database name fn)
with-database : (U string path) (db -> 'a) -> 'a

Calls fn with a connection to the given SI database


> (read-samples db)
read-samples : db -> (list-of sample)

> sample?
sample? : any -> (U #t #f)

> sample-name
sample-name : sample -> symbol

> sample-time
sample-time : sample -> int

> sample-successes
sample-successes : sample -> int

> sample-failures
sample-failures : sample -> int

> sample-errors
sample-errors : sample -> int

> sample-bugs
sample-bugs : sample -> int


Simple Improvements to SI
=========================

At present SI is pretty simple.  In particular, there are no
data analysis facilities.  I intend to remedy this when I
have collected sufficent data from my own tests to perform
an interesting analysis.  Suggestions and contributions are
welcome.