0 | 0 |
Falderal
|
1 | 1 |
========
|
|
2 |
|
|
3 |
Falderal is a framework for writing, running, and formatting "doctest"-like
|
|
4 |
literate test suites for Haskell functions. It is particularly suited for
|
|
5 |
testing and documenting functions which interpret or compile programming
|
|
6 |
languages -- especially esoteric ones.
|
2 | 7 |
|
3 | 8 |
Here's the situation:
|
4 | 9 |
|
5 | 10 |
* You have a Haskell program, formatted in literate Haskell.
|
6 | 11 |
* You have some Haskell functions which take Strings to Strings.
|
7 | |
* You have some unit tests for those functions that you want to
|
8 | |
include them in the literate Haskell source in a nicely readable
|
9 | |
fashion.
|
10 | |
* You want to be able to optionally treat the literate Haskell
|
11 | |
source as being in Markdown format, to convert it to HTML, etc.
|
|
12 |
* You have some unit tests for those functions that you want to present in
|
|
13 |
a nicely readable fashion, possibly included right in the literate Haskell
|
|
14 |
source.
|
12 | 15 |
|
13 | |
If this describes you, then Falderal might help. The particular need
|
14 | |
I had that encouraged me to write it is having implemented several
|
|
16 |
If this describes you, then Falderal might help. The particular need I had
|
|
17 |
that encouraged me to write it is having implemented several esoteric
|
15 | 18 |
programming languages in Haskell, and wanting to write nicely formatted
|
16 | 19 |
tests suites for them.
|
17 | 20 |
|
18 | |
How to Use it
|
19 | |
-------------
|
|
21 |
Current Version
|
|
22 |
---------------
|
20 | 23 |
|
21 | |
* Write a literate Haskell program as usual.
|
22 | |
* Define a section for each function you want to test. Delimit
|
23 | |
the section just as you would with Markdown.
|
24 | |
* In that section, write whatever text you like describing the
|
25 | |
tests. Generally, you would preface each test with text revelant
|
26 | |
to it; this text will be output if the test fails.
|
27 | |
* Write a test by prefixing each line of input with a | character in
|
28 | |
the first column, and prefixing each line of output with a = character.
|
29 | |
For example,
|
|
24 |
The current version of Falderal is 0.1. The API should not be expected to
|
|
25 |
be stable through the 0.x series, however Test.Falderal.Runner.run is not
|
|
26 |
expected to change its type signature (it takes a "property list" of options,
|
|
27 |
although no options are currently honoured.)
|
30 | 28 |
|
31 | |
| 2+2
|
32 | |
= 4
|
|
29 |
Development
|
|
30 |
-----------
|
33 | 31 |
|
34 | |
* If you expect your test to fail, you can include the name of an
|
35 | |
exception to expect, prefixed with a ? character, instead of
|
36 | |
expected output. For example,
|
|
32 |
Falderal development is hosted on BitBucket:
|
37 | 33 |
|
38 | |
| 1/0
|
39 | |
? DivideByZeroError
|
|
34 |
https://bitbucket.org/catseye/falderal/
|
40 | 35 |
|
41 | |
* Write a driver for the tests. The driver can be included in the
|
42 | |
selfsame literate Haskell file, or it can be located elsewhere.
|
43 | |
It will typically set up some configuration, then call one of the
|
44 | |
Falderal test runners. The main piece of configuration to set up
|
45 | |
is a mapping between section names and the functions that are to be
|
46 | |
tested in those sections. How and when your driver is called is
|
47 | |
up to you.
|
48 | |
* Optionally, preprocess your literate Haskell source with the included
|
49 | |
script before sending it through Markdown to help it come out the
|
50 | |
other end nicely.
|
|
36 |
Bugs may be reported (and features requested) on the Issue Tracker:
|
51 | 37 |
|
52 | |
TODO
|
53 | |
----
|
|
38 |
https://bitbucket.org/catseye/falderal/issues
|
54 | 39 |
|
55 | |
* Equivalency tests: for testing functions of type
|
|
40 |
Official release distfiles may at some point be available through Falderal's
|
|
41 |
project page on Cat's Eye Technologies' website:
|
56 | 42 |
|
57 | |
(Eq a) => String -> a
|
58 | |
|
59 | |
The idea is that you give multiple input strings in a set; if the
|
60 | |
function does not map them all to the same value, that's a test
|
61 | |
failure.
|
62 | |
* Test monadic functions somehow.
|
63 | |
* Expand on the previous point to test external programs via
|
64 | |
Unix subprocesses; after all, Unix programs are more or less
|
65 | |
functions from Strings to Strings. In other words, (ab)use
|
66 | |
Falderal as a kind of shunit variant.
|
67 | |
* There is no hard-and-fast requirement to use Markdown. I originally
|
68 | |
considered it because its syntax for blockquotes coincides with
|
69 | |
literate Haskell's syntax for code; however, when I tried it with
|
70 | |
Burro, preprocessing was still desirable anyway, and with preprocessing,
|
71 | |
just about any markup format could be used for the literal text.
|
72 | |
The markup format could be specified in the Haskell source, and the
|
73 | |
formatting process could be driven by a function call.
|
|
43 |
http://catseye.tc/project/falderal/
|
|
44 |
|
|
45 |
For Further Information
|
|
46 |
-----------------------
|
|
47 |
|
|
48 |
Please see the Falderal wiki on BitBucket:
|
|
49 |
|
|
50 |
https://bitbucket.org/catseye/falderal/wiki/
|