README
1
2The C test cases are currently (loosely) based on the CuTest harness. Loosely
3because the harness has been heavily modified from the original version.
4
5There are still a few old test cases in the source tree. Those will be
6converted to run within CuTest at some stage. New tests should all work within
7the CuTest structure.
8
9=================== BUILDING ================
10
11To build CuTest on POSIX (*nix) run "make cutest"
12
13To build CuTest on Windows load the test_cutest.vcproj project into the
14Berkeley DB solution file, and build the resulting project. It should depend
15on the Berkeley DB library (db).
16
17
18=================== RUNNING ================
19
20To run CuTest on POSIX (*nix) run:
21./cutest
22from the build_unix directory.
23
24To run CuTest on Windows run:
25
26./test_cutest.exe
27from the build_windows/Win32/Debug directory.
28
29=================== WRITING ================
30
31To write a new test case, open the relevant test suite source file under
32test/c/suites/
33
34Create a new function, with a name that begins with "Test", that returns an int
35and takes a CuTest * argument. For example:
36
37int TestExampleFunction(CuTest *ct)
38
39
40To write a new test suite (to test a different type of functionality):
41 * Create a source file in test/c/suites the name beginning with Test.
42 Of course, as with any new source file, it needs to be
43 mentioned in dist/Makefile.in and the corresponding Windows files.
44 * Include "CuTest.h" in that source file
45 * Probably include "test_util.h" in the new source file, to access
46 shared utility functions and macros.
47 * Add any test cases, conforming to the test case guidelines above.
48 * Optionally specify setup and teardown functions for the suite.
49 Named <SuiteName>SuiteSetup and <SuiteName>SuiteTeardown respectively.
50 * Optionally specify setup and teardown functions for each test case
51 in the suite. Named <SuiteName>TestSetup and <SuiteName>TestTeardown
52 respectively.
53 * Use the CuAssertXXX macros to validate behavior.
54 * See TestEnvConfig.c for an example of good practice.
55
56
57When adding a new test case or a new test suite, it's necessary to run the a
58script to regenerate the test harness wrapper. You'll need a shell script to
59do that. The script is:
60test/c/cutest/gen_tester.sh
61
62It should be run as:
63$ cd test/c/cutest
64$ ./gen_tester.sh > CuTests.c
65
66
67NOTE: A comment on naming.
68
69All tests and suites should be clearly named. Long names are fine, and more
70descriptive is generally better.
71
72A test suite should be named to reflect the component and functionality that
73is being tested.
74An individual test case should be named to identify the specific functionality
75being tested.
76It's best to avoid including SR numbers in test and suite names. Relevant SRs
77should be referenced in comments.
78
79=================== FUTURES ================a
80
81 * Add a configuration object to the setup and teardown functions, so they can
82 pass and maintain state.
83 * Fix the naming so that it's more Berkeley DB compatible (not camel case).
84 * Implement the RunTest and RunSuite functionality in test/c/cutest/CuTest.c,
85 so that it's possible to run parts of the test suite. The format will be:
86
87./cutest -s TestSuiteName -s TestSuiteName -t TestSuiteName:TestCase
88 * Implement more shared functionality in test/c/common, move the function
89 implementations from the header file in there, so shared library builds will
90 work.
91
92