Provided by: erlang-manpages_12.b.3-1_all bug

NAME

       common_test  - A framework for automatic testing of a variety of target
       nodes

DESCRIPTION

       The Common Test  framework is an environment for writing and  executing
       automatic  and semi-automatic test cases. The framework is based on the
       underlying implementation as is used with great success in  the  Visual
       Test  Server  (AXD301)  and  by  Erlang/OTP.  The main function in this
       framework is the test server which runs all the test cases.

       In brief the test server supports:

         * Running multiple test suites

         * Logging of the events in a test  suite,  on  both  suite  and  case
           levels

         * HTML presentation of test suite results

         * HTML presentation of test suite code

         * Support functions for test suite authors

         * Step by step execution

       The following sections describes the callback functions the test server
       expects to find in a test suite.  For  more  details  see  Common  Test
       User’s Guide.

TEST CASE CALLBACK FUNCTIONS

       The following functions define the callback interface for a test suite.

EXPORTS

       Module:all() -> TestCases | {skip,Reason}

              Types  TestCases = [atom() | {sequence, SeqName}]
                     Reason = term()
                     SeqName = atom()

              MANDATORY

              This function must return the list of all test cases in the test
              suite module. Each test case is represented by an atom, the name
              of the test case function.

              If {skip, Reason} is returned, all test cases in the module will
              be  skipped,  and  the Reason will be printed on the HTML result
              page.

              For details on sequences, see Dependencies  between  Test  Cases
              and Suites in the User’s Guide.

       Module:sequences() -> Sequences

              Types  Sequences = [{SeqName, Testcases}]
                     SeqName = atom()
                     Testcases = [atom()]

              OPTIONAL

              See  Dependencies  between  Test  Cases and Suites in the User’s
              Guide for details.

       Module:suite() -> [Info]

              Types    Info  =  {timetrap,  Time}  |  {require,  Required}   |
                     {require,   Name,  Required}  |  {userdata,  UserData}  |
                     {silent_connections, Conns} | {stylesheet, CSSFile}
                      Time =  MilliSec  |  {seconds,  integer()}  |  {minutes,
                     integer()} | {hours, integer()}
                      MilliSec = integer()
                      Required = Key | {Key, SubKeys}
                      Key = atom()
                      SubKeys = SubKey | [SubKey]
                      SubKey = atom()
                      Name = atom()
                      UserData = term()
                      Conns = [atom()]
                      CSSFile = string()

              OPTIONAL

              Use this function to set default data for the test suite.

       Module:init_per_suite(Config)    ->   NewConfig   |   {skip,Reason}   |
       {skip_and_save,Reason,Config}

              Types   Config = NewConfig = [{Key, Value}]
                      Key = atom()
                      Value = term()
                      Reason = term()

              OPTIONAL

              This function is called as the first test case in the suite.  It
              typically  contains  initialization which is common for all test
              cases in the suite, and which  shall  only  be  done  once.  The
              Config  parameter  is  the  configuration  which can be modified
              here. Whatever is returned from this function is given as Config
              to  all  test cases in the suite. If {skip, Reason} is returned,
              all test cases in the suite will be skipped and  Reason  printed
              in the overview log for the suite.

              For  information  on  save_config  and skip_and_save, please see
              Dependencies between Test Cases and Suites in the User’s  Guide.

       Module:end_per_suite(Config) -> void() | {save_config,Config}

              Types   Config = [{Key, Value}]
                      Key = atom()
                      Value = term()

              OPTIONAL

              This  function  is called as the last test case in the suite. It
              is meant to be used for cleaning up  after  init_per_suite.  For
              information on save_config, please see Dependencies between Test
              Cases and Suites in the User’s Guide.

       Module:init_per_testcase(TestCase, Config) -> NewConfig | {skip,Reason}

              Types   Config = NewConfig = [{Key, Value}]
                      Key = atom()
                      Value = term()
                      Reason = term()

              OPTIONAL

              This  function  is  called  before  each test case. The TestCase
              argument is the name  of  the  test  case,  and  Config  is  the
              configuration  which  can be modified here. Whatever is returned
              from this function is given as  Config  to  the  test  case.  If
              {skip,  Reason}  is  returned, the test case will be skipped and
              Reason printed in the overview log for the suite.

       Module:end_per_testcase(TestCase,     Config)     ->      void()      |
       {save_config,Config}

              Types  Config = [{Key, Value}]
                      Key = atom()
                      Value = term()

              OPTIONAL

              This function is called after each test case, and can be used to
              clean up whatever the test case has done. The  return  value  is
              ignored. For information on save_config, please see Dependencies
              between Test Cases and Suites in the User’s Guide

       Module:testcase() -> [Info]

              Types    Info  =  {timetrap,  Time}  |  {require,  Required}   |
                     {require,   Name,  Required}  |  {userdata,  UserData}  |
                     {silent_connections, Conns}
                      Time =  MilliSec  |  {seconds,  integer()}  |  {minutes,
                     integer()} | {hours, integer()}
                      MilliSec = integer()
                      Required = Key | {Key, SubKeys}
                      Key = atom()
                      SubKeys = SubKey | [SubKey]
                      SubKey = atom()
                      Name = atom()
                      UserData = term()
                      Conns = [atom()]

              OPTIONAL

              This  is  the test case info function. It shall return a list of
              tagged tuples that specify various properties regarding the test
              case.

              The  timetrap tag sets the maximum time the test case is allowed
              to take. If the timetrap time is exceeded, the test  case  fails
              with     reason    timetrap_timeout.    init_per_testcase    and
              end_per_testcase are included in the timetrap time.

              The require  tag  specifies  configuration  variables  that  are
              required  by  the  test  case.  If  the  required  configuration
              variables are not found in any of the configuration  files,  the
              test  case  is skipped. For more information about the ’require’
              functionality,  see  the  reference  manual  for  the   function
              ct:require/[1, 2].

              If  timetrap  and/or  require  is  not  set,  the default values
              specified in the suite/0 return list will be used.

              Apart from the above mentioned tags, there is no limitation  for
              which tags that can be specified in the test case info function.

       Module:testcase(Config) -> ok |  {skip,Reason}  |  {comment,Comment}  |
       {save_config,Config} | {skip_and_save,Reason,Config} | exit()

              Types  Config = [{Key, Value}]
                      Key = atom()
                      Value = term()

              MANDATORY

              This  is  the  implementation of a test case. Here you must call
              the functions you want to test, and  do  whatever  you  need  to
              check  the  result.  If  someting  fails,  make sure the process
              crashes or call  ct:fail/[0,  1]  (which  also  will  cause  the
              process to crash).

              Elements  from the Config parameter can be read with the ?config
              macro. The config macro is defined in ct.hrl

              You can return {skip, Reason} if you decide not to run the  test
              case  after  all. Reason will then be printed in ’Comment’ field
              on the HTML result page.

              You can return {comment, Comment} if  you  wish  to  print  some
              information in the ’Comment’ field on the HTML result page.

              If  the  function  returns  anything  else,  it  is considered a
              success.

              For information on save_config  and  skip_and_save,  please  see
              Dependencies  between Test Cases and Suites in the User’s Guide.