aboutsummaryrefslogtreecommitdiffstats
path: root/lib/common_test/doc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/common_test/doc')
-rw-r--r--lib/common_test/doc/src/config_file_chapter.xml148
1 files changed, 74 insertions, 74 deletions
diff --git a/lib/common_test/doc/src/config_file_chapter.xml b/lib/common_test/doc/src/config_file_chapter.xml
index 5199807f48..d402b121b3 100644
--- a/lib/common_test/doc/src/config_file_chapter.xml
+++ b/lib/common_test/doc/src/config_file_chapter.xml
@@ -180,38 +180,37 @@
</section>
<section>
- <title>Using own configuration data formats</title>
+ <title>User specific configuration data formats</title>
- <p>The nature of the configuration variables can be not only plain text
- files with the key-value tuples, they also can be loaded from the files in
- various formats, fetched via http from the Web, or can be loaded with help
- of some driver process. For this purpose, mechanism of plugging in user
- configuration handling callback modules is implemented in the Common Test.</p>
+ <p>It is possible for the user to specify configuration data on a
+ different format than key-value tuples in a text file, as described
+ so far. The data can e.g. be read from arbitrary files, fetched from
+ the web over http, or requested from a user specific process.
+ To support this, Common Test provides a callback module plugin
+ mechanism to handle configuration data.</p>
<section>
- <title>Standard callback modules for loading configuration variables</title>
- <p>Two callback modules for handling of configuration files are provided
- with the Common Test application:</p>
+ <title>Default callback modules for handling configuration data</title>
+ <p>The Common Test application includes default callback modules
+ for handling configuration data specified in standard config files
+ (see above) and in xml files:</p>
<list>
- <item>
- <c>ct_config_plain</c> - for reading configuration files with
- key-value tuples (traditional format). This handler will be tried to
- parse configuration file, if no user callback is specified.
- </item>
- <item>
- <c>ct_config_xml</c> - for reading configuration data from the XML
- files.
- </item>
+ <item>
+ <c>ct_config_plain</c> - for reading configuration files with
+ key-value tuples (standard format). This handler will be used to
+ parse configuration files if no user callback is specified.
+ </item>
+ <item>
+ <c>ct_config_xml</c> - for reading configuration data from XML
+ files.
+ </item>
</list>
</section>
<section>
<title>Using XML configuration files</title>
-
- <p>This is an example of the XML configuration file:</p>
-
- <pre>
- <![CDATA[
+ <p>This is an example of an XML configuration file:</p>
+ <pre><![CDATA[
<config>
<ftp_host>
<ftp>"targethost"</ftp>
@@ -219,8 +218,7 @@
<password>"letmein"</password>
</ftp_host>
<lm_directory>"/test/loadmodules"</lm_directory>
-</config>]]>
- </pre>
+</config>]]></pre>
<p>This configuration file, once read, will produce the same configuration
variables as the following text file:</p>
@@ -229,77 +227,79 @@
{username,"tester"},
{password,"letmein"}]}.
-{lm_directory, "/test/loadmodules"}.
- </pre>
+{lm_directory, "/test/loadmodules"}.</pre>
</section>
<section>
- <title>Implementing of the own handler</title>
+ <title>How to implement a user specific handler</title>
+
+ <p>The user specific handler can be written to handle special
+ configuration file formats. The parameter can be either file
+ name(s) or configuration string(s) (the empty list is valid).</p>
- <p>Own handler can be written to handle special configuration file formats.
- The parameter can be either file name(s) or configuration string (empty list
- is valid).</p>
- <p>The callback module is completely responsible for the
- configuration string correctness checks during runtime.</p>
+ <p>The callback module implementing the handler is responsible for
+ checking correctness of configuration strings.</p>
- <p>To perform validation of the configuration string, callback module
- should have the following function exported:</p>
+ <p>To perform validation of the configuration strings, the callback module
+ should have the following function exported:</p>
<p><c>Callback:check_parameter/1</c></p>
- <p>Input value will be passed from the Common Test, as defined in the test
- specification or given as an option to the run_test.</p>
- <p>Return value should be any of the following value indicating if given
- configuration parameter is valid:</p>
+ <p>The input argument will be passed from Common Test, as defined in the test
+ specification or given as an option to <c>run_test</c>.</p>
+
+ <p>The return value should be any of the following values indicating if given
+ configuration parameter is valid:</p>
<list>
<item>
<c>{ok, {file, FileName}}</c> - parameter is a file name and
- file exists;
+ the file exists,
</item>
<item>
<c>{ok, {config, ConfigString}}</c> - parameter is a config string
- and it is correct;
+ and it is correct,
</item>
<item>
<c>{error, {nofile, FileName}}</c> - there is no file with the given
- name in the current directory;
+ name in the current directory,
</item>
<item>
- <c>{error, {wrong_config, ConfigString}}</c> - configuration string
+ <c>{error, {wrong_config, ConfigString}}</c> - the configuration string
is wrong.
</item>
</list>
- <p>To perform actual reading, in cases of initial loading of the
- configuration variables and runtime re-loading, function</p>
+ <p>To perform reading of configuration data - initially before the tests
+ start, or as a result of data being reloaded during test execution -
+ the following function should be exported from the callback module:</p>
+
<p><c>Callback:read_config/1</c></p>
- <p>should be exported from the callback module</p>
- <p>Input value is the same as for <c>check_parameter/1</c> function</p>
- <p>Return value should be either:</p>
+
+ <p>The input argument is the same as for the <c>check_parameter/1</c> function.</p>
+ <p>The return value should be either:</p>
<list>
<item>
- <c>{ok, Config}</c> - if configuration variables read successfully;
+ <c>{ok, Config}</c> - if the configuration variables are read successfully,
</item>
<item>
- <c>{error, Error, ErrorDetails}</c> - if callback module failed to
+ <c>{error, Error, ErrorDetails}</c> - if the callback module fails to
proceed with the given configuration parameters.
</item>
</list>
- <p>Above, the <c>Config</c> variable is the proper Erlang key-value list,
- with possible key-value sublists as values,
- e.g. for the configuration files above it will be the following:</p>
+ <p><c>Config</c> is the proper Erlang key-value list, with possible
+ key-value sublists as values, like for the configuration file
+ example above:</p>
<pre>
[{ftp_host, [{ftp, "targethost"}, {username, "tester"}, {password, "letmein"}]},
- {lm_directory, "/test/loadmodules"}]
- </pre>
+ {lm_directory, "/test/loadmodules"}]</pre>
</section>
</section>
<section>
- <title>Examples of the configuration files</title>
+ <title>Examples of configuration data handling</title>
<p>A config file for using the FTP client to access files on a remote
host could look like this:</p>
@@ -311,9 +311,9 @@
{lm_directory, "/test/loadmodules"}.</pre>
- <p>XML version shown in chapter above can also be used, but it should be
- explicitly specified that <c>ct_config_xml</c> callback module is to be
- used by the Common Test.</p>
+ <p>The XML version shown in the chapter above can also be used, but it should be
+ explicitly specified that the <c>ct_config_xml</c> callback module is to be
+ used by Common Test.</p>
<p>Example of how to assert that the configuration data is available and
use it for an FTP session:</p>
@@ -361,9 +361,9 @@
</section>
<section>
- <title>Example of own configuration handler</title>
- <p>Simple configuration hanling driver which will ask external server for
- configuration data can be implemented this way:</p>
+ <title>Example of user specific configuration handler</title>
+ <p>A simple configuration handling driver which will ask an external server for
+ configuration data can be implemented this way:</p>
<pre>
-module(config_driver).
-export([read_config/1, check_parameter/1]).
@@ -385,17 +385,16 @@ check_parameter(ServerName)->
{error, nofile}->
{error, {wrong_config, "File not found: " ++ ServerName ++ ".beam"}}
end
- end.
- </pre>
- <p>Configuration string for this driver may be "config_server", if the
- config_server.erl module below is built and is exist in the code path
- during test execution:</p>
+ end.</pre>
+
+ <p>The configuration string for this driver may be "config_server", if the
+ config_server.erl module below is compiled and exists in the code path
+ during test execution:</p>
<pre>
-module(config_server).
-export([start/0, stop/0, init/1, get_config/0, loop/0]).
-define(REGISTERED_NAME, ct_test_config_server).
--define(vsn, 0.1).
start()->
case whereis(?REGISTERED_NAME) of
@@ -452,12 +451,13 @@ wait()->
wait();
_Pid->
ok
- end.
- </pre>
- <p>There two modules provide the ability to dynamically reload configuration
- variables. If the <c>ct:reload_config(localtime)</c> is called from the test
- case, all variables which were loaded with the config_driver above, will be
- updated with the new values.</p>
+ end.</pre>
+
+ <p>In this example, the handler also provides the ability to dynamically reload
+ configuration variables. If <c>ct:reload_config(localtime)</c> is called from
+ the test case function, all variables loaded with <c>config_driver:read_config/1</c>
+ will be updated with their latest values, and the new value for variable
+ <c>localtime</c> will be returned.</p>
</section>
</chapter>