openscad/doc/testing.txt

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

Prerequisites: cmake, python

cd tests
mkdir build
cd build
cmake ..
make
make test

Running on 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
mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
sed -i s/\/MD/\/MT/ CMakeCache.txt
cmake ..
nmake -f Makefile
nmake -f Makefile test

Running on headless (no X) servers:

Xvnc :5 -screen 0 800x600x24 &
DISPLAY=:5 make test


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