= PostGIS Garden Test =

The PostGIS Garden Test is a suite of SQL statements designed to stress test the PostGIS library within the PostgreSQL environment.  It is a test generated from the reference.xml that tries to test every documented function against every kind of geometry supported by PostGIS.  The main objective of the tests is to try to catch bugs that will crash the server.  It is also useful for monitoring odd behavior as well as a regression test against prior versions of the software.  To test against prior versions, build a test from the prior version reference.xml and test against both the old and the new version on the same server and then do a diff between the two.  With postgis-1.4 and postgis-1.5 this is much easier to do as you can run both versions on the same server in different databases.

To build the garden test you need an xsltproc (the same that is used to build the docs or some other .xsl processor).  On windows you can download precompiled binaries from [http://www.zlatkovic.com/pub/libxml/] and its part of the libxslt package.

The reference.xml and postgis_gardentest.sql.xsl located in the doc and doc/xsl folders are both needed to build the tests.  

NOTE that these tests are equivalent to a monkey testing the software so a lot of tests fail. Its good in a sense as a monkey will stuff a geometry in any function that takes that and as such will test the system as human monkeys are bound to do.

Below is a basic script to build the tests and run them (if you are running from dos, change the 
slashes or just run everything from same folder:

{{{
xsltproc -o torturetest.sql trunk/doc/xsl/postgis_gardentest.sql.xsl trunk/doc/reference.xml
psql -p 5432 -U postgres -d postgres -c "CREATE DATABASE testpostgis;" 
psql -p 5432 -U postgres -d testpostgis -f postgis.sql 
psql -p 5432 -U postgres -d testpostgis -f geography.sql
psql -p 5432 -U postgres -d testpostgis -f spatial_ref_sys.sql
psql -p 5432 -U postgres -d testpostgis -f torturetest.sql > torturetest_results.txt 
psql -p 5432 -U postgres -d postgres -c "DROP DATABASE testpostgis;" 

}}}

If you want it to output the actual query that is being tested, then use the -a command like so


{{{
psql -p 5432 -U postgres -d testpostgis -f torturetest.sql -a > torturetest_results.txt
}}}


If you want to include timing information - you can edit the generated torturetest.sql and add a 


{{{
\timing 
}}}

= Testing subset of functions =
A companion to the full postgis_gardentest.sql.xsl is the postgis_gardentest_subset.sql.xsl.  
This version skips the table creation battery of tests and allows you to specify a subset of functions to test.

This test is useful to test out new functions introduced or just test functions that have changed from prior
versions to make sure they are behaving as expected.  It makes the output file much shorter and easier to scan.

It will only test functions whose ids are contained in the inputfninclude parameter.  NOTE this currently causes a bit of overtesting since ST_MakeLine and ST_M will match ST_MakeLine. Below is an example use.

{{{
xsltproc --param inputfninclude '"ST_Collect ST_Distance ST_DWithin ST_MakeLine"' -o torturetest_subset.sql trunk/doc/xsl/postgis_gardentest_subset.sql.xsl trunk/doc/reference.xml
psql -p 5432 -U postgres -d postgres -c "CREATE DATABASE testpostgis;" 
psql -p 5432 -U postgres -d testpostgis -f postgis.sql 
psql -p 5432 -U postgres -d testpostgis -f geography.sql
psql -p 5432 -U postgres -d testpostgis -f spatial_ref_sys.sql
psql -p 5432 -U postgres -d testpostgis -f torturetest_subset.sql > torturetest_results.txt 
psql -p 5432 -U postgres -d postgres -c "DROP DATABASE testpostgis;" 

}}}