mirror of
https://git.osgeo.org/gitea/postgis/postgis
synced 2024-10-24 00:52:40 +00:00
cb3fcd1b5b
git-svn-id: http://svn.osgeo.org/postgis/trunk@5348 b70326c6-7e19-0410-871a-916f4a2858ee
202 lines
6 KiB
Plaintext
202 lines
6 KiB
Plaintext
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 <suite name>
|
|
|
|
To run just one test:
|
|
|
|
./cu_tester <test name>
|
|
|
|
To run selected suites or tests (will be run in the order you specify):
|
|
|
|
./cu_tester <test name> <suite name> <other suite name> <other test name> <etc>
|
|
|
|
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_<suite name>.c file, and add your
|
|
new test function. Test functions must have the following signature:
|
|
|
|
static void <test_name>(void)
|
|
|
|
<test_name> must be unique among all tests. A useful naming convention is:
|
|
|
|
static void test_<suite>_<specific name>(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_<suite name>.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(<your test function name>),
|
|
|
|
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_<suite name> or clean_<suite name> 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_<suite name>.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 <suite name>_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 <function name>(void)
|
|
|
|
The naming convention is generally:
|
|
|
|
static int init_<suite name>(void)
|
|
static int clean_<suite_name>(void)
|
|
|
|
The very last line of the file (after all the functions and the tests
|
|
array) should look like this:
|
|
|
|
CU_SuiteInfo <suite info name> = {"<suite display name>", <init function>, <clean function>, <test array>};
|
|
|
|
The naming convention is generally <suite name>_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();
|
|
<do something here>
|
|
if (strlen(cu_error_msg) > 0)
|
|
{
|
|
printf("\nError: <whatever your test was> generated an error: %s\n", cu_error_msg);
|
|
CU_FAIL();
|
|
/* be nice and clean it up for the next test. */
|
|
cu_error_msg_reset();
|
|
}
|
|
|
|
|