subversion/tests/README

   1
   2                 ================================
   3                  A Subversion Testing Framework
   4                 ================================
   5
   6
   7 The three goals of Subversion's automated test-suite:
   8
   9       1.  It must be easy to run.
  10       2.  It must be easy to understand the results.
  11       3.  It must be easy to add new tests.
  12
  13
  14
  15 Definition of an SVN "test program"
  16 -----------------------------------
  17
  18 A Subversion test program is any executable that contains a number of
  19 sub-tests it can run.  It has a standard interface:
  20
  21 1.  If run with a numeric argument N, the program runs sub-test N.
  22
  23 2.  If run with the argument `list', it will list the names of all sub-tests.
  24
  25 3.  If run with no arguments, the program runs *all* sub-tests.
  26
  27 4.  The program returns either 0 (success) or 1 (if any sub-test failed).
  28
  29 5.  Upon finishing a test, the program reports the results in a format
  30     which is both machine-readable (for the benefit of automatic
  31     regression tracking scripts), and human-readable (for the sake of
  32     painstaking grovelling by hand in the dead of night):
  33
  34       (PASS | FAIL): (argv[0]) (argv[1]): (description)
  35
  36 For example,
  37
  38   [sussman@newton:~] ./frobtest 2
  39   PASS: frobtest 2: frobnicating fragile data
  40   [sussman@newton:~]
  41
  42 Note that no particular programming language is required to write a
  43 set of tests;  they just needs to export this user interface.
  44
  45
  46
  47 How to write new C tests
  48 ------------------------
  49
  50 The C test framework tests library APIs, both internal and external.
  51
  52 All test programs use a standard `main' function.  You write .c files
  53 that contain only test functions --- you should not define your own
  54 `main' function.
  55
  56 Instead, your code should define an externally visible array
  57 `test_funcs', like this:
  58
  59     /* The test table.  */
  60     struct svn_test_descriptor_t test_funcs[] =
  61     {
  62       SVN_TEST_NULL,
  63       SVN_TEST_PASS(test_a),
  64       SVN_TEST_PASS(test_b),
  65       SVN_TEST_PASS(test_c),
  66       SVN_TEST_NULL
  67     };
  68
  69 In this example, `test_a', `test_b', and `test_c' are the names of
  70 test functions.  The first and last elements of the array must be
  71 SVN_TEST_NULL.  The first SVN_TEST_NULL is there to leave room for
  72 Buddha.  The standard `main' function searches for the final
  73 SVN_TEST_NULL to determine the size of the array.
  74
  75 Instead of SVN_TEST_PASS, you can use SVN_TEST_XFAIL to declare that a
  76 test is expected to fail. The status of such tests is then no longer
  77 marked as PASS or FAIL, but rather as XFAIL (eXpected FAILure) or
  78 XPASS (uneXpected PASS).
  79
  80 The purpose of XFAIL tests is to confirm that a known bug still
  81 exists. When you see such a test uneXpectedly PASS, you've probably
  82 fixed the bug it tests for, even if that wasn't your intention. :-)
  83 XFAIL is not to be used as a way of testing a deliberately invalid
  84 operation that is expected to fail when Subversion is working
  85 correctly, nor as a place-holder for a test that is not yet written.
  86
  87 Each test function conforms to the svn_test_driver_t prototype:
  88
  89         svn_error_t *f (const char **MSG,
  90                         svn_boolean_t MSG_ONLY
  91                         apr_pool_t *POOL);
  92
  93 When called, a test function should first set *MSG to a brief (as in,
  94 half-line) description of the test.  Then, if MSG_ONLY is TRUE, the
  95 test should immediately return SVN_NO_ERROR.  Else it should perform a
  96 test.  If the test passes, the function should return SVN_NO_ERROR;
  97 otherwise, it should return an error object, built using the functions
  98 in svn_error.h.
  99
 100 Once you've got a .c file with a bunch of tests and a `test_funcs'
 101 array, you should link it against the `libsvn_tests_main.la' libtool
 102 library, in this directory, `subversion/tests'.  That library provides
 103 a `main' function which will check the command-line arguments, pick
 104 the appropriate tests to run from your `test_funcs' array, and print
 105 the results in the standard way.
 106
 107
 108 How to write new Python tests
 109 -----------------------------
 110
 111 The python test framework exercises the command-line client as a
 112 "black box".
 113
 114 To write python tests, please look at the README file inside the
 115 cmdline/ subdirectory.
 116
 117
 118 When to write new tests
 119 -----------------------
 120
 121 In the world of CVS development, people have noticed that the same
 122 bugs tend to recur over and over.  Thus the CVS community has adopted
 123 a hard-and-fast rule that whenever somebody fixes a bug, a *new* test
 124 is added to the suite to specifically check for it.  It's a common
 125 case that in the process of fixing a bug, several old bugs are
 126 accidentally resurrected... and then quickly revealed by the test
 127 suite.
 128
 129 This same rule applies to Subversion development: ** If you fix a
 130 bug, write a test for it. **
 131
 132
 133 What not to test
 134 ----------------
 135
 136 Regression tests are for testing interface promises.  This might
 137 include semi-private interfaces (such as the non-public .h files
 138 inside module subdirs), but does not include implementation details
 139 behind the interfaces.  For example, this is a good way to test
 140 svn_fs_txn_name:
 141
 142       /* Test that svn_fs_txn_name fulfills its promise. */
 143       char *txn_name = NULL;
 144       SVN_ERR = svn_fs_txn_name (&txn_name, txn, pool);
 145       if (txn_name == NULL)
 146         return fail();
 147
 148 But this is not:
 149
 150       /* Test that the txn got id "0", since it's the first txn. */
 151       char *txn_name = NULL;
 152       SVN_ERR = svn_fs_txn_name (&txn_name, txn, pool);
 153       if (txn_name && (strcmp (txn_name, "0") != 0))
 154         return fail();
 155
 156 During development, it may sometimes be very convenient to
 157 *temporarily* test implementation details via the regular test suite.
 158 It's okay to do that, but please remove the test when you're done and
 159 make sure it's clearly marked in the meantime.  Since implementation
 160 details are not interface promises, they might legitimately change --
 161 and when they change, that test will break.  At which point whoever
 162 encountered the problem will look into the test suite and find the
 163 temporary test you forgot to remove.  As long as it's marked like
 164 this...
 165
 166       /* Temporary test for debugging only: Test that the txn got id
 167        * "0", since it's the first txn.
 168        * NOTE: If the test suite is failing because of this test, then
 169        * just remove the test.  It was written to help me debug an
 170        * implementation detail that might have changed by now, so its
 171        * failure does not necessarily mean there's anything wrong with
 172        * Subversion. */
 173       char *txn_name = NULL;
 174       SVN_ERR = svn_fs_txn_name (&txn_name, txn, pool);
 175       if (txn_name && (strcmp (txn_name, "0") != 0))
 176         return fail();
 177
 178 ...then they won't have wasted much time.
 179
 180
 181 What's here
 182 -----------
 183
 184    * svn_test_main.c
 185      [shared library "libsvn_tests_main"]
 186      A standardized main() function to drive tests.  Link this into
 187      your automated test-programs.
 188
 189    * svn_test_editor.c
 190      [shared library "libsvn_tests_editor"]
 191      An editor for testing drivers of svn_delta_edit_fns_t.  This
 192      editor's functions simply print information to stdout.
 193
 194    * cmdline/
 195      A collection of python scripts to test the command-line client.
 196
 197
 198 `make check`
 199 ------------
 200
 201 The file `build.conf' (at the top level of the tree) defines a
 202 [test-scripts] section.  These are a list of scripts that will be run
 203 whenever someone types `make check`.
 204
 205 Each script is expected to output sub-test information as described in
 206 the first section of this document;  the `make check` rule scans for
 207 FAIL codes, and logs all the sub-test output into a top-level file
 208 called `tests.log'.
 209
 210 If you write a new C executable that contains subtests, be sure to add
 211 a build "target" under the TESTING TARGETS section of build.conf.
 212
 213 If you write a new python-script, be sure to add to the [test-scripts]
 214 section.
 215
 216
 217 Testing Over DAV
 218 ----------------
 219
 220 Please see subversion/tests/cmdline/README for how to run the
 221 command-line client test suite against a remote repository.
 222
 223 Conclusion
 224 ----------
 225
 226 Our test suite...
 227
 228
 229   1.  ...must be easy to run.
 230
 231       * run `make check`
 232
 233   2.  ...must be easy to understand the results.
 234
 235       * test programs output standardized messages
 236       * all messages are logged
 237       * `make check` only displays errors (not successes!)
 238
 239   3.  ...must be easy to add new tests.
 240
 241       * add your own sub-test to an existing test program, or
 242       * add a new test program using template C or python code.