readme

hdt is an automatic test unit framework consisting of a guile module with test, assert macros 
and command line test runner.

  install

$ git clone https://github.com/her01n/hdt
$ cd hdt
$ make
$ sudo make install

After installation run 'hdt' in the project directory to check everything works.

  assert macro

syntax: (assert expr [message])

Evaluates an expression and fails the current test if the result is #f. The message will be displayed 
in the report in case of failure. For some functions and macros the arguments are evaluated beforehand, 
and displayed in the test report. For example:

(assert (equal? 4 (fun 2)))

And the test report will display:

assertion failed:
  (equal? 4 (fun 2))
  (equal? 4 7)

This way, additional macros like assert-equal are not necessary.

  test macro

syntax: (test ["name"] expr...)

Register a test to be consisted of the expressions. The test is considered passing 
if evaluating expressions does not throw any exceptions and all assertions passes. 
Test can start with inner definitions. Right now the definitions cannot use bindings introduced later.
Tests could be nested. The nested tests execute the preceding expressions from the parent test first. 
For example, to implement common setup code:

(test root
  (before)
  (test first (a))
  (test second (b)))

will execute:

(before) ; root
 (before) (a) ; first
(before) (b) ; second

  hook macro

syntax: (hook expr...)

Shedules the expressions to be evaluated after the current test is done, in all cases.
For example:

(test
  (setup)
  (hook teardown)
  (test ...)
  (test ...))

The expressions are evaluated only if execution reaches the hook macro. 
So it have to be placed right after or even before the setup it needs to reverse. 
Multiple hooks could be defined that would be executed in the opposite order as defined.

As a special case, hook macro used outside a test would be executed once,
after all tests finish, successfuly or otherwise.
This way, one time initialization and clean up can be performed:

    (one-time-setup)
    (hook (one-time-teardown))
    (test ...)
    (test ...)

  throws-exception macro

syntax: (throws-exception expr)

Returns #t if evaluating expr throws any exception, #f otherwise. May be used to assert
the failure path.
For example:

  (assert (throws-exception (/ 1 0)))

  command hdt

Loads and executes all tests under ./test directory. 
Includes current working directory in the guile path (passing '-L .' argument). 
The project orion layout may look like this:

test/
test/calc.hs
orion/
orion/calc.hs

test/calc.hs:

  (use-modules (hdt hdt))
  (use-modules (orion calc))

  (test add
    (assert 7 (add 3 4)))

orion/calc.hs:

  (define-module (orion calc))

  (define-public (add . args) 
    #f)

## guile version
HDT is tested with guile 2.0 and 2.2. To run the tests under different guile version,
use GUILE environment variable. For example:

   $ env GUILE=guile2.0 hdt 

## TODO

- show the arguments for nested function calls in assert:

      (define a 4)
      (assert (not (< a 6)))

  =>

      (assert (not #t))
      (assert (not (< 4 6))) 

- run the parent test before the children, if the parent fails, skip the children
- on interactive terminal, instead of printing dots, display the current test name
- if a test module loads another test module, do not run the second module tests twice
- (assert (not (throws-exception value)))
  should display the exception in case of failure
- think of a better name for the test framework?
- make the documentation
  - update to use proper markdown formatting
- Allow nested tests inside 'map', 'if', 'foreach', and similar. This will require to rework the way
  the tests are registered?