tests/README.test_maintainers.txt

   1
   2 The following is provided as a reference for those interested in understanding
   3 how the test suite works, and how to add and maintain tests.
   4
   5 Overview of types of tests
   6 ==========================
   7
   8 Darcs has tests in two formats.  Unit tests that directly test Haskell
   9 functions are written in Haskell and live in src/unit.lhs.  Functional
  10 tests that test the darcs binary are written in Shell and live in
  11 tests/. Additionally, there are some functional tests which are
  12 expected to fail, kept in bugs/ and used for documenting bugs and todos.
  13
  14 Haskell tests
  15 --------------------------
  16
  17 These are QuickCheck tests primarily testing the Darcs core.
  18
  19 Shell tests
  20 ---------------------------
  21
  22 Shell tests are useful because they are easy to create from a copy/paste
  23 of actual shell commands executed. They are considered successful if no
  24 bad exit codes are returned from the commands in the script.
  25
  26 How to run tests
  27 =============================
  28
  29 "make unit" builds the unit tests, "./unit" runs them. They take a while.
  30 Output like "good" and "OK, passed 100 tests." is good. Output like
  31 "*** Gave up! Passed only n tests." is a shortage of quickcheck test
  32 cases, not a test failure.
  33
  34 "make test" causes all the functional tests in "tests/" to be run against
  35 repositories in the old, hashed, and darcs2 formats.
  36
  37 "make bugs" runs the scripts in "bugs/", also on all three types of
  38 repository, with the expectation that they currently fail.
  39
  40 Because "make test" can take a long time to run, it's useful to run fewer
  41 tests at once.  To help with that, the following make targets are also
  42 available:
  43
  44   make test-old        # darcs1 old format
  45   make test-hashed     # darcs1 hashed format
  46   make test-format2    # darcs2 hashed format
  47   make bugs-old
  48   make bugs-hashed
  49   make bugs-format2
  50
  51
  52 Running specific tests
  53 ------------------------------
  54
  55 Add test file names to tests_to_run to do only those tests:
  56
  57   echo annotate.pl > tests/tests_to_run
  58   echo annotate.sh >> tests/tests_to_run
  59   make test-old # or whichever you like!
  60
  61
  62 Running a single test
  63 -----------------------------
  64
  65 Shell tests are run with the shell_harness script:
  66
  67   perl shell_harness annotate.sh
  68
  69 ("chmod +x shell_harness" to use it directly.)
  70
  71
  72 Tips for writing (and reading) tests
  73 ====================================
  74
  75 - Avoid including a repo format type to "darcs init"
  76   This insures that all three repo formats will be tested.
  77   However, if you know that the test only passes under some
  78   repo formats, *do* explicity include a format option to "darcs init".
  79
  80
  81 Tips for writing tests
  82 ----------------------
  83
  84 - Copy an existing test, which will already have the following properties:
  85
  86 - Simply call darcs using "darcs" as you would in the shell.  It is the
  87   responsibility of the test harness to ensure that the darcs we are
  88   testing is first in the path.
  89
  90 - Always use bash explicitly--this improves the portability of our tests.
  91
  92 - Always add this near the top of the script:
  93
  94    set -ev
  95
  96   The "v" causes the contents of the script to be printed as part of the run,
  97   which is helpful for debugging.  The "e" causes the script to exit as soon as
  98   there is an error.
  99
 100 - Try to avoid defining functions where possible.  This makes them
 101   harder to run and generally harder to use.  There are certainly cases
 102   where it is appropriate to define a function, but please do not do
 103   this just to avoid a little duplication.