test/README

   1 __COPYRIGHT__
   2
   3 This directory contains our end-to-end SCons tests.
   4
   5 They are all meant to be run essentially standalone, with the exception
   6 of the TestSCons.py module and the other modules imported by the various
   7 tests.  These modules are in the testing/framework/ subdirectory, and PYTHONPATH
   8 needs to be set up correctly so that the test scripts can find them,
   9 and so that the SCons script itself can find the build engine modules.
  10
  11 There is a wrapper script, runtest.py, that takes care of this for you,
  12 so the canonical invocation of a test is:
  13
  14         python runtest.py test/option-x.py
  15
  16 There is also a "runtest.py -a" option that will search the tree for
  17 all tests, and execute them.
  18
  19 Some of these tests have code for features that are not yet supported.
  20
  21         commented out with a "#XXX" at the beginning of the line;
  22
  23         short-circuited entirely by having the test pass via an
  24         early call to test.pass_test(), which has a "#XXX" comment
  25         at the end of the line
  26
  27 If you're trying to implement one of these features, DO NOT BLINDLY
  28 ASSUME THAT THE NEW CODE IN THE TEST IS CORRECT.  It may have problems
  29 that have gone undiscovered due to the fact that the code testing the
  30 future feature couldn't be run yet!
  31
  32 We're not going to be dogmatic about it, but so that there's some
  33 semblance of uniformity, here are the naming conventions for tests:
  34
  35     --  All tests end with a .py suffix.
  36
  37     --  General form:
  38
  39                 Feature.py      test of specified feature; try to
  40                                 keep this description reasonably
  41                                 short
  42
  43                 Feature-x.py    test of specified feature using
  44                                 option x
  45
  46     --  Command line option tests take the form:
  47
  48                 option-x.py     lower-case single-letter option
  49
  50                 option--X.py    upper-case single-letter option
  51                                 (extra hyphen so the file names will
  52                                 be unique on case-insensitive systems)
  53
  54                 option--lo.py   long option; abbreviate the long
  55                                 option name to a few characters
  56
  57 For some more information about running the tests and writing them, please
  58 refer to the documentation for the testing framework. It can be found in
  59 the 'testing/framework' folder, as file 'test-framework.rst'.