File	Date	Author	Commit
examples	2011-09-05	unknown	[6c5143] first night of coding - established basic design
src	2011-09-09	unknown	[f10162] minimal framework, sufficient for TDD of the rest
tests	2011-09-09	unknown	[f10162] minimal framework, sufficient for TDD of the rest
COPYING.txt	2011-09-02	Shaun Green	[32d057] initial commit - beginning of project structure...
README.txt	2011-09-09	unknown	[f10162] minimal framework, sufficient for TDD of the rest

Read Me

PROTEST
-------

This project provides a unit testing framework for testing OpenEdge (ie: 
Progress, DLC, etc) source code.

To build the code, add the /src directory to your PROPATH and compile.
There are no external dependencies, other than Progress itself.

For examples of how to use the code, see the /examples directory.

The test framework uses itself to test itself, so if you want you can look
at those tests as well.


WRITING TESTS IN PROTEST
------------------------

First, some definitions:

  * A Test Suite is a dot-p that is used to group together Test Fixtures, 
    usually for regression testing purposes.

  * A Test Fixture is a dot-p that contains zero or more Tests.  It is
    used to test a single dot-p or dot-cls.
  
  * A Test is an internal procedure inside a Test Fixture.  It tests a single
    behaviour.

  * An Assertion is made inside a Test, and asserts that a condition is true.
    If the condition is not true, the Assertion *fails*.  Failures bubble up
    through the test hierarchy - a failing Assert fails the Test that it was
    made in, the Test Fixture that contained the Test, and the Test Suite that
    contained the Test Fixture (if any).



YOUR FIRST TEST FIXTURE
-----------------------

Consider the following dot-p ("HelloTests.p"):

    {Tuxedo/Tools/Protest/TestFixture.i}
    PROCEDURE HelloWorld:
	{Tuxedo/Tools/Protest/Test.i}
	Assert:IsTrue(FALSE).
	{Tuxedo/Tools/Protest/TestEnd.i}
    END.
	
Running the dot-p will let you know that the test has failed (and why).  The 
way you are informed will be different, depending on whether you are running
the test from a character or a gui runtime.

If all tests pass, like for this code:

    {Tuxedo/Tools/Protest/TestFixture.i}
    PROCEDURE HelloWorld:
	{Tuxedo/Tools/Protest/Test.i}
	Assert:AreNotEqual("Hello", "World").
	{Tuxedo/Tools/Protest/TestEnd.i}
    END.

... then you are told that all tests pass.



WHAT DO THE INCLUDE FILES DO?
-----------------------------

TestFixture.i	Defines the minimal code necessary to let a Test Fixture run
		stand-alone, or as part of a Test Suite.  If you do not include 
		Fixture.i, none of the tests will run!

Test.i		Identifies an internal procedure as a Test, and provides the Test
		with access to an "Assert" instance.  Also, begins the wrapping of
		the rest of the Test code inside a DO: block, so that any errors
		in the Test code will fail the test.

TestEnd.i	Closes off the DO: block that was started by Test.i, and adds a
		catch block to capture errors in the Test code.



HOW DO I WRITE A REGRESSION TEST SUITE?
---------------------------------------

Like this:

    {Tuxedo/Tools/Protest/TestSuite.i}
    PROCEDURE HelloSuite:
	TestSuite:TestFixture("my/path/to/testfixture1.p").
	TestSuite:TestFixture("my/path/to/testfixture2.p").
    END.

... where testfixture1.p and testfixture2.p are Test Fixtures conforming to the
design for Test Fixtures outlined above.



WHAT ASSERTIONS CAN I MAKE?
---------------------------

Assert:Fail()			- Fail the test
Assert:Fail(char)		- Fail the test, with a reason
Assert:IsTrue(log)		- Is "log" true?
Assert:IsTrue(log, char)	- Is "log" true?  If not, why not?
Assert:IsFalse(log)		- Is "log" false?
Assert:IsFalse(log, char)	- Is "log" false? If not, why not?
Assert:AreEqual(var1, var2)*	- Is "var1" the same as "var2"?  By convention, 
				  var1 should be the expected value, and var2 
				  should be the variable under test. 
Assert:AreNotEqual(var1, var2)*	- Are "var1" and "var2" different?
Assert:IsNull(var)*		- Is "var" null (does it contain '?').
Assert:IsNotNull(var)*		- Is "var" something other that null?

* Assertions marked with an asterix (*) are overloaded methods and "var"
  parameters can be of any type.