______________________________________________________
PLUnit
Basic Usage
Copyright (c) Andres Olarte, 2007
______________________________________________________

1- JUSTIFICATION
----------------

Stored procedures are normally the best way to manipulate data within RDBMS. However Procedural Languages are not as suited for test driven development (TDD) as other more general purpose languages. PLU fills this void with a simple test framework for PostgreSQL.

2- HOW IT WORKS
---------------

PLU doesn't have a "set up" / "tear down" mechanism.  Instead, it uses the built in transaction facilities of PostgreSQL to always roll back the chances made to the database by each test, effectively simulating the "tear down" construct found in most testing frameworks. The set "up step" becomes the responsability of each test.

To run the tests, to functions are provided:

plu.run_bare(schema_prefix,table_prefix)
This function runs all tests until one fails, in which case an exception is thrown.  If all test pass, true is returned.

plu.run_detail(schema_prefix,table_prefix)
This function runs all tests, returning a table with a summary of passed and failed tests.

Both functions take the prefix of the schemas and tables to match.  Therefore "SELECT plu.run_bare('test','test');" will match all function that have names that start with 'test' in all schemas that start with 'test'

3- EXAMPLES
-----------

Some examples are included in sql/examples.sql

To run the examples execute:

SELECT plu.run_bare('test','test');

OK

SELECT * FROM plu.run_detail('test','test');

To run a failing test:

SELECT plu.run_bare('test','fail');


4- ISSUES
---------

Sequences are not rolled back after tests. This is due to PostgreSQL's way of handling sequences and is therefore outside the scope of PLU.  Therefore tests should not assume which number a sequence will generate, and instead should query every test for the last value.

Since the framework uses function overloading, it's sometimes necessary to use explicit casts.  For example:

PERFORM plu.assert(5.5::numeric,(SELECT SUM(total) FROM invoices)::numeric,'Sum');