From 215cdbcb6312caf49cd1fd1b37f0fb5842b5e13d Mon Sep 17 00:00:00 2001 From: Andrey Pampukha Date: Wed, 28 Apr 2010 16:00:12 +0200 Subject: Documentation update --- lib/common_test/doc/src/config_file_chapter.xml | 148 ++++++++++++------------ lib/common_test/src/ct_slave.erl | 8 ++ lib/common_test/src/ct_testspec.erl | 2 +- 3 files changed, 83 insertions(+), 75 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 @@
- Using own configuration data formats + User specific configuration data formats -

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.

+

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.

- Standard callback modules for loading configuration variables -

Two callback modules for handling of configuration files are provided - with the Common Test application:

+ Default callback modules for handling configuration data +

The Common Test application includes default callback modules + for handling configuration data specified in standard config files + (see above) and in xml files:

- - ct_config_plain - 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. - - - ct_config_xml - for reading configuration data from the XML - files. - + + ct_config_plain - 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. + + + ct_config_xml - for reading configuration data from XML + files. +
Using XML configuration files - -

This is an example of the XML configuration file:

- - 
-      This is an example of an XML configuration file:

+      

     
         "targethost"
@@ -219,8 +218,7 @@
         "letmein"
     
     "/test/loadmodules"
-]]>
-      

+]]>

This configuration file, once read, will produce the same configuration variables as the following text file:

@@ -229,77 +227,79 @@ {username,"tester"}, {password,"letmein"}]}. -{lm_directory, "/test/loadmodules"}. - +{lm_directory, "/test/loadmodules"}.
- Implementing of the own handler + How to implement a user specific handler + +

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).

-

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).

-

The callback module is completely responsible for the - configuration string correctness checks during runtime.

+

The callback module implementing the handler is responsible for + checking correctness of configuration strings.

-

To perform validation of the configuration string, callback module - should have the following function exported:

+

To perform validation of the configuration strings, the callback module + should have the following function exported:

Callback:check_parameter/1

-

Input value will be passed from the Common Test, as defined in the test - specification or given as an option to the run_test.

-

Return value should be any of the following value indicating if given - configuration parameter is valid:

+

The input argument will be passed from Common Test, as defined in the test + specification or given as an option to run_test.

+ +

The return value should be any of the following values indicating if given + configuration parameter is valid:

{ok, {file, FileName}} - parameter is a file name and - file exists; + the file exists, {ok, {config, ConfigString}} - parameter is a config string - and it is correct; + and it is correct, {error, {nofile, FileName}} - there is no file with the given - name in the current directory; + name in the current directory, - {error, {wrong_config, ConfigString}} - configuration string + {error, {wrong_config, ConfigString}} - the configuration string is wrong. -

To perform actual reading, in cases of initial loading of the - configuration variables and runtime re-loading, function

+

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:

+

Callback:read_config/1

-

should be exported from the callback module

-

Input value is the same as for check_parameter/1 function

-

Return value should be either:

+ +

The input argument is the same as for the check_parameter/1 function.

+

The return value should be either:

- {ok, Config} - if configuration variables read successfully; + {ok, Config} - if the configuration variables are read successfully, - {error, Error, ErrorDetails} - if callback module failed to + {error, Error, ErrorDetails} - if the callback module fails to proceed with the given configuration parameters. -

Above, the Config 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:

+

Config is the proper Erlang key-value list, with possible + key-value sublists as values, like for the configuration file + example above:

         [{ftp_host, [{ftp, "targethost"}, {username, "tester"}, {password, "letmein"}]},
-        {lm_directory, "/test/loadmodules"}]
-
+ {lm_directory, "/test/loadmodules"}]
- Examples of the configuration files + Examples of configuration data handling

A config file for using the FTP client to access files on a remote host could look like this:

@@ -311,9 +311,9 @@ {lm_directory, "/test/loadmodules"}. -

XML version shown in chapter above can also be used, but it should be - explicitly specified that ct_config_xml callback module is to be - used by the Common Test.

+

The XML version shown in the chapter above can also be used, but it should be + explicitly specified that the ct_config_xml callback module is to be + used by Common Test.

Example of how to assert that the configuration data is available and use it for an FTP session:

@@ -361,9 +361,9 @@
- Example of own configuration handler -

Simple configuration hanling driver which will ask external server for - configuration data can be implemented this way:

+ Example of user specific configuration handler +

A simple configuration handling driver which will ask an external server for + configuration data can be implemented this way:

 -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.
-
-

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:

+ end. + +

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:

 -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.
-
-

There two modules provide the ability to dynamically reload configuration - variables. If the ct:reload_config(localtime) is called from the test - case, all variables which were loaded with the config_driver above, will be - updated with the new values.

+ end. + +

In this example, the handler also provides the ability to dynamically reload + configuration variables. If ct:reload_config(localtime) is called from + the test case function, all variables loaded with config_driver:read_config/1 + will be updated with their latest values, and the new value for variable + localtime will be returned.

diff --git a/lib/common_test/src/ct_slave.erl b/lib/common_test/src/ct_slave.erl index 22cb17e55d..d2a491e079 100644 --- a/lib/common_test/src/ct_slave.erl +++ b/lib/common_test/src/ct_slave.erl @@ -15,6 +15,14 @@ %% under the License. %% %% %CopyrightEnd% + +%%% @doc Common Test Framework functions for starting and stopping nodes for +%%% Large Scale Testing. +%%% +%%%

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 +%%% {init, node_start} term of the Test Specification.

+ %%---------------------------------------------------------------------- %% File : ct_slave.erl %% Description : CT module for starting nodes for large-scale testing. diff --git a/lib/common_test/src/ct_testspec.erl b/lib/common_test/src/ct_testspec.erl index 4e34c1513e..582ce5e49f 100644 --- a/lib/common_test/src/ct_testspec.erl +++ b/lib/common_test/src/ct_testspec.erl @@ -17,7 +17,7 @@ %% %CopyrightEnd% %% -%%% @doc Common Test Framework functions handlig test specifikations. +%%% @doc Common Test Framework functions handlig test specifications. %%% %%%

This module exports functions that are used within CT to %%% scan and parse test specifikations.

-- cgit v1.2.3