src/dom/test/README

   1 ELinks testing infrastructure
   2 =============================
   3
   4 This directory holds test scripts for the DOM implementation. The first part of
   5 this short document describes how to run the tests and read their output.
   6
   7 When fixing the tools or adding enhancements, you are strongly encouraged to
   8 add tests in this directory to cover what you are trying to fix or enhance.
   9 The later part of this short document describes how your test scripts should be
  10 organized.
  11
  12
  13 Running Tests
  14 -------------
  15
  16 The easiest way to run tests is to say "make test". This runs all the tests.
  17
  18     *** test-sgml-parser-basic ***
  19     *   ok 1: parse a small document.
  20     ...
  21     *   ok 23: parse a CDATA section.
  22     * passed all 23 test(s)
  23     *** test-dom-select-basic ***
  24     *   ok 1: match the root node.
  25     *   ok 2: match universal element.
  26     ...
  27
  28 Or you can run each test individually from command line, like this:
  29
  30     $ TEST_LIB=${path_to_top_srcdir}/test/libtest.sh sh ./test-sgml-parser-basic
  31     *   ok 1: parse a small document.
  32     ...
  33     *   ok 23: parse a CDATA section.
  34     * passed all 23 test(s)
  35
  36 You can pass --verbose (or -v), --debug (or -d), and --immediate (or -i)
  37 command line argument to the test.
  38
  39 --verbose::
  40         This makes the test more verbose.  Specifically, the
  41         command being run and their output if any are also
  42         output.
  43
  44 --debug::
  45         This may help the person who is developing a new test.
  46         It causes the command defined with test_debug to run.
  47
  48 --immediate::
  49         This causes the test to immediately exit upon the first
  50         failed test.
  51
  52 Note, these options can be passed indirectly to all tests when running test using
  53 make by setting TEST_OPTS, like this:
  54
  55         make test TEST_OPTS=--immediate
  56
  57 Naming Tests
  58 ------------
  59
  60 The test files should be named so that it is clear what part of the DOM
  61 implementation it is aimed for. The name MUST start with "test-" and have four
  62 hyphen separated words which name first the module, then the feature and last
  63 what the purpose of the test is (such as basic stuff or a specific use case).
  64 In short use the following as a template:
  65
  66         test-<module>-<feature>-<purpose>
  67
  68 For example test-sgml-parser-basic.
  69
  70 If you create files under test/ directory (i.e. here) that is not the top-level
  71 test script, never name the file to match the above pattern.  The Makefile here
  72 considers all such files as the top-level test script and tries to run all of
  73 them. A care is especially needed if you are creating a common test library
  74 file, similar to libtest, because such a library file may not be suitable for
  75 standalone execution.
  76
  77
  78 Writing Tests
  79 -------------
  80
  81 The test script is written as a shell script. It should start with the standard
  82 "#!/bin/sh" with copyright notices, and an assignment to variable
  83 'test_description', like this:
  84
  85         #!/bin/sh
  86         #
  87         # Copyright (c) 2005 Junio C Hamano
  88         #
  89
  90         test_description='Test the very basic feature of module foo.
  91
  92         This test runs very basic features, like checking that bar is correctly
  93         bazzed.
  94         '
  95
  96
  97 Source 'libtest'
  98 ----------------
  99
 100 After assigning test_description, the test script should source the shell test
 101 library like this:
 102
 103         . "$TEST_LIB"
 104
 105 This assumes that the TEST_LIB environment variable has been set and is needed
 106 for test to run from out of tree builds.
 107
 108 This test harness library does the following things:
 109
 110  - If the script is invoked with command line argument --help (or -h), it shows
 111    the test_description and exits.
 112
 113  - Creates an empty test directory. This directory is 'trash' if you must know,
 114    but I do not think you care.
 115
 116  - Defines standard test helper functions for your scripts to use.  These
 117    functions are designed to make all scripts behave consistently when command
 118    line arguments --verbose (or -v), --debug (or -d), and --immediate (or -i)
 119    is given.
 120
 121
 122 End with test_done
 123 ------------------
 124
 125 Your script will be a sequence of tests, using helper functions from the test
 126 harness library.  At the end of the script, call 'test_done'.
 127
 128
 129 Test harness library
 130 --------------------
 131
 132 There are a handful helper functions defined in the test harness library for
 133 your script to use.
 134
 135  - test_expect_success <message> <script>
 136
 137    This takes two strings as parameter, and evaluates the <script>. If it
 138    yields success, test is considered successful. <message> should state what
 139    it is testing.
 140
 141    Example:
 142
 143         test_expect_success \
 144             'git-write-tree should be able to write an empty tree.' \
 145             'tree=$(git-write-tree)'
 146
 147  - test_expect_failure <message> <script>
 148
 149    This is the opposite of test_expect_success. If <script> yields success,
 150    test is considered a failure.
 151
 152    Example:
 153
 154         test_expect_failure \
 155             'git-update-index without --add should fail adding.' \
 156             'git-update-index should-be-empty'
 157
 158  - test_debug <script>
 159
 160    This takes a single argument, <script>, and evaluates it only when the test
 161    script is started with --debug command line argument. This is primarily
 162    meant for use during the development of a new test script.
 163
 164  - test_done
 165
 166    Your test script must have test_done at the end. Its purpose is to summarize
 167    successes and failures in the test script and exit with an appropriate error
 168    code.
 169
 170
 171 Tips for Writing Tests
 172 ----------------------
 173
 174 As with any programming projects, existing programs are the best source of the
 175 information. So look at some of the basic test scripts for examples.