Ruby Q.E.D.

    homepage: http://proutils.rubyforge.org/qed
mailing list: http://groups.google.com/group/tigerops-community?hl=en
 development: http://github.com/proutils/qed/tree/master

Introduction

Q.E.D. stands for Quality Enhanced Demos. QED is an easy to use quality assurance and documentation system for Ruby Developers. QED sit between low-level testing tools like Test Unit and requirements specifications like Cucumber. It is designed to address Interface-driven devleopment, which is especailly useful when designing reusble libraries.

Features

Demos can be RDoc or Markdown format.
Uses AE as backend assertion system.

Synopsis

Assertion Syntax

QED uses AE (Assertive Expressions) libary to provide an elegant means of express behaviors. To give a quck overview, you can use code such as:

4.assert == 5

In this example, because 4 != 5, this expression will raise an Assertion exception. QED’s Runner class is thus just a means of running and capturing code block containing these assertions.

You can learn more about AE at proutils.rubyforge/ae.

Document Structure

QED documents are simply text files –thus a practice of literal programming. For example:

# Example

Shows that the number 5 does not equal 4.

    5.assert! == 4

But in fact equals 5.

    5.assert == 5

As you can see, we used Markdown for this document. Almost any text format can be used. The only neccesary distinction is that desciption text be align to the left margin and all code be indented. However QED recognizes RDoc and Markdown style headers, so any format that supports this style (which covers many markup formats in use today) will work a bit better. While strictly speaking QED does not need to recognize headers, it does improve console output a bit.

Give this design some thought. It should become clear that this approach is especially fruitful in that it allows documentation and specification to seemlessly merge into a unified demonstraion.

If we run this document through QED in verbatim mode the output would be identical (assuming we did not make a typo and the assertions passed). If there were errors or failures, we would see information detaling each.

Running Demonstrations

To run a document through QED, simply use the qed command.

$ qed demo/01_example.rdoc

Notice we placed the QED document in the demo directory, this is the traditional place we have designated for them, though you can put them elsewhre in your project if you prefer. Also notice the 01_ in front of the name. While this is not necessary, it helps order the documents properly with generatingQED documentation (QEDocs).

Speaking of which, to generate documentation from QED documents, use the qedoc command. Eg.

$ qed --output doc/qedoc --title "Example" demo/*.rdoc

Use the --help options on each command to get more inforamtion on the use of these commands.

Copyright and License

Q.E.D.

QED is distributed under the terms of the GPLv3.