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 describes 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         0 - the testcase was successfully passed
  47         1 - the testcase failed
  48         2 - the testcase cannot be executed (e.g. because the needed
  49             compiler is not available)
  50
  51   - Error message:
  52     In the case of error, the file '_error' should contain more
  53     detailed description of the error.
  54
  55   - stdout and stderr: The output of testcase execution is captured
  56     and is included in the results log. It should contain useful
  57     information to ease debugging problems.
  58
  59 Rules Description
  60 -----------------
  61
  62 If the 'runtest*.rules' files are contained in the test directory,
  63 this file defines a set of Makefile.rules the particular testcase can
  64 be applied to. If there is no rules file, this testcase is applied to
  65 all the rules.
  66
  67 The rules file contains one line of one of the following forms:
  68
  69 * <rules name> - This selects only one rules file
  70
  71 * all: - this selects all the rules files
  72
  73 * snip:<snippet name> - this selects all the rules, which contain the
  74   given snippet.
  75
  76 * python:<python expression> - The python expression is evaluated. The
  77   global namespace contains the following variables:
  78
  79     - rules: the name of tested rules
  80
  81     - snippets: is of type list and contains the snippet names from
  82       which the tested rules are composed.
  83
  84   If the expression evaluates as True, the testcase is executed with
  85   this rules, otherwise it is not.
  86
  87   Example: python: "config_h" in snippets and rules != "rtems"