<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2006</year><year>2016</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions 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>General</title>

    <p>A test is performed by running one or more test suites. A test suite
    consists of test cases, configuration functions, and information 
    functions. Test cases can 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>
    <marker id="skipping_test_cases"></marker>
    <title>Skipping Test Cases</title>

    <p>Certain test cases can be skipped, for example, if you
    know beforehand that a specific test case fails. The reason can be
    functionality that is not yet implemented, a bug that is known but
    not yet fixed, or some functionality that does not work or is not
    applicable on a specific platform.</p>

    <p>Test cases can be skipped in the following ways:</p>
    <list type="bulleted">

      <item>Using <c>skip_suites</c> and <c>skip_cases</c>
      terms in 
      <seeguide marker="run_test_chapter#test_specifications">test specifications</seeguide>.
      </item>

      <item>Returning <c>{skip,Reason}</c> from function
      <seemfa marker="common_test#Module:init_per_testcase/2"><c>init_per_testcase/2</c></seemfa> or 
      <seemfa marker="common_test#Module:init_per_suite/1"><c>init_per_suite/1</c></seemfa>.</item>

      <item>Returning <c>{skip,Reason}</c> from the execution clause
      of the test case. The execution clause is called, so the author 
      must ensure that the test case does not run.</item>

    </list>

    <p>When a test case is skipped, it is 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>
        <p>When a configuration function fails (that is, terminates unexpectedly), 
	the test cases depending on the configuration function are
	skipped automatically by <c>Common Test</c>. The status of the test cases 
	is then "auto-skipped".	Test cases are also "auto-skipped" by
	<c>Common Test</c> if the required configuration data is unavailable at
	runtime.</p>
      </item>

      <tag><em>Configuration function</em></tag>
      <item>
        <p>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 System Under Test (SUT) and/or the <c>Common Test</c> 
	host node, so that a test case (or a set of test cases) can 
	execute correctly.</p>     
      </item>

      <tag><em>Configuration file</em></tag>
      <item>
        <p>A file containing data related to a test and/or an SUT,
	for example, protocol server addresses, client
	login details, and hardware interface addresses. That is, any data
	that is to be handled as variable in the suite and not
	be hard-coded.</p>   
      </item>

      <tag><em>Configuration variable</em></tag>
      <item>
        <p>A name (an Erlang atom) associated with a data value read from
	a configuration file.</p>
      </item>

      <tag><c>data_dir</c></tag>
      <item>
	<p>Data directory for a test suite. This directory contains
	any files used by the test suite, for example, extra Erlang
	modules, binaries, or data files.</p>
      </item>

      <tag><em>Information function</em></tag>
      <item>
        <p>A function in a test suite that returns a list of properties
	(read by the <c>Common Test</c> server) that describes the conditions 
	for executing the test cases in the suite.</p>
      </item>
      
      <tag><em>Major log file</em></tag>
      <item>
	<p>An overview and summary log file for one or more test suites.</p>
      </item>

      <tag><em>Minor log file</em></tag>
      <item>
	<p>A log file for one particular test case. Also called the 
	test case log file.</p>
      </item>

      <tag><c>priv_dir</c></tag>
      <item>
	<p>Private directory for a test suite. This directory is to
	be used when the test suite needs to write to files.</p>
      </item>

      <tag><c>ct_run</c></tag>
      <item>
        <p>The name of an executable program that can be
	used as an interface for specifying and running
	tests with <c>Common Test</c>.</p>
      </item>

      <tag><em>Test case</em></tag>
      <item>
	<p>A single test included in a test suite. A test case is
	implemented as a function in a test suite module.</p>
      </item>

      <tag><em>Test case group</em></tag>
      <item>
        <p>A set of test cases sharing configuration functions and 
	execution properties. The execution properties specify if 
	the test cases in the group are to be executed in random order,
	in parallel, or in sequence, and if the execution of the group 
        is be repeated. Test case groups can also be nested. That is, 
	a group can, besides test cases, contain subgroups.</p>
      </item>
      
      <tag><em>Test suite</em></tag>
      <item>
	<p>An Erlang module containing a collection of test cases for
	a specific functional area.</p>
      </item>

      <tag><em>Test directory</em></tag>
      <item>
	<p>A directory containing one or more test suite modules,
	that is, a group of test suites.</p>
      </item>

      <tag><em>Argument</em> <c>Config</c></tag>
      <item>
        <p>A list of key-value tuples (that is, a property list) containing
	runtime configuration data passed from the configuration
	functions to the test cases.</p>
      </item>

      <tag><em>User-skipped test case</em></tag>
      <item>
        <p>The status of a test case explicitly skipped in any of 
	the ways described in section
	<seeguide marker="#skipping_test_cases">Skipping Test Cases</seeguide>.
	</p>
      </item>


    </taglist>
    
  </section>


</chapter>

