<!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 -- Getting Started</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="loadscrollpos" title="Getting Started" expanded="true">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="no" title="Running Tests" expanded="false">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>2 Getting Started</h1>
<h3><a name="id61356">2.1
Are you new around here?</a></h3>
<p>
The purpose of this short chapter is to, with a "learning by example"
approach, give the newcomer a chance to get started quickly writing and
executing some first simple tests. The chapter will introduce some of the
basics, but leave most explanations and details for the later
chapters in this User's Guide. Hopefully though, after this chapter, you
will be inspired and unintimidated enough to go on and get into the
nitty-gritty that follows in this rather heavy User's Guide! If you're
not much into "learning by example" and prefer to get into more technical
detail right away, go ahead and skip to the next chapter. Again, the basics
presented here will be covered in detail in later chapters.
</p>
<p>
This chapter also tries to demonstrate how dead simple it actually is
to write a very basic (yet for many module testing purposes, often sufficiently
complex) test suite, and execute its test cases. This is not necessarily
obvious when you read the rest of the chapters in the User's Guide.
</p>
<p>
A quick note before we start: In order to understand what's discussed and
examplified here, it is recommended that you first read through the
opening <span class="bold_code"><a href="basics_chapter.html#basics">Common Test Basics</a></span>
chapter.
</p>
<h3><a name="id63050">2.2
Test case execution</a></h3>
<p>Execution of test cases is handled this way:</p>
<p>
<img alt="IMAGE MISSING" src="tc_execution.gif"><br>
<em>Figure
.1:
Successful vs unsuccessful test case execution.
</em>
</p>
<p>For each test case that Common Test is told to execute, it spawns a
dedicated process on which the test case function in question starts
running. (In parallel to the test case process, an idle waiting timer
process is started which is linked to the test case process. If the timer
process runs out of waiting time, it sends an exit signal to terminate
the test case process and this is what's called a <strong>timetrap</strong>).
</p>
<p>In scenario 1, the test case process terminates normally after case A has
finished executing its test code without detecting any errors. The test
case function simply returns a value and Common Test logs the test case as
successful.
</p>
<p>In scenario 2, an error is detected during test case execution
which causes the test case B function to generate an exception.
This causes the test case process to exit with reason
other than normal, and as a result, Common Test will log this as an
unsuccessful test case.
</p>
<p>As you can understand from the illustration above, Common Test requires
that a test case generates a runtime error to indicate failure (e.g.
by causing a bad match error or by calling <span class="code">exit/1</span>, preferrably
through the <span class="code"><span class="bold_code"><a href="ct.html#fail-1">ct:fail/1,2</a></span></span> help function). A succesful execution is
indicated by means of a normal return from the test case function.
</p>
<h3><a name="id63909">2.3
A simple test suite</a></h3>
<p>As you've seen in the basics chapter, the test suite module implements
<span class="bold_code"><a href="common_test.html">callback functions</a></span>
(mandatory or optional) for various purposes, e.g:
<ul>
<li>Init/end configuration function for the test suite</li>
<li>Init/end configuration function for a test case</li>
<li>Init/end configuration function for a test case group</li>
<li>Test cases</li>
</ul>
The configuration functions are optional and if you don't need them for
your test, a test suite with one simple test case could look like this:
</p>
<div class="example"><pre>
-module(my1st_SUITE).
-compile(export_all).
all() ->
[mod_exists].
mod_exists(_) ->
{module,mymod} = code:load_file(mymod).</pre></div>
<p>
In this example we check that the <span class="code">mymod</span> module exists (i.e. can be
successfully loaded by the code server). If the operation fails, we will
get a bad match error which terminates the test case.
</p>
<h3><a name="id68094">2.4
A test suite with configuration functions</a></h3>
<p>
If we need to perform configuration operations in order to run our test, we
implement configuration functions in our suite. The result from a
configuration function is configuration data, or simply <strong><span class="code">Config</span></strong>.
This is a list of key-value tuples which get passed from the configuration
function to the test cases (possibly through configuration functions on
"lower level"). The data flow looks like this:
</p>
<p>
<img alt="IMAGE MISSING" src="config.gif"><br>
<em>Figure
.2:
Config data flow in the suite.
</em>
</p>
<p>
Here's an example of a test suite which uses configuration functions
to open and close a log file for the test cases (an operation that would
be unnecessary and irrelevant to perform by each test case):
</p>
<div class="example"><pre>
-module(check_log_SUITE).
-export([all/0, init_per_suite/1, end_per_suite/1]).
-export([check_restart_result/1, check_no_errors/1]).
-define(value(Key,Config), proplists:get_value(Key,Config)).
all() -> [check_restart_result, check_no_errors].
init_per_suite(InitConfigData) ->
[{logref,open_log()} | InitConfigData].
end_per_suite(ConfigData) ->
close_log(?value(logref, ConfigData)).
check_restart_result(ConfigData) ->
TestData = read_log(restart, ?value(logref, ConfigData)),
{match,_Line} = search_for("restart successful", TestData).
check_no_errors(ConfigData) ->
TestData = read_log(all, ?value(logref, ConfigData)),
case search_for("error", TestData) of
{match,Line} -> ct:fail({error_found_in_log,Line});
nomatch -> ok
end.</pre></div>
<p>
In this example we have test cases that verify, by parsing a
log file, that our SUT has performed a successful restart and
that no unexpected errors have been printed.
</p>
<p>To execute the test cases in the test suite above, we could type this on
the Unix/Linux command line (assuming for this example that the suite module
is in the current working directory):
</p>
<div class="example"><pre>
$ ct_run -dir .</pre></div>
<p>or</p>
<div class="example"><pre>
$ ct_run -suite check_log_SUITE</pre></div>
<p>If we want to use the Erlang shell to run our test, we could evaluate this call:
</p>
<div class="example"><pre>
1> ct:run_test([{dir, "."}]).</pre></div>
<p>or</p>
<div class="example"><pre>
1> ct:run_test([{suite, "check_log_SUITE"}]).</pre></div>
<p>
The result from running our test is printed in log files in HTML format
(stored in unique log directories on different level). This illustration
shows the log file structure:
</p>
<p>
<img alt="IMAGE MISSING" src="html_logs.gif"><br>
<em>Figure
.3:
HTML log file structure.
</em>
</p>
<h3><a name="id62545">2.5
What happens next?</a></h3>
<p>Well, you might already be asking yourself questions such as:</p>
<ul>
<li>"How and where can I specify variable data for my tests that mustn't
be hard-coded in the test suites (such as host names, addresses,
user login data, etc)?" The
<span class="bold_code"><a href="config_file_chapter.html#top">External Configuration Data</a></span>
chapter will give you that information.
</li>
<li>"Is there a way to declare a number of different tests and run them
in one session without having to write my own scripts? And can such
declarations be used for regression testing?" The
<span class="bold_code"><a href="run_test_chapter.html#test_specifications">Test Specifications</a></span>
chapter answers these questions.
</li>
<li>"Can test cases and/or test runs be automatically repeated?" Learn more about
<span class="bold_code"><a href="write_test_chapter.html#test_case_groups">Test Case Groups</a></span>
and also read about start flags/options in the
<span class="bold_code"><a href="run_test_chapter.html#ct_run">Running Tests</a></span> chapter and
the Reference Manual.
</li>
<li>"Will Common Test execute my test cases in sequence or in parallel?" The
<span class="bold_code"><a href="write_test_chapter.html#test_case_groups">Test Case Groups</a></span>
section in the Running Tests chapter will give you the answer.
</li>
<li>"What's the syntax for timetraps (mentioned above), and how do I set them?"
This is explained in the
<span class="bold_code"><a href="write_test_chapter.html#timetraps">Timetrap Timeouts</a></span>
part of the Writing Test Suites chapter.
</li>
<li>"What functions are available for logging and printing?" Check the
<span class="bold_code"><a href="write_test_chapter.html#logging">Logging</a></span>
section in the Writing Test Suites chapter.
</li>
<li>"I need data files for my tests. Where do I store them preferrably?"
You should read about
<span class="bold_code"><a href="write_test_chapter.html#data_priv_dir">Data and Private
Directories</a></span> for information about this.
</li>
<li>"May I start with a test suite example, please?"
<span class="bold_code"><a href="example_chapter.html#top">Sure!</a></span>
</li>
</ul>
<p>You will probably want to get started on your own first test suites now, while
at the same time digging deeper into the Common Test User's Guide and Reference Manual.
You will find that there's lots more to learn about the things that have been introduced
in this chapter. You will of course also be presented many more useful features, such as the
ones listed above. Have fun!
</p>
</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
>
252
