tools/testing/selftests/tc-testing/creating-plugins/AddingPlugins.txt

   1 tdc - Adding plugins for tdc
   2
   3 Author: Brenda J. Butler - bjb@mojatatu.com
   4
   5 ADDING PLUGINS
   6 --------------
   7
   8 A new plugin should be written in python as a class that inherits from TdcPlugin.
   9 There are some examples in plugin-lib.
  10
  11 The plugin can be used to add functionality to the test framework,
  12 such as:
  13
  14 - adding commands to be run before and/or after the test suite
  15 - adding commands to be run before and/or after the test cases
  16 - adding commands to be run before and/or after the execute phase of the test cases
  17 - ability to alter the command to be run in any phase:
  18     pre        (the pre-suite stage)
  19     prepare
  20     execute
  21     verify
  22     teardown
  23     post       (the post-suite stage)
  24 - ability to add to the command line args, and use them at run time
  25
  26
  27 The functions in the class should follow the following interfaces:
  28
  29     def __init__(self)
  30     def pre_suite(self, testcount, testidlist)     # see "PRE_SUITE" below
  31     def post_suite(self, ordinal)                  # see "SKIPPING" below
  32     def pre_case(self, test_ordinal, testid)       # see "PRE_CASE" below
  33     def post_case(self)
  34     def pre_execute(self)
  35     def post_execute(self)
  36     def adjust_command(self, stage, command)       # see "ADJUST" below
  37     def add_args(self, parser)                     # see "ADD_ARGS" below
  38     def check_args(self, args, remaining)          # see "CHECK_ARGS" below
  39
  40
  41 PRE_SUITE
  42
  43 This method takes a testcount (number of tests to be run) and
  44 testidlist (array of test ids for tests that will be run).  This is
  45 useful for various things, including when an exception occurs and the
  46 rest of the tests must be skipped.  The info is stored in the object,
  47 and the post_suite method can refer to it when dumping the "skipped"
  48 TAP output.  The tdc.py script will do that for the test suite as
  49 defined in the test case, but if the plugin is being used to run extra
  50 tests on each test (eg, check for memory leaks on associated
  51 co-processes) then that other tap output can be generated in the
  52 post-suite method using this info passed in to the pre_suite method.
  53
  54
  55 SKIPPING
  56
  57 The post_suite method will receive the ordinal number of the last
  58 test to be attempted.  It can use this info when outputting
  59 the TAP output for the extra test cases.
  60
  61
  62 PRE_CASE
  63
  64 The pre_case method will receive the ordinal number of the test
  65 and the test id.  Useful for outputing the extra test results.
  66
  67
  68 ADJUST
  69
  70 The adjust_command method receives a string representing
  71 the execution stage and a string which is the actual command to be
  72 executed.  The plugin can adjust the command, based on the stage of
  73 execution.
  74
  75 The stages are represented by the following strings:
  76
  77     'pre'
  78     'setup'
  79     'command'
  80     'verify'
  81     'teardown'
  82     'post'
  83
  84 The adjust_command method must return the adjusted command so tdc
  85 can use it.
  86
  87
  88 ADD_ARGS
  89
  90 The add_args method receives the argparser object and can add
  91 arguments to it.  Care should be taken that the new arguments do not
  92 conflict with any from tdc.py or from other plugins that will be used
  93 concurrently.
  94
  95 The add_args method should return the argparser object.
  96
  97
  98 CHECK_ARGS
  99
 100 The check_args method is so that the plugin can do validation on
 101 the args, if needed.  If there is a problem, and Exception should
 102 be raised, with a string that explains the problem.
 103
 104 eg:  raise Exception('plugin xxx, arg -y is wrong, fix it')