Common Test
Common Test
version 1.3
Typeset in LATEX from SGML source using the DocBuilder-0.9.8.4 Document System.
Contents
iv Common Test
2 Common Test Reference Manual 37
2.1 Common Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
2.2 The run test shell script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
2.3 ct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
2.4 ct cover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
2.5 ct ftp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
2.6 ct master . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
2.7 ct rpc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
2.8 ct snmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
2.9 ct telnet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
2.10 unix telnet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Common Test v
vi Common Test
Chapter 1
Common Test is a portable application for automated testing. It is suitable for black-box testing of target
systems of any type (i.e. not necessarily implemented in Erlang), as well as for white-box testing of
Erlang/OTP programs. Black-box testing is performed via standard O&M interfaces (such as SNMP,
HTTP, Corba, Telnet, etc) and, if required, via user specific interfaces (often called test ports).
White-box testing of Erlang/OTP programs is easily accomplished by calling the target API functions
directly from the test case functions. Common Test also integrates usage of the OTP cover tool for code
coverage analysis of Erlang/OTP programs.
Common Test executes test suite programs automatically, without operator interaction. Test progress
and results is printed to logs on HTML format, easily browsed with a standard web browser. Common
Test also sends notifications about progress and results via an OTP event manager to event handlers
plugged in to the system. This way users can integrate their own programs for e.g. logging, database
storing or supervision with Common Test.
Common Test provides libraries that contain useful support functions to fill various testing needs and
requirements. There is for example support for flexible test declarations by means of so called test
specifications. There is also support for central configuration and control of multiple independent test
sessions (towards different target systems) running in parallel.
Common Test is implemented as a framework based on the OTP Test Server application.
Common Test 1
Chapter 1: Common Test User’s Guide
The main idea is that CT based test programs connect to the target system(s) via standard O&M
interfaces. CT provides implementations and wrappers of some of these O&M interfaces and will be
extended with more interfaces later. There are a number of target independent interfaces supported in
CT such as Generic Telnet, FTP etc. which can be specialized or used directly for controlling
instruments, traffic generators etc.
For white-box testing of Erlang code, the test programs can of course call Erlang API functions directly.
Black-box testing of Erlang code can use Erlang RPC as well as standard O&M interfaces if desired.
A test case can handle several connections towards one or several target systems, instruments and traffic
generators in parallel in order to perform the necessary actions for a test. The handling of many
connections in parallel is one of the major strengths of CT!
2 Common Test
1.2: Installation
As a test suite runs, all information (including output to stdout) is recorded in several different log files.
A minimum of information is displayed in the user console (only start and stop information, plus a note
for each failed test case).
The result from each test case is recorded in an HTML log file which is created for the particular test
run. Each test case is represented by a row in a table that shows the total execution time, whether the
case was successful or if it failed or was skipped, plus a possible user comment. For a failed test case, the
reason for termination is printed. The HTML file has a link to the logfile for each test case (which may
also be viewed with an HTML browser).
For each test case the CT test server needs these functions:
1.2 Installation
1.2.1 Unix
Copy the Common Test and Test Server application directories, common test-<vsn> and
test server-<vsn>, to a location of your choice. They do not have to be placed among the Erlang
applications under the OTP lib directory, nor do they need to have a particular path relative to your test
suite modules. In the Common Test directory you find the shell script install.sh. Execute this script
to generate the Common Test start script run test in the sub directory
common test-<vsn>/priv/bin.
install.sh takes one input parameter which specifies the absolute path to the top directory of
Common Test and Test Server. (This path is inserted in the run test script so that when the script
starts Erlang, the Erlang code server will be able to load the Common Test and Test Server application
modules). Example (assuming Common Test and Test Server have been placed in
/usr/local/test tools):
$ install.sh /usr/local/test tools
Note that the common test-<vsn> and test server-<vsn> directories must be located under the
same top directory for the installation to work properly. Note also that the install script does not e.g.
copy files or update environment variables. It only generates the run test script.
If the directories are later moved, make sure to run install.sh again or edit the run test script
(Bourne shell) manually.
Common Test 3
Chapter 1: Common Test User’s Guide
For more information on the run test script, please see the reference manual.
1.2.2 Windows
On Windows it is very convenient to use Cygwin (www.cygwin.com) for running Common Test and
Erlang, since it enables you to use the run test script for starting Common Test. If you are a Cygwin
user, simply follow the instructions for installing Common Test on Unix above.
If you do not use Cygwin, you have to rely on the API functions in the ct module (instead of run test)
for running Common Test. In this case you do not need to install Common Test (i.e. no need to
generate the run test script). Simply copy the common test-<vsn> and test server-<vsn>
directories to a location of your choice. They do not have to be placed among the Erlang applications
under the OTP lib directory, nor do they need to have a particular path relative to your test suite
modules.
When you start the Erlang node on which you will be running Common Test, make sure the Common
Test and Test Server ebin directories are included in the Erlang code server path (so the application
modules can be loaded). If you do copy the application directories to the OTP lib directory, there is no
need to explicitly update the code server path as the code server will be able to locate the modules
automatically.
Please turn to the reference manual for the ct module for details about these functions.
The CT application also includes other modules named ct <something> that provide support for the
use of communication mechanisms such as rpc, snmp, ftp, telnet etc in test suites.
4 Common Test
1.3: Writing Test Suites
Common Test 5
Chapter 1: Common Test User’s Guide
Note:
The test case function argument Config should not be confused with the information that can be
retrieved from configuration files (using ct:get config/[1,2]). The Config argument should be used for
runtime configuration of the test suite and the test cases. A configuration file should contain data
related to the SUT (system under test). These two types of config data are handled differently!
All Config items can be extracted using the ?config macro, e.g PrivDir =
?config(priv dir,Config).
If the test case function crashes or exits, it is considered a failure. If it returns a value (no matter what
actual value) it is considered a success. An exception to this rule is the return value fskip,Reasong. If
this is returned, the test case is considered skipped and gets logged as such.
If the test case returns the tuple fcomment,Commentg, Comment is printed out in the overview log (this is
equal to calling ct:comment(Comment)).
timetrap Set the maximum time the test case is allowed to take. If the timetrap time is exceeded, the
test case fails with reason timetrap timeout. Note that init per testcase and
end per testcase are included in the timetrap time.
userdata Use this to specify arbitrary data related to the testcase. This data can be retrieved at any
time using the ct:userdata/3 utility function.
silent connections Please see the Silent Connections [page 21] chapter for details.
require Use this to specify configuration variables that are required by the test case. If the required
configuration variables are not found in any of the test system configuration files, the test case is
skipped.
It is also possible to give a required variable a default value that will be used if the variable is not
found in any configuration file. To specify a default value, start by adding a normal require-tuple
to the list for the variable in question and then let the key-value definition for the variable follow.
The definition should have the same form as in the configuration file. Example:
my testcase() ->
[frequire, unix telnet, funix, [telnet, username, password]gg,
funix telnet, funix, [ftelnet, "durin.du.uab"g,
fusername, "alladin"g,
fpassword, "sesame"g]gg].
Note:
Giving a required variable a default value can result in that a test case is always run. For many types
of configuration values this is not a desired behavior.
6 Common Test
1.3: Writing Test Suites
If timetrap and/or require is not set specifically for a particular test case, default values specified by
the suite/0 function are used.
Other tags than the ones mentioned above will simply be ignored by the test server.
Example:
Example:
suite() ->
[
ftimetrap,fminutes,10gg,
frequire,global namesg,
fuserdata,[finfo,"This suite tests database transactions."g]g,
fsilent connections,[telnet]g,
fstylesheet,"db testing.css"g
].
Common Test 7
Chapter 1: Common Test User’s Guide
Note:
You should not depend on current working directory for reading and writing data files since this is
not portable. All scratch files are to be written in the priv dir and all data files should be located in
data dir. If you do need to use the current working directory, you must set it explicitly with
file:set cwd/1 for each individual test case before use. (The Common Test server sets current
working directory to the test case log directory at the start of every case).
8 Common Test
1.4: Test Structure
Using skip suites and skip cases terms in test specifications [page 15].
Returning fskip,Reasong from the init per testcase/2 or init per suite/1 functions.
Returning fskip,Reasong from the execution clause of the test case.
The latter of course means that the execution clause is actually called, so the author must make sure
that the test case is not run.
When a test case is skipped, it will be noted as SKIPPED in the HTML log.
Common Test 9
Chapter 1: Common Test User’s Guide
1.5 Examples
1.5.1 Test suite
The example test suite shows some tests of an HTTP client that uses a proxy.
-module(httpc_proxy_SUITE).
-include("ct.hrl").
-define(URL, "http://www.erlang.org").
-define(PROXY, "www-proxy.ericsson.se").
-define(PROXY_PORT, 8080).
%%--------------------------------------------------------------------
%% Test server callback functions
%%--------------------------------------------------------------------
%%--------------------------------------------------------------------
%% Function: suite() -> DefaultData
%% DefaultData: [tuple()]
%% Description: Require variables and set default values for the suite
%%--------------------------------------------------------------------
suite() -> [{timetrap,{minutes,1}}].
%%--------------------------------------------------------------------
%% Function: init_per_suite(Config) -> Config
%% Config: [tuple()]
%% A list of key/value pairs, holding the test case configuration.
%% Description: Initiation before the whole suite
%%
%% Note: This function is free to add any key/value pairs to the Config
%% variable, but should NOT alter/remove any existing entries.
%%--------------------------------------------------------------------
init_per_suite(Config) ->
application:start(inets),
http:set_options([{proxy, {{?PROXY, ?PROXY_PORT}, ["localhost"]}}]),
Config.
%%--------------------------------------------------------------------
%% Function: end_per_suite(Config) -> _
%% Config: [tuple()]
%% A list of key/value pairs, holding the test case configuration.
%% Description: Cleanup after the whole suite
%%--------------------------------------------------------------------
end_per_suite(_Config) ->
application:stop(inets),
ok.
%%--------------------------------------------------------------------
10 Common Test
1.5: Examples
%%-------------------------------------------------------------------------
%% Test cases starts here.
%%-------------------------------------------------------------------------
options() ->
[{userdata,[{doc,"Perform an OPTIONS request that goes through a proxy."}]}].
options(_Config) ->
{ok, {{_,200,_}, Headers, _}} =
http:request(options, {?URL, []}, [], []),
case lists:keysearch("allow", 1, Headers) of
{value, {"allow", _}} ->
ok;
_ ->
ct:fail(http_options_request_failed)
end.
head() ->
[{userdata,[{doc,"Perform a HEAD request that goes through a proxy."}]}].
head(_Config) ->
{ok, {{_,200, _}, [_ | _], []}} =
http:request(head, {?URL, []}, [], []).
get() ->
[{userdata,[{doc, "Perform a GET request that goes through a proxy."}]}].
get(_Config) ->
{ok, {{_,200,_}, [_ | _], Body = [_ | _]}} =
http:request(get, {?URL, []}, [], []),
check_body(Body).
trace() ->
[{userdata,[{doc, "Perform a TRACE request that goes through a proxy."}]}].
trace(_Config) ->
{ok, {{_,200,_}, [_ | _], "TRACE /" ++ _}} =
http:request(trace, {?URL, []}, [], []),
ok.
%%--------------------------------------------------------------------
%% Internal functions
%%--------------------------------------------------------------------
Common Test 11
Chapter 1: Common Test User’s Guide
check_body(Body) ->
case string:rstr(Body, "\html>") of
0 ->
ct:fail(did_not_receive_whole_body);
_ ->
ok
end.
12 Common Test
1.6: Running Test Suites
Examples:
$ run test -config $CFGS/sys1.cfg $CFGS/sys2.cfg -dir $SYS1 TEST $SYS2 TEST
$ run test -suite $SYS1 TEST/setup SUITE $SYS2 TEST/config SUITE
$ run test -suite $SYS1 TEST/setup SUITE -case start stop
Other flags that may be used with run test:
-logdir <dir>, specifies where the HTML log files are to be written.
-refresh logs, refreshes the top level HTML index files.
-vts, start web based GUI (see below).
-shell, start interactive shell mode (see below).
-spec <testspecs>, use test specification as input (see below).
-allow user terms, allows user specific terms in a test specification (see below).
-silent connections [conn types], tells Common Test to suppress printouts for specified
connections (see below).
-stylesheet <css file>, points out a user HTML style sheet (see below).
-cover <cover cfg file>, to perform code coverage test (see Code Coverage Analysis [page
23]).
-event handler <event handlers>, to install event handlers [page 27].
-repeat <n>, tells Common Test to repeat the tests n times (see below).
-duration <time>, tells Common Test to repeat the tests for duration of time (see below).
-until <stop time>, tells Common Test to repeat the tests until stop time (see below).
-force stop, on timeout, the test run will be aborted when current test job is finished (see
below).
Common Test 13
Chapter 1: Common Test User’s Guide
If no specific browser start command is specified, netscape will be the default browser on UNIX
platforms and Internet Explorer on Windows. For the VTS mode to work properly with netscape, make
sure the netscape program in your path starts version 7!
> ct:require(a,funix,[telnet]g).
ok
> ct:cmd(a,"ls").
fok,["ls","file1 ...",...]g
Everything that Common Test normally prints in the test case logs, will in the interactive mode be
written to a log named ctlog.html in the ct run.<timestamp> directory. A link to this file will be
available in the file named last interactive.html in the directory from which you executed
run test.
If you for some reason want to exit the interactive mode, use the function ct:stop interactive/0.
This shuts down the running ct application. Associations between configuration names and data
created with require are consequently deleted. ct:start interactive/0 will get you back into
interactive mode, but previous state is not restored.
14 Common Test
1.6: Running Test Suites
fcover, CoverSpecFileg.
fcover, NodeRef, CoverSpecFileg.
fconfig, ConfigFilesg.
fconfig, NodeRefs, ConfigFilesg.
flogdir, LogDirg.
flogdir, NodeRefs, LogDirg.
Test terms:
Common Test 15
Chapter 1: Common Test User’s Guide
Types:
NodeAlias = atom()
Node = node()
NodeRef = NodeAlias | Node | master
NodeRefs = all nodes | [NodeRef] | NodeRef
CoverSpecFile = string()
ConfigFiles = string() | [string()]
DirAlias = atom()
Dir = string()
LogDir = string()
EventHandlers = atom() | [atom()]
InitArgs = [term()]
DirRef = DirAlias | Dir
Suites = atom() | [atom()] | all
Cases = atom() | [atom()] | all
Comment = string() | ""
Example:
flogdir, "/home/test/logs"g.
fconfig, "/home/test/t1/cfg/config.cfg"g.
fconfig, "/home/test/t2/cfg/config.cfg"g.
fconfig, "/home/test/t3/cfg/config.cfg"g.
The specified logdir directory will be used for storing the HTML log files (in subdirectories tagged
with node name, date and time).
The variables in the specified test system config files will be imported for the test.
16 Common Test
1.6: Running Test Suites
Aliases are given for three test system directories. The suites in this example are stored in
“/home/test/tX/test”.
The first test to run includes all suites for system t1. Excluded from the test are however the t1B
and t1D suites. Also test cases test3 and test4 in t1A as well as the test1 case in t1C are excluded
from the test.
Secondly, the test for system t2 should run. The included suites are t2B and t2C. Included are also
test cases test4, test1 and test7 in suite t2A. Note that the test cases will be executed in the
specified order.
Lastly, all suites for systems t3 are to be completely skipped and this should be explicitly noted in
the log files.
It is possible for the user to provide a test specification that includes (for Common Test) unrecognizable
terms. If this is desired, the -allow user terms flag should be used when starting tests with run test.
This forces Common Test to ignore unrecognizable terms. Note that in this mode, Common Test is not
able to check the specification for errors as efficiently as if the scanner runs in default mode. If
ct:run test/1 is used for starting the tests, the relaxed scanner mode is enabled by means of the tuple:
fallow user terms,trueg
Typically the operator, who may run hundreds or thousands of test cases, doesn’t want to fill the screen
with details about/from the specific test cases. By default, the operator will only see:
A confirmation that the test has started and information about how many test cases will be
executed totally.
A small note about each failed test case.
A summary of all the run test cases.
A confirmation that the test run is complete.
Some special information like error reports and progress reports, printouts written with
erlang:display/1 or io:format/3 specifically addressed to somewhere other than standard io.
This is enough for the operator to know, and if he wants to dig in deeper into a specific test case result,
he can do so by following the links in the HTML presentation to take a look in the major or minor log
files. The “all runs.html” page is a practical starting point usually. It’s located in logdir and contains a
link to each test run including a quick overview (date and time, node name, number of tests, test names
and test result totals).
An “index.html” page is written for each test run (i.e. stored in the “ct run” directory tagged with node
name, date and time). This file gives a short overview of all individual tests performed in the same test
run. The test names follow this convention:
Common Test 17
Chapter 1: Common Test User’s Guide
On the test run index page there is a link to the Common Test Framework log file in which information
about imported configuration data and general test progress is written. This log file is useful to get
snapshot information about the test run during execution. It can also be very helpful when analyzing
test results or debugging test suites.
On the test run index page it is noted if a test has missing suites (i.e. suites that Common Test has failed
to compile). Names of the missing suites can be found in the Common Test Framework log file.
A detailed report of the test run is stored in the major logfile (textual log file). This includes test suite
and test case names, execution time, the exact reason for failure etc. There is an HTML log file that
corresponds to this textual file. The HTML file is a summary which gives a better overview of the test
run. It also has links to each individual test case log file for quick viewing with an HTML browser.
The minor log file contain full details of every single test case, each one in a separate file. This way the
files should be easy to compare with previous test runs, even if the set of test cases change.
Which information goes where is user configurable via the test server controller. Three threshold values
determine what comes out on screen, and in the major or minor log files. See the OTP Test Server
manual for information. The contents that goes to the HTML log file is fixed however and cannot be
altered.
The log files are written continously during a test run and links are always created initially when a test
starts. This makes it possible to follow test progress simply by refreshing pages in the HTML browser.
Statistics totals are not presented until a test is complete however.
<style>
div.ct internal f background:lightgrey; color:black g
div.default f background:lightgreen; color:black g
div.sys config f background:blue; color:white g
div.sys state f background:yellow; color:black g
div.error f background:red; color:white g
</style>
To install the CSS file (Common Test inlines the definition in the HTML code), the name may be
provided when executing run test. Example:
18 Common Test
1.6: Running Test Suites
Categories in a CSS file installed with the -stylesheet flag are on a global test level in the sense that
they can be used in any suite which is part of the test run.
It is also possible to install style sheets on a per suite and per test case basis. Example:
-module(my SUITE).
...
suite() -> [..., fstylesheet,"suite categories.css"g, ...].
...
my testcase( ) ->
...
ct:log(sys config, "Test node version: ~p", [VersionInfo]),
...
ct:log(sys state, "Connections: ~p", [ConnectionInfo]),
...
ct:pal(error, "Error ~p detected! Info: ~p", [SomeFault,ErrorInfo]),
ct:fail(SomeFault).
If the style sheet is installed as in this example, the categories are private to the suite in question. They
can be used by all test cases in the suite, but can not be used by other suites. A suite private style sheet,
if specified, will be used in favour of a global style sheet (one specified with the -stylesheet flag). A
stylesheet tuple (as returned by suite/0 above) can also be returned from a test case info function. In
this case the categories specified in the style sheet can only be used in that particular test case. A test
case private style sheet is used in favour of a suite or global level style sheet.
In a tuple fstylesheet,CSSFileg, if CSSFile is specified with a path, e.g.
"$TEST/styles/categories.css", this full name will be used to locate the file. If only the file name is
specified however, e.g. “categories.css”, then the CSS file is assumed to be located in the data directory,
data dir, of the suite. The latter usage is recommended since it is portable compared to hard coding
path names in the suite!
The Category argument in the example above may have the value (atom) sys config (white on blue),
sys state (black on yellow) or error (white on red).
If the Category argument is not specified, Common Test will use the CSS selector div.default for the
printout. For this reason a user supplied style sheet must include this selector. Also the selector
div.ct internal must be included. Hence a minimal user style sheet should look like this (which is
also the default style sheet Common Test uses if no user CSS file is provided):
<style>
div.ct internal f background:lightgrey; color:black g
div.default f background:lightgreen; color:black g
</style>
Common Test 19
Chapter 1: Common Test User’s Guide
$ run test -dir $TEST ROOT/to1 $TEST ROOT/to2 -duration 001000 -force stop
Here the suites in test directory to1, followed by the suites in to2, will be executed in one test run. A
timeout event will occur after 10 minutes. As long as there is time left, Common Test will repeat the
test run (i.e. starting over with the to1 test). When the timeout occurs, Common Test will stop as soon
as the current job is finished (because of the force stop flag). As a result, the specified test run might
be aborted after the to1 test and before the to2 test.
Example 2:
$ date
Fri Sep 28 15:00:00 MEST 2007
Here the same test run as in the example above will be executed (and possibly repeated). In this
example, however, the timeout will occur after 1 hour and when that happens, Common Test will finish
the entire test run before stopping (i.e. the to1 and to2 test will always both be executed in the same
test run).
Example 3:
Here the test run, including both the to1 and the to2 test, will be repeated 5 times.
20 Common Test
1.6: Running Test Suites
-module(my SUITE).
...
suite() -> [..., fsilent connections,[telnet,ftp]g, ...].
...
my testcase1() ->
[fsilent connections,[ftp]g].
my testcase1( ) ->
...
my testcase2( ) ->
...
In this example, suite/0 tells Common Test to suppress printouts from telnet and ftp connections.
This is valid for all test cases. However, my testcase1/0 specifies that for this test case, only ftp should
be silent. The result is that my testcase1 will get telnet info (if any) printed in the log, but not ftp info.
my testcase2 will get no info from either connection printed.
The -silent connections tag (or silent connections tagged tuple in the call to ct:run test/1)
overrides any settings in the test suite.
Note that in the current Common Test version, the silent connections feature only works for telnet
connections. Support for other connection types will be added in future Common Test versions.
Common Test 21
Chapter 1: Common Test User’s Guide
1.7.2 Syntax
A config file can contain any number of elements of the type:
fKey,Valueg.
where
Key = atom()
Value = term() | [fKey,Valueg]
1.7.4 Examples
A config file for usning telnet to communicate with a unix host could look like this:
funix,[ftelnet,"durin.du.uab"g,
fusername,"someuser"g,
fpassword,"somepassword"g]g.
22 Common Test
1.8: Code Coverage Analysis
1.8.2 Usage
To specify what modules should be included in the code coverage test, you provide a cover specification
file. Using this file you can point out specific modules or specify directories that contain modules which
should all be included in the analysis. You can also, in the same fashion, specify modules that should be
excluded from the analysis.
If you are testing a distributed Erlang application, it is likely that code you want included in the code
coverage analysis gets executed on an Erlang node other than the one Common Test is running on. If
this is the case you need to specify these other nodes in the cover specification file or add them
dynamically to the code coverage set of nodes. See the ct cover page in the reference manual for
details on the latter.
In the cover specification file you can also specify your required level of the code coverage analysis;
details or overview. In detailed mode, you get a coverage overview page, showing you per module
and total coverage percentages, as well as one HTML file printed for each module included in the
analysis that shows exactly what parts of the code have been executed during the test. In overview
mode, only the code coverage overview page gets printed.
Note: Currently, for Common Test to be able to print code coverage HTML files for the modules
included in the analysis, the source code files of these modules must be located in the same directory as
the corresponding .beam files. This is a limitation that will be removed later.
You can choose to export and import code coverage data between tests. If you specify the name of an
export file in the cover specification file, Common Test will export collected coverage data to this file at
the end of the test. You may similarly specify that previously exported data should be imported and
included in the analysis for a test (you can specify multiple import files). This way it is possible to
analyse total code coverage without necessarily running all tests at once. Note that even if you run
separate tests in one test run, code coverage data will not be passed on from one test to another unless
you specify an export file for Common Test to use for this purpose.
To activate the code coverage support, you simply specify the name of the cover specification file as you
start Common Test. This you do either by using the -cover flag with run test. Example:
$ run test -dir $TESTOBJS/db -cover $TESTOBJS/db/config/db.coverspec
You may also pass the cover specification file name in a call to ct:run test/1, by adding a
fcover,CoverSpecg tuple to the Opts argument. Also, you can of course enable code coverage in your
test specifications (read more in the chapter about using test specifications [page 15]).
Common Test 23
Chapter 1: Common Test User’s Guide
The incl dirs r and excl dirs r terms tell Common Test to search the given directories recursively
and include or exclude any module found during the search. The incl dirs and excl dirs terms
result in a non-recursive search for modules (i.e. only modules found in the given directories are
included or excluded).
Note: Directories containing Erlang modules that are to be included in a code coverage test must exist
in the code server path, or the cover tool will fail to recompile the modules. (It is not sufficient to
specify these directories in the cover specification file for Common Test).
24 Common Test
1.9: Using Common Test for Large Scale Testing
1.8.4 Logging
To view the result of a code coverage test, follow the “Coverage log” link on the test suite results page.
This takes you to the code coverage overview page. If you have successfully performed a detailed
coverage analysis, you find links to each individual module coverage page here.
1.9.2 Usage
CT Master requires all test nodes to be on the same network and share a common file system. As of this
date, CT Master can not start test nodes automatically. The nodes must have been started in advance
for CT Master to be able to start test sessions on them.
Tests are started by calling:
ct master:run(TestSpecs) or ct master:run(TestSpecs, InclNodes, ExclNodes)
TestSpecs is either the name of a test specification file (string) or a list of test specifications. In case of a
list, the specifications will be handled (and the corresponding tests executed) in sequence. An element
in a TestSpecs list can also be list of test specifications. The specifications in such a list will be merged
into one combined specification prior to test execution. For example:
ct master:run(["ts1","ts2",["ts3","ts4"]])
means first the tests specified by “ts1” will run, then the tests specified by “ts2” and finally the tests
specified by both “ts3” and “ts4”.
The InclNodes argument to run/3 is a list of node names. The run/3 function runs the tests in
TestSpecs just like run/1 but will also take any test in TestSpecs that’s not explicitly tagged with a
particular node name and execute it on the nodes listed in InclNodes. By using run/3 this way it is
possible to use any test specification, with or without node information, in a large scale test
environment! ExclNodes is a list of nodes that should be excluded from the test. I.e. tests that have
been specified in the test specification to run on a particular node will not be performed if that node is
at runtime listed in ExclNodes.
If CT Master fails initially to connect to any of the test nodes specified in a test specification or in the
InclNodes list, the operator will be prompted with the option to either start over again (after manually
checking the status of the node(s) in question), to run without the missing nodes, or to abort the
operation.
Common Test 25
Chapter 1: Common Test User’s Guide
When tests start, CT Master prints information to console about the nodes that are involved. CT
Master also reports when tests finish, successfully or unsuccessfully. If connection is lost to a node, the
test on that node is considered finished. CT Master will not attempt to reestablish contact with the
failing node. At any time to get the current status of the test nodes, call the function:
ct master:progress()
To stop one or more tests, use:
ct master:abort() (stop all) or ct master:abort(Nodes)
For detailed information about the ct master API, please see the manual page for this module.
26 Common Test
1.10: Event Handling
This example specfies the same tests as the original example. But now if started with a call to
ct master:run(TestSpecName), the t1 test will be executed on node ct node@host x (node1), the t2
test on ct node@host y (node2) and the t3 test on both node1 and node2. The t1 config file will only
be read on node1 and the t2 config file only on node2, while the t3 config file will be read on both
node1 and node2. Both test nodes will write log files to the same directory. (The CT Master node will
however use a different log directory than the test nodes).
If the test session is instead started with a call to ct master:run(TestSpecName, [ct node@host z],
[ct node@host x]), the result is that the t1 test does not run on ct node@host x (or any other node)
while the t3 test runs on ct node@host y and ct node@host z.
A nice feature is that a test specification that includes node information can still be used as input to the
regular Common Test server (as described in the Running Test Suites [page 15] chapter). The result is
that any test specified to run on a node with the same name as the Common Test node in question
(typically ct@somehost if started with the run test script), will be performed. Tests without explicit
node association will always be performed too of course!
Note:
It is recommended that absolute paths are used for log directories, config files and test directory
aliases in the test specifications so that current working directory settings are not important.
Common Test 27
Chapter 1: Common Test User’s Guide
1.10.2 Usage
Event handlers may be plugged in by means of test specification [page 15] terms:
fevent handler, EventHandlersg, or
fevent handler, EventHandlers, InitArgsg, or
fevent handler, NodeRefs, EventHandlersg, or
fevent handler, NodeRefs, EventHandlers, InitArgsg
EventHandlers is a list of modules (each having gen event behaviour). An event handler module must
be precompiled and its location must be specified in the Erlang runtime system code path. Before a test
session starts, the init function of each plugged in event handler is called (with the InitArgs list as
argument or [] if no start arguments are given).
To plug a handler into the CT Master event manager, specify master as the node in NodeRefs.
For an event handler to be able to match on events, the module must include the header file
ct event.hrl. An event is a record with the following definition:
#eventfname, node, datag
name is the label (type) of the event. node is the name of the node the event has originated from (only
relevant for CT Master event handlers). data is data specific for the particular event.
Events:
#event.name = tc start
#event.data = fSuite,Caseg
Suite = atom()
Case = atom()
#event.name = tc done
#event.data = fSuite,Case,Resultg
Suite = atom()
Case = atom()
Result = ok | fskipped,Reasong | ffailed,Reasong
Reason = term()
28 Common Test
1.10: Event Handling
#event.data = fSuite,Case,Commentg
Suite = atom()
Case = atom()
Comment = string()
The events are also documented in ct event.erl. This module may serve as an example of what an
event handler for the CT event manager can look like.
Besides the event handler test specification terms, it is also possible to install event handlers by means
of the run test flag -event handler, e.g:
Note that it is not posible to specify start arguments to the event handlers when using the run test
script. You may however pass along start arguments if you use the ct:run test/1 function. An
event handler tuple in the argument Opts has the following definition (see also ct:run test/1 in the
reference manual):
fevent handler,EventHandlersg
EventHandlers = EH | [EH]
EH = atom() | fatom(),InitArgsg | f[atom()],InitArgsg
InitArgs = [term()]
Example:
Common Test 29
Chapter 1: Common Test User’s Guide
This will install two event handlers for the my testobj test. Event handler my evh1 is started with [] as
argument to the init function. Event handler my evh2 is started with the name of the current node in
the init argument list.
There are often sufficient means to work around the need for test case dependencies. Generally, the
problem is related to the state of the system under test (SUT). The action of one test case may alter the
state of the system and for some other test case to run properly, the new state must be known.
Instead of passing data between test cases, it is recommended that the test cases read the state from the
SUT and perform assertions (i.e. let the test case run if the state is as expected, otherwise reset or fail)
and/or use the state to set variables necessary for the test case to execute properly. Common actions can
often be implemented as library functions for test cases to call to set the SUT in a required state. (Such
common actions may of course also be separately tested if necessary, to ensure they are working as
expected). It is sometimes also possible, but not always desirable, to group tests together in one test
case, i.e. let a test case perform a “scenario” test (a test that consists of subtests).
Consider for example a server application under test. The following functionality is to be tested:
There are obvious dependencies between the listed functions. We can’t configure the server if it hasn’t
first been started, we can’t connect a client until the server has been properly configured, etc. If we
want to have one test case for each of the functions, we might be tempted to try to always run the test
cases in the stated order and carry possible data (identities, handles, etc) between the cases and
therefore introduce dependencies between them. To avoid this we could consider starting and stopping
the server for every test. We would implement the start and stop action as common functions that may
be called from init per testcase and end per testcase. (We would of course test the start and stop
functionality separately). The configuration could perhaps also be implemented as a common function,
30 Common Test
1.11: Dependencies between Test Cases and Suites
maybe grouped with the start function. Finally the testing of connecting and disconnecting a client may
be grouped into one test case. The resulting suite would look something like this:
%% configuration test
config(Config) ->
ServerPid = ?config(server pid, Config),
configure server(ServerPid).
Common Test 31
Chapter 1: Common Test User’s Guide
ServerPid.
-module(server b SUITE).
-compile(export all).
-include lib("ct.hrl").
32 Common Test
1.11: Dependencies between Test Cases and Suites
allocate(Config) ->
fServerId,SessionIdg = ?config(ids, Config),
fok,Handleg = allocate resource(ServerId, SessionId),
%% save handle for deallocation test
NewConfig = [fhandle,Handleg],
fsave config,NewConfigg.
deallocate(Config) ->
fServerId,SessionIdg = ?config(ids, Config),
fallocate,OldConfigg = ?config(saved config, Config),
Handle = ?config(handle, OldConfig),
ok = deallocate resource(ServerId, SessionId, Handle).
It is also possible to save Config data from a test case that is to be skipped. To accomplish this, return
the following tuple:
fskip and save,Reason,ConfigListg
The result will be that the test case is skipped with Reason printed to the log file (as described in
previous chapters), and ConfigList is saved for the next test case. ConfigList may be read by means
of ?config(saved config, Config), as described above. skip and save may also be returned from
init per suite, in which case the saved data can be read by init per suite in the suite that follows.
1.11.3 Sequences
It is possible that test cases depend on each other so that if one case fails, the following test(s) should
not be executed. Typically, if the save config facility is used and a test case that is expected to save
data crashes, the following case can not run. CT offers a way to declare such dependencies, called
sequences.
A sequence of test cases is declared by means of the function sequences/0. This function should return
a list of tuples on the format: fSeqTag,TestCasesg. SeqTag is an atom that identifies one particular
sequence. TestCases is a list of test case names. Sequences must be included in the list that all/0
returns. They are declared as: fsequence,SeqTagg.
For example, if we would like to make sure that if allocate in server b SUITE (above) crashes,
deallocate is skipped, we may declare the sequence:
Let’s also assume the suite contains the test case get resource status, which is independent of the
other two cases. The all function could look like this:
Common Test 33
Chapter 1: Common Test User’s Guide
If alloc succeeds, dealloc is also executed. If alloc fails however, dealloc is not executed but
marked as SKIPPED in the html log. get resource status will run no matter what happens to the
alloc and dealloc cases.
Test cases in a sequence will be executed in order until they have all succeeded or until one case fails. If
one fails, all following cases in the sequence are skipped. The cases in the sequence that have succeeded
up to that point are reported as successful in the log. An arbitrary number of sequence tuples may be
specified. Example:
Note:
It is not possible to execute a test case which is part of a sequence as a regular (stand alone) test case.
It is also not possible to use the same test case in multiple sequences. Remember that you can always
work around these limitations if necessary by means of help functions common for the test cases in
question.
34 Common Test
1.12: Some thoughts about testing
Common Test 35
Chapter 1: Common Test User’s Guide
36 Common Test
Common Test Reference
Manual
Short Summaries
Application common test [page 44] – A framework for automatic testing of a
variety of target nodes
Application run test [page 48] – Shell script used for starting Common Test from
the Unix command line.
Erlang Module ct [page 50] – Main user interface for the Common Test
framework.
Erlang Module ct cover [page 58] – Common Test Framework code coverage
support module.
Erlang Module ct ftp [page 59] – Common Test specific layer on top of OTP ftp
clinet ftp.erl.
Erlang Module ct master [page 62] – Distributed test execution control for
Common Test.
Erlang Module ct rpc [page 65] – Common Test specific layer on Erlang/OTP rpc.
Erlang Module ct snmp [page 68] – Common Test specific layer on top of the
OTPs snmp.
Erlang Module ct telnet [page 73] – Common Test specific layer on top of telnet
client ct telnet client.erl.
Erlang Module unix telnet [page 78] – Callback module for ct telnet for talking
telnet to a unix host.
common test
The following functions are exported:
Module:all() -> TestCases | fskip,Reasong
[page 44] Returns the list of all test cases in the module.
Module:sequences() -> Sequences
[page 45] Returns a list of test cases that depend on each other.
Module:suite() -> [Info]
[page 45] Function for providing default test suite data.
Module:init per suite(Config) -> NewConfig | fskip,Reasong |
fskip and save,Reason,Configg
[page 45] Test suite initialization.
Common Test 37
Common Test Reference Manual
run test
No functions are exported.
ct
The following functions are exported:
abort current testcase(Reason) -> ok | ferror, no testcase runningg
[page 50] When calling this function, the currently executing test case will be
aborted.
comment(Comment) -> void()
[page 50] Print the given Comment in the comment field of the table on the test
suite result page.
fail(Reason) -> void()
[page 51] Terminate a test case with the given error Reason.
get config(Required) -> Value
[page 51] Equivalent to get config(Required, undefined).
get config(Required, Default) -> Value
[page 51] Get the value of config data.
get status() -> TestStatus | ferror, Reasong
[page 51] Returns status of ongoing tests.
get target name(Handle) -> fok, TargetNameg | ferror, Reasong
[page 52] Return the name of the target that the given connection belongs to.
install(Opts) -> ok | ferror, Reasong
[page 52] Install config files and event handlers.
listenv(Telnet) -> [Env]
[page 52] Performs the listenv command on the given telnet connection and
returns the result as a list of Key-Value pairs.
log(Format) -> ok
[page 52] Equivalent to log(default, Format, []).
log(X1, X2) -> ok
[page 52] Equivalent to log(Category, Format, Args).
38 Common Test
Common Test Reference Manual
Common Test 39
Common Test Reference Manual
ct cover
The following functions are exported:
add nodes(Nodes) -> fok, StartedNodesg | ferror, Reasong
[page 58] Add nodes to current cover test (only works if cover support is active!).
remove nodes(Nodes) -> ok | ferror, Reasong
[page 58] Remove nodes from current cover test.
ct ftp
The following functions are exported:
cd(Connection, Dir) -> ok | ferror, Reasong
[page 59] Change directory on remote host.
close(Connection) -> ok | ferror, Reasong
[page 59] Close the FTP connection.
delete(Connection, File) -> ok | ferror, Reasong
[page 59] Delete a file on remote host.
get(Name, RemoteFile, LocalFile) -> ok | ferror, Reasong
[page 59] Open a ftp connection and fetch a file from the remote host.
ls(Connection, Dir) -> fok, Listingg | ferror, Reasong
[page 60] List the directory Dir.
open(Name) -> fok, Handleg | ferror, Reasong
[page 60] Open an FTP connection to the specified node.
put(Name, LocalFile, RemoteFile) -> ok | ferror, Reasong
[page 60] Open a ftp connection and send a file to the remote host.
recv(Connection, RemoteFile) -> ok | ferror, Reasong
[page 60] Fetch a file over FTP.
recv(Connection, RemoteFile, LocalFile) -> ok | ferror, Reasong
[page 60] Fetch a file over FTP.
send(Connection, LocalFile) -> ok | ferror, Reasong
[page 61] Send a file over FTP.
send(Connection, LocalFile, RemoteFile) -> ok | ferror, Reasong
[page 61] Send a file over FTP.
type(Connection, Type) -> ok | ferror, Reasong
[page 61] Change file transfer type.
ct master
The following functions are exported:
abort() -> ok
[page 62] Stops all running tests.
abort(Nodes) -> ok
[page 62] Stops tests on specified nodes.
progress() -> [fNode, Statusg]
[page 62] Returns test progress.
40 Common Test
Common Test Reference Manual
run(TestSpecs) -> ok
[page 62] Equivalent to run(TestSpecs, false, [], []).
run(TestSpecs, InclNodes, ExclNodes) -> ok
[page 62] Equivalent to run(TestSpecs, false, InclNodes, ExclNodes).
run(TestSpecs, AllowUserTerms, InclNodes, ExclNodes) -> ok
[page 63] Tests are spawned on the nodes as specified in TestSpecs.
run on node(TestSpecs, Node) -> ok
[page 63] Equivalent to run on node(TestSpecs, false, Node).
run on node(TestSpecs, AllowUserTerms, Node) -> ok
[page 63] Tests are spawned on Node according to TestSpecs.
run test(Node, Opts) -> ok
[page 63] Tests are spawned on Node using ct:run test/1.
ct rpc
The following functions are exported:
app node(App, Candidates) -> NodeName
[page 65] From a set of candidate nodes determines which of them is running the
application App.
app node(App, Candidates, FailOnBadRPC) -> NodeName
[page 65] Same as app node/2 only the FailOnBadRPC argument will determine if
the search for a candidate node should stop or not if badrpc is received at some
point.
app node(App, Candidates, FailOnBadRPC, Cookie) -> NodeName
[page 65] Same as app node/2 only the FailOnBadRPC argument will determine if
the search for a candidate node should stop or not if badrpc is received at some
point.
call(Node, Module, Function, Args) -> term() | fbadrpc, Reasong
[page 66] Same as call(Node, Module, Function, Args, infinity).
call(Node, Module, Function, Args, TimeOut) -> term() | fbadrpc,
Reasong
[page 66] Evaluates apply(Module, Function, Args) on the node Node.
call(Node, Module, Function, Args, TimeOut, Cookie) -> term() |
fbadrpc, Reasong
[page 66] Evaluates apply(Module, Function, Args) on the node Node.
cast(Node, Module, Function, Args) -> ok
[page 66] Evaluates apply(Module, Function, Args) on the node Node.
cast(Node, Module, Function, Args, Cookie) -> ok
[page 67] Evaluates apply(Module, Function, Args) on the node Node.
ct snmp
The following functions are exported:
get next values(Agent, Oids, ConfName) -> SnmpReply
[page 70] Issues a synchronous snmp get next request.
get values(Agent, Oids, ConfName) -> SnmpReply
[page 70] Issues a synchronous snmp get request.
Common Test 41
Common Test Reference Manual
ct telnet
The following functions are exported:
close(Connection) -> ok | ferror, Reasong
[page 74] Close the telnet connection and stop the process managing it.
cmd(Connection, Cmd) -> fok, Datag | ferror, Reasong
[page 74] Equivalent to cmd(Connection, Cmd, DefaultTimeout).
cmd(Connection, Cmd, Timeout) -> fok, Datag | ferror, Reasong
[page 74] Send a command via telnet and wait for prompt.
cmdf(Connection, CmdFormat, Args) -> fok, Datag | ferror, Reasong
[page 74] Equivalent to cmdf(Connection, CmdFormat, Args, DefaultTimeout).
cmdf(Connection, CmdFormat, Args, Timeout) -> fok, Datag | ferror,
Reasong
[page 74] Send a telnet command and wait for prompt (uses a format string and
list of arguments to build the command).
cont log(Str, Args) -> term()
[page 74]
end log() -> term()
[page 74]
expect(Connection, Patterns) -> term()
[page 74] Equivalent to expect(Connections, Patterns, []).
42 Common Test
Common Test Reference Manual
unix telnet
No functions are exported.
Common Test 43
Common Test Common Test Reference Manual
Common Test
Application
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:
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. [page 4]
Exports
44 Common Test
Common Test Reference Manual Common Test
Common Test 45
Common Test Common Test Reference Manual
46 Common Test
Common Test Reference Manual Common Test
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.
Common Test 47
The run test shell script Common Test Reference Manual
The run test script is automatically generated as Common Test is installed (please see
the Installation chapter in the Common Test User’s Guide for more information). The
script accepts a number of different start flags. Some flags trigger run test to start the
Common Test application and pass on data to it. Some flags start an Erlang node
prepared for running Common Test in a particular mode.
run test also accepts Erlang emulator flags. These are used when run test calls erl to
start the Erlang node (making it possible to e.g. add directories to the code server path,
change the cookie on the node, start additional applications, etc).
If run test is called without parameters, it prints all valid start flags to stdout.
48 Common Test
Common Test Reference Manual The run test shell script
See also
Please read the Running Test Suites [page 12] chapter in the Common Test User’s
Guide for information about the meaning of the different start flags.
Common Test 49
ct Common Test Reference Manual
ct
Erlang Module
DATA TYPES
handle() = handle() (see module ct gen conn) | term() The identity of a
specific connection.
target name() = var name() The name of a target.
var name() = atom() A variable name which is specified when ct:require/2 is
called, e.g. ct:require(mynodename,fnode,[telnet]g)
Exports
50 Common Test
Common Test Reference Manual ct
Comment = term()
Print the given Comment in the comment field of the table on the test suite result page.
If called several times, only the last comment is printed. comment/1 is also overwritten
by the return value fcomment,Commentg or by the function fail/1 (which prints
Reason as a comment).
Common Test 51
ct Common Test Reference Manual
log(Format) -> ok
Equivalent to log(default, Format, []) [page 53].
52 Common Test
Common Test Reference Manual ct
Args = list()
Printout from a testcase to the log.
This function is meant for printing stuff directly from a testcase (i.e. not from within
the CT framework) in the test log.
Default Category is default and default Args is [].
pal(Format) -> ok
Equivalent to pal(default, Format, []) [page 53].
print(Format) -> ok
Equivalent to print(default, Format, []) [page 54].
Common Test 53
ct Common Test Reference Manual
Category = atom()
Format = string()
Args = list()
Printout from a testcase to the console.
This function is meant for printing stuff from a testcase on the console.
Default Category is default and default Args is [].
54 Common Test
Common Test Reference Manual ct
fnode,[ftelnet,IpAddrg,
fftp,IpAddrg]g.
See also: get config/1 [page 51], get config/2 [page 51], require/1 [page 54].
Common Test 55
ct Common Test Reference Manual
N = integer()
DurTime = string(HHMMSS)
StopTime = string(YYMoMoDDHHMMSS) | string(HHMMSS)
Result = [TestResult] | ferror, Reasong
Run tests as specified by the combination of options in Opts. The options are the same
as those used with the run test script. Note that here a TestDir can be used to point
out the path to a Suite. Note also that the option testcase corresponds to the -case
option in the run test script. Configuration files specified in Opts will be installed
automatically at startup.
56 Common Test
Common Test Reference Manual ct
Common Test 57
ct cover Common Test Reference Manual
ct cover
Erlang Module
Exports
58 Common Test
Common Test Reference Manual ct ftp
ct ftp
Erlang Module
DATA TYPES
connection() = handle() | target name() (see module ct)
handle() = handle() (see module ct gen conn) Handle for a specific ftp
connection.
Exports
Common Test 59
ct ftp Common Test Reference Manual
Open a ftp connection and fetch a file from the remote host.
RemoteFile and LocalFile must be absolute paths.
The config file must be as for put/3.
See also: put/3 [page 60].
60 Common Test
Common Test Reference Manual ct ftp
RemoteFile = string()
LocaFile = string()
Fetch a file over FTP.
The file will be named LocalFile on the local host.
Common Test 61
ct master Common Test Reference Manual
ct master
Erlang Module
Exports
abort() -> ok
Stops all running tests.
abort(Nodes) -> ok
Types:
Nodes = atom() | [atom()]
Stops tests on specified nodes.
run(TestSpecs) -> ok
Types:
TestSpecs = string() | [SeparateOrMerged]
Equivalent to run(TestSpecs, false, [], []) [page 63].
62 Common Test
Common Test Reference Manual ct master
Common Test 63
ct master Common Test Reference Manual
InitArgs = [term()]
Conns = all | [atom()]
Tests are spawned on Node using ct:run test/1.
64 Common Test
Common Test Reference Manual ct rpc
ct rpc
Erlang Module
Exports
Common Test 65
ct rpc Common Test Reference Manual
call(Node, Module, Function, Args, TimeOut, Cookie) -> term() | fbadrpc, Reasong
Types:
Node = NodeName | fFun, FunArgsg
Fun = fun()
FunArgs = term()
NodeName = atom()
Module = atom()
Function = atom()
Args = [term()]
Reason = timeout | term()
Cookie = atom()
Evaluates apply(Module, Function, Args) on the node Node. Returns whatever
Function returns or fbadrpc, Reasong if the remote procedure call fails. If Node is fFun,
FunArgsg applying Fun to FunArgs should return a node name. The cookie on the client
node will be set to Cookie for this rpc operation (use to match the server node cookie).
66 Common Test
Common Test Reference Manual ct rpc
Common Test 67
ct snmp Common Test Reference Manual
ct snmp
Erlang Module
68 Common Test
Common Test Reference Manual ct snmp
The ConfName parameter in the functions should be the name you allocated in your test
suite using require statement. Example:
suite() -> [frequire, ConfName,fsnmp,[users, managed agents]gg].
or
ct:require(ConfName,fsnmp,[users, managed agents]g).
Note that Usm users are needed for snmp v3 configuration and are not to be confused
with users.
Snmp traps, inform and report messages are handled by the user callback module. For
more information about this see the snmp application.
Note: It is recommended to use the .hrl-files created by the Erlang/OTP mib-compiler
to define the oids. Ex for the getting the erlang node name from the erlNodeTable in
the OTP-MIB
Oid = ?erlNodeEntry ++ [?erlNodeName, 1]
DATA TYPES
agent config() = fItem, Valueg
agent ip() = ip()
agent name() = atom()
agent port() = integer()
call back module() = atom()
error index() = integer()
error status() = noError | atom()
ip() = string() | finteger(), integer(), integer(), integer()g
manager ip() = ip()
oid() = [byte()]
oids() = [oid()]
rel path() = string()
sec type() = none | minimum | semi
Common Test 69
ct snmp Common Test Reference Manual
Exports
70 Common Test
Common Test Reference Manual ct snmp
Reason = term()
Explicitly instruct the manager to handle this agent. Corresponds to making an entry in
agents.conf
Common Test 71
ct snmp Common Test Reference Manual
Value = term()
ConfName = atom()
Starts an snmp manager and/or agent. In the manager case also registrations of users and
agents as specified by the configuration <ConfName> will be performed. When using
snmp v3 also so called usm users will be registered. Note that users, usm users and
managed agents may also be registerd at a later time using ct snmp:register users/2,
ct snmp:register agents/2, and ct snmp:register usm users/2. The agent started will be
called snmp master agent. Use ct snmp:load mibs to load mibs into the agent.
stop(Config) -> ok
Types:
Config = [fKey, Valueg]
Key = atom()
Value = term()
ConfName = atom()
Stops the snmp manager and/or agent removes all files created.
72 Common Test
Common Test Reference Manual ct telnet
ct telnet
Erlang Module
These parameters can be altered by the user with the following configuration term:
ftelnet settings, [fconnect timeout,Millisecg,
fcommand timeout,Millisecg,
freconnection attempts,Ng,
freconnection interval,Millisecg]g.
DATA TYPES
connection() = handle() | ftarget name() (see module ct), connection type()g | target n
Common Test 73
ct telnet Common Test Reference Manual
Exports
74 Common Test
Common Test Reference Manual ct telnet
Common Test 75
ct telnet Common Test Reference Manual
The repeat and sequence options can be combined in order to match a sequence
multiple times.
76 Common Test
Common Test Reference Manual ct telnet
See also
unix telnet [page 78]
Common Test 77
unix telnet Common Test Reference Manual
unix telnet
Erlang Module
See also
ct [page 50], ct telnet [page 73]
78 Common Test
Index of Modules and Functions
abort/0 cmdf/3
ct master , 62 ct telnet , 74
abort/1 cmdf/4
ct master , 62 ct telnet , 74
abort_current_testcase/1 comment/1
ct , 50 ct , 50
add_nodes/1 Common Test
ct cover , 58 Module:all/0Application, 44
Module:end_per_suite/1Application, 45
app_node/2
Module:end_per_testcase/2Application,
ct rpc , 65
46
app_node/3 Module:init_per_suite/1Application,
ct rpc , 65 45
Module:init_per_testcase/2Application,
app_node/4
46
ct rpc , 65
Module:sequences/0Application, 45
Module:suite/0Application, 45
call/4 Module:testcase/0Application, 46
ct rpc , 66 Module:testcase/1Application, 47
call/5 cont_log/2
ct rpc , 66 ct telnet , 74
call/6 ct
ct rpc , 66 abort_current_testcase/1, 50
cast/4 comment/1, 50
ct rpc , 66 fail/1, 51
get_config/1, 51
cast/5 get_config/2, 51
ct rpc , 67 get_status/0, 51
cd/2 get_target_name/1, 52
ct ftp , 59 install/1, 52
listenv/1, 52
close/1 log/1, 52
ct ftp , 59 log/2, 52
ct telnet , 74 log/3, 52
cmd/2 pal/1, 53
ct telnet , 74 pal/2, 53
pal/3, 53
cmd/3
parse_table/1, 53
ct telnet , 74
Common Test 79
print/1, 53 ct snmp
print/2, 53 get_next_values/3, 70
print/3, 53 get_values/3, 70
require/1, 54 load_mibs/1, 70
require/2, 54 register_agents/2, 70
run/1, 55 register_users/2, 71
run/2, 55 register_usm_users/2, 71
run/3, 55 set_info/1, 71
run_test/1, 55 set_values/4, 71
run_testspec/1, 56 start/2, 71
start_interactive/0, 56 stop/1, 72
step/3, 56 unregister_agents/1, 72
stop_interactive/0, 56 unregister_users/1, 72
testcases/2, 56 update_usm_users/2, 72
userdata/2, 57
ct telnet
userdata/3, 57
close/1, 74
ct cover cmd/2, 74
add_nodes/1, 58 cmd/3, 74
remove_nodes/1, 58 cmdf/3, 74
cmdf/4, 74
ct ftp
cont_log/2, 74
cd/2, 59
end_log/0, 74
close/1, 59
expect/2, 74
delete/2, 59
expect/3, 74
get/3, 59
get_data/1, 76
ls/2, 60
open/1, 76
open/1, 60
open/2, 76
put/3, 60
open/3, 76
recv/2, 60
open/4, 76
recv/3, 60
send/2, 76
send/2, 61
sendf/3, 77
send/3, 61
type/2, 61
delete/2
ct master ct ftp , 59
abort/0, 62
abort/1, 62
end_log/0
progress/0, 62
ct telnet , 74
run/1, 62
run/3, 62 expect/2
run/4, 63 ct telnet , 74
run_on_node/2, 63
expect/3
run_on_node/3, 63
ct telnet , 74
run_test/2, 63
ct rpc fail/1
app_node/2, 65 ct , 51
app_node/3, 65
app_node/4, 65
get/3
call/4, 66
ct ftp , 59
call/5, 66
call/6, 66 get_config/1
cast/4, 66 ct , 51
cast/5, 67 get_config/2
80 Common Test
ct , 51 Module:testcase/1Application
Common Test , 47
get_data/1
ct telnet , 76
open/1
get_next_values/3 ct ftp , 60
ct snmp , 70 ct telnet , 76
get_status/0 open/2
ct , 51 ct telnet , 76
get_target_name/1 open/3
ct , 52 ct telnet , 76
get_values/3 open/4
ct snmp , 70 ct telnet , 76
install/1 pal/1
ct , 52 ct , 53
pal/2
listenv/1
ct , 53
ct , 52
pal/3
load_mibs/1
ct , 53
ct snmp , 70
parse_table/1
log/1
ct , 53
ct , 52
print/1
log/2
ct , 53
ct , 52
print/2
log/3
ct , 53
ct , 52
print/3
ls/2
ct , 53
ct ftp , 60
progress/0
Module:all/0Application ct master , 62
Common Test , 44 put/3
Module:end_per_suite/1Application ct ftp , 60
Common Test , 45
recv/2
Module:end_per_testcase/2Application
ct ftp , 60
Common Test , 46
recv/3
Module:init_per_suite/1Application
ct ftp , 60
Common Test , 45
register_agents/2
Module:init_per_testcase/2Application
ct snmp , 70
Common Test , 46
register_users/2
Module:sequences/0Application
ct snmp , 71
Common Test , 45
register_usm_users/2
Module:suite/0Application
ct snmp , 71
Common Test , 45
remove_nodes/1
Module:testcase/0Application
ct cover , 58
Common Test , 46
Common Test 81
require/1 stop_interactive/0
ct , 54 ct , 56
require/2
ct , 54 testcases/2
ct , 56
run/1
ct , 55 type/2
ct master , 62 ct ftp , 61
run/2
ct , 55 unregister_agents/1
ct snmp , 72
run/3
ct , 55 unregister_users/1
ct master , 62 ct snmp , 72
run/4 update_usm_users/2
ct master , 63 ct snmp , 72
run_on_node/2 userdata/2
ct master , 63 ct , 57
run_on_node/3 userdata/3
ct master , 63 ct , 57
run_test/1
ct , 55
run_test/2
ct master , 63
run_testspec/1
ct , 56
send/2
ct ftp , 61
ct telnet , 76
send/3
ct ftp , 61
sendf/3
ct telnet , 77
set_info/1
ct snmp , 71
set_values/4
ct snmp , 71
start/2
ct snmp , 71
start_interactive/0
ct , 56
step/3
ct , 56
stop/1
ct snmp , 72
82 Common Test