tests/README.tests

   1 Description of Testcases for OMK
   2 ================================
   3
   4 Each test resides in a separate directory. Every directory can
   5 contains multiple testcases. The directories can be nested. There is
   6 no difference between the tests in different levels of directory
   7 structure.
   8
   9 Structure of a Testcase
  10 -----------------------
  11
  12 A directory contains a testcase if it contains at least one file that
  13 matches runtest* pattern (files ending with "~" or ".rules" are not
  14 counted).
  15
  16 * Testcase Definition:
  17
  18   Each test is represented by a set of files. Some of these files are
  19   used as "data" files for the test (e.g. source code, config.omk,
  20   etc.) and some files controls how is the test run. Here follows the
  21   description of control files in the test directory.
  22
  23   - runtest*: is the executable that runs the test(s). It is possible
  24     to have more files in a test directory, whose name starts with
  25     `runtest'. In that case all these files will be executed in
  26     alphabetical order as separate testcases. The goal is to be able
  27     to run several tests on the same structure of files and
  28     directories.
  29
  30   - runtest*.rules: Specifies the set of rules the testcase applies
  31     to. If there is more runtest files, every testcase can have its
  32     own .rules file. The syntax of this files is described in section
  33     `Rules description'.
  34
  35 * Testcase Execution:
  36
  37   Runtest is executed with OMK_RULES environment variable set to the
  38   name of the actual rules tested and OMK_TESTSROOT to the directory
  39   containing the `tester.py' script.
  40
  41 * Testcase Output:
  42
  43   Each execution of testcase should produce the following outputs:
  44
  45   - Exit status of make or runtest:
  46         zero - the testcase was successfully passed
  47         other than zero - the testcase failed or cannot be executed
  48                           (e.g. because the needed compiler is not
  49                           available)
  50
  51   - Error message:
  52     In the case of nonzero exit status, if file '_canttest' exists in
  53     the same directory as Makefile.rules, it is considered that the
  54     test cannot be executed (i.e. the compiler is missing) and the
  55     content of that file is provided as error message in results
  56     log. Otherwise, the test is considered as failed and file '_error'
  57     can contain more detailed description of the error.
  58
  59   - stdout and stderr: The output of testcase execution is captured
  60     and is included in the results log. It should contain useful
  61     information to ease the debugging process.
  62
  63 Rules Description
  64 -----------------
  65
  66 If the 'runtest*.rules' files are contained in the test directory,
  67 this file defines a set of Makefile.rules the particular testcase can
  68 be applied to. If there is no rules file, this testcase is applied to
  69 all the rules.
  70
  71 The rules file contains one line of one of the following forms:
  72
  73 * <rules name> - This selects only one rules file
  74
  75 * all: - this selects all the rules files
  76
  77 * snip:<snippet name> - this selects all the rules, which contain the
  78   given snippet.
  79
  80 * python:<python expression> - The python expression is evaluated. The
  81   global namespace contains the following variables:
  82
  83     - rules: the name of tested rules
  84
  85     - snippets: is of type list and contains the snippet names from
  86       which the tested rules are composed.
  87
  88   If the expression evaluates as True, the testcase is executed with
  89   this rules, otherwise it is not.
  90
  91   Example: python: "config_h" in snippets and rules != "rtems"