Common Test: Editorial changes 3

Reference Manual files from Pär Wennstad added

1 files changed, 1386 insertions, 0 deletions

diff --git a/lib/common_test/doc/src/ct.xml b/lib/common_test/doc/src/ct.xml
new file mode 100644
index 0000000000..ed3d76061a
--- /dev/null
+++ b/lib/common_test/doc/src/ct.xml
@@ -0,0 +1,1386 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>2010</year><year>2012</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>ct</title>
+    <prepared></prepared>
+    <responsible></responsible>
+    <docno></docno>
+    <approved></approved>
+    <checked></checked>
+    <date></date>
+    <rev>A</rev>
+    <file>ct.xml</file>
+  </header>
+  <module>ct</module>
+  <modulesummary>Main user interface for the Common Test framework.</modulesummary>
+
+  <description>
+
+     <p>Main user interface for the <c>Common Test</c> framework.</p>
+
+     <p>This module implements the command-line interface for running
+       tests and basic functions for <c>Common Test</c> case issues, such as
+       configuration and logging.</p>
+
+     <p><em>Test Suite Support Macros</em></p> 
+
+     <p>The <c>config</c> macro is defined in <c>ct.hrl</c>. This macro is
+       to be used to retrieve information from the <c>Config</c> variable sent
+       to all test cases. It is used with two arguments; the first is the name
+       of the configuration variable to retrieve, the second is the
+       <c>Config</c> variable supplied to the test case.</p>
+
+    <p>Possible configuration variables include:</p>
+
+    <list type="bulleted">
+      <item><p><c>data_dir</c> - Data file directory</p></item>
+      <item><p><c>priv_dir</c> - Scratch file directory</p></item>
+      <item><p>Whatever added by
+      <seealso marker="#Module:init_per_suite-1"><c>init_per_suite/1</c></seealso>
+      or
+      <seealso marker="#Module:init_per_testcase-2"><c>init_per_testcase/2</c></seealso>
+      in the test suite.</p></item>
+    </list>
+
+  </description>
+
+  <section>
+    <title>Data Types</title>
+    <marker id="types"/>
+    <taglist>
+
+      <tag><c>handle() = pid()</c></tag>
+        <item><marker id="type-handle"/>
+          <p>The identity (handle) of a connection.</p></item>
+
+      <tag><c>target_name() = atom()</c></tag>
+        <item><marker id="type-target_name"/>
+          <p>A name and association to configuration data introduced
+            through a require statement, or a call to
+            <seealso marker="#require-2"><c>ct:require/2</c></seealso>,
+            for example,
+            <c>ct:require(mynodename,{node,[telnet]})</c>.</p></item>
+
+    </taglist>
+  </section>
+
+  <funcs>
+    <func>
+      <name>abort_current_testcase(Reason) -&gt; ok | {error, ErrorReason}</name>
+      <fsummary>Aborts the currently executing test case.</fsummary>
+      <type>
+        <v>Reason = term()</v>
+        <v>ErrorReason = no_testcase_running | parallel_group</v>
+      </type>
+      <desc><marker id="abort_current_testcase-1"/>
+        <p>Aborts the currently executing test case. The user must know with
+          certainty which test case is currently executing. The function is
+          therefore only safe to call from a function that has been called
+          (or synchronously invoked) by the test case.</p>
+
+        <p><c>Reason</c>, the reason for aborting the test case, is printed
+          in the test case log.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>add_config(Callback, Config) -&gt; ok | {error, Reason}</name>
+      <fsummary>Loads configuration variables using the specified callback
+        module and configuration string.</fsummary>
+      <type>
+        <v>Callback = atom()</v>
+        <v>Config = string()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc><marker id="add_config-2"/>
+        <p>Loads configuration variables using the specified callback module and
+          configuration string. The callback module is to be either loaded or
+          present in the code part. Loaded configuration variables can later
+          be removed using function
+          <seealso marker="#remove_config-2"><c>ct:remove_config/2</c></seealso>.
+        </p>
+      </desc>
+    </func>
+
+    <func>
+      <name>break(Comment) -&gt; ok | {error, Reason}</name>
+      <fsummary>Cancels any active timetrap and pause the execution of the
+        current test case until the user calls function continue/0.</fsummary>
+      <type>
+        <v>Comment = string()</v>
+        <v>Reason = {multiple_cases_running, TestCases} | 'enable break with release_shell option'</v>
+        <v>TestCases = [atom()]</v>
+      </type>
+      <desc><marker id="break-1"/>
+        <p>Cancels any active timetrap and pauses the execution of the
+          current test case until the user calls function <c>continue/0</c>.
+          The user can then interact with the Erlang node running the tests,
+          for example, for debugging purposes or for manually executing a
+          part of the test case. If a parallel group is executing,
+          <seealso marker="#break-2"><c>ct:break/2</c></seealso> is to be
+          called instead.</p>
+       <p>A cancelled timetrap is not automatically reactivated after the
+         break, but must be started exlicitly with
+         <seealso marker="#timetrap-1"><c>ct:timetrap/1</c></seealso>.</p>
+       <p>In order for the break/continue functionality to work, <c>Common
+         Test</c> must release the shell process controlling <c>stdin</c>.
+         This is done by setting start option <c>release_shell</c>
+         to <c>true</c>. For details, see section
+         <seealso marker="run_test_chapter#erlang_shell_or_program">Running
+         Tests from the Erlang Shell or from an Erlang Program</seealso>
+         in the User's Guide.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>break(TestCase, Comment) -&gt; ok | {error, Reason}</name>
+      <fsummary>Works the same way as break/1, only argument TestCase makes it
+        possible to pause a test case executing in a parallel group.</fsummary>
+      <type>
+        <v>TestCase = atom()</v>
+        <v>Comment = string()</v>
+        <v>Reason = 'test case not running' | 'enable break with release_shell option'</v>
+      </type>
+      <desc><marker id="break-2"/>
+        <p>Works the same way as
+          <seealso marker="#break-1"><c>ct:break/1</c></seealso>, only
+          argument <c>TestCase</c> makes it possible to pause a test case
+          executing in a parallel group. Function
+          <seealso marker="#continue-1"><c>ct:continue/1</c></seealso> is to
+          be used to resume execution of <c>TestCase</c>.</p>
+
+        <p>For details, see
+          <seealso marker="#break/1"><c>ct:break/1</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>capture_get() -&gt; ListOfStrings</name>
+      <fsummary>Equivalent to capture_get([default]).</fsummary>
+      <type>
+        <v>ListOfStrings = [string()]</v>
+      </type>
+      <desc><marker id="capture_get-0"/>
+        <p>Equivalent to
+          <seealso marker="#capture_get-1">ct:capture_get([default])</seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>capture_get(ExclCategories) -&gt; ListOfStrings</name>
+      <fsummary>Returns and purges the list of text strings buffered during
+        the latest session of capturing printouts to stdout.</fsummary>
+      <type>
+        <v>ExclCategories = [atom()]</v>
+        <v>ListOfStrings = [string()]</v>
+      </type>
+      <desc><marker id="capture_get-1"/>
+        <p>Returns and purges the list of text strings buffered during the
+          latest session of capturing printouts to <c>stdout</c>. Log
+          categories that are to be ignored in <c>ListOfStrings</c> can be
+          specified with <c>ExclCategories</c>.
+          If <c>ExclCategories = []</c>, no filtering takes place.</p>
+
+        <p>See also
+          <seealso marker="#capture_start-0"><c>ct:capture_start/0</c></seealso>,
+          <seealso marker="#capture_stop-0"><c>ct:capture_stop/0</c></seealso>,
+          <seealso marker="#log-3"><c>ct:log/3</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>capture_start() -&gt; ok</name>
+      <fsummary>Starts capturing all text strings printed to stdout
+        during execution of the test case.</fsummary>
+        <desc><marker id="capture_start-0"/>
+        <p>Starts capturing all text strings printed to <c>stdout</c>
+          during execution of the test case.</p>
+
+        <p>See also
+          <seealso marker="#capture_get-1"><c>ct:capture_get/1</c></seealso>,
+          <seealso marker="#capture_stop-0"><c>ct:capture_stop/0</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>capture_stop() -&gt; ok</name>
+      <fsummary>Stops capturing text strings (a session started with
+        capture_start/0).</fsummary>
+      <desc><marker id="capture_stop-0"/>
+        <p>Stops capturing text strings (a session started with
+          <c>capture_start/0</c>).</p>
+
+        <p>See also
+          <seealso marker="#capture_get-1"><c>ct:capture_get/1</c></seealso>,
+          <seealso marker="#capture_start-0"><c>ct:capture_start/0</c></seealso>.</p>
+       </desc>
+    </func>
+
+    <func>
+      <name>comment(Comment) -&gt; ok</name>
+      <fsummary>Prints the specified Comment in the comment field in the
+        table on the test suite result page.</fsummary>
+      <type>
+        <v>Comment = term()</v>
+      </type>
+      <desc><marker id="comment-1"/>
+        <p>Prints the specified <c>Comment</c> in the comment field in the
+          table on the test suite result page.</p>
+
+        <p>If called several times, only the last comment is printed. The
+          test case return value <c>{comment,Comment}</c> overwrites the
+          string set by this function.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>comment(Format, Args) -&gt; ok</name>
+      <fsummary>Prints the formatted string in the comment field in the
+        table on the test suite result page.</fsummary>
+      <type>
+        <v>Format = string()</v>
+        <v>Args = list()</v>
+      </type>
+      <desc><marker id="comment-2"/>
+        <p>Prints the formatted string in the comment field in the table
+          on the test suite result page.</p>
+
+        <p>Arguments <c>Format</c> and <c>Args</c> are used in a call to
+          <c>io_lib:format/2</c> to create the comment string. The behavior
+          of <c>comment/2</c> is otherwise the same as function
+          <seealso marker="#comment-1"><c>ct:comment/1</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>continue() -&gt; ok</name>
+      <fsummary>This function must be called to continue after a test
+        case (not executing in a parallel group) has called break/1.</fsummary>
+      <desc><marker id="continue-0"/>
+        <p>This function must be called to continue after a test case
+          (not executing in a parallel group) has called function
+          <seealso marker="#break-1"><c>ct:break/1</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>continue(TestCase) -&gt; ok</name>
+      <fsummary>This function must be called to continue after a test case
+        has called break/2.</fsummary>
+      <type>
+        <v>TestCase = atom()</v>
+      </type>
+      <desc><marker id="continue-1"/>
+        <p>This function must be called to continue after a test case has
+          called <seealso marker="#break-2"><c>ct:break/2</c></seealso>.
+          If the paused test case, <c>TestCase</c>, executes in a parallel
+          group, this function, rather than <c>continue/0</c>, must be used
+          to let the test case proceed.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>decrypt_config_file(EncryptFileName, TargetFileName) -&gt; ok | {error, Reason}</name>
+      <fsummary>Decrypts EncryptFileName, previously generated with
+        encrypt_config_file/2,3.</fsummary>
+      <type>
+        <v>EncryptFileName = string()</v>
+        <v>TargetFileName = string()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc><marker id="decrypt_config_file-2"/>
+        <p>Decrypts <c>EncryptFileName</c>, previously generated with
+          <seealso marker="#encrypt_config_file-2"><c>ct:encrypt_config_file/2,3</c></seealso>.
+          The original file contents is saved in the target file. The
+          encryption key, a string, must be available in a text file named
+          <c>.ct_config.crypt</c>, either in the current directory, or the
+          home directory of the user (it is searched for in that order).</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>decrypt_config_file(EncryptFileName, TargetFileName, KeyOrFile) -&gt; ok | {error, Reason}</name>
+      <fsummary>Decrypts EncryptFileName, previously generated with
+        encrypt_config_file/2,3.</fsummary>
+      <type>
+        <v>EncryptFileName = string()</v>
+        <v>TargetFileName = string()</v>
+        <v>KeyOrFile = {key, string()} | {file, string()}</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc><marker id="decrypt_config_file-3"/>
+        <p>Decrypts <c>EncryptFileName</c>, previously generated with
+          <seealso marker="#encrypt_config_file-2"><c>ct:encrypt_config_file/2,3</c></seealso>.
+          The original file contents is saved in the target file. The key
+          must have the same value as that used for encryption.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>encrypt_config_file(SrcFileName, EncryptFileName) -&gt; ok | {error, Reason}</name>
+      <fsummary>Encrypts the source configuration file with DES3 and saves the
+        result in file EncryptFileName.</fsummary>
+      <type>
+        <v>SrcFileName = string()</v>
+        <v>EncryptFileName = string()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc><marker id="encrypt_config_file-2"/>
+        <p>Encrypts the source configuration file with DES3 and saves the result
+          in file <c>EncryptFileName</c>. The key, a string, must be
+          available in a text file named <c>.ct_config.crypt</c>, either
+          in the current directory, or the home directory of the user (it
+          is searched for in that order).</p>
+
+        <p>For information about using encrypted configuration files when
+          running tests, see section
+          <seealso marker="config_file_chapter#encrypted_config_files">Encrypted
+          Configuration Files</seealso> in the User's Guide.</p>
+
+        <p>For details on DES3 encryption/decryption, see application
+          <seealso marker="crypto"><c>Crypto</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>encrypt_config_file(SrcFileName, EncryptFileName, KeyOrFile) -&gt; ok | {error, Reason}</name>
+      <fsummary>Encrypts the source configuration file with DES3 and saves the
+       result in the target file EncryptFileName.</fsummary>
+      <type>
+        <v>SrcFileName = string()</v>
+        <v>EncryptFileName = string()</v>
+        <v>KeyOrFile = {key, string()} | {file, string()}</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc><marker id="encrypt_config_file-3"/>
+        <p>Encrypts the source configuration file with DES3 and saves the result
+          in the target file <c>EncryptFileName</c>. The encryption key
+          to use is either the value in <c>{key,Key}</c> or the value
+          stored in the file specified by <c>{file,File}</c>.</p>
+
+        <p>For information about using encrypted configuration files when
+          running tests, see section
+          <seealso marker="config_file_chapter#encrypted_config_files">Encrypted
+          Configuration Files</seealso> in the User's Guide.</p>
+
+        <p>For details on DES3 encryption/decryption, see application
+          <seealso marker="crypto"><c>Crypto</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>fail(Reason) -&gt; ok</name>
+      <fsummary>Terminates a test case with the specified error
+        Reason.</fsummary>
+      <type>
+        <v>Reason = term()</v>
+      </type>
+      <desc><marker id="fail-1"/>
+        <p>Terminates a test case with the specified error <c>Reason</c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>fail(Format, Args) -&gt; ok</name>
+      <fsummary>Terminates a test case with an error message specified by
+        a format string and a list of values (used as arguments to
+        io_lib:format/2).</fsummary>
+        <type>
+          <v>Format = string()</v>
+          <v>Args = list()</v>
+       </type>
+      <desc><marker id="fail-2"/>
+        <p>Terminates a test case with an error message specified by a
+          format string and a list of values (used as arguments to
+          <c>io_lib:format/2</c>).</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>get_config(Required) -&gt; Value</name>
+      <fsummary>Equivalent to get_config(Required, undefined, []).</fsummary>
+      <desc><marker id="get_config-1"/>
+        <p>Equivalent to <seealso marker="#get_config-3"><c>ct:get_config(Required,
+          undefined, [])</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>get_config(Required, Default) -&gt; Value</name>
+      <fsummary>Equivalent to get_config(Required, Default, []).</fsummary>
+      <desc><marker id="get_config-2"/>
+        <p>Equivalent to <seealso marker="#get_config-3"><c>ct:get_config(Required,
+          Default, [])</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>get_config(Required, Default, Opts) -&gt; ValueOrElement</name>
+      <fsummary>Reads configuration data values.</fsummary>
+      <type>
+        <v>Required = KeyOrName | {KeyOrName, SubKey} | {KeyOrName, SubKey, SubKey}</v>
+        <v>KeyOrName = atom()</v>
+        <v>SubKey = atom()</v>
+        <v>Default = term()</v>
+        <v>Opts = [Opt] | []</v>
+        <v>Opt = element | all</v>
+        <v>ValueOrElement = term() | Default</v>
+      </type>
+      <desc><marker id="get_config-3"/>
+        <p>Reads configuration data values.</p>
+
+        <p>Returns the matching values or configuration elements, given a
+          configuration variable key or its associated name (if one has been
+          specified with
+          <seealso marker="#require-2"><c>ct:require/2</c></seealso>
+          or a <c>require</c> statement).</p>
+
+        <p><em>Example:</em></p>
+
+        <p>Given the following configuration file:</p>
+
+        <pre>
+ {unix,[{telnet,IpAddr},
+        {user,[{username,Username},
+               {password,Password}]}]}.</pre>
+
+        <p>Then:</p>
+
+        <pre>
+ ct:get_config(unix,Default) -&gt; [{telnet,IpAddr}, 
+  {user, [{username,Username}, {password,Password}]}]
+ ct:get_config({unix,telnet},Default) -&gt; IpAddr
+ ct:get_config({unix,user,username},Default) -&gt; Username
+ ct:get_config({unix,ftp},Default) -&gt; Default
+ ct:get_config(unknownkey,Default) -&gt; Default</pre>
+
+        <p>If a configuration variable key has been associated with a name (by
+          <seealso marker="#require-2"><c>ct:require/2</c></seealso>
+          or a <c>require</c> statement), the name can be used instead
+          of the key to read the value:</p>
+
+        <pre>
+ ct:require(myuser,{unix,user}) -&gt; ok.
+ ct:get_config(myuser,Default) -&gt; [{username,Username}, {password,Password}]</pre>
+  
+        <p>If a configuration variable is defined in multiple files, use option
+         <c>all</c> to access all possible values. The values are returned
+          in a list. The order of the elements corresponds to the order
+          that the configuration files were specified at startup.</p>
+
+        <p>If configuration elements (key-value tuples) are to be returned as
+          result instead of values, use option <c>element</c>. The
+          returned elements are then on the form <c>{Required,Value}</c>.</p>
+
+        <p>See also
+          <seealso marker="#get_config-1"><c>ct:get_config/1</c></seealso>,
+          <seealso marker="#get_config-2"><c>ct:get_config/2</c></seealso>,
+          <seealso marker="#require-1"><c>ct:require/1</c></seealso>,
+          <seealso marker="#require-2"><c>ct:require/2</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>get_event_mgr_ref() -&gt; EvMgrRef</name>
+      <fsummary>Gets a reference to the <c>Common Test</c> event manager.</fsummary>
+        <type>
+          <v>EvMgrRef = atom()</v>
+        </type>
+        <desc><marker id="get_event_mgr_ref-0"/>
+          <p>Gets a reference to the <c>Common Test</c> event manager.
+            The reference can be used to, for example, add a user-specific
+            event handler while tests are running.</p>
+
+          <p><em>Example:</em></p>
+
+          <pre>
+ gen_event:add_handler(ct:get_event_mgr_ref(), my_ev_h, [])</pre>
+      </desc>
+    </func>
+
+    <func>
+      <name>get_status() -&gt; TestStatus | {error, Reason} | no_tests_running</name>
+      <fsummary>Returns status of ongoing test.</fsummary>
+      <type>
+        <v>TestStatus = [StatusElem]</v>
+        <v>StatusElem = {current, TestCaseInfo} | {successful, Successful} | {failed, Failed} | {skipped, Skipped} | {total, Total}</v>
+        <v>TestCaseInfo = {Suite, TestCase} | [{Suite, TestCase}]</v>
+        <v>Suite = atom()</v>
+        <v>TestCase = atom()</v>
+        <v>Successful = integer()</v>
+        <v>Failed = integer()</v>
+        <v>Skipped = {UserSkipped, AutoSkipped}</v>
+        <v>UserSkipped = integer()</v>
+        <v>AutoSkipped = integer()</v>
+        <v>Total = integer()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc><marker id="get_status-0"/>
+        <p>Returns status of ongoing test. The returned list contains
+          information about which test case is executing (a list of cases
+          when a parallel test case group is executing), as well as
+          counters for successful, failed, skipped, and total test cases
+          so far.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>get_target_name(Handle) -&gt; {ok, TargetName} | {error, Reason}</name>
+      <fsummary>Returns the name of the target that the specified connection
+        belongs to.</fsummary>
+      <type>
+        <v>Handle = handle()</v>
+        <v>TargetName = target_name()</v>
+      </type>
+      <desc><marker id="get_target_name-1"/>
+        <p>Returns the name of the target that the specified connection
+          belongs to.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>get_testspec_terms() -&gt; TestSpecTerms | undefined</name>
+      <fsummary>Gets a list of all test specification terms used to
+        configure and run this test.</fsummary>
+      <type>
+        <v>TestSpecTerms = [{Tag, Value}]</v>
+        <v>Value = [term()]</v>
+      </type>
+      <desc><marker id="get_testspec_terms-0"/>
+        <p>Gets a list of all test specification terms used to configure
+          and run this test.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>get_testspec_terms(Tags) -&gt; TestSpecTerms | undefined</name>
+      <fsummary>Reads one or more terms from the test specification used to
+        configure and run this test.</fsummary>
+      <type>
+        <v>Tags = [Tag] | Tag</v>
+        <v>Tag = atom()</v>
+        <v>TestSpecTerms = [{Tag, Value}] | {Tag, Value}</v>
+        <v>Value = [{Node, term()}] | [term()]</v>
+        <v>Node = atom()</v>
+      </type>
+      <desc><marker id="get_testspec_terms-1"/>
+        <p>Reads one or more terms from the test specification used to
+          configure and run this test. <c>Tag</c> is any valid test
+          specification tag, for example, <c>label</c>, <c>config</c>, or
+          <c>logdir</c>. User-specific terms are also available to read if
+          option <c>allow_user_terms</c> is set.</p>
+        <p>All value tuples returned, except user terms, have the node
+          name as first element.</p>
+        <p>To read test terms, use <c>Tag = tests</c> (rather than
+          <c>suites</c>, <c>groups</c>, or <c>cases</c>). <c>Value</c> is
+          then the list of <em>all</em> tests on the form
+          <c>[{Node,Dir,[{TestSpec,GroupsAndCases1},...]},...]</c>, where
+          <c>GroupsAndCases = [{Group,[Case]}] | [Case]</c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>get_timetrap_info() -&gt; {Time, Scale}</name>
+      <fsummary>Reads information about the timetrap set for the current
+        test case.</fsummary>
+      <type>
+        <v>Time = integer() | infinity</v>
+        <v>Scale = true | false</v>
+      </type>
+     <desc><marker id="get_timetrap_info-0"/>
+        <p>Reads information about the timetrap set for the current test
+          case. <c>Scale</c> indicates if <c>Common Test</c> will attempt
+          to compensate timetraps automatically for runtime delays
+          introduced by, for example, tools like cover.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>install(Opts) -&gt; ok | {error, Reason}</name>
+      <fsummary>Installs configuration files and event handlers.</fsummary>
+      <type>
+        <v>Opts = [Opt]</v>
+        <v>Opt = {config, ConfigFiles} | {event_handler, Modules} | {decrypt, KeyOrFile}</v>
+        <v>ConfigFiles = [ConfigFile]</v>
+        <v>ConfigFile = string()</v>
+        <v>Modules = [atom()]</v>
+        <v>KeyOrFile = {key, Key} | {file, KeyFile}</v>
+        <v>Key = string()</v>
+        <v>KeyFile = string()</v>
+      </type>
+      <desc><marker id="install-1"/>
+        <p>Installs configuration files and event handlers.</p>
+
+        <p>Run this function once before the first test.</p>
+
+        <p><em>Example:</em></p>
+
+        <pre>
+ install([{config,["config_node.ctc","config_user.ctc"]}])</pre>
+
+        <p>This function is automatically run by program <c>ct_run</c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>listenv(Telnet) -&gt; [Env]</name>
+      <fsummary>Performs command listenv on the specified Telnet connection
+        and returns the result as a list of key-value pairs.</fsummary>
+      <type>
+        <v>Telnet = term()</v>
+        <v>Env = {Key, Value}</v>
+        <v>Key = string()</v>
+        <v>Value = string()</v>
+      </type>
+      <desc><marker id="listenv-1"/>
+        <p>Performs command <c>listenv</c> on the specified Telnet connection
+          and returns the result as a list of key-value pairs.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>log(Format) -&gt; ok</name>
+      <fsummary>Equivalent to log(default, 50, Format, []).</fsummary>
+      <desc><marker id="log-1"/>
+        <p>Equivalent to
+          <seealso marker="#log-4"><c>ct:log(default, 50, Format, [])</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>log(X1, X2) -&gt; ok</name>
+      <fsummary>Equivalent to log(Category, Importance, Format,
+        Args).</fsummary>
+      <type>
+        <v>X1 = Category | Importance | Format</v>
+        <v>X2 = Format | Args</v>
+      </type>
+      <desc><marker id="log-2"/>
+        <p>Equivalent to <seealso marker="#log-4"><c>ct:log(Category,
+          Importance, Format, Args)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>log(X1, X2, X3) -&gt; ok</name>
+      <fsummary>Equivalent to log(Category, Importance, Format,
+        Args).</fsummary>
+      <type>
+        <v>X1 = Category | Importance</v>
+        <v>X2 = Importance | Format</v>
+        <v>X3 = Format | Args</v>
+      </type>
+      <desc><marker id="log-3"/>
+        <p>Equivalent to <seealso marker="#log-4"><c>ct:log(Category,
+          Importance, Format, Args)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>log(Category, Importance, Format, Args) -&gt; ok</name>
+      <fsummary>Prints from a test case to the log file.</fsummary>
+      <type>
+        <v>Category = atom()</v>
+        <v>Importance = integer()</v>
+        <v>Format = string()</v>
+        <v>Args = list()</v>
+      </type>
+      <desc><marker id="log-4"/>
+        <p>Prints from a test case to the log file.</p>
+
+        <p>This function is meant for printing a string directly from a
+          test case to the test case log file.</p>
+
+        <p>Default <c>Category</c> is <c>default</c>,
+          default <c>Importance</c> is <c>?STD_IMPORTANCE</c>,
+          and default value for <c>Args</c> is <c>[]</c>.</p>
+
+        <p>For details on <c>Category</c> and <c>Importance</c>, see section
+          <seealso marker="write_test_chapter#logging">Logging - Categories
+          and Verbosity Levels</seealso> in the User's Guide.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>make_priv_dir() -&gt; ok | {error, Reason}</name>
+      <fsummary>If the test has been started with option create_priv_dir
+        set to manual_per_tc, in order for the test case to use the private
+        directory, it must first create it by calling this function.</fsummary>
+      <type>
+        <v>Reason = term()</v>
+      </type>
+      <desc><marker id="make_priv_dir-0"/>
+        <p>If the test is started with option <c>create_priv_dir</c>
+          set to <c>manual_per_tc</c>, in order for the test case to use
+          the private directory, it must first create it by calling this
+          function.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>notify(Name, Data) -&gt; ok</name>
+      <fsummary>Sends an asynchronous notification of type Name with Data
+        to the <c>Common Test</c> event manager.</fsummary>
+      <type>
+        <v>Name = atom()</v>
+        <v>Data = term()</v>
+      </type>
+      <desc><marker id="notify-2"/>
+        <p>Sends an asynchronous notification of type <c>Name</c> with
+          <c>Data</c>to the Common Test event manager. This can later be
+          caught by any installed event manager.</p>
+
+        <p>See also
+          <seealso marker="stdlib:gen_event"><c>stdlib:gen_event(3)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>pal(Format) -&gt; ok</name>
+      <fsummary>Equivalent to pal(default, 50, Format, []).</fsummary>
+      <desc><marker id="pal-1"/>
+        <p>Equivalent to
+          <seealso marker="#pal-4"><c>ct:pal(default, 50, Format,
+            [])</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>pal(X1, X2) -&gt; ok</name>
+      <fsummary>Equivalent to pal(Category, Importance, Format,
+        Args).</fsummary>
+      <type>
+        <v>X1 = Category | Importance | Format</v>
+        <v>X2 = Format | Args</v>
+      </type>
+      <desc><marker id="pal-2"/>
+        <p>Equivalent to <seealso marker="#pal-4"><c>ct:pal(Category,
+          Importance, Format, Args)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>pal(X1, X2, X3) -&gt; ok</name>
+      <fsummary>Equivalent to pal(Category, Importance, Format,
+        Args).</fsummary>
+      <type>
+        <v>X1 = Category | Importance</v>
+        <v>X2 = Importance | Format</v>
+        <v>X3 = Format | Args</v>
+      </type>
+      <desc><marker id="pal-3"/>
+        <p>Equivalent to <seealso marker="#pal-4"><c>ct:pal(Category,
+          Importance, Format, Args)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>pal(Category, Importance, Format, Args) -&gt; ok</name>
+      <fsummary>Prints and logs from a test case.</fsummary>
+      <type>
+        <v>Category = atom()</v>
+        <v>Importance = integer()</v>
+        <v>Format = string()</v>
+        <v>Args = list()</v>
+      </type>
+      <desc><marker id="pal-4"/>
+        <p>Prints and logs from a test case.</p>
+
+        <p>This function is meant for printing a string from a test case,
+          both to the test case log file and to the console.</p>
+
+        <p>Default <c>Category</c> is <c>default</c>,
+          default <c>Importance</c> is <c>?STD_IMPORTANCE</c>,
+          and default value for <c>Args</c> is <c>[]</c>.</p>
+
+        <p>For details on <c>Category</c> and <c>Importance</c>, see section
+          <seealso marker="write_test_chapter#logging">Logging - Categories
+          and Verbosity Levels</seealso> in the User's Guide.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>parse_table(Data) -&gt; {Heading, Table}</name>
+      <fsummary>Parses the printout from an SQL table and returns a list of
+        tuples.</fsummary>
+      <type>
+        <v>Data = [string()]</v>
+        <v>Heading = tuple()</v>
+        <v>Table = [tuple()]</v>
+      </type>
+      <desc><marker id="parse_table-1"/>
+        <p>Parses the printout from an SQL table and returns a list of
+          tuples.</p>
+
+        <p>The printout to parse is typically the result of a <c>select</c>
+          command in SQL. The returned <c>Table</c> is a list of tuples,
+          where each tuple is a row in the table.</p>
+
+        <p><c>Heading</c> is a tuple of strings representing the headings
+          of each column in the table.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>print(Format) -&gt; ok</name>
+      <fsummary>Equivalent to print(default, 50, Format, []).</fsummary>
+      <desc><marker id="print-1"/>
+        <p>Equivalent to <seealso marker="#print-4"><c>ct:print(default,
+        50, Format, [])</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>print(X1, X2) -&gt; ok</name>
+      <fsummary>Equivalent to print(Category, Importance, Format,
+        Args).</fsummary>
+      <type>
+        <v>X1 = Category | Importance | Format</v>
+        <v>X2 = Format | Args</v>
+      </type>
+      <desc><marker id="print-2"/>
+        <p>Equivalent to <seealso marker="#print-4"><c>ct:print(Category,
+          Importance, Format, Args)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>print(X1, X2, X3) -&gt; ok</name>
+      <fsummary>Equivalent to print(Category, Importance, Format,
+        Args).</fsummary>
+      <type>
+        <v>X1 = Category | Importance</v>
+        <v>X2 = Importance | Format</v>
+        <v>X3 = Format | Args</v>
+      </type>
+      <desc><marker id="print-3"/>
+        <p>Equivalent to <seealso marker="#print-4"><c>ct:print(Category,
+          Importance, Format, Args)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>print(Category, Importance, Format, Args) -&gt; ok</name>
+      <fsummary>Prints from a test case to the console.</fsummary>
+      <type>
+        <v>Category = atom()</v>
+        <v>Importance = integer()</v>
+        <v>Format = string()</v>
+        <v>Args = list()</v>
+      </type>
+      <desc><marker id="print-4"/>
+        <p>Prints from a test case to the console.</p>
+
+        <p>This function is meant for printing a string from a test case to
+          the console.</p>
+
+        <p>Default <c>Category</c> is <c>default</c>,
+          default <c>Importance</c> is <c>?STD_IMPORTANCE</c>,
+          and default value for <c>Args</c> is <c>[]</c>.</p>
+
+        <p>For details on <c>Category</c> and <c>Importance</c>, see section
+          <seealso marker="write_test_chapter#logging">Logging - Categories
+          and Verbosity Levels</seealso> in the User's Guide.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>reload_config(Required) -&gt; ValueOrElement</name>
+      <fsummary>Reloads configuration file containing specified configuration
+        key.</fsummary>
+      <type>
+        <v>Required = KeyOrName | {KeyOrName, SubKey} | {KeyOrName, SubKey, SubKey}</v>
+        <v>KeyOrName = atom()</v>
+        <v>SubKey = atom()</v>
+        <v>ValueOrElement = term()</v>
+      </type>
+      <desc><marker id="reload_config-1"/>
+        <p>Reloads configuration file containing specified configuration key.</p>
+
+        <p>This function updates the configuration data from which the
+          specified configuration variable was read, and returns the (possibly)
+          new value of this variable.</p>
+
+        <p>If some variables were present in the configuration, but are
+          not loaded using this function, they are removed from the
+          configuration table together with their aliases.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>remove_config(Callback, Config) -&gt; ok</name>
+      <fsummary>Removes configuration variables (together with
+        their aliases) that were loaded with specified callback module and
+        configuration string.</fsummary>
+      <type>
+        <v>Callback = atom()</v>
+        <v>Config = string()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc><marker id="remove_config-2"/>
+        <p>Removes configuration variables (together wih their aliases)
+          that were loaded with specified callback module and configuration
+          string.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>require(Required) -&gt; ok | {error, Reason}</name>
+      <fsummary>Checks if the required configuration is available.</fsummary>
+      <type>
+        <v>Required = Key | {Key, SubKeys} | {Key, SubKey, SubKeys}</v>
+        <v>Key = atom()</v>
+        <v>SubKeys = SubKey | [SubKey]</v>
+        <v>SubKey = atom()</v>
+      </type>
+      <desc><marker id="require-1"/>
+        <p>Checks if the required configuration is available. Arbitrarily
+          deep tuples can be specified as <c>Required</c>. Only the last
+          element of the tuple can be a list of <c>SubKey</c>s.</p>
+
+        <p><em>Example 1.</em> Require the variable <c>myvar</c>:</p>
+
+        <pre>
+ ok = ct:require(myvar).</pre>
+ 
+        <p>In this case the configuration file must at least contain:</p>
+
+        <pre>
+ {myvar,Value}.</pre>
+  
+        <p><em>Example 2.</em> Require key <c>myvar</c> with subkeys
+          <c>sub1</c> and <c>sub2</c>:</p>
+
+        <pre>
+ ok = ct:require({myvar,[sub1,sub2]}).</pre>
+
+        <p>In this case the configuration file must at least contain:</p>
+
+        <pre>
+ {myvar,[{sub1,Value},{sub2,Value}]}.</pre>
+
+        <p><em>Example 3.</em> Require key <c>myvar</c> with subkey
+          <c>sub1</c> with <c>subsub1</c>:</p>
+
+        <pre>
+ ok = ct:require({myvar,sub1,sub2}).</pre>
+
+        <p>In this case the configuration file must at least contain:</p>
+
+        <pre>
+ {myvar,[{sub1,[{sub2,Value}]}]}.</pre>
+
+        <p>See also
+          <seealso marker="#get_config-1"><c>ct:get_config/1</c></seealso>,
+          <seealso marker="#get_config-2"><c>ct:get_config/2</c></seealso>,
+          <seealso marker="#get_config-3"><c>ct:get_config/3</c></seealso>,
+          <seealso marker="#require-2"><c>ct:require/2</c></seealso>.</p>
+        </desc>
+    </func>
+
+    <func>
+      <name>require(Name, Required) -&gt; ok | {error, Reason}</name>
+      <fsummary>Checks if the required configuration is available and gives
+        it a name.</fsummary>
+      <type>
+        <v>Name = atom()</v>
+        <v>Required = Key | {Key, SubKey} | {Key, SubKey, SubKey}</v>
+        <v>SubKey = Key</v>
+        <v>Key = atom()</v>
+      </type>
+      <desc><marker id="require-2"/>
+        <p>Checks if the required configuration is available and gives it a
+          name. The semantics for <c>Required</c> is the same as in
+          <seealso marker="#require-1"><c>ct:require/1</c></seealso> except
+          that a list of <c>SubKey</c>s cannot be specified.</p>
+
+       <p>If the requested data is available, the subentry is associated
+         with <c>Name</c> so that the value of the element can be read with
+         <seealso marker="#get_config-1"><c>ct:get_config/1,2</c></seealso>
+         provided <c>Name</c> is used instead of the whole <c>Required</c>
+         term.</p>
+
+       <p><em>Example:</em></p>
+
+       <p>Require one node with a Telnet connection and an FTP connection.
+         Name the node <c>a</c>:</p>
+
+       <pre>
+ ok = ct:require(a,{machine,node}).</pre>
+
+        <p>All references to this node can then use the node name. For
+          example, a file over FTP is fetched like follows:</p>
+
+        <pre>
+ ok = ct:ftp_get(a,RemoteFile,LocalFile).</pre>
+
+        <p>For this to work, the configuration file must at least contain:</p>
+
+        <pre>
+ {machine,[{node,[{telnet,IpAddr},{ftp,IpAddr}]}]}.</pre>
+
+        <note><p>The behavior of this function changed radically in
+          <c>Common Test</c> 1.6.2. To keep some backwards compatability,
+          it is still possible to do:<br/>
+          <c>ct:require(a,{node,[telnet,ftp]}).</c><br/>
+          This associates the name <c>a</c> with the top-level <c>node</c>
+          entry. For this to work, the configuration file must at least
+          contain:<br/>
+          <c>{node,[{telnet,IpAddr},{ftp,IpAddr}]}.</c></p>
+        </note>
+
+        <p>See also
+          <seealso marker="#get_config-1"><c>ct:get_config/1</c></seealso>,
+          <seealso marker="#get_config-2"><c>ct:get_config/2</c></seealso>,
+          <seealso marker="#get_config-3"><c>ct:get_config/3</c></seealso>,
+          <seealso marker="#require-1"><c>ct:require/1</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>run(TestDirs) -&gt; Result</name>
+      <fsummary>Runs all test cases in all suites in the specified
+        directories.</fsummary>
+      <type>
+        <v>TestDirs = TestDir | [TestDir]</v>
+      </type>
+      <desc><marker id="run-1"/>
+        <p>Runs all test cases in all suites in the specified directories.</p>
+
+        <p>See also <seealso marker="#run-3"><c>ct:run/3</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>run(TestDir, Suite) -&gt; Result</name>
+      <fsummary>Runs all test cases in the specified suite.</fsummary>
+      <desc><marker id="run-2"/>
+        <p>Runs all test cases in the specified suite.</p>
+
+        <p>See also <seealso marker="#run-3"><c>ct:run/3</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>run(TestDir, Suite, Cases) -&gt; Result</name>
+      <fsummary>Runs the specified test cases.</fsummary>
+      <type>
+        <v>TestDir = string()</v>
+        <v>Suite = atom()</v>
+        <v>Cases = atom() | [atom()]</v>
+        <v>Result = [TestResult] | {error, Reason}</v>
+      </type>
+      <desc><marker id="run-3"/>
+        <p>Runs the specified test cases.</p>
+
+        <p>Requires that
+          <seealso marker="#install-1"><c>ct:install/1</c></seealso> has been
+            run first.</p>
+
+        <p>Suites (<c>*_SUITE.erl</c>) files must be stored in <c>TestDir</c>
+          or <c>TestDir/test</c>. All suites are compiled when the test is
+          run.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>run_test(Opts) -&gt; Result</name>
+      <fsummary>Runs tests as specified by the combination of options in
+        Opts.</fsummary>
+      <type>
+        <v>Opts = [OptTuples]</v>
+        <v>OptTuples = {dir, TestDirs} | {suite, Suites} | {group, Groups} | {testcase, Cases} | {spec, TestSpecs} | {join_specs, Bool} | {label, Label} | {config, CfgFiles} | {userconfig, UserConfig} | {allow_user_terms, Bool} | {logdir, LogDir} | {silent_connections, Conns} | {stylesheet, CSSFile} | {cover, CoverSpecFile} | {cover_stop, Bool} | {step, StepOpts} | {event_handler, EventHandlers} | {include, InclDirs} | {auto_compile, Bool} | {abort_if_missing_suites, Bool} | {create_priv_dir, CreatePrivDir} | {multiply_timetraps, M} | {scale_timetraps, Bool} | {repeat, N} | {duration, DurTime} | {until, StopTime} | {force_stop, ForceStop} | {decrypt, DecryptKeyOrFile} | {refresh_logs, LogDir} | {logopts, LogOpts} | {verbosity, VLevels} | {basic_html, Bool} | {ct_hooks, CTHs} | {enable_builtin_hooks, Bool} | {release_shell, Bool}</v>
+        <v>TestDirs = [string()] | string()</v>
+        <v>Suites = [string()] | [atom()] | string() | atom()</v>
+        <v>Cases = [atom()] | atom()</v>
+        <v>Groups = GroupNameOrPath | [GroupNameOrPath]</v>
+        <v>GroupNameOrPath = [atom()] | atom() | all</v>
+        <v>TestSpecs = [string()] | string()</v>
+        <v>Label = string() | atom()</v>
+        <v>CfgFiles = [string()] | string()</v>
+        <v>UserConfig = [{CallbackMod, CfgStrings}] | {CallbackMod, CfgStrings}</v>
+        <v>CallbackMod = atom()</v>
+        <v>CfgStrings = [string()] | string()</v>
+        <v>LogDir = string()</v>
+        <v>Conns = all | [atom()]</v>
+        <v>CSSFile = string()</v>
+        <v>CoverSpecFile = string()</v>
+        <v>StepOpts = [StepOpt] | []</v>
+        <v>StepOpt = config | keep_inactive</v>
+        <v>EventHandlers = EH | [EH]</v>
+        <v>EH = atom() | {atom(), InitArgs} | {[atom()], InitArgs}</v>
+        <v>InitArgs = [term()]</v>
+        <v>InclDirs = [string()] | string()</v>
+        <v>CreatePrivDir = auto_per_run | auto_per_tc | manual_per_tc</v>
+        <v>M = integer()</v>
+        <v>N = integer()</v>
+        <v>DurTime = string(HHMMSS)</v>
+        <v>StopTime = string(YYMoMoDDHHMMSS) | string(HHMMSS)</v>
+        <v>ForceStop = skip_rest | Bool</v>
+        <v>DecryptKeyOrFile = {key, DecryptKey} | {file, DecryptFile}</v>
+        <v>DecryptKey = string()</v>
+        <v>DecryptFile = string()</v>
+        <v>LogOpts = [LogOpt]</v>
+        <v>LogOpt = no_nl | no_src</v>
+        <v>VLevels = VLevel | [{Category, VLevel}]</v>
+        <v>VLevel = integer()</v>
+        <v>Category = atom()</v>
+        <v>CTHs = [CTHModule | {CTHModule, CTHInitArgs}]</v>
+        <v>CTHModule = atom()</v>
+        <v>CTHInitArgs = term()</v>
+        <v>Result = {Ok, Failed, {UserSkipped, AutoSkipped}} | TestRunnerPid | {error, Reason}</v>
+        <v>Ok = integer()</v>
+        <v>Failed = integer()</v>
+        <v>UserSkipped = integer()</v>
+        <v>AutoSkipped = integer()</v>
+        <v>TestRunnerPid = pid()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc><marker id="run_test-1"/>
+        <p>Runs tests as specified by the combination of options in
+          <c>Opts</c>. The options are the same as those used with program
+          <c>ct_run</c>, see <seealso marker="ct_run#ct_run">Run Tests from
+          Command Line</seealso> in the <c>ct_run</c> manual page.</p>
+        <p>Here a <c>TestDir</c> can be used to point out the path to a
+          <c>Suite</c>. Option <c>testcase</c> corresponds to option
+          <c>-case</c> in program <c>ct_run</c>. Configuration files
+          specified in <c>Opts</c> are installed automatically at startup.</p>
+
+        <p><c>TestRunnerPid</c> is returned if <c>release_shell == true</c>.
+          For details, see
+          <seealso marker="#break-1"><c>ct:break/1</c></seealso>.</p>
+
+        <p><c>Reason</c> indicates the type of error encountered.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>run_testspec(TestSpec) -&gt; Result</name>
+      <fsummary>Runs a test specified by TestSpec.</fsummary>
+      <type>
+        <v>TestSpec = [term()]</v>
+        <v>Result = {Ok, Failed, {UserSkipped, AutoSkipped}} | {error, Reason}</v>
+        <v>Ok = integer()</v>
+        <v>Failed = integer()</v>
+        <v>UserSkipped = integer()</v>
+        <v>AutoSkipped = integer()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc><marker id="run_testspec-1"/>
+        <p>Runs a test specified by <c>TestSpec</c>. The same terms are used
+          as in test specification files.</p>
+
+        <p><c>Reason</c> indicates the type of error encountered.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>sleep(Time) -&gt; ok</name>
+      <fsummary>This function, similar to timer:sleep/1, suspends the
+        test case for a specified time.</fsummary>
+      <type>
+        <v>Time = {hours, Hours} | {minutes, Mins} | {seconds, Secs} | Millisecs | infinity</v>
+        <v>Hours = integer()</v>
+        <v>Mins = integer()</v>
+        <v>Secs = integer()</v>
+        <v>Millisecs = integer() | float()</v>
+      </type>
+      <desc><marker id="sleep-1"/>
+        <p>This function, similar to <c>timer:sleep/1</c> in <c>STDLIB</c>, 
+          suspends the test case for a specified time.
+          However, this function also multiplies <c>Time</c> with the
+          <c>multiply_timetraps</c> value (if set) and under certain
+          circumstances also scales up the time automatically if
+          <c>scale_timetraps</c> is set to <c>true</c> (default is
+          <c>false</c>).</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>start_interactive() -&gt; ok</name>
+      <fsummary>Starts <c>Common Test</c> in interactive mode.</fsummary>
+      <desc><marker id="start_interactive-0"/>
+        <p>Starts <c>Common Test</c> in interactive mode.</p>
+
+        <p>From this mode, all test case support functions can be executed
+          directly from the Erlang shell. The interactive mode can also be
+          started from the OS command line with <c>ct_run -shell
+          [-config File...]</c>.</p>
+
+        <p>If any functions (for example, Telnet or FTP) using
+          "required configuration data" are to be called from the Erlang shell,
+          configuration data must first be required with
+          <seealso marker="#require-2"><c>ct:require/2</c></seealso>.</p>
+
+        <p><em>Example:</em></p>
+
+        <pre>
+ &gt; ct:require(unix_telnet, unix).
+ ok
+ &gt; ct_telnet:open(unix_telnet).
+ {ok,&lt;0.105.0&gt;}
+ &gt; ct_telnet:cmd(unix_telnet, "ls .").
+ {ok,["ls","file1  ...",...]}</pre>
+      </desc>
+    </func>
+
+    <func>
+      <name>step(TestDir, Suite, Case) -&gt; Result</name>
+      <fsummary>Steps through a test case with the debugger.</fsummary>
+      <type>
+        <v>Case = atom()</v>
+      </type>
+      <desc><marker id="step-3"/>
+        <p>Steps through a test case with the debugger.</p>
+
+        <p>See also <seealso marker="#run-3"><c>ct:run/3</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>step(TestDir, Suite, Case, Opts) -&gt; Result</name>
+      <fsummary>Steps through a test case with the debugger.</fsummary>
+      <type>
+        <v>Case = atom()</v>
+        <v>Opts = [Opt] | []</v>
+        <v>Opt = config | keep_inactive</v>
+      </type>
+      <desc><marker id="step-4"/>
+        <p>Steps through a test case with the debugger. If option
+          <c>config</c> has been specifed, breakpoints are also set on
+          the configuration functions in <c>Suite</c>.</p>
+
+        <p>See also <seealso marker="#run-3"><c>ct:run/3</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>stop_interactive() -&gt; ok</name>
+      <fsummary>Exits the interactive mode.</fsummary>
+      <desc><marker id="stop_interactive-0"/>
+        <p>Exits the interactive mode.</p>
+
+        <p>See also
+          <seealso marker="#start_interactive-0"><c>ct:start_interactive/0</c></seealso>.
+        </p>
+      </desc>
+    </func>
+
+    <func>
+      <name>sync_notify(Name, Data) -&gt; ok</name>
+      <fsummary>Sends a synchronous notification of type Name with Data to
+        the <c>Common Test</c> event manager.</fsummary>
+      <type>
+        <v>Name = atom()</v>
+        <v>Data = term()</v>
+      </type>
+      <desc><marker id="sync_notify-2"/>
+        <p>Sends a synchronous notification of type <c>Name</c> with
+          <c>Data</c> to the <c>Common Test</c> event manager. This can later be
+          caught by any installed event manager.</p>
+
+        <p>See also
+          <seealso marker="stdlib:gen_event"><c>stdlib:gen_event(3)</c></seealso>.
+        </p>
+      </desc>
+    </func>
+
+    <func>
+      <name>testcases(TestDir, Suite) -&gt; Testcases | {error, Reason}</name>
+      <fsummary>Returns all test cases in the specified suite.</fsummary>
+      <type>
+        <v>TestDir = string()</v>
+        <v>Suite = atom()</v>
+        <v>Testcases = list()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc><marker id="testcases-2"/>
+        <p>Returns all test cases in the specified suite.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>timetrap(Time) -&gt; ok</name>
+      <fsummary>Sets a new timetrap for the running test case.</fsummary>
+      <type>
+        <v>Time = {hours, Hours} | {minutes, Mins} | {seconds, Secs} | Millisecs | infinity | Func</v>
+        <v>Hours = integer()</v>
+        <v>Mins = integer()</v>
+        <v>Secs = integer()</v>
+        <v>Millisecs = integer() | float()</v>
+        <v>Func = {M, F, A} | function()</v>
+        <v>M = atom()</v>
+        <v>F = atom()</v>
+        <v>A = list()</v>
+      </type>
+      <desc><marker id="timetrap-1"/>
+        <p>Sets a new timetrap for the running test case.</p>
+
+        <p>If the argument is <c>Func</c>, the timetrap is triggered when
+          this function returns. <c>Func</c> can also return a new
+          <c>Time</c> value, which in that case is the value for the new
+          timetrap.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>userdata(TestDir, Suite) -&gt; SuiteUserData | {error, Reason}</name>
+      <fsummary>Returns any data specified with tag userdata in the list of
+        tuples returned from Suite:suite/0.</fsummary>
+      <type>
+        <v>TestDir = string()</v>
+        <v>Suite = atom()</v>
+        <v>SuiteUserData = [term()]</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc><marker id="userdata-2"/>
+        <p>Returns any data specified with tag <c>userdata</c> in the list
+          of tuples returned from
+          <seealso marker="#Module:suite-0"><c>suite/0</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>userdata(TestDir, Suite, Case::GroupOrCase) -&gt; TCUserData | {error, Reason}</name>
+      <fsummary>Returns any data specified with tag userdata in the list of
+        tuples returned from Suite:group(GroupName) or Suite:Case().</fsummary>
+      <type>
+        <v>TestDir = string()</v>
+        <v>Suite = atom()</v>
+        <v>GroupOrCase = {group, GroupName} | atom()</v>
+        <v>GroupName = atom()</v>
+        <v>TCUserData = [term()]</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc><marker id="userdata-3"/>
+        <p>Returns any data specified with tag <c>userdata</c> in the list
+          of tuples returned from <c>Suite:group(GroupName)</c> or
+          <c>Suite:Case()</c>.</p>
+      </desc>
+    </func>
+  </funcs>
+
+</erlref>
+
+