From cb3fcd1b5b162f1a555b8af2f891dfae25ed661c Mon Sep 17 00:00:00 2001 From: Paul Ramsey Date: Fri, 26 Feb 2010 02:50:58 +0000 Subject: [PATCH] Instructions on adding new tests to cunit, from Jeff Adams. git-svn-id: http://svn.osgeo.org/postgis/trunk@5348 b70326c6-7e19-0410-871a-916f4a2858ee --- liblwgeom/cunit/Makefile.in | 1 + liblwgeom/cunit/README | 201 ++++++++++++++++++++++++++++++++++++ liblwgeom/cunit/cu_tester.h | 4 + 3 files changed, 206 insertions(+) create mode 100644 liblwgeom/cunit/README diff --git a/liblwgeom/cunit/Makefile.in b/liblwgeom/cunit/Makefile.in index 919478f64..e58ca4ba0 100644 --- a/liblwgeom/cunit/Makefile.in +++ b/liblwgeom/cunit/Makefile.in @@ -16,6 +16,7 @@ CFLAGS=@CFLAGS@ @WARNFLAGS@ CUNIT_LDFLAGS=@CUNIT_LDFLAGS@ CUNIT_CPPFLAGS=@CUNIT_CPPFLAGS@ -I.. +# ADD YOUR NEW TEST FILE HERE (1/1) OBJS= \ cu_algorithm.o \ cu_print.o \ diff --git a/liblwgeom/cunit/README b/liblwgeom/cunit/README new file mode 100644 index 000000000..5edc167dc --- /dev/null +++ b/liblwgeom/cunit/README @@ -0,0 +1,201 @@ +TABLE OF CONTENTS + 1. HOW TO RUN LIBLWGEOM UNIT TESTS + 2. HOW TO ADD A SINGLE TEST + 3. HOW TO ADD AN ENTIRE TEST SUITE + 4. ABOUT TEST OUTPUT + 5. HOW TO ASSERT A FAILURE + + +1. HOW TO RUN LIBLWGEOM UNIT TESTS + +NOTE: We use the CUnit test framework, so you will need to have + this installed before you will be able to build and run the + unit tests. + +If you have already built the rest of the code, then from the +postgis/liblwgeom/cunit directory, run: + +make +./cu_tester + +This will run all the tests. To run just one suite: + +./cu_tester + +To run just one test: + +./cu_tester + +To run selected suites or tests (will be run in the order you specify): + +./cu_tester + +Unit tests for the entire system (including both these unit tests and others +that require postgresql to be running) can be done by running the following +command from the top of the directory tree (postgis directory): + +make check + + +2. HOW TO ADD A SINGLE TEST + +To add a test to an existing suite, follow these steps: + +2.1 Create the test: + +Open the cu_.c file, and add your +new test function. Test functions must have the following signature: + +static void (void) + + must be unique among all tests. A useful naming convention is: + +static void test__(void) + +Although not all existing tests follow that convention. + +For information on the various ASSERT macros you can use, see the CUnit +documentation: + +http://cunit.sourceforge.net/doc/writing_tests.html + +2.2 Add the test to the suite: + +At the bottom of the cu_.c file, below all the test functions, you +will find a block that looks like this (this example is from cu_print.c): + +/* +** Used by the test harness to register the tests in this file. +*/ +CU_TestInfo print_tests[] = { + PG_TEST(test_lwprint_default_format), + PG_TEST(test_lwprint_format_orders), + PG_TEST(test_lwprint_optional_format), + PG_TEST(test_lwprint_oddball_formats), + PG_TEST(test_lwprint_bad_formats), + CU_TEST_INFO_NULL +}; + +Add a new line for your test: + + PG_TEST(), + +The tests will be run in the order they appear in the list. +CU_TEST_INFO_NULL must always be the last entry. + +2.3 Add any necessary init / cleanup code. + +If your test needs global data created or any other kind of init done +before it runs, or cleanup done after it runs, add the appropriate code +to the init_ or clean_ functions. If the test +suite does not seem to have these functions (they are optional), see +below (3.3) for how to create them. + +Save your changes, run make, and run ./cu_tester, and your test +should be executed. + + + +3. HOW TO ADD AN ENTIRE TEST SUITE + +Do the following steps to create a whole new test suite (new .c file). + +3.1 Create the file. + +Create the new file (remember to add to svn as well). The naming convention +is cu_.c. + +Make sure to import: + +#include "CUnit/Basic.h" +#include "cu_tester.h" + +Now add the file to Makefile.in. Look for "ADD YOUR NEW TEST FILE HERE". +Remember that you'll have to re-run "configure" (from the top directory) +after modifying a .in file. + +3.2 Write the tests. + +Write the test functions as described in section 2. Then at the bottom +of the file, construct the array of tests (example taken from cu_print.c): + +/* +** Used by the test harness to register the tests in this file. +*/ +CU_TestInfo print_tests[] = { + PG_TEST(test_lwprint_default_format), + PG_TEST(test_lwprint_format_orders), + PG_TEST(test_lwprint_optional_format), + PG_TEST(test_lwprint_oddball_formats), + PG_TEST(test_lwprint_bad_formats), + CU_TEST_INFO_NULL +}; + +Note that each test function must be wrapped with the PG_TEST macro, and +the last entry must be CU_TEST_INFO_NULL. The naming convention is +generally _tests. + +3.3 Construct the init / clean functions and the suite struct. + +Test suites can have initialization and cleanup functions to setup and +dispose of any common or global data. They must have the following +signature: + +static int (void) + +The naming convention is generally: + +static int init_(void) +static int clean_(void) + +The very last line of the file (after all the functions and the tests +array) should look like this: + +CU_SuiteInfo = {"", , , }; + +The naming convention is generally _suite. If you do not have +an init function, you may pass "NULL" instead. Same with the clean function. + +3.4 Add your suite to cu_tester.c. + +Edit cu_tester.c. Search for "ADD YOUR SUITE HERE" and add new lines in +the appropriate places, using the suite info name you used in the last step. + +Now run make (remember to run configure first), then ./cu_tester and your +new suite should run. + + + +4. ABOUT TEST OUTPUT + +CUnit does not print much about asserts that fail, just the line number +within the appropriate file. If you need any more detailed output, it +is up to you to printf it. If you discover that all the test suites +are full of individual hacks to do this, please consolidate them into +cu_tester.h / .c, and/or enter a trac issue suggesting an improvement. + + +5. HOW TO ASSERT A FAILURE + +Often you may want to assert that lwerror was called, possibly verifying +that a specific error message was generated. There is now a way to do +this. The global char array "cu_error_msg" will always contain the most +recent error from an lwerror call. You can check it in your test function +(either asserting its length is greater than zero, or looking for a +specific string). Then call cu_error_msg_reset() to clear it when you're +done. It is a good idea to call cu_error_msg_reset prior to your test, +in case a previous test has generated an error that was not cleared. + +Example: + +cu_error_msg_reset(); + +if (strlen(cu_error_msg) > 0) +{ + printf("\nError: generated an error: %s\n", cu_error_msg); + CU_FAIL(); + /* be nice and clean it up for the next test. */ + cu_error_msg_reset(); +} + + diff --git a/liblwgeom/cunit/cu_tester.h b/liblwgeom/cunit/cu_tester.h index bf5ff95cf..9d492837c 100644 --- a/liblwgeom/cunit/cu_tester.h +++ b/liblwgeom/cunit/cu_tester.h @@ -1,5 +1,9 @@ #define PG_TEST(test_func) { #test_func, test_func } #define MAX_CUNIT_ERROR_LENGTH 512 + +/* Contains the most recent error message generated by lwerror. */ char cu_error_msg[MAX_CUNIT_ERROR_LENGTH+1]; + +/* Resets cu_error_msg back to blank. */ void cu_error_msg_reset(void); -- 2.40.0