# Common Test

### APPLICATION

common_test

### APPLICATION SUMMARY

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.

common_test 1.3.3
Copyright © 1991-2008 Ericsson AB