<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- Running Tests</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/common_test-1.6.3.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>Common Test</strong><br><strong>User's Guide</strong><br><small>Version 1.6.3</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p>
<ul class="flipMenu" imagepath="../../../../doc/js/flipmenu">
<li id="no" title="Common Test Basics" expanded="false">Common Test Basics<ul>
<li><a href="basics_chapter.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="basics_chapter.html#id66143">Introduction</a></li>
<li title="Test Suite Organisation"><a href="basics_chapter.html#id61412">Test Suite Organisation</a></li>
<li title="Support Libraries"><a href="basics_chapter.html#id67203">Support Libraries</a></li>
<li title="Suites and Test Cases"><a href="basics_chapter.html#id61632">Suites and Test Cases</a></li>
<li title="External Interfaces"><a href="basics_chapter.html#id63930">External Interfaces</a></li>
</ul>
</li>
<li id="no" title="Getting Started" expanded="false">Getting Started<ul>
<li><a href="getting_started_chapter.html">
Top of chapter
</a></li>
<li title="Are you new around here?"><a href="getting_started_chapter.html#id61356">Are you new around here?</a></li>
<li title="Test case execution"><a href="getting_started_chapter.html#id63050">Test case execution</a></li>
<li title="A simple test suite"><a href="getting_started_chapter.html#id63909">A simple test suite</a></li>
<li title="A test suite with configuration functions"><a href="getting_started_chapter.html#id68094">A test suite with configuration functions</a></li>
<li title="What happens next?"><a href="getting_started_chapter.html#id62545">What happens next?</a></li>
</ul>
</li>
<li id="no" title="Installation" expanded="false">Installation<ul>
<li><a href="install_chapter.html">
Top of chapter
</a></li>
<li title="General information"><a href="install_chapter.html#id66699">General information</a></li>
</ul>
</li>
<li id="no" title="Writing Test Suites" expanded="false">Writing Test Suites<ul>
<li><a href="write_test_chapter.html">
Top of chapter
</a></li>
<li title="Support for test suite authors"><a href="write_test_chapter.html#id71900">Support for test suite authors</a></li>
<li title="Test suites"><a href="write_test_chapter.html#id70761">Test suites</a></li>
<li title="Init and end per suite"><a href="write_test_chapter.html#id70806">Init and end per suite</a></li>
<li title="Init and end per test case"><a href="write_test_chapter.html#id70917">Init and end per test case</a></li>
<li title="Test cases"><a href="write_test_chapter.html#id71162">Test cases</a></li>
<li title="Test case info function"><a href="write_test_chapter.html#id71322">Test case info function</a></li>
<li title="Test suite info function"><a href="write_test_chapter.html#id71521">Test suite info function</a></li>
<li title="Test case groups"><a href="write_test_chapter.html#id71611">Test case groups</a></li>
<li title="The parallel property and nested groups"><a href="write_test_chapter.html#id72823">The parallel property and nested groups</a></li>
<li title="Parallel test cases and IO"><a href="write_test_chapter.html#id72860">Parallel test cases and IO</a></li>
<li title="Repeated groups"><a href="write_test_chapter.html#id72908">Repeated groups</a></li>
<li title="Shuffled test case order"><a href="write_test_chapter.html#id73046">Shuffled test case order</a></li>
<li title="Group info function"><a href="write_test_chapter.html#id73105">Group info function</a></li>
<li title="Info functions for init- and end-configuration"><a href="write_test_chapter.html#id73139">Info functions for init- and end-configuration</a></li>
<li title="Data and Private Directories"><a href="write_test_chapter.html#id73202">Data and Private Directories</a></li>
<li title="Execution environment"><a href="write_test_chapter.html#id73327">Execution environment</a></li>
<li title="Timetrap timeouts"><a href="write_test_chapter.html#id73364">Timetrap timeouts</a></li>
<li title="Logging - categories and verbosity levels"><a href="write_test_chapter.html#id73549">Logging - categories and verbosity levels</a></li>
<li title="Illegal dependencies"><a href="write_test_chapter.html#id73756">Illegal dependencies</a></li>
</ul>
</li>
<li id="no" title="Test Structure" expanded="false">Test Structure<ul>
<li><a href="test_structure_chapter.html">
Top of chapter
</a></li>
<li title="Test structure"><a href="test_structure_chapter.html#id73930">Test structure</a></li>
<li title="Skipping test cases"><a href="test_structure_chapter.html#id73944">Skipping test cases</a></li>
<li title="Definition of terms"><a href="test_structure_chapter.html#id74020">Definition of terms</a></li>
</ul>
</li>
<li id="no" title="Examples and Templates" expanded="false">Examples and Templates<ul>
<li><a href="example_chapter.html">
Top of chapter
</a></li>
<li title="Test suite example"><a href="example_chapter.html#id74246">Test suite example</a></li>
<li title="Test suite templates"><a href="example_chapter.html#id74298">Test suite templates</a></li>
</ul>
</li>
<li id="loadscrollpos" title="Running Tests" expanded="true">Running Tests<ul>
<li><a href="run_test_chapter.html">
Top of chapter
</a></li>
<li title="Using the Common Test Framework"><a href="run_test_chapter.html#id74488">Using the Common Test Framework</a></li>
<li title="Automatic compilation of test suites and help modules"><a href="run_test_chapter.html#id74528">Automatic compilation of test suites and help modules</a></li>
<li title="Running tests from the OS command line"><a href="run_test_chapter.html#id74645">Running tests from the OS command line</a></li>
<li title="Running tests from the Erlang shell or from an Erlang program"><a href="run_test_chapter.html#id75142">Running tests from the Erlang shell or from an Erlang program</a></li>
<li title="Test case group execution"><a href="run_test_chapter.html#id75304">Test case group execution</a></li>
<li title="Running the interactive shell mode"><a href="run_test_chapter.html#id75821">Running the interactive shell mode</a></li>
<li title="Step by step execution of test cases with the Erlang Debugger"><a href="run_test_chapter.html#id76003">Step by step execution of test cases with the Erlang Debugger</a></li>
<li title="Test Specifications"><a href="run_test_chapter.html#id76102">Test Specifications</a></li>
<li title="Running tests from the Web based GUI"><a href="run_test_chapter.html#id76643">Running tests from the Web based GUI</a></li>
<li title="Log files"><a href="run_test_chapter.html#id76735">Log files</a></li>
<li title="HTML Style Sheets"><a href="run_test_chapter.html#id77053">HTML Style Sheets</a></li>
<li title="Repeating tests"><a href="run_test_chapter.html#id77201">Repeating tests</a></li>
<li title="Silent Connections"><a href="run_test_chapter.html#id77412">Silent Connections</a></li>
</ul>
</li>
<li id="no" title="External Configuration Data" expanded="false">External Configuration Data<ul>
<li><a href="config_file_chapter.html">
Top of chapter
</a></li>
<li title="General"><a href="config_file_chapter.html#id77631">General</a></li>
<li title="Syntax"><a href="config_file_chapter.html#id77671">Syntax</a></li>
<li title="Requiring and reading configuration data"><a href="config_file_chapter.html#id77695">Requiring and reading configuration data</a></li>
<li title="Using configuration variables defined in multiple files"><a href="config_file_chapter.html#id77839">Using configuration variables defined in multiple files</a></li>
<li title="Encrypted configuration files"><a href="config_file_chapter.html#id77870">Encrypted configuration files</a></li>
<li title="Opening connections by using configuration data"><a href="config_file_chapter.html#id77934">Opening connections by using configuration data</a></li>
<li title="User specific configuration data formats"><a href="config_file_chapter.html#id78002">User specific configuration data formats</a></li>
<li title="Examples of configuration data handling"><a href="config_file_chapter.html#id78216">Examples of configuration data handling</a></li>
<li title="Example of user specific configuration handler"><a href="config_file_chapter.html#id78268">Example of user specific configuration handler</a></li>
</ul>
</li>
<li id="no" title="Code Coverage Analysis" expanded="false">Code Coverage Analysis<ul>
<li><a href="cover_chapter.html">
Top of chapter
</a></li>
<li title="General"><a href="cover_chapter.html#id78384">General</a></li>
<li title="Usage"><a href="cover_chapter.html#id78404">Usage</a></li>
<li title="The cover specification file"><a href="cover_chapter.html#id78510">The cover specification file</a></li>
<li title="Logging"><a href="cover_chapter.html#id78563">Logging</a></li>
</ul>
</li>
<li id="no" title="Using Common Test for Large Scale Testing" expanded="false">Using Common Test for Large Scale Testing<ul>
<li><a href="ct_master_chapter.html">
Top of chapter
</a></li>
<li title="General"><a href="ct_master_chapter.html#id78634">General</a></li>
<li title="Usage"><a href="ct_master_chapter.html#id78668">Usage</a></li>
<li title="Test Specifications"><a href="ct_master_chapter.html#id78815">Test Specifications</a></li>
<li title="Automatic startup of test target nodes"><a href="ct_master_chapter.html#id78987">Automatic startup of test target nodes</a></li>
</ul>
</li>
<li id="no" title="Event Handling" expanded="false">Event Handling<ul>
<li><a href="event_handler_chapter.html">
Top of chapter
</a></li>
<li title="General"><a href="event_handler_chapter.html#id79190">General</a></li>
<li title="Usage"><a href="event_handler_chapter.html#id79226">Usage</a></li>
</ul>
</li>
<li id="no" title="Dependencies between Test Cases and Suites" expanded="false">Dependencies between Test Cases and Suites<ul>
<li><a href="dependencies_chapter.html">
Top of chapter
</a></li>
<li title="General"><a href="dependencies_chapter.html#id80143">General</a></li>
<li title="Saving configuration data"><a href="dependencies_chapter.html#id80265">Saving configuration data</a></li>
<li title="Sequences"><a href="dependencies_chapter.html#id80430">Sequences</a></li>
</ul>
</li>
<li id="no" title="Common Test Hooks" expanded="false">Common Test Hooks<ul>
<li><a href="ct_hooks_chapter.html">
Top of chapter
</a></li>
<li title="General"><a href="ct_hooks_chapter.html#id80622">General</a></li>
<li title="Installing a CTH"><a href="ct_hooks_chapter.html#id80676">Installing a CTH</a></li>
<li title="CTH Scope"><a href="ct_hooks_chapter.html#id80835">CTH Scope</a></li>
<li title="Manipulating tests"><a href="ct_hooks_chapter.html#id81189">Manipulating tests</a></li>
<li title="Example CTH"><a href="ct_hooks_chapter.html#id81482">Example CTH</a></li>
<li title="Built-in CTHs"><a href="ct_hooks_chapter.html#id81535">Built-in CTHs</a></li>
</ul>
</li>
<li id="no" title="Some thoughts about testing" expanded="false">Some thoughts about testing<ul>
<li><a href="why_test_chapter.html">
Top of chapter
</a></li>
<li title="Goals"><a href="why_test_chapter.html#id81722">Goals</a></li>
<li title="What to test?"><a href="why_test_chapter.html#id81742">What to test?</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>7 Running Tests</h1>
<h3><a name="id74488">7.1
Using the Common Test Framework</a></h3>
<p>The Common Test Framework provides a high level
operator interface for testing. It adds the following features to
the Erlang/OTP Test Server:</p>
<ul>
<li>Automatic compilation of test suites (and help modules).</li>
<li>Creation of additional HTML pages for better overview.</li>
<li>Single command interface for running all available tests.</li>
<li>Handling of configuration files specifying data related to
the System Under Test (and any other variable data).</li>
<li>Mode for running multiple independent test sessions in parallel with
central control and configuration.</li>
</ul>
<h3><a name="id74528">7.2
Automatic compilation of test suites and help modules</a></h3>
<p>When Common Test starts, it will automatically attempt to compile any
suites included in the specified tests. If particular
suites have been specified, only those suites will be compiled. If a
particular test object directory has been specified (meaning all suites
in this directory should be part of the test), Common Test runs
make:all/1 in the directory to compile the suites.</p>
<p>If compilation should fail for one or more suites, the compilation errors
are printed to tty and the operator is asked if the test run should proceed
without the missing suites, or be aborted. If the operator chooses to proceed,
it is noted in the HTML log which tests have missing suites.</p>
<p>Any help module (i.e. regular Erlang module with name not ending with
"_SUITE") that resides in the same test object directory as a suite
which is part of the test, will also be automatically compiled. A help
module will not be mistaken for a test suite (unless it has a "_SUITE"
name of course). All help modules in a particular test object directory
are compiled no matter if all or only particular suites in the directory
are part of the test.</p>
<p>If test suites or help modules include header files stored in other
locations than the test directory, you may specify these include directories
by means of the <span class="code">-include</span> flag with <span class="code">ct_run</span>,
or the <span class="code">include</span> option with <span class="code">ct:run_test/1</span>.
In addition to this, an include path may be specified with an OS
environment variable; <span class="code">CT_INCLUDE_PATH</span>. Example (bash):</p>
<p><span class="code">$ export CT_INCLUDE_PATH=~testuser/common_suite_files/include:~testuser/common_lib_files/include</span></p>
<p>Common Test will pass all include directories (specified either with the
<span class="code">include</span> flag/option, or the <span class="code">CT_INCLUDE_PATH</span>
variable, or both) to the compiler.</p>
<p>It is also possible to specify include directories in test specifications
(see below).</p>
<p>If the user wants to run all test suites for a test object (or OTP application)
by specifying only the top directory (e.g. with the <span class="code">dir</span> start flag/option),
Common Test will primarily look for test suite modules in a subdirectory named
<span class="code">test</span>. If this subdirectory doesn't exist, the specified top directory
is assumed to be the actual test directory, and test suites will be read from
there instead.</p>
<p>It is possible to disable the automatic compilation feature by using the
<span class="code">-no_auto_compile</span> flag with <span class="code">ct_run</span>, or
the <span class="code">{auto_compile,false}</span> option with
<span class="code">ct:run_test/1</span>. With automatic compilation
disabled, the user is responsible for compiling the test suite modules
(and any help modules) before the test run. If the modules can not be loaded
from the local file system during startup of Common Test, the user needs to
pre-load the modules before starting the test. Common Test will only verify
that the specified test suites exist (i.e. that they are, or can be, loaded).
This is useful e.g. if the test suites are transferred and loaded as binaries via
RPC from a remote node.</p>
<a name="ct_run"></a>
<h3><a name="id74645">7.3
Running tests from the OS command line</a></h3>
<p>The <span class="code">ct_run</span> program can be used for running tests from
the OS command line, e.g.
</p>
<ul>
<li><span class="code">ct_run -config <configfilenames> -dir <dirs></span></li>
<li>
<span class="code">ct_run -config <configfilenames> -suite <suiteswithfullpath></span>
</li>
<li>
<span class="code">ct_run -userconfig <callbackmodulename> <configfilenames> -suite <suiteswithfullpath></span>
</li>
<li><span class="code">ct_run -config <configfilenames> -suite <suitewithfullpath>
-group <groups> -case <casenames></span></li>
</ul>
<p>Examples:</p>
<p><span class="code">$ ct_run -config $CFGS/sys1.cfg $CFGS/sys2.cfg -dir $SYS1_TEST $SYS2_TEST</span></p>
<p><span class="code">$ ct_run -userconfig ct_config_xml $CFGS/sys1.xml $CFGS/sys2.xml -dir $SYS1_TEST $SYS2_TEST</span></p>
<p><span class="code">$ ct_run -suite $SYS1_TEST/setup_SUITE $SYS2_TEST/config_SUITE</span></p>
<p><span class="code">$ ct_run -suite $SYS1_TEST/setup_SUITE -case start stop</span></p>
<p><span class="code">$ ct_run -suite $SYS1_TEST/setup_SUITE -group installation -case start stop</span></p>
<p>It is also possible to combine the <span class="code">dir</span>, <span class="code">suite</span> and <span class="code">group/case</span> flags. E.g, to run
<span class="code">x_SUITE</span> and <span class="code">y_SUITE</span> in directory <span class="code">testdir</span>:</p>
<p><span class="code">$ ct_run -dir ./testdir -suite x_SUITE y_SUITE</span></p>
<p>This has the same effect as calling:</p>
<p><span class="code">$ ct_run -suite ./testdir/x_SUITE ./testdir/y_SUITE</span></p>
<p>For more details on <span class="bold_code"><a href="run_test_chapter.html#group_execution">test case group execution</a></span>, please see below.</p>
<p>Other flags that may be used with <span class="code">ct_run</span>:</p>
<ul>
<li>
<span class="code">-logdir <dir></span>, specifies where the HTML log files are to be written.</li>
<li>
<span class="code">-label <name_of_test_run></span>, associates the test run with a name that gets printed
in the overview HTML log files.</li>
<li>
<span class="code">-refresh_logs</span>, refreshes the top level HTML index files.</li>
<li>
<span class="code">-vts</span>, start web based GUI (see below).</li>
<li>
<span class="code">-shell</span>, start interactive shell mode (see below).</li>
<li>
<span class="code">-step [step_opts]</span>, step through test cases using the Erlang Debugger (see below).</li>
<li>
<span class="code">-spec <testspecs></span>, use test specification as input (see below).</li>
<li>
<span class="code">-allow_user_terms</span>, allows user specific terms in a test specification (see below).</li>
<li>
<span class="code">-silent_connections [conn_types]</span>, tells Common Test to suppress printouts for
specified connections (see below).</li>
<li>
<span class="code">-stylesheet <css_file></span>, points out a user HTML style sheet (see below).</li>
<li>
<span class="code">-cover <cover_cfg_file></span>, to perform code coverage test (see
<span class="bold_code"><a href="cover_chapter.html#cover">Code Coverage Analysis</a></span>).</li>
<li>
<span class="code">-event_handler <event_handlers></span>, to install
<span class="bold_code"><a href="event_handler_chapter.html#event_handling">event handlers</a></span>.</li>
<li>
<span class="code">-event_handler_init <event_handlers></span>, to install
<span class="bold_code"><a href="event_handler_chapter.html#event_handling">event handlers</a></span> including start arguments.</li>
<li>
<span class="code">-ct_hooks <ct_hooks></span>, to install
<span class="bold_code"><a href="ct_hooks_chapter.html#installing">Common Test Hooks</a></span> including start arguments.</li>
<li>
<span class="code">-enable_builtin_hooks <bool></span>, to enable/disable
<span class="bold_code"><a href="ct_hooks_chapter.html#builtin_cths">Built-in Common Test Hooks</a></span>. Default is <span class="code">true</span>.</li>
<li>
<span class="code">-include</span>, specifies include directories (see above).</li>
<li>
<span class="code">-no_auto_compile</span>, disables the automatic test suite compilation feature (see above).</li>
<li>
<span class="code">-multiply_timetraps <n></span>, extends <span class="bold_code"><a href="write_test_chapter.html#timetraps">timetrap
timeout</a></span> values.</li>
<li>
<span class="code">-scale_timetraps <bool></span>, enables automatic <span class="bold_code"><a href="write_test_chapter.html#timetraps">timetrap
timeout</a></span> scaling.</li>
<li>
<span class="code">-repeat <n></span>, tells Common Test to repeat the tests n times (see below).</li>
<li>
<span class="code">-duration <time></span>, tells Common Test to repeat the tests for duration of time (see below).</li>
<li>
<span class="code">-until <stop_time></span>, tells Common Test to repeat the tests until stop_time (see below).</li>
<li>
<span class="code">-force_stop</span>, on timeout, the test run will be aborted when current test job is finished (see below).</li>
<li>
<span class="code">-decrypt_key <key></span>, provides a decryption key for
<span class="bold_code"><a href="config_file_chapter.html#encrypted_config_files">encrypted configuration files</a></span>.</li>
<li>
<span class="code">-decrypt_file <key_file></span>, points out a file containing a decryption key for
<span class="bold_code"><a href="config_file_chapter.html#encrypted_config_files">encrypted configuration files</a></span>.</li>
<li>
<span class="code">-basic_html</span>, switches off html enhancements that might not be compatible with older browsers.</li>
<li>
<span class="code">-logopts <opts></span>, makes it possible to modify aspects of the logging behaviour, see
<span class="bold_code"><a href="run_test_chapter.html#logopts">Log options</a></span> below.</li>
<li>
<span class="code">-verbosity <levels></span>, sets <span class="bold_code"><a href="write_test_chapter.html#logging">verbosity levels
for printouts</a></span>.</li>
</ul>
<div class="note">
<div class="label">Note</div>
<div class="content"><p><p>Directories passed to Common Test may have either relative or absolute paths.</p></p></div>
</div>
<div class="note">
<div class="label">Note</div>
<div class="content"><p><p>Arbitrary start flags to the Erlang Runtime System may also be passed as
parameters to <span class="code">ct_run</span>. It is, for example, useful to be able to
pass directories that should be added to the Erlang code server search path
with the <span class="code">-pa</span> or <span class="code">-pz</span> flag. If you have common help- or library
modules for test suites (separately compiled), stored in other directories
than the test suite directories, these help/lib directories are preferrably
added to the code path this way. Example:</p>
<p><span class="code">$ ct_run -dir ./chat_server -logdir ./chat_server/testlogs -pa $PWD/chat_server/ebin</span></p>
<p>Note how in this example, the absolute path of the <span class="code">chat_server/ebin</span>
directory is passed to the code server. This is essential since relative
paths are stored by the code server as relative, and Common Test changes
the current working directory of the Erlang Runtime System during the test run!</p>
</p></div>
</div>
<p>The <span class="code">ct_run</span> program sets the exit status before shutting down. The following values
are defined:</p>
<ul>
<li>
<span class="code">0</span> indicates a successful testrun, i.e. one without failed or auto-skipped test cases.</li>
<li>
<span class="code">1</span> indicates that one or more test cases have failed, or have been auto-skipped.</li>
<li>
<span class="code">2</span> indicates that the test execution has failed because of e.g. compilation errors, an
illegal return value from an info function, etc.</li>
</ul>
<p>If auto-skipped test cases should not affect the exit status, you may change the default
behaviour using start flag:</p>
<div class="example"><pre>-exit_status ignore_config</pre></div>
<p>For more information about the <span class="code">ct_run</span> program, see the
<span class="bold_code"><a href="ct_run.html#top">Reference Manual</a></span> and the
<span class="bold_code"><a href="install_chapter.html#general">Installation</a></span> chapter.
</p>
<h3><a name="id75142">7.4
Running tests from the Erlang shell or from an Erlang program</a></h3>
<p>Common Test provides an Erlang API for running tests. The main (and most
flexible) function for specifying and executing tests is called
<span class="code"><span class="bold_code"><a href="ct.html#run_test-1">ct:run_test/1</a></span></span>.
This function takes the same start parameters as
the <span class="code"><span class="bold_code"><a href="run_test_chapter.html#ct_run">ct_run</a></span></span>
program described above, only the flags are instead
given as options in a list of key-value tuples. E.g. a test specified
with <span class="code">ct_run</span> like:</p>
<p><span class="code">$ ct_run -suite ./my_SUITE -logdir ./results</span></p>
<p>is with <span class="code"><span class="bold_code"><a href="ct.html#run_test-1">ct:run_test/1</a></span></span> specified as:</p>
<p><span class="code">1> ct:run_test([{suite,"./my_SUITE"},{logdir,"./results"}]).</span></p>
<p>The function returns the test result, represented by the tuple:
<span class="code">{Ok,Failed,{UserSkipped,AutoSkipped}}</span>, where each element is an
integer. If test execution fails, the function returns the tuple:
<span class="code">{error,Reason}</span>, where the term <span class="code">Reason</span> explains the
failure.</p>
<h4>Releasing the Erlang shell</h4>
<p>During execution of tests, started with
<span class="code"><span class="bold_code"><a href="ct.html#run_test-1">ct:run_test/1</a></span></span>,
the Erlang shell process, controlling stdin, will remain the top
level process of the Common Test system of processes. The result
is that the Erlang shell is not available for interaction during
the test run. If this is not desirable, maybe because the shell is needed
for debugging purposes or for interaction with the SUT during test
execution, you may set the <span class="code">release_shell</span> start option to
<span class="code">true</span> (in the call to <span class="code">ct:run_test/1</span> or by
using the corresponding test specification term, see below). This will
make Common Test release the shell immediately after the test suite
compilation stage. To accomplish this, a test runner process
is spawned to take control of the test execution, and the effect is that
<span class="code">ct:run_test/1</span> returns the pid of this process rather than the
test result - which instead is printed to tty at the end of the test run.</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p><p>Note that in order to use the
<span class="code"><span class="bold_code"><a href="ct.html#break-1">ct:break/1/2</a></span></span> and
<span class="code"><span class="bold_code"><a href="ct.html#continue-0">ct:continue/0/1</a></span></span> functions,
<span class="code">release_shell</span> <strong>must</strong> be set to <span class="code">true</span>.</p></p></div>
</div>
<p>For detailed documentation about
<span class="code"><span class="bold_code"><a href="ct.html#run_test-1">ct:run_test/1</a></span></span>,
please see the
<span class="code"><span class="bold_code"><a href="ct.html#run_test-1">ct</a></span></span> manual page.</p>
<a name="group_execution"></a>
<h3><a name="id75304">7.5
Test case group execution</a></h3>
<p>With the <span class="code">ct_run</span> flag, or <span class="code">ct:run_test/1</span> option <span class="code">group</span>,
one or more test case groups can be specified, optionally in combination
with specific test cases. The syntax for specifying groups is as follows
(on the command line):</p>
<div class="example"><pre>
$ ct_run -group <group_names_or_paths> [-case <cases>]</pre></div>
<p>or (in the Erlang shell):</p>
<div class="example"><pre>
1> ct:run_test([{group,GroupsNamesOrPaths}, {case,Cases}]).</pre></div>
<p>The <span class="code">group_names_or_paths</span> parameter specifies either one
or more group names and/or one or more group paths. At start up,
Common Test will search for matching groups in the group definitions
tree (i.e. the list returned from <span class="code">Suite:groups/0</span>, please see the
<span class="bold_code"><a href="write_test_chapter.html#test_case_groups">Test case groups</a></span>
chapter for details).
Given a group name, say <span class="code">g</span>, Common Test will search for all paths
that lead to <span class="code">g</span>. By path here we mean a sequence of nested groups,
all of which have to be followed in order to get from the top level
group to <span class="code">g</span>. Actually, what Common Test needs to do in order to
execute the test cases in group <span class="code">g</span>, is to call the
<span class="code">init_per_group/2</span> function for each group in the path to
<span class="code">g</span>, as well as all corresponding <span class="code">end_per_group/2</span>
functions afterwards. The obvious reason for this is that the configuration
of a test case in <span class="code">g</span> (and its <span class="code">Config</span> input data) depends on
<span class="code">init_per_testcase(TestCase, Config)</span> and its return value, which
in turn depends on <span class="code">init_per_group(g, Config)</span> and its return value,
which in turn depends on <span class="code">init_per_group/2</span> of the group above
<span class="code">g</span>, etc, all the way up to the top level group.</p>
<p>As you may have already realized, this means that if there is more than
one way to locate a group (and its test cases) in a path, the result of the
group search operation is a number of tests, all of which will be performed.
Common Test actually interprets a group specification that consists of a
single name this way:</p>
<p>"Search and find all paths in the group definitions tree that lead
to the specified group and, for each path, create a test which (1) executes
all configuration functions in the path to the specified group, then (2)
executes all - or all matching - test cases in this group, as well as (3)
all - or all matching - test cases in all sub groups of the group".
</p>
<p>It is also possible for the user to specify a specific group path with
the <span class="code">group_names_or_paths</span> parameter. With this type of specification it's
possible to avoid execution of unwanted groups (in otherwise matching paths),
and/or the execution of sub groups. The syntax of the group path is a list of
group names in the path, e.g. on the command line:
</p>
<p><span class="code">$ ct_run -suite "./x_SUITE" -group [g1,g3,g4] -case tc1 tc5</span></p>
<p>or similarly in the Erlang shell (requires a list within the groups list):</p>
<p><span class="code">1> ct:run_test([{suite,"./x_SUITE"}, {group,[[g1,g3,g4]]}, {testcase,[tc1,tc5]}]).</span></p>
<p>The last group in the specified path will be the terminating group in
the test, i.e. no sub groups following this group will be executed. In the
example above, <span class="code">g4</span> is the terminating group, hence Common Test will
execute a test that calls all init configuration functions in the path to
<span class="code">g4</span>, i.e. <span class="code">g1..g3..g4</span>. It will then call test cases <span class="code">tc1</span>
and <span class="code">tc5</span> in <span class="code">g4</span> and finally all end configuration functions in order
<span class="code">g4..g3..g1</span>.</p>
<p>Note that the group path specification doesn't necessarily
have to include <strong>all</strong> groups in the path to the terminating group.
Common Test will search for all matching paths if given an incomplete group
path.</p>
<p>Note also that it's possible to combine group names and group paths with the
<span class="code">group_names_or_paths</span> parameter. Each element is treated as
an individual specification in combination with the <span class="code">cases</span> parameter.
See examples below.</p>
<p>Examples:</p>
<div class="example"><pre>
-module(x_SUITE).
...
%% The group definitions:
groups() ->
[{top1,[],[tc11,tc12,
{sub11,[],[tc12,tc13]},
{sub12,[],[tc14,tc15,
{sub121,[],[tc12,tc16]}]}]},
{top2,[],[{group,sub21},{group,sub22}]},
{sub21,[],[tc21,{group,sub2X2}]},
{sub22,[],[{group,sub221},tc21,tc22,{group,sub2X2}]},
{sub221,[],[tc21,tc23]},
{sub2X2,[],[tc21,tc24]}].
</pre></div>
<br>
<p><span class="code">$ ct_run -suite "x_SUITE" -group all</span></p>
<p><span class="code">1> ct:run_test([{suite,"x_SUITE"}, {group,all}]).</span></p>
<p>Two tests will be executed, one for all cases and all sub groups under <span class="code">top1</span>,
and one for all under <span class="code">top2</span>. (We would get the same result with
<span class="code">-group top1 top2</span>, or <span class="code">{group,[top1,top2]}</span>.</p>
<br>
<p><span class="code">$ ct_run -suite "x_SUITE" -group top1</span></p>
<p><span class="code">1> ct:run_test([{suite,"x_SUITE"}, {group,[top1]}]).</span></p>
<p>This will execute one test for all cases and sub groups under <span class="code">top1</span>.</p>
<br>
<p><span class="code">$ ct_run -suite "x_SUITE" -group top1 -case tc12</span></p>
<p><span class="code">1> ct:run_test([{suite,"x_SUITE"}, {group,[top1]}, {testcase,[tc12]}]).</span></p>
<p>This will run a test that executes <span class="code">tc12</span> in <span class="code">top1</span> and any sub group
under <span class="code">top1</span> where it can be found (<span class="code">sub11</span> and <span class="code">sub121</span>).</p>
<br>
<p><span class="code">$ ct_run -suite "x_SUITE" -group [top1] -case tc12</span></p>
<p><span class="code">1> ct:run_test([{suite,"x_SUITE"}, {group,[[top1]]}, {testcase,[tc12]}]).</span></p>
<p>This will execute <span class="code">tc12</span> <strong>only</strong> in group <span class="code">top1</span>.</p>
<br>
<p><span class="code">$ ct_run -suite "x_SUITE" -group top1 -case tc16</span></p>
<p><span class="code">1> ct:run_test([{suite,"x_SUITE"}, {group,[top1]}, {testcase,[tc16]}]).</span></p>
<p>This will search <span class="code">top1</span> and all its sub groups for <span class="code">tc16</span> and the result
will be that this test case executes in group <span class="code">sub121</span>. (The specific path:
<span class="code">-group [sub121]</span> or <span class="code">{group,[[sub121]]}</span>, would have given
us the same result in this example).</p>
<br>
<p><span class="code">$ ct_run -suite "x_SUITE" -group sub12 [sub12]</span></p>
<p><span class="code">1> ct:run_test([{suite,"x_SUITE"}, {group,[sub12,[sub12]]}]).</span></p>
<p>This will execute two tests, one that includes all cases and sub groups under
<span class="code">sub12</span>, and one with <strong>only</strong> the test cases in <span class="code">sub12</span>.</p>
<br>
<p><span class="code">$ ct_run -suite "x_SUITE" -group sub2X2</span></p>
<p><span class="code">1> ct:run_test([{suite,"x_SUITE"}, {group,[sub2X2]}]).</span></p>
<p>In this example, Common Test will find and execute two tests, one for the path from
<span class="code">top2</span> to <span class="code">sub2X2</span> via <span class="code">sub21</span>, and one from <span class="code">top2</span> to <span class="code">sub2X2</span>
via <span class="code">sub22</span>.</p>
<br>
<p><span class="code">$ ct_run -suite "x_SUITE" -group [sub21,sub2X2]</span></p>
<p><span class="code">1> ct:run_test([{suite,"x_SUITE"}, {group,[[sub21,sub2X2]]}]).</span></p>
<p>Here, by specifying the unique path: <span class="code">top2 -> sub21 -> sub2X2</span>, only one test
is executed. The second possible path from <span class="code">top2</span> to <span class="code">sub2X2</span> (above)
will be discarded.</p>
<br>
<p><span class="code">$ ct_run -suite "x_SUITE" -group [sub22] -case tc22 tc21</span></p>
<p><span class="code">1> ct:run_test([{suite,"x_SUITE"}, {group,[[sub22]]}, {testcase,[tc22,tc21]}]).</span></p>
<p>In this example only the test cases for <span class="code">sub22</span> will be executed, and in
reverse order compared to the group definition.</p>
<br>
<p>If a test case that belongs to a group (according to the group definition), is executed
without a group specification, i.e. simply by means of (command line):</p>
<p><span class="code">$ ct_run -suite "my_SUITE" -case my_tc</span></p>
<p>or (Erlang shell):</p>
<p><span class="code">1> ct:run_test([{suite,"my_SUITE"}, {testcase,my_tc}]).</span></p>
<p>then Common Test ignores the group definition and executes the test case in the scope of the
test suite only (no group configuration functions are called).</p>
<p>The group specification feature, exactly as it has been presented in this section, can also
be used in <span class="bold_code"><a href="run_test_chapter.html#test_specifications">Test
Specifications</a></span> (with some extra features added). Please see below.</p>
<h3><a name="id75821">7.6
Running the interactive shell mode</a></h3>
<p>You can start Common Test in an interactive shell mode where no
automatic testing is performed. Instead, in this mode, Common Test
starts its utility processes, installs configuration data (if any),
and waits for the user to call functions (typically test case support
functions) from the Erlang shell.</p>
<p>The shell mode is useful e.g. for debugging test suites, for analysing
and debugging the SUT during "simulated" test case execution, and
for trying out various operations during test suite development.</p>
<p>To invoke the interactive shell mode, you can start an Erlang shell
manually and call <span class="code"><span class="bold_code"><a href="ct.html#install-1">ct:install/1</a></span></span> to install any configuration
data you might need (use <span class="code">[]</span> as argument otherwise), then
call <span class="code"><span class="bold_code"><a href="ct.html#start_interactive-0">ct:start_interactive/0</a></span></span> to start Common Test. If you use
the <span class="code">ct_run</span> program, you may start the Erlang shell and Common Test
in the same go by using the <span class="code">-shell</span> and, optionally, the <span class="code">-config</span>
and/or <span class="code">-userconfig</span> flag. Examples:
</p>
<ul>
<li><span class="code">ct_run -shell</span></li>
<li><span class="code">ct_run -shell -config cfg/db.cfg</span></li>
<li><span class="code">ct_run -shell -userconfig db_login testuser x523qZ</span></li>
</ul>
<p>If no config file is given with the <span class="code">ct_run</span> command,
a warning will be displayed. If Common Test has been run from the same
directory earlier, the same config file(s) will be used
again. If Common Test has not been run from this directory before, no
config files will be available.</p>
<p>If any functions using "required config data" (e.g. ct_telnet or
ct_ftp functions) are to be called from the erlang shell, config
data must first be required with <span class="code"><span class="bold_code"><a href="ct.html#require-1">
ct:require/1/2</a></span></span>. This is
equivalent to a <span class="code">require</span> statement in the <span class="bold_code"><a href="write_test_chapter.html#suite">Test Suite Info
Function</a></span> or in the <span class="bold_code"><a href="write_test_chapter.html#info_function">Test Case Info
Function</a></span>.</p>
<p>Example:</p>
<div class="example"><pre>
1> ct:require(unix_telnet, unix).
ok
2> ct_telnet:open(unix_telnet).
{ok,<0.105.0>}
4> ct_telnet:cmd(unix_telnet, "ls .").
{ok,["ls .","file1 ...",...]}
</pre></div>
<p>Everything that Common Test normally prints in the test case logs,
will in the interactive mode be written to a log named
<span class="code">ctlog.html</span> in the <span class="code">ct_run.<timestamp></span>
directory. A link to this file will be available in the file
named <span class="code">last_interactive.html</span> in the directory from which
you executed <span class="code">ct_run</span>. Currently, specifying a different
root directory for the logs than the current working directory,
is not supported.</p>
<p>If you wish to exit the interactive mode (e.g. to start an
automated test run with <span class="code"><span class="bold_code"><a href="ct.html#run_test-1">ct:run_test/1</a></span></span>), call the function
<span class="code"><span class="bold_code"><a href="ct.html#stop_interactive-0">ct:stop_interactive/0</a></span></span>. This shuts down the
running <span class="code">ct</span> application. Associations between
configuration names and data created with <span class="code">require</span> are
consequently deleted. <span class="code"><span class="bold_code"><a href="ct.html#start_interactive-0">ct:start_interactive/0</a></span></span> will get you
back into interactive mode, but the previous state is not restored.</p>
<h3><a name="id76003">7.7
Step by step execution of test cases with the Erlang Debugger</a></h3>
<p>By means of <span class="code">ct_run -step [opts]</span>, or by passing the
<span class="code">{step,Opts}</span> option to <span class="code"><span class="bold_code"><a href="ct.html#run_test-1">ct:run_test/1</a></span></span>, it is possible
to get the Erlang Debugger started automatically and use its
graphical interface to investigate the state of the current test
case and to execute it step by step and/or set execution breakpoints.</p>
<p>If no extra options are given with the <span class="code">step</span> flag/option,
breakpoints will be set automatically on the test cases that
are to be executed by Common Test, and those functions only. If
the step option <span class="code">config</span> is specified, breakpoints will
also be initially set on the configuration functions in the suite, i.e.
<span class="code">init_per_suite/1</span>, <span class="code">end_per_suite/1</span>,
<span class="code">init_per_group/2</span>, <span class="code">end_per_group/2</span>,
<span class="code">init_per_testcase/2</span> and <span class="code">end_per_testcase/2</span>.</p>
<p>Common Test enables the Debugger auto attach feature, which means
that for every new interpreted test case function that starts to execute,
a new trace window will automatically pop up. (This is because each test
case executes on a dedicated Erlang process). Whenever a new test case starts,
Common Test will attempt to close the inactive trace window of the previous
test case. However, if you prefer that Common Test leaves inactive trace
windows, use the <span class="code">keep_inactive</span> option.</p>
<p>The step functionality can be used together with the <span class="code">suite</span> and
the <span class="code">suite</span> + <span class="code">case/testcase</span> flag/option, but not together
with <span class="code">dir</span>.</p>
<a name="test_specifications"></a>
<h3><a name="id76102">7.8
Test Specifications</a></h3>
<p>The most flexible way to specify what to test, is to use a so
called test specification. A test specification is a sequence of
Erlang terms. The terms are normally declared in a text file (see
<span class="code"><span class="bold_code"><a href="ct.html#run_test-1">ct:run_test/1</a></span></span>), but
may also be passed to Common Test on the form of a list (see
<span class="code"><span class="bold_code"><a href="ct.html#run_testspec-1">ct:run_testspec/1</a></span></span>).
There are two general types of terms: configuration terms and test
specification terms.</p>
<p>With configuration terms it is possible to e.g. label the test
run (similar to <span class="code">ct_run -label</span>), evaluate arbitrary expressions
before starting the test, import configuration data (similar to
<span class="code">ct_run -config/-userconfig</span>), specify the top level HTML log
directory (similar to <span class="code">ct_run -logdir</span>), enable code coverage
analysis (similar to <span class="code">ct_run -cover</span>), install Common Test Hooks
(similar to <span class="code">ct_run -ch_hooks</span>), install event_handler plugins
(similar to <span class="code">ct_run -event_handler</span>), specify include directories
that should be passed to the compiler for automatic compilation
(similar to <span class="code">ct_run -include</span>), disable the auto compilation
feature (similar to <span class="code">ct_run -no_auto_compile</span>), set verbosity
levels (similar to <span class="code">ct_run -verbosity</span>), and more.</p>
<p>Configuration terms can be combined with <span class="code">ct_run</span> start flags,
or <span class="code">ct:run_test/1</span> options. The result will for some flags/options
and terms be that the values are merged (e.g. configuration files,
include directories, verbosity levels, silent connections), and for
others that the start flags/options override the test specification
terms (e.g. log directory, label, style sheet, auto compilation).</p>
<p>With test specification terms it is possible to state exactly
which tests should run and in which order. A test term specifies
either one or more suites, one or more test case groups (possibly nested),
or one or more test cases in a group (or in multiple groups) or in a suite.</p>
<p>An arbitrary number of test terms may be declared in sequence.
Common Test will by default compile the terms into one or more tests
to be performed in one resulting test run. Note that a term that
specifies a set of test cases will "swallow" one that only
specifies a subset of these cases. E.g. the result of merging
one term that specifies that all cases in suite S should be
executed, with another term specifying only test case X and Y in
S, is a test of all cases in S. However, if a term specifying
test case X and Y in S is merged with a term specifying case Z
in S, the result is a test of X, Y and Z in S. To disable this
behaviour, i.e. to instead perform each test sequentially in a "script-like"
manner, the term <span class="code">merge_tests</span> can be set to <span class="code">false</span> in
the test specification.</p>
<p>A test term can also specify one or more test suites, groups,
or test cases to be skipped. Skipped suites, groups and cases
are not executed and show up in the HTML log files as
SKIPPED.</p>
<p>When a test case group is specified, the resulting test
executes the <span class="code">init_per_group</span> function, followed by all test
cases and sub groups (including their configuration functions), and
finally the <span class="code">end_per_group</span> function. Also if particular
test cases in a group are specified, <span class="code">init_per_group</span>
and <span class="code">end_per_group</span> for the group in question are
called. If a group which is defined (in <span class="code">Suite:group/0</span>) to
be a sub group of another group, is specified (or if particular test
cases of a sub group are), Common Test will call the configuration
functions for the top level groups as well as for the sub group
in question (making it possible to pass configuration data all
the way from <span class="code">init_per_suite</span> down to the test cases in the
sub group).</p>
<p>The test specification utilizes the same mechanism for specifying
test case groups by means of names and paths, as explained in the
<span class="bold_code"><a href="run_test_chapter.html#group_execution">Group Execution</a></span>
section above, with the addition of the <span class="code">GroupSpec</span> element
described next.</p>
<p>The <span class="code">GroupSpec</span> element makes it possible to specify
group execution properties that will override those in the
group definition (i.e. in <span class="code">groups/0</span>). Execution properties for
sub-groups may be overridden as well. This feature makes it possible to
change properties of groups at the time of execution,
without even having to edit the test suite. The very same
feature is available for <span class="code">group</span> elements in the <span class="code">Suite:all/0</span>
list. Therefore, more detailed documentation, and examples, can be
found in the <span class="bold_code"><a href="write_test_chapter.html#test_case_groups">
Test case groups</a></span> chapter.</p>
<p>Below is the test specification syntax. Test specifications can
be used to run tests both in a single test host environment and
in a distributed Common Test environment (Large Scale
Testing). The node parameters in the <span class="code">init</span> term are only
relevant in the latter (see the
<span class="bold_code"><a href="ct_master_chapter.html#test_specifications">Large
Scale Testing</a></span> chapter for information). For more information
about the various terms, please see the corresponding sections in the
User's Guide, such as e.g. the
<span class="bold_code"><a href="run_test_chapter.html#ct_run"><span class="code">ct_run</span>
program</a></span> for an overview of available start flags
(since most flags have a corresponding configuration term), and
more detailed explanation of e.g.
<span class="bold_code"><a href="write_test_chapter.html#logging">Logging</a></span>
(for the <span class="code">verbosity</span>, <span class="code">stylesheet</span> and <span class="code">basic_html</span> terms),
<span class="bold_code"><a href="config_file_chapter.html#top">External Configuration Data</a></span>
(for the <span class="code">config</span> and <span class="code">userconfig</span> terms),
<span class="bold_code"><a href="event_handler_chapter.html#event_handling">Event
Handling</a></span> (for the <span class="code">event_handler</span> term),
<span class="bold_code"><a href="ct_hooks_chapter.html#installing">Common Test Hooks</a></span>
(for the <span class="code">ct_hooks</span> term), etc.</p>
<p>Config terms:</p>
<div class="example"><pre>
{merge_tests, Bool}.
{define, Constant, Value}.
{node, NodeAlias, Node}.
{init, InitOptions}.
{init, [NodeAlias], InitOptions}.
{label, Label}.
{label, NodeRefs, Label}.
{verbosity, VerbosityLevels}.
{verbosity, NodeRefs, VerbosityLevels}.
{stylesheet, CSSFile}.
{stylesheet, NodeRefs, CSSFile}.
{silent_connections, ConnTypes}.
{silent_connections, NodeRefs, ConnTypes}.
{multiply_timetraps, N}.
{multiply_timetraps, NodeRefs, N}.
{scale_timetraps, Bool}.
{scale_timetraps, NodeRefs, Bool}.
{cover, CoverSpecFile}.
{cover, NodeRefs, CoverSpecFile}.
{include, IncludeDirs}.
{include, NodeRefs, IncludeDirs}.
{auto_compile, Bool},
{auto_compile, NodeRefs, Bool},
{config, ConfigFiles}.
{config, ConfigDir, ConfigBaseNames}.
{config, NodeRefs, ConfigFiles}.
{config, NodeRefs, ConfigDir, ConfigBaseNames}.
{userconfig, {CallbackModule, ConfigStrings}}.
{userconfig, NodeRefs, {CallbackModule, ConfigStrings}}.
{logdir, LogDir}.
{logdir, NodeRefs, LogDir}.
{logopts, LogOpts}.
{logopts, NodeRefs, LogOpts}.
{create_priv_dir, PrivDirOption}.
{create_priv_dir, NodeRefs, PrivDirOption}.
{event_handler, EventHandlers}.
{event_handler, NodeRefs, EventHandlers}.
{event_handler, EventHandlers, InitArgs}.
{event_handler, NodeRefs, EventHandlers, InitArgs}.
{ct_hooks, CTHModules}.
{ct_hooks, NodeRefs, CTHModules}.
{enable_builtin_hooks, Bool}.
{basic_html, Bool}.
{basic_html, NodeRefs, Bool}.
{release_shell, Bool}.</pre></div>
<p>Test terms:</p>
<div class="example"><pre>
{suites, Dir, Suites}.
{suites, NodeRefs, Dir, Suites}.
{groups, Dir, Suite, Groups}.
{groups, NodeRefs, Dir, Suite, Groups}.
{groups, Dir, Suite, Groups, {cases,Cases}}.
{groups, NodeRefs, Dir, Suite, Groups, {cases,Cases}}.
{cases, Dir, Suite, Cases}.
{cases, NodeRefs, Dir, Suite, Cases}.
{skip_suites, Dir, Suites, Comment}.
{skip_suites, NodeRefs, Dir, Suites, Comment}.
{skip_groups, Dir, Suite, GroupNames, Comment}.
{skip_groups, NodeRefs, Dir, Suite, GroupNames, Comment}.
{skip_cases, Dir, Suite, Cases, Comment}.
{skip_cases, NodeRefs, Dir, Suite, Cases, Comment}.</pre></div>
<p>Types:</p>
<div class="example"><pre>
Bool = true | false
Constant = atom()
Value = term()
NodeAlias = atom()
Node = node()
NodeRef = NodeAlias | Node | master
NodeRefs = all_nodes | [NodeRef] | NodeRef
InitOptions = term()
Label = atom() | string()
VerbosityLevels = integer() | [{Category,integer()}]
Category = atom()
CSSFile = string()
ConnTypes = all | [atom()]
N = integer()
CoverSpecFile = string()
IncludeDirs = string() | [string()]
ConfigFiles = string() | [string()]
ConfigDir = string()
ConfigBaseNames = string() | [string()]
CallbackModule = atom()
ConfigStrings = string() | [string()]
LogDir = string()
LogOpts = [term()]
PrivDirOption = auto_per_run | auto_per_tc | manual_per_tc
EventHandlers = atom() | [atom()]
InitArgs = [term()]
CTHModules = [CTHModule | {CTHModule, CTHInitArgs} | {CTHModule, CTHInitArgs, CTHPriority}]
CTHModule = atom()
CTHInitArgs = term()
Dir = string()
Suites = atom() | [atom()] | all
Suite = atom()
Groups = GroupPath | [GroupPath] | GroupSpec | [GroupSpec] | all
GroupPath = [GroupName]
GroupSpec = GroupName | {GroupName,Properties} | {GroupName,Properties,GroupSpec}
GroupName = atom()
GroupNames = GroupName | [GroupName]
Cases = atom() | [atom()] | all
Comment = string() | ""</pre></div>
<p>The difference between the <span class="code">config</span> terms above, is that with
<span class="code">ConfigDir</span>, <span class="code">ConfigBaseNames</span> is a list of base names,
i.e. without directory paths. <span class="code">ConfigFiles</span> must be full names,
including paths. E.g, these two terms have the same meaning:</p>
<div class="example"><pre>
{config, ["/home/testuser/tests/config/nodeA.cfg",
"/home/testuser/tests/config/nodeB.cfg"]}.
{config, "/home/testuser/tests/config", ["nodeA.cfg","nodeB.cfg"]}.</pre></div>
<div class="note">
<div class="label">Note</div>
<div class="content"><p><p>Any relative paths specified in the test specification, will be
relative to the directory which contains the test specification file, if
<span class="code">ct_run -spec TestSpecFile ...</span> or
<span class="code">ct:run:test([{spec,TestSpecFile},...])</span>
executes the test. The path will be relative to the top level log directory, if
<span class="code">ct:run:testspec(TestSpec)</span> executes the test.</p></p></div>
</div>
<p>The <span class="code">define</span> term introduces a constant, which is used to
replace the name <span class="code">Constant</span> with <span class="code">Value</span>, wherever it's found in
the test specification. This replacement happens during an initial iteration
through the test specification. Constants may be used anywhere in the test
specification, e.g. in arbitrary lists and tuples, and even in strings
and inside the value part of other constant definitions! A constant can
also be part of a node name, but that is the only place where a constant
can be part of an atom.</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p><p>For the sake of readability, the name of the constant must always
begin with an upper case letter, or a <span class="code">$</span>, <span class="code">?</span>, or <span class="code">_</span>.
This also means that it must always be single quoted (obviously, since
the constant name is actually an atom, not text).</p></p></div>
</div>
<p>The main benefit of constants is that they can be used to reduce the size
(and avoid repetition) of long strings, such as file paths. Compare these
terms:</p>
<div class="example"><pre>
%% 1a. no constant
{config, "/home/testuser/tests/config", ["nodeA.cfg","nodeB.cfg"]}.
{suites, "/home/testuser/tests/suites", all}.
%% 1b. with constant
{define, 'TESTDIR', "/home/testuser/tests"}.
{config, "'TESTDIR'/config", ["nodeA.cfg","nodeB.cfg"]}.
{suites, "'TESTDIR'/suites", all}.
%% 2a. no constants
{config, [testnode@host1, testnode@host2], "../config", ["nodeA.cfg","nodeB.cfg"]}.
{suites, [testnode@host1, testnode@host2], "../suites", [x_SUITE, y_SUITE]}.
%% 2b. with constants
{define, 'NODE', testnode}.
{define, 'NODES', ['NODE'@host1, 'NODE'@host2]}.
{config, 'NODES', "../config", ["nodeA.cfg","nodeB.cfg"]}.
{suites, 'NODES', "../suites", [x_SUITE, y_SUITE]}.</pre></div>
<p>Constants make the test specification term <span class="code">alias</span>, in previous
versions of Common Test, redundant. This term has been deprecated but will
remain supported in upcoming Common Test releases. Replacing <span class="code">alias</span>
terms with <span class="code">define</span> is strongly recommended though! Here's an example
of such a replacement:</p>
<div class="example"><pre>
%% using the old alias term
{config, "/home/testuser/tests/config/nodeA.cfg"}.
{alias, suite_dir, "/home/testuser/tests/suites"}.
{groups, suite_dir, x_SUITE, group1}.
%% replacing with constants
{define, 'TestDir', "/home/testuser/tests"}.
{define, 'CfgDir', "'TestDir'/config"}.
{define, 'SuiteDir', "'TestDir'/suites"}.
{config, 'CfgDir', "nodeA.cfg"}.
{groups, 'SuiteDir', x_SUITE, group1}.</pre></div>
<p>Actually, constants could well replace the <span class="code">node</span> term too, but
this still has declarative value, mainly when used in combination
with <span class="code">NodeRefs == all_nodes</span> (see types above).</p>
<p>Here follows a simple test specification example:</p>
<div class="example"><pre>
{define, 'Top', "/home/test"}.
{define, 'T1', "'Top'/t1"}.
{define, 'T2', "'Top'/t2"}.
{define, 'T3', "'Top'/t3"}.
{define, 'CfgFile', "config.cfg"}.
{logdir, "'Top'/logs"}.
{config, ["'T1'/'CfgFile'", "'T2'/'CfgFile'", "'T3'/'CfgFile'"]}.
{suites, 'T1', all}.
{skip_suites, 'T1', [t1B_SUITE,t1D_SUITE], "Not implemented"}.
{skip_cases, 'T1', t1A_SUITE, [test3,test4], "Irrelevant"}.
{skip_cases, 'T1', t1C_SUITE, [test1], "Ignore"}.
{suites, 'T2', [t2B_SUITE,t2C_SUITE]}.
{cases, 'T2', t2A_SUITE, [test4,test1,test7]}.
{skip_suites, 'T3', all, "Not implemented"}.</pre></div>
<p>The example specifies the following:</p>
<ul>
<li>The specified logdir directory will be used for storing
the HTML log files (in subdirectories tagged with node name,
date and time).</li>
<li>The variables in the specified test system config files will be
imported for the test.</li>
<li>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.</li>
<li>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.</li>
<li>Lastly, all suites for systems t3 are to be completely skipped and this
should be explicitly noted in the log files.</li>
</ul>
<p>With the <span class="code">init</span> term it's possible to specify initialization options
for nodes defined in the test specification. Currently, there are options
to start the node and/or to evaluate any function on the node.
See the <span class="bold_code"><a href="ct_master_chapter.html#ct_slave">Automatic startup of
the test target nodes</a></span> chapter for details.</p>
<p>It is possible for the user to provide a test specification that
includes (for Common Test) unrecognizable terms. If this is desired,
the <span class="code">-allow_user_terms</span> flag should be used when starting tests with
<span class="code">ct_run</span>. 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 <span class="code"><span class="bold_code"><a href="ct.html#run_test-1">ct:run_test/1</a></span></span> is used for starting the tests, the relaxed scanner
mode is enabled by means of the tuple: <span class="code">{allow_user_terms,true}</span></p>
<h3><a name="id76643">7.9
Running tests from the Web based GUI</a></h3>
<p>The web based GUI, VTS, is started with the
<span class="code"><span class="bold_code"><a href="run_test_chapter.html#ct_run">ct_run</a></span></span>
program. From the GUI you can load config files, and select
directories, suites and cases to run. You can also state the
config files, directories, suites and cases on the command line
when starting the web based GUI.
</p>
<ul>
<li><span class="code">ct_run -vts</span></li>
<li><span class="code">ct_run -vts -config <configfilename></span></li>
<li><span class="code">ct_run -vts -config <configfilename> -suite <suitewithfullpath>
-case <casename></span></li>
</ul>
<p>From the GUI you can run tests and view the result and the logs.
</p>
<p>Note that <span class="code">ct_run -vts</span> will try to open the Common Test start
page in an existing web browser window or start the browser if it is
not running. Which browser should be started may be specified with
the browser start command option:</p>
<p><span class="code">ct_run -vts -browser <browser_start_cmd></span></p>
<p>Example:</p>
<p><span class="code">$ ct_run -vts -browser 'firefox&'</span></p>
<p>Note that the browser must run as a separate OS process or VTS will hang!</p>
<p>If no specific browser start command is specified, Firefox will
be the default browser on Unix platforms and Internet Explorer on Windows.
If Common Test fails to start a browser automatically, or <span class="code">'none'</span> is
specified as the value for -browser (i.e. <span class="code">-browser none</span>), start your
favourite browser manually and type in the URL that Common Test
displays in the shell.</p>
<h3><a name="id76735">7.10
Log files</a></h3>
<a name="log_files"></a>
<p>As the execution of the test suites proceed, events are logged in
four different ways:</p>
<ul>
<li>Text to the operator's console.</li>
<li>Suite related information is sent to the major log file.</li>
<li>Case related information is sent to the minor log file.</li>
<li>The HTML overview log file gets updated with test results.</li>
<li>A link to all runs executed from a certain directory is written in
the log named "all_runs.html" and direct links to all tests (the
latest results) are written to the top level "index.html".</li>
</ul>
<p>Typically the operator, who may run hundreds or thousands of
test cases, doesn't want to fill the console with details
about, or printouts from, the specific test cases. By default, the
operator will only see:</p>
<ul>
<li>A confirmation that the test has started and information about how
many test cases will be executed totally.</li>
<li>A small note about each failed test case.</li>
<li>A summary of all the run test cases.</li>
<li>A confirmation that the test run is complete.</li>
<li>Some special information like error reports and progress
reports, printouts written with erlang:display/1, or io:format/3
specifically addressed to a receiver other than <span class="code">standard_io</span>
(e.g. the default group leader process 'user').</li>
</ul>
<p>If/when the operator wants to dig deeper into the general results, or
the result of a specific test case, he should do so by
following the links in the HTML presentation and 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 <span class="code">logdir</span> 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).</p>
<p>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:</p>
<ul>
<li>
<strong>TopLevelDir.TestDir</strong> (all suites in TestDir executed)</li>
<li>
<strong>TopLevelDir.TestDir:suites</strong> (specific suites were executed)</li>
<li>
<strong>TopLevelDir.TestDir.Suite</strong> (all cases in Suite executed)</li>
<li>
<strong>TopLevelDir.TestDir.Suite:cases</strong> (specific test cases were executed)</li>
<li>
<strong>TopLevelDir.TestDir.Suite.Case</strong> (only Case was executed)</li>
</ul>
<p>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.</p>
<p>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.</p>
<p>The major logfile shows a detailed report of the test run. It
includes test suite and test case names, execution time, the
exact reason for failures etc. The information is available in both
a file with textual and with HTML representation. The HTML file shows a
summary which gives a good overview of the test run. It also has links
to each individual test case log file for quick viewing with an HTML
browser.</p>
<p>The minor log files contain full details of every single test
case, each one in a separate file. This way, it should be
straightforward to compare the latest results to that of previous
test runs, even if the set of test cases changes. If SASL is running,
its logs will also be printed to the current minor log file by the
<span class="bold_code"><a href="javascript:erlhref('../../../../doc/../','common_test','ct_hooks_chapter.html#builtin_cths');">
cth_log_redirect built-in hook</a></span>.
</p>
<p>The full name of the minor log file (i.e. the name of the file
including the absolute directory path) can be read during execution
of the test case. It comes as value in the tuple
<span class="code">{tc_logfile,LogFileName}</span> in the <span class="code">Config</span> list (which means it
can also be read by a pre- or post Common Test hook function). Also,
at the start of a test case, this data is sent with an event
to any installed event handler. Please see the
<span class="bold_code"><a href="event_handler_chapter.html#event_handling">Event Handling</a></span>
chapter for details.
</p>
<p>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.</p>
<p>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.</p>
<h4>Log options</h4>
<a name="logopts"></a>
<p>With the <span class="code">logopts</span> start flag, it's possible to specify
options that modify some aspects of the logging behaviour.
Currently, the following options are available:</p>
<ul>
<li><span class="code">no_src</span></li>
<li><span class="code">no_nl</span></li>
</ul>
<p>With <span class="code">no_src</span>, the html version of the test suite source
code will not be generated during the test run (and consequently
not be available in the log file system).</p>
<p>With <span class="code">no_nl</span>, Common Test will not add a newline character
(\n) to the end of an output string that it receives from a call to e.g.
<span class="code">io:format/2</span>, and which it prints to the test case log.</p>
<p>For example, if a test is started with:</p>
<p><span class="code">$ ct_run -suite my_SUITE -logopts no_src</span></p>
<p>then printouts during the test made by successive calls to <span class="code">io:format("x")</span>,
will appear in the test case log as:</p>
<p><span class="code">xxx</span></p>
<p>instead of each <span class="code">x</span> printed on a new line, which is the default behaviour.</p>
<h4>Sorting HTML table columns</h4>
<a name="table_sorting"></a>
<p>By clicking the name in the column header of any table (e.g. "Ok", "Case", "Time", etc),
the table rows are sorted in whatever order makes sense for the type of value (e.g.
numerical for "Ok" or "Time", and alphabetical for "Case"). The sorting is performed
by means of JavaScript code, automatically inserted into the HTML log files. Common Test
uses the <span class="bold_code"><a href="http://jquery.com">jQuery</a></span> library and the
<span class="bold_code"><a href="http://tablesorter.com">tablesorter</a></span> plugin, with customized sorting
functions, for this implementation.</p>
<h3><a name="id77053">7.11
HTML Style Sheets</a></h3>
<a name="html_stylesheet"></a>
<p>Common Test uses an HTML Style Sheet (CSS file) to control the look of
the HTML log files generated during test runs. If, for some reason, the
log files are not displayed correctly in the browser of your
choice, or you prefer a more primitive ("pre Common Test v1.6") look
of the logs, use the start flag/option:</p>
<div class="example"><pre>basic_html</pre></div>
<p>This disables the use of Style Sheets, as well as JavaScripts (see
table sorting above).</p>
<p>Common Test includes an <strong>optional</strong> feature to allow
user HTML style sheets for customizing printouts. The
functions in <span class="code">ct</span> that print to a test case HTML log
file (<span class="code">log/3</span> and <span class="code">pal/3</span>) accept <span class="code">Category</span>
as first argument. With this argument it's possible to
specify a category that can be mapped to a selector in a CSS
definition. This is useful especially for coloring text
differently depending on the type of (or reason for) the
printout. Say you want one color for test system
configuration information, a different one for test system
state information and finally one for errors detected by the
test case functions. The corresponding style sheet may
look like this:</p>
<div class="example"><pre>
div.sys_config { background:blue; color:white }
div.sys_state { background:yellow; color:black }
div.error { background:red; color:white }</pre></div>
<p>To install the CSS file (Common Test inlines the definition in the
HTML code), the name may be provided when executing <span class="code">ct_run</span>.
Example:</p>
<div class="example"><pre>
$ ct_run -dir $TEST/prog -stylesheet $TEST/styles/test_categories.css</pre></div>
<p>Categories in a CSS file installed with the <span class="code">-stylesheet</span> 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.</p>
<p>It is also possible to install style sheets on a per suite and
per test case basis. Example:</p>
<div class="example"><pre>
-module(my_SUITE).
...
suite() -> [..., {stylesheet,"suite_categories.css"}, ...].
...
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).</pre></div>
<p>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 <span class="code">-stylesheet</span> flag). A stylesheet tuple (as returned by <span class="code">suite/0</span>
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.
</p>
<p>In a tuple <span class="code">{stylesheet,CSSFile}</span>, if <span class="code">CSSFile</span> is specified
with a path, e.g. <span class="code">"$TEST/styles/categories.css"</span>, 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, <span class="code">data_dir</span>, of the suite. The latter usage is
recommended since it is portable compared to hard coding path names in the
suite!</p>
<p>The <span class="code">Category</span> argument in the example above may have the
value (atom) <span class="code">sys_config</span> (white on blue), <span class="code">sys_state</span>
(black on yellow) or <span class="code">error</span> (white on red).</p>
<h3><a name="id77201">7.12
Repeating tests</a></h3>
<a name="repeating_tests"></a>
<p>You can order Common Test to repeat the tests you specify. You can choose
to repeat tests a certain number of times, repeat tests for a specific period of time,
or repeat tests until a particular stop time is reached. If repetition is controlled by
means of time, it is also possible to specify what action Common Test should
take upon timeout. Either Common Test performs all tests in the current run before stopping,
or it stops as soon as the current test job is finished. Repetition can be activated by
means of <span class="code">ct_run</span> start flags, or tuples in the <span class="code">ct:run:test/1</span>
option list argument. The flags (options in parenthesis) are:</p>
<ul>
<li>
<span class="code">-repeat N ({repeat,N})</span>, where <span class="code">N</span> is a positive integer.</li>
<li>
<span class="code">-duration DurTime ({duration,DurTime})</span>, where <span class="code">DurTime</span> is the duration, see below.</li>
<li>
<span class="code">-until StopTime ({until,StopTime})</span>, where <span class="code">StopTime</span> is finish time, see below.</li>
<li><span class="code">-force_stop ({force_stop,true})</span></li>
</ul>
<p>The duration time, <span class="code">DurTime</span>, is specified as <span class="code">HHMMSS</span>. Example:
<span class="code">-duration 012030</span> or <span class="code">{duration,"012030"}</span>, means the tests will
be executed and (if time allows) repeated, until timeout occurs after 1 h, 20 min
and 30 secs.
<span class="code">StopTime</span> can be specified as <span class="code">HHMMSS</span> and is then interpreted as a time today
(or possibly tomorrow). <span class="code">StopTime</span> can also be specified as <span class="code">YYMoMoDDHHMMSS</span>.
Example: <span class="code">-until 071001120000</span> or <span class="code">{until,"071001120000"}</span>, which means the tests
will be executed and (if time allows) repeated, until 12 o'clock on the 1st of Oct 2007.</p>
<p>When timeout occurs, Common Test will never abort the test run immediately, since
this might leave the system under test in an undefined, and possibly bad, state.
Instead Common Test will finish the current test job, or the complete test
run, before stopping. The latter is the default behaviour. The <span class="code">force_stop</span>
flag/option tells Common Test to stop as soon as the current test job is finished.
Note that since Common Test always finishes off the current test job or test session,
the time specified with <span class="code">duration</span> or <span class="code">until</span> is never definitive!</p>
<p>Log files from every single repeated test run is saved in normal Common Test fashion (see above).
Common Test may later support an optional feature to only store the last (and possibly
the first) set of logs of repeated test runs, but for now the user must be careful not
to run out of disk space if tests are repeated during long periods of time.</p>
<p>Note that for each test run that is part of a repeated session, information about the
particular test run is printed in the Common Test Framework Log. There you can read
the repetition number, remaining time, etc.</p>
<p>Example 1:</p>
<div class="example"><pre>
$ ct_run -dir $TEST_ROOT/to1 $TEST_ROOT/to2 -duration 001000 -force_stop</pre></div>
<p>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 <span class="code">force_stop</span> flag). As a result, the specified test run might be
aborted after the to1 test and before the to2 test.</p>
<p>Example 2:</p>
<div class="example"><pre>
$ date
Fri Sep 28 15:00:00 MEST 2007
$ ct_run -dir $TEST_ROOT/to1 $TEST_ROOT/to2 -until 160000</pre></div>
<p>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).</p>
<p>Example 3:</p>
<div class="example"><pre>
$ ct_run -dir $TEST_ROOT/to1 $TEST_ROOT/to2 -repeat 5</pre></div>
<p>Here the test run, including both the to1 and the to2 test, will be repeated 5 times.</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p><p>This feature should not be confused with the <span class="code">repeat</span> property of a test
case group. The options described here are used to repeat execution of entire test runs,
while the <span class="code">repeat</span> property of a test case group makes it possible to repeat
execution of sets of test cases within a suite. For more information about the latter,
see the <span class="bold_code"><a href="write_test_chapter.html#test_case_groups">Writing Test Suites</a></span>
chapter.</p></p></div>
</div>
<h3><a name="id77412">7.13
Silent Connections</a></h3>
<a name="silent_connections"></a>
<p>The protocol handling processes in Common Test, implemented by ct_telnet,
ct_ssh, ct_ftp etc, do verbose printing to the test case logs. This can be switched off
by means of the <span class="code">-silent_connections</span> flag:</p>
<div class="example"><pre>
ct_run -silent_connections [conn_types]
</pre></div>
<p>where <span class="code">conn_types</span> specifies <span class="code">ssh, telnet, ftp, rpc</span> and/or <span class="code">snmp</span>.</p>
<p>Example:</p>
<div class="example"><pre>
ct_run ... -silent_connections ssh telnet</pre></div>
<p>switches off logging for ssh and telnet connections.</p>
<div class="example"><pre>
ct_run ... -silent_connections</pre></div>
<p>switches off logging for all connection types.</p>
<p>Fatal communication error and reconnection attempts will always be printed even
if logging has been suppressed for the connection type in question. However, operations
such as sending and receiving data will be performed silently.</p>
<p>It is possible to also specify <span class="code">silent_connections</span> in a test suite. This is
accomplished by returning a tuple, <span class="code">{silent_connections,ConnTypes}</span>, in the
<span class="code">suite/0</span> or test case info list. If <span class="code">ConnTypes</span> is a list of atoms
(<span class="code">ssh, telnet, ftp, rpc</span> and/or <span class="code">snmp</span>), output for any corresponding connections
will be suppressed. Full logging is per default enabled for any connection of type not
specified in <span class="code">ConnTypes</span>. Hence, if <span class="code">ConnTypes</span> is the empty list, logging
is enabled for all connections.</p>
<p>Example:</p>
<div class="example"><pre>
-module(my_SUITE).
suite() -> [..., {silent_connections,[telnet,ssh]}, ...].
...
my_testcase1() ->
[{silent_connections,[ssh]}].
my_testcase1(_) ->
...
my_testcase2(_) ->
...
</pre></div>
<p>In this example, <span class="code">suite/0</span> tells Common Test to suppress
printouts from telnet and ssh connections. This is valid for
all test cases. However, <span class="code">my_testcase1/0</span> specifies that
for this test case, only ssh should be silent. The result is
that <span class="code">my_testcase1</span> will get telnet info (if any) printed
in the log, but not ssh info. <span class="code">my_testcase2</span> will get no
info from either connection printed.</p>
<p><span class="code">silent_connections</span> may also be specified with a term
in a test specification
(see <span class="bold_code"><a href="run_test_chapter.html#test_specifications">Test
Specifications</a></span>). Connections provided with the
<span class="code">silent_connections</span> start flag/option, will be merged with
any connections listed in the test specification.</p>
<p>The <span class="code">silent_connections</span> start flag/option and test
specification term, overrides any settings made by the info functions
inside the test suite.</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p><p>Note that in the current Common Test version, the
<span class="code">silent_connections</span> feature only works for telnet
and ssh connections! Support for other connection types will be added
in future Common Test versions.</p></p></div>
</div>
</div>
<div class="footer">
<hr>
<p>Copyright © 2003-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
675c8c8167236dfcf8d66da674f931e8
>
files
>
258
