git @ Cat's Eye Technologies Falderal / rel_0_2 README.text
rel_0_2

Tree @rel_0_2 (Download .tar.gz)

README.text @rel_0_2raw · history · blame

Falderal
========

Falderal is a framework for writing, running, and formatting "doctest"-like
literate test suites for Haskell functions.  It is particularly suited for
testing and documenting functions which interpret or compile programming
languages -- especially esoteric ones.

Here's the situation:

* You have a Haskell program, formatted in literate Haskell.
* You have some Haskell functions which take Strings to Strings.
* You have some unit tests for those functions that you want to present in
  a nicely readable fashion, possibly included right in the literate Haskell
  source.

If this describes you, then Falderal might help.  The particular need I had
that encouraged me to write it is having implemented several esoteric
programming languages in Haskell, and wanting to write nicely formatted
tests suites for them.

History
-------

The current released version of Falderal is 0.2.  It introduced the following
features:

* Added a test harness for Falderal itself, in the form of a simple shell
  script which diffs the output of Test.Falderal.Demo against a text file
  containing the expected content.
* Improved formatting of failure reports.  Multi-line input text or expected
  output is always presented starting on its own line.
* Tests may be organized into groups; the entire group is preceded by some
  literal text, but there is no literal text between the tests in the group.
  When one of these tests fails, the literal text for the group is reported,
  along with the number of the test within the group.
* Fixed a bug where exception text which extended over multiple lines
  could not be expected correctly.

The previous released version of Falderal is 0.1.  It introduced the following
features:

* Provision of a framework for writing and running literate tests which may
  be embedded in literate Haskell source code.
* Testing Haskell functions of type String -> String.  A test specifies input
  to the function, and may expect a particular output, or that a particular
  exception is thrown.
* Through simple adapters, testing functions of other types such as
  (Show a) => String -> a. 

The current version under development is 0.3.  It will likely mark the
start of a transition away from being specific to Haskell, and thus will
involve a few very significant changes.

The API should not be expected to be stable through the 0.x series.

Development
-----------

Falderal development is hosted on Bitbucket:

    https://bitbucket.org/catseye/falderal/

Bugs may be reported (and features requested) on the Issue Tracker:

    https://bitbucket.org/catseye/falderal/issues

Official release distfiles are available on the [Falderal
project page][] at [Cat's Eye Technologies'][].

[Falderal project page]: http://catseye.tc/projects/falderal/
[Cat's Eye Technologies]: http://catseye.tc/

For Further Information
-----------------------

Please see the [Falderal wiki][] on Bitbucket.

[Falderal wiki]: https://bitbucket.org/catseye/falderal/wiki/