diff options
Diffstat (limited to 'lib/common_test/doc/src')
| -rw-r--r-- | lib/common_test/doc/src/config_file_chapter.xml | 39 | ||||
| -rw-r--r-- | lib/common_test/doc/src/ct_slave.xml | 139 |
2 files changed, 160 insertions, 18 deletions
diff --git a/lib/common_test/doc/src/config_file_chapter.xml b/lib/common_test/doc/src/config_file_chapter.xml index 850bc74e19..77b0c0c0b7 100644 --- a/lib/common_test/doc/src/config_file_chapter.xml +++ b/lib/common_test/doc/src/config_file_chapter.xml @@ -21,7 +21,7 @@ </legalnotice> - <title>Config Files</title> + <title>External Configuration Data</title> <prepared>Siri Hansen, Peter Andersson</prepared> <docno></docno> <date></date> @@ -32,16 +32,19 @@ <section> <title>General</title> - <p>The Common Test framework uses configuration files to - describe data related to a test and/or an SUT (System Under Test). - The configuration data makes it possible to change properties without - changing the test program itself. Configuration data can for example be:</p> + <p>To avoid hard coding data values related to the test and/or SUT (System + Under Test) in the test suites, the data may instead be specified by means + of configuration files or strings that Common Test reads before + the start of a test run. External configuration data makes it possible to + change test properties without having to modify the actual test suites + using the data. Examples of configuration data:</p> <list> <item>Addresses to the test plant or other instruments</item> - <item>Filenames for files needed by the test</item> - <item>Program names for programs that shall be run by the test</item> - <item>Any other variable that is needed by the test</item> + <item>User login information</item> + <item>Names of files needed by the test</item> + <item>Names of programs that should be executed during the test</item> + <item>Any other variable needed by the test</item> </list> </section> @@ -51,12 +54,12 @@ <p>A configuration file can contain any number of elements of the type:</p> <pre> - {Key,Value}.</pre> + {CfgVarName,Value}.</pre> <p>where</p> <pre> - Key = atom() - Value = term() | [{Key,Value}]</pre> + CfgVarName = atom() + Value = term() | [{CfgVarName,Value}]</pre> </section> @@ -65,8 +68,8 @@ <marker id="require_config_data"></marker> <p>In a test suite, one must <em>require</em> that a configuration - variable exists before attempting to read the associated - value in a test case.</p> + variable (<c>CfgVarName</c> in the definition above) exists before + attempting to read the associated value in a test case or config function.</p> <p><c>require</c> is an assert statement that can be part of the <seealso marker="write_test_chapter#suite">test suite info function</seealso> or @@ -83,13 +86,13 @@ <p>A <c>require</c> statement in the test suite info- or test case info-list should look like this: - <c>{require,Required}</c> or <c>{require,Name,Required}</c>. The - arguments <c>Name</c> and <c>Required</c> are the same as the + <c>{require,CfgVarName}</c> or <c>{require,AliasName,CfgVarName}</c>. + The arguments <c>AliasName</c> and <c>CfgVarName</c> are the same as the arguments to <c>ct:require/[1,2]</c> which are described in the reference manual for <seealso marker="ct">ct</seealso>. - <c>Name</c> becomes an alias for the configuration variable - <c>Required</c>, and can be used as reference to the configuration - data value. The configuration variable may be associated with an + <c>AliasName</c> becomes an alias for the configuration variable, + and can be used as reference to the configuration data value. + The configuration variable may be associated with an arbitrary number of alias names, but each name must be unique within the same test suite. There are two main uses for alias names:</p> <list> diff --git a/lib/common_test/doc/src/ct_slave.xml b/lib/common_test/doc/src/ct_slave.xml new file mode 100644 index 0000000000..ceebf51f1a --- /dev/null +++ b/lib/common_test/doc/src/ct_slave.xml @@ -0,0 +1,139 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> +<erlref> +<header> +<title>ct_slave</title> +<prepared></prepared> +<responsible></responsible> +<docno>1</docno> +<approved></approved> +<checked></checked> +<date></date> +<rev>A</rev> +<file>ct_slave.xml</file></header> +<module>ct_slave</module> +<modulesummary>Common Test Framework functions for starting and stopping nodes for +Large Scale Testing.</modulesummary> +<description> +<p>Common Test Framework functions for starting and stopping nodes for +Large Scale Testing.</p> + + <p>This module exports functions which are used by the Common Test Master + to start and stop "slave" nodes. It is the default callback module for the + <c>{init, node_start}</c> term of the Test Specification.</p></description> +<funcs> +<func> +<name>start(Node) -> Result</name> +<fsummary>Starts an Erlang node with name Node on the local host.</fsummary> +<type> +<v>Node = atom()</v><v>Result = {ok, NodeName} | {error, already_started, NodeName} | {error, started_not_connected, NodeName} | {error, boot_timeout, NodeName} | {error, init_timeout, NodeName} | {error, startup_timeout, NodeName} | {error, not_alive, NodeName}</v><v>NodeName = atom()</v></type> +<desc><marker id="start-1"/> + +<p>Starts an Erlang node with name <c>Node</c> on the local host.</p> +<p><em>See also:</em> <seealso marker="#start-3">start/3</seealso>.</p> +</desc></func> +<func> +<name>start(Host, Node) -> Result</name> +<fsummary>Starts an Erlang node with name Node on host + Host with the default options.</fsummary> +<type> +<v>Node = atom()</v><v>Host = atom()</v><v>Result = {ok, NodeName} | {error, already_started, NodeName} | {error, started_not_connected, NodeName} | {error, boot_timeout, NodeName} | {error, init_timeout, NodeName} | {error, startup_timeout, NodeName} | {error, not_alive, NodeName}</v><v>NodeName = atom()</v></type> +<desc><marker id="start-2"/> + +<p>Starts an Erlang node with name <c>Node</c> on host + <c>Host</c> with the default options.</p> +<p><em>See also:</em> <seealso marker="#start-3">start/3</seealso>.</p> +</desc></func> +<func> +<name>start(Host, Node, Options::Opts) -> Result</name> +<fsummary>Starts an Erlang node with name Node on host + Host as specified by the combination of options in + Opts.</fsummary> +<type> +<v>Node = atom()</v><v>Host = atom()</v><v>Opts = [OptTuples]</v><v>OptTuples = {username, Username} | {password, Password} | {boot_timeout, BootTimeout} | {init_timeout, InitTimeout} | {startup_timeout, StartupTimeout} | {startup_functions, StartupFunctions} | {monitor_master, Monitor} | {kill_if_fail, KillIfFail} | {erl_flags, ErlangFlags}</v><v>Username = string()</v><v>Password = string()</v><v>BootTimeout = integer()</v><v>InitTimeout = integer()</v><v>StartupTimeout = integer()</v><v>StartupFunctions = [StartupFunctionSpec]</v><v>StartupFunctionSpec = {Module, Function, Arguments}</v><v>Module = atom()</v><v>Function = atom()</v><v>Arguments = [term]</v><v>Monitor = bool()</v><v>KillIfFail = bool()</v><v>ErlangFlags = string()</v><v>Result = {ok, NodeName} | {error, already_started, NodeName} | {error, started_not_connected, NodeName} | {error, boot_timeout, NodeName} | {error, init_timeout, NodeName} | {error, startup_timeout, NodeName} | {error, not_alive, NodeName}</v><v>NodeName = atom()</v></type> +<desc><marker id="start-3"/> + +<p>Starts an Erlang node with name <c>Node</c> on host + <c>Host</c> as specified by the combination of options in + <c>Opts</c>.</p> + + <p>Options <c>Username</c> and <c>Password</c> will be used + to log in onto the remote host <c>Host</c>. + Username, if omitted, defaults to the current user name, + and password is empty by default.</p> + + <p>A list of functions specified in the <c>Startup</c> option will be + executed after startup of the node. Note that all used modules should be + present in the code path on the <c>Host</c>.</p> + + <p>The timeouts are applied as follows: + <list> + <item> + <c>BootTimeout</c> - time to start the Erlang node, in seconds. + Defaults to 3 seconds. If node does not become pingable within this time, + the result <c>{error, boot_timeout, NodeName}</c> is returned; + </item> + <item> + <c>InitTimeout</c> - time to wait for the node until it calls the + internal callback function informing master about successfull startup. + Defaults to one second. + In case of timed out message the result + <c>{error, init_timeout, NodeName}</c> is returned; + </item> + <item> + <c>StartupTimeout</c> - time to wait intil the node finishes to run + the <c>StartupFunctions</c>. Defaults to one second. + If this timeout occurs, the result + <c>{error, startup_timeout, NodeName}</c> is returned. + </item> + </list></p> + + <p>Option <c>monitor_master</c> specifies, if the slave node should be + stopped in case of master node stop. Defaults to false.</p> + + <p>Option <c>kill_if_fail</c> specifies, if the slave node should be + killed in case of a timeout during initialization or startup. + Defaults to true. Note that node also may be still alive it the boot + timeout occurred, but it will not be killed in this case.</p> + + <p>Option <c>erlang_flags</c> specifies, which flags will be added + to the parameters of the <c>erl</c> executable.</p> + + <p>Special return values are: + <list> + <item><c>{error, already_started, NodeName}</c> - if the node with + the given name is already started on a given host;</item> + <item><c>{error, started_not_connected, NodeName}</c> - if node is + started, but not connected to the master node.</item> + <item><c>{error, not_alive, NodeName}</c> - if node on which the + <c>ct_slave:start/3</c> is called, is not alive. Note that + <c>NodeName</c> is the name of current node in this case.</item> + </list></p> + +</desc></func> +<func> +<name>stop(Node) -> Result</name> +<fsummary>Stops the running Erlang node with name Node on + the localhost.</fsummary> +<type> +<v>Node = atom()</v><v>Result = {ok, NodeName} | {error, not_started, NodeName} | {error, not_connected, NodeName} | {error, stop_timeout, NodeName}</v><v>NodeName = atom()</v></type> +<desc><marker id="stop-1"/> + +<p>Stops the running Erlang node with name <c>Node</c> on + the localhost.</p> +</desc></func> +<func> +<name>stop(Host, Node) -> Result</name> +<fsummary>Stops the running Erlang node with name Node on + host Host.</fsummary> +<type> +<v>Host = atom()</v><v>Node = atom()</v><v>Result = {ok, NodeName} | {error, not_started, NodeName} | {error, not_connected, NodeName} | {error, stop_timeout, NodeName}</v><v>NodeName = atom()</v></type> +<desc><marker id="stop-2"/> + +<p>Stops the running Erlang node with name <c>Node</c> on + host <c>Host</c>.</p> +</desc></func></funcs> + +<authors> +<aname> </aname> +<email> </email></authors></erlref>
\ No newline at end of file |