1Requirements for run_test.pl
2----------------------------
3
4run_test.pl requires the following Perl modules to be installed
5
6 Text::Diff;
7 File::Which;
8 File::Basename;
9 File::Temp 'tempdir';
10 File::Copy;
11 File::Path 'make_path';
12 File::Path 'remove_tree';
13 Cwd 'abs_path';
14 Getopt::Long;
15
16Most distributions of Perl will have everything except Text::Diff and File::Which.
17To install them from the command-line, as root run
18
19 cpan Text::Diff
20 cpan File::Which
21
22
23How to add a regression test
24----------------------------
25
261. Write a /regress/<testname>.sql file with data and sql queries for testing
272. Write a /regress/<testname>_expected or <testname>_expected.in file with
28   expected results per query
29   The expected results provided in the <testname>_expected file must be
30   formatted using the following psql options:
31      -a -- unaligned columns
32      -f | -- use | (pipe) as the field separator between columns
33      -t -- output rows only, ie. no table header
34
35   cat file.sql | psql -F\| -t -A > file_expected
36
373. Edit regress/Makefile adding <testname> to the TESTS variable.
38   Any _expected.in files need to be added to the PREPROC variable.
39
40Optional:
41   If your test has unusual setup or teardown requirements, you may create
42   any of the following optional files (they will run in this order):
43        /regress/<testname>-pre.sh
44        /regress/<testname>-pre.sql   (run via psql)
45                 (The test itself is run here.)
46        /regress/<testname>-post.sql  (run via psql)
47        /regress/<testname>-post.sh
48
49Notes about changes in regression tests introduces with PostGIS 1.1.0
50---------------------------------------------------------------------
51
52- Mixed-dimensioned geometries are no longer supported
53  (previous behaviour was to fill Z with a 0 value)
54  [ updated to use new behaviour ]
55
56- geometry_same operator (=~) now requires all dimensions equality
57  Previously only x/y were checked
58
59- geometry_same operator (=~) now requires geom type equality
60  Previous behaviour:
61     GEOMETRYCOLLECTION(POINT(0 1), POINT(2 3)) =~  MULTIPOINT(0 1,2 3)
62
63- numb_sub_geometries does not exist anymore
64  [updated to use numgeometries]
65
66- truly_inside does not exist anymore
67  [updated to use within]
68
69Notes about <testname>_expected.in
70----------------------------------
71
72The first line of the <testname>_expected.in should include the postgis
73configuration header.
74
75  #include "../postgis_config.h"
76
77The ability to run a c preprocessor over the expected results prior to
78regression testing was needed for testing curved string functionality that
79would elicit different responses from JTS vs GEOS compilations.  Since
80JTS is no longer supported, this may not be required anymore.
81
82Notes about running individual regression tests
83-----------------------------------------------
84
85The script run_test.pl can be called directly to run individual
86regression tests. Run it without parameters for info about its usage.
87
88Note that tests run in a staged install which is created by running
89make staged-install. This step is a part of the complete make check.
90