Testing PLplot

We encourage those who build PLplot to test both their build-tree version and their install-tree version and report any problems back to either the plplot-general or plplot-devel mailing lists.

Build-tree tests

Build-tree tests can only be performed if cmake is invoked with the -DBUILD_TEST=ON option (which roughly doubles the build time because all the examples must be built).

Build-tree tests are done from the top-level directory of the build tree (the directory where you invoke cmake command that configures the build of PLplot). The methods for invoking these tests are given below. These tests include executing all our 31 standard examples for all language interfaces and non-interactive device drivers that we currently support. This is a comprehensive test of the PLplot build. For example, our standard examples exercise virtually all of the PLplot API. Furthermore, this series of tests generates more than 2GB of plot files in various formats. The tests also include a comparison of PostScript (-dev psc) results and stdout from each language interface to PLplot with the corresponding results for C. In general, these results are identical which is a stringent test of our language bindings. (Note it is the user's responsibility to insure the locales are consistent for all languages since inconsistent locales can produce inconsistent stdout results which have nothing to do with PLplot bindings or examples issues.)

You should search test results for obvious errors such as segfaults. In addition, you can test for rendering errors by viewing the file results using an appropriate viewer. Here are typical file results for example 1.

The results not generated by -dev psc should be tested for rendering errors by viewing them with a viewer appropriate for each particular file type that is generated.

Invocation of legacy build-tree tests

After running "make all" from the top-level of the build tree, then run

ctest --verbose >& ctest.out

This creates test plot file results in the plplot-test subdirectory of the build tree, and ctest.out should contain a table of comparisons of Postscript results from each of our standard examples and each of our language bindings against the corresponding C versions.

Tests on Windows

Since the tests are done using bash scripts, there is some work needed to make the tests run in Windows. First download win-bash

Install tree tests

After PLplot has been configured (with "cmake"), built (with "make"), and installed (with "make install"), you can test the PLplot install on Unix systems by doing the following commands:

cp -a $prefix/share/plplot$plplot_version/examples /tmp
cd /tmp/examples
make test_noninteractive >& make_test.out
make test_interactive

where "$prefix" is the installation prefix chosen at the configuration stage, and $plplot_version is the PLplot version (currently 5.9.4). The effect of the above "cp" and "cd" commands is to copy the examples subtree of the install tree to /tmp and build and test the examples in the copied subtree to keep a clean install tree. However, an alternative is to replace those two commands with

cd $prefix/share/plplot$plplot_version/examples

and build and test the install-tree examples right in the examples subtree of the install tree with the above "make" commands.

Regardless of whether you build and test the examples in a copy of the examples subtree of the install tree or directly in that subtree, check all the *.out files for any errors.

N.B. the above "make test_noninteractive" command does the same tests for the installed PLplot version as ctest does for the build-tree version of PLplot so the same remarks hold about the comprehensive nature of the test, the size (2GB) of the files produced, the comparison of results for various language interfaces with the C result for -dev psc, locale issues, and testing non-psc results using the viewer appropriate for the format. Although the tests are the same, the Makefile implementation is different from the ctest implementation in the build tree so that in particular you can do these install tree tests in parallel using the (GNU-)make -j option to greatly speed up these tests on a multi-processor computer.

N.B. the above "make test_interactive" command executes our interactive examples. There is currently no counterpart for this test in the build tree.