Running regression tests:
-------------------------

Prerequisites: cmake, python

A) Building test environment

Linux, Mac:
$ cd tests
$ cmake .
$ make

Windows:

First, get a normal build working by following instructions at 
http://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Building_on_Windows
Then, from the QT command prompt:

$ cd tests
$ cmake . -DCMAKE_BUILD_TYPE=Release
$ sed -i s/\/MD/\/MT/ CMakeCache.txt
$ cmake .
$ nmake -f Makefile

B) Running tests

Easy version:
$ make test

Windows:
$ nmake -f Makefile test

Headless servers (no X11):
$ Xvnc :5 -screen 0 800x600x24 &
$ DISPLAY=:5 make test

Partial or extended test runs:
$ ctest               Runs tests enabled by default
$ ctest -R <regex>    Runs only matching tests, e.g. ctest -R dxf
$ ctest -C <configs>  Adds extended tests belonging to configs.
                      Valid configs:
                      Default  - Run default tests
                      Heavy    - Run more time consuming tests (> ~10 seconds)
                      Examples - test all examples
                      All      - test everything


Adding  a new regression test:
------------------------------

1) create a test file at an appropriate location under testdata/
2) if the test is non-obvious, create a human readable description of the test in the same directory (e.g testdata/scad/mytest.txt)
3) if a new test app was written, this must be added to tests/CMakeLists.txt
4) Add the tests to the test apps for which you want them to run (in tests/CMakeLists.txt)
5) run the test with the environment variable TEST_GENERATE=1, e.g.:
   $ TEST_GENERATE=1 ctest -R mytest
   (this will generate a mytest-expected.txt file which is used for regression testing)
6) manually verify that the output is correct (tests/regression/<testapp>/mytest-expected.<suffix>)
7) run the test normally and verify that it passes:
  $ ctest -R mytest

Troubleshooting a failed test:
------------------------------

You can run a single test by passing the test name to ctest:
 $ ctest -R throwntogethertest_sphere

You can run a series of tests by passing part of a name to ctest:
 $ ctest -R cgalpng  # runs all cgalpng tests
 $ ctest -R sphere   # runs all sphere tests
    
Logs of test runs are found in tests/build/Testing/Temporary
Expected results are found in tests/regression/*
Actual results are found in tests/build/testname-output/*

You can also compile a single test program:

 $ make cgalpngtest