<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
<year>2006</year><year>2010</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
The contents of this file are subject to the Erlang Public License,
Version 1.1, (the "License"); you may not use this file except in
compliance with the License. You should have received a copy of the
Erlang Public License along with this software. If not, it can be
retrieved online at http://www.erlang.org/.
Software distributed under the License is distributed on an "AS IS"
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
the License for the specific language governing rights and limitations
under the License.
</legalnotice>
<title>Test Structure</title>
<prepared>Siri Hansen, Kenneth Lundin</prepared>
<docno></docno>
<date></date>
<rev></rev>
<file>test_structure_chapter.xml</file>
</header>
<section>
<title>Test structure</title>
<p>A test is performed by running one or more test suites. A test suite
consists of test cases (as well as configuration functions and info
functions). Test cases may be grouped in so called test case groups.
A test suite is an Erlang module and test cases are implemented as
Erlang functions. Test suites are stored in test directories.</p>
</section>
<section>
<title>Skipping test cases</title>
<p>It is possible to skip certain test cases, for example if you
know beforehand that a specific test case fails. This might be
functionality which isn't yet implemented, a bug that is known but
not yet fixed or some functionality which doesn't work or isn't
applicable on a specific platform.</p>
<p>There are several different ways to state that one or more
test cases should be skipped:</p>
<list>
<item>Using <c>skip_suites</c> and <c>skip_cases</c>
terms in
<seealso marker="run_test_chapter#test_specifications">test specifications</seealso>.
</item>
<item>Returning <c>{skip,Reason}</c> from the
<c>init_per_testcase/2</c> or <c>init_per_suite/1</c> functions.</item>
<item>Returning <c>{skip,Reason}</c> from the execution clause
of the test case.</item>
</list>
<p>The latter of course means that the execution clause is
actually called, so the author must make sure that the test case
does not run.</p>
<p>When a test case is skipped, it will be noted as <c>SKIPPED</c>
in the HTML log.</p>
</section>
<section>
<title>Definition of terms</title>
<taglist>
<tag><em>Auto skipped test case</em></tag>
<item>
When a configuration function fails (i.e. terminates unexpectedly),
the test cases that depend on the configuration function will be
skipped automatically by Common Test. The status of the test cases
is then "auto skipped". Test cases are also auto skipped by
Common Test if required configuration data is not available at
runtime.
</item>
<tag><em>Configuration function</em></tag>
<item>
A function in a test suite that is meant to be used for
setting up, cleaning up, and/or verifying the state and
environment on the SUT (System Under Test) and/or the Common Test
host node, so that a test case (or a set of test cases) can
execute correctly.
</item>
<tag><em>Configuration file</em></tag>
<item>
A file that contains data related to a test and/or an SUT
(System Under Test), e.g. protocol server addresses, client
login details, hardware interface addresses, etc - any data
that should be handled as variable in the suite and not
be hardcoded.
</item>
<tag><em>Configuration variable</em></tag>
<item>
A name (an Erlang atom) associated with a data value read from
a configuration file.
</item>
<tag><em>data_dir</em></tag>
<item>
Data directory for a test suite. This directory contains
any files used by the test suite, e.g. additional Erlang
modules, binaries or data files.
</item>
<tag><em>Info function</em></tag>
<item>
A function in a test suite that returns a list of properties
(read by the Common Test server) that describes the conditions
for executing the test cases in the suite.
</item>
<tag><em>Major log file</em></tag>
<item>
An overview and summary log file for one or more test suites.
</item>
<tag><em>Minor log file</em></tag>
<item>
A log file for one particular test case. Also called the
test case log file.
</item>
<tag><em>priv_dir</em></tag>
<item>
Private directory for a test suite. This directory should
be used when the test suite needs to write to files.
</item>
<tag><em>ct_run</em></tag>
<item>
The name of an executable program that may be
used as an interface for specifying and running
tests with Common Test.
</item>
<tag><em>Test case</em></tag>
<item>
A single test included in a test suite. A test case is
implemented as a function in a test suite module.
</item>
<tag><em>Test case group</em></tag>
<item>
A set of test cases that share configuration functions and
execution properties. The execution properties specify whether
the test cases in the group should be executed in random order,
in parallel, in sequence, and if the execution of the group
should be repeated. Test case groups may also be nested (i.e. a
group may, besides test cases, contain sub-groups).
</item>
<tag><em>Test suite</em></tag>
<item>
An erlang module containing a collection of test cases for
a specific functional area.
</item>
<tag><em>Test directory</em></tag>
<item>
A directory that contains one or more test suite modules, i.e.
a group of test suites.
</item>
<tag><em>The Config argument</em></tag>
<item>
A list of key-value tuples (i.e. a property list) containing
runtime configuration data passed from the configuration
functions to the test cases.
</item>
<tag><em>User skipped test case</em></tag>
<item>
This is the status of a test case that has been explicitly
skipped in any of the ways described in the "Skipping test cases"
section above.
</item>
</taglist>
</section>
</chapter>
