postgis/regress

Requirements for run_test.pl
----------------------------

run_test.pl requires the following Perl modules to be installed

 Text::Diff;
 File::Which;
 File::Basename;
 File::Temp 'tempdir';
 File::Copy;
 File::Path 'make_path';
 File::Path 'remove_tree';
 Cwd 'abs_path';
 Getopt::Long;

Most distributions of Perl will have everything except Text::Diff and File::Which.
To install them from the command-line, as root run

 cpan Text::Diff
 cpan File::Which


How to add a regression test
----------------------------

1. Write a /regress/<testname>.sql file with data and sql queries for testing
2. Write a /regress/<testname>_expected or <testname>_expected.in file with
   expected results per query
   The expected results provided in the <testname>_expected file must be
   formatted using the following psql options:
      -a -- unaligned columns
      -f | -- use | (pipe) as the field separator between columns
      -t -- output rows only, ie. no table header

   cat file.sql | psql -F\| -t -A > file_expected

3. Edit regress/Makefile adding <testname> to the TESTS variable.
   Any _expected.in files need to be added to the PREPROC variable.

Optional:
   If your test has unusual setup or teardown requirements, you may create
   any of the following optional files (they will run in this order):
        /regress/<testname>-pre.sh
        /regress/<testname>-pre.sql   (run via psql)
                 (The test itself is run here.)
        /regress/<testname>-post.sql  (run via psql)
        /regress/<testname>-post.sh

Notes about changes in regression tests introduces with PostGIS 1.1.0
---------------------------------------------------------------------

- Mixed-dimensioned geometries are no longer supported
  (previous behaviour was to fill Z with a 0 value)
  [ updated to use new behaviour ]

- geometry_same operator (=~) now requires all dimensions equality
  Previously only x/y were checked

- geometry_same operator (=~) now requires geom type equality
  Previous behaviour:
     GEOMETRYCOLLECTION(POINT(0 1), POINT(2 3)) =~  MULTIPOINT(0 1,2 3)

- numb_sub_geometries does not exist anymore
  [updated to use numgeometries]

- truly_inside does not exist anymore
  [updated to use within]

Notes about <testname>_expected.in
----------------------------------

The first line of the <testname>_expected.in should include the postgis
configuration header.

  #include "../postgis_config.h"

The ability to run a c preprocessor over the expected results prior to
regression testing was needed for testing curved string functionality that
would elicit different responses from JTS vs GEOS compilations.  Since
JTS is no longer supported, this may not be required anymore.

Notes about running individual regression tests
-----------------------------------------------

The script run_test.pl can be called directly to run individual
regression tests. Run it without parameters for info about its usage.

Note that tests run in a staged install which is created by running
make staged-install. This step is a part of the complete make check.