From a9c315929d96c7d0d0e5e79f8fc0ba0c7f17e94d Mon Sep 17 00:00:00 2001 From: Andrey Pampukha Date: Mon, 15 Mar 2010 15:26:02 +0100 Subject: Changed return value tags for config file handling Return value tags modified and various documentation updates made (work in progress). --- lib/common_test/doc/src/config_file_chapter.xml | 241 ++++++++++++++++++++++-- lib/common_test/doc/src/run_test_chapter.xml | 3 + 2 files changed, 233 insertions(+), 11 deletions(-) (limited to 'lib/common_test/doc') diff --git a/lib/common_test/doc/src/config_file_chapter.xml b/lib/common_test/doc/src/config_file_chapter.xml index a22a5270c1..ef07ef6154 100644 --- a/lib/common_test/doc/src/config_file_chapter.xml +++ b/lib/common_test/doc/src/config_file_chapter.xml @@ -4,7 +4,7 @@
- 20042009 + 20042010 Ericsson AB. All Rights Reserved. @@ -180,7 +180,123 @@
- Examples + Using own configuration data formats + +

The nature of the configuration variables can be not only plain text + files with the key-value tuples, but they 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.

+ +
+ Standard callback modules for loading configuration variables +

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

+ + + 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. + + +
+ +
+ Using XML configuration files + +

This is an example of the XML configuration file:

+ + 
+      
+    
+        "targethost"
+        "tester"
+        "letmein"
+    
+    "/test/loadmodules"
+]]>
+
+ +

This configuration file, once read, will produce the same configuration + variables as the following "traditional" file:

+ 
+{ftp_host, [{ftp,"targethost"},
+            {username,"tester"},
+            {password,"letmein"}]}.
+
+{lm_directory, "/test/loadmodules"}.
+
+
+ +
+ Implementing of the own handler + +

Own handler can be written to handle special configuration file formats. + The parameter can be either file name or configuration string (empty list + is valid).

+

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

+ +

Callback module should have the following functions exported:

+

One for checking configuration parameter

+ +

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:

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

And second function performs reading of the configuration variables:

+

Callback:read_config/1

+

Input value is the same as for check_parameter/1 function

+

Return value should be either:

+ + + + {ok, Config} - is configuration variables read successfully; + + + {error, Error, ErrorDetails} - if callback module failed to + proceed. + + +

Above, the Config variable is the key-value list, possibly nested, + e.g. for the configuration files above it will be the following

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

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

@@ -188,28 +304,33 @@ 
     {ftp_host, [{ftp,"targethost"},
                 {username,"tester"},
-	        {password,"letmein"}]}.
+                {password,"letmein"}]}.
 
     {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.

+

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

     init_per_testcase(ftptest, Config) ->
         {ok,_} = ct_ftp:open(ftp),
-	Config.
+        Config.
 
     end_per_testcase(ftptest, _Config) ->
         ct_ftp:close(ftp).
 
     ftptest() ->
         [{require,ftp,ftp_host},
-	 {require,lm_directory}].
+         {require,lm_directory}].
 
     ftptest(Config) ->
-	Remote = filename:join(ct:get_config(lm_directory), "loadmodX"),
+        Remote = filename:join(ct:get_config(lm_directory), "loadmodX"),
         Local = filename:join(?config(priv_dir,Config), "loadmodule"),
         ok = ct_ftp:recv(ftp, Remote, Local),
-	...
+ ...

An example of how the above functions could be rewritten if necessary to open multiple connections to the FTP server:

@@ -217,7 +338,7 @@ init_per_testcase(ftptest, Config) -> {ok,Handle1} = ct_ftp:open(ftp_host), {ok,Handle2} = ct_ftp:open(ftp_host), - [{ftp_handles,[Handle1,Handle2]} | Config]. + [{ftp_handles,[Handle1,Handle2]} | Config]. end_per_testcase(ftptest, Config) -> lists:foreach(fun(Handle) -> ct_ftp:close(Handle) end, @@ -225,17 +346,115 @@ ftptest() -> [{require,ftp_host}, - {require,lm_directory}]. + {require,lm_directory}]. ftptest(Config) -> - Remote = filename:join(ct:get_config(lm_directory), "loadmodX"), + Remote = filename:join(ct:get_config(lm_directory), "loadmodX"), Local = filename:join(?config(priv_dir,Config), "loadmodule"), [Handle | MoreHandles] = ?config(ftp_handles,Config), ok = ct_ftp:recv(Handle, Remote, Local), - ... + ...
+
+ Example of own configuration handler +

Simple configuration hanling "driver" can be implemented this way:

+ 
+-module(config_driver).
+-export([read_config/1, check_parameter/1]).
+
+read_config(ServerName)->
+    ServerModule = list_to_atom(ServerName),
+    ServerModule:start(),
+    ServerModule:get_config().
+
+check_parameter(ServerName)->
+    ServerModule = list_to_atom(ServerName),
+    case code:is_loaded(ServerModule) of
+        {file, _}->
+            {ok, {config, ServerName}};
+        false->
+            case code:load_file(ServerModule) of
+                {module, ServerModule}->
+                    {ok, {config, 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:

+ 
+-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
+        undefined->
+            spawn(?MODULE, init, [?REGISTERED_NAME]),
+            wait();
+        _Pid->
+        ok
+    end,
+    ?REGISTERED_NAME.
+
+init(Name)->
+    register(Name, self()),
+    loop().
+
+get_config()->
+    call(self(), get_config).
+
+stop()->
+    call(self(), stop).
+
+call(Client, Request)->
+    case whereis(?REGISTERED_NAME) of
+        undefined->
+            {error, not_started, Request};
+        Pid->
+            Pid ! {Client, Request},
+            receive
+                Reply->
+                    {ok, Reply}
+            after 4000->
+                {error, timeout, Request}
+            end
+    end.
+
+loop()->
+    receive
+        {Pid, stop}->
+            Pid ! ok;
+        {Pid, get_config}->
+            {D,T} = erlang:localtime(),
+            Pid !
+                [{localtime, [{date, D}, {time, T}]},
+                 {node, erlang:node()},
+                 {now, erlang:now()},
+                 {config_server_pid, self()},
+                 {config_server_vsn, ?vsn}],
+            ?MODULE:loop()
+    end.
+
+wait()->
+    case whereis(?REGISTERED_NAME) of
+        undefined->
+            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.

+
+ diff --git a/lib/common_test/doc/src/run_test_chapter.xml b/lib/common_test/doc/src/run_test_chapter.xml index d731d18783..b7e9ab88e3 100644 --- a/lib/common_test/doc/src/run_test_chapter.xml +++ b/lib/common_test/doc/src/run_test_chapter.xml @@ -111,11 +111,14 @@ -dir ]]> -suite ]]> + -suite ]]> + -suite -group -case ]]>

Examples:

$ run_test -config $CFGS/sys1.cfg $CFGS/sys2.cfg -dir $SYS1_TEST $SYS2_TEST

+

$ run_test -userconfig ct_config_xml $CFGS/sys1.xml $CFGS/sys2.xml -dir $SYS1_TEST $SYS2_TEST

$ run_test -suite $SYS1_TEST/setup_SUITE $SYS2_TEST/config_SUITE

$ run_test -suite $SYS1_TEST/setup_SUITE -case start stop

$ run_test -suite $SYS1_TEST/setup_SUITE -group installation -case start stop

-- cgit v1.2.3 From eda9f3c82d3241549352969c59488b232e902d69 Mon Sep 17 00:00:00 2001 From: Andrey Pampukha Date: Thu, 18 Mar 2010 14:44:48 +0100 Subject: Change spelling, phrasing and structure in documentation --- lib/common_test/doc/src/config_file_chapter.xml | 33 ++++++++++++++----------- 1 file changed, 19 insertions(+), 14 deletions(-) (limited to 'lib/common_test/doc') diff --git a/lib/common_test/doc/src/config_file_chapter.xml b/lib/common_test/doc/src/config_file_chapter.xml index ef07ef6154..5199807f48 100644 --- a/lib/common_test/doc/src/config_file_chapter.xml +++ b/lib/common_test/doc/src/config_file_chapter.xml @@ -183,7 +183,7 @@ Using own configuration data formats

The nature of the configuration variables can be not only plain text - files with the key-value tuples, but they can be loaded from the files in + 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.

@@ -223,7 +223,7 @@

This configuration file, once read, will produce the same configuration - variables as the following "traditional" file:

+ variables as the following text file:

 {ftp_host, [{ftp,"targethost"},
             {username,"tester"},
@@ -237,13 +237,13 @@
       Implementing of the own handler
 
       
Own handler can be written to handle special configuration file formats.
-      The parameter can be either file name or configuration string (empty list
+      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.

 
-      
Callback module should have the following functions exported:

-      
One for checking configuration parameter

+      
To perform validation of the configuration string, 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
@@ -269,22 +269,25 @@
         
       
 
-      
And second function performs reading of the configuration variables:

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

       
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:

 
       
         
-          {ok, Config} - is configuration variables read successfully;
+          {ok, Config} - if configuration variables read successfully;
         
         
           {error, Error, ErrorDetails} - if callback module failed to
-          proceed.
+          proceed with the given configuration parameters.
         
       
-      
Above, the Config variable is the key-value list, possibly nested,
-      e.g. for the configuration files above it will be the following

+      
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:

 
       
         [{ftp_host, [{ftp, "targethost"}, {username, "tester"}, {password, "letmein"}]},
@@ -310,9 +313,9 @@
 
     
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.

+    used by the Common Test.

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

     
     init_per_testcase(ftptest, Config) ->
@@ -359,7 +362,8 @@
 
   

     Example of own configuration handler
-    
Simple configuration hanling "driver" can be implemented this way:

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

     
 -module(config_driver).
 -export([read_config/1, check_parameter/1]).
@@ -384,7 +388,8 @@ check_parameter(ServerName)->
     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:

+    config_server.erl module below is built and is exist in the code path
+    during test execution:

     
 -module(config_server).
 -export([start/0, stop/0, init/1, get_config/0, loop/0]).
-- 
cgit v1.2.3


From 2c711e660df6683eee9cdfeb204e02f093153c36 Mon Sep 17 00:00:00 2001
From: Andrey Pampukha 
Date: Thu, 25 Mar 2010 11:42:26 +0100
Subject: Add test suites for ct_master

Also includes minor documentation updates.
---
 lib/common_test/doc/src/run_test.xml         | 14 +++++++++++---
 lib/common_test/doc/src/run_test_chapter.xml |  3 +++
 2 files changed, 14 insertions(+), 3 deletions(-)

(limited to 'lib/common_test/doc')

diff --git a/lib/common_test/doc/src/run_test.xml b/lib/common_test/doc/src/run_test.xml
index d9dd22d411..451d3c5737 100644
--- a/lib/common_test/doc/src/run_test.xml
+++ b/lib/common_test/doc/src/run_test.xml
@@ -4,7 +4,7 @@
 
   

     
-      20072009
+      20072010
       Ericsson AB. All Rights Reserved.
     
     
@@ -27,8 +27,8 @@
     
     
     
-    2007-07-04
-    PA1
+    2010-04-01
+    PA2
     run_test.xml
   

   run_test 
@@ -61,6 +61,8 @@
 	 [[-group Group1 Group2 .. GroupN] [-case Case1 Case2 .. CaseN]]]
 	[-step [config | keep_inactive]]
 	[-config ConfigFile1 ConfigFile2 .. ConfigFileN]
+	[-userconfig CallbackModule1 ConfigString1 and CallbackModule2
+    ConfigString2 and .. and CallbackModuleN ConfigStringN]
 	[-decrypt_key Key] | [-decrypt_file KeyFile]
 	[-logdir LogDir]
 	[-silent_connections [ConnType1 ConnType2 .. ConnTypeN]]
@@ -79,6 +81,8 @@
     
 	run_test -spec TestSpec1 TestSpec2 .. TestSpecN
 	[-config ConfigFile1 ConfigFile2 .. ConfigFileN]
+	[-userconfig CallbackModule1 ConfigString1 and CallbackModule2
+    ConfigString2 and .. and CallbackModuleN ConfigStringN]
 	[-decrypt_key Key] | [-decrypt_file KeyFile]
 	[-logdir LogDir]
 	[-allow_user_terms]
@@ -98,6 +102,8 @@
     
         run_test -vts [-browser Browser]
 	[-config ConfigFile1 ConfigFile2 .. ConfigFileN]
+	[-userconfig CallbackModule1 ConfigString1 and CallbackModule2
+    ConfigString2 and .. and CallbackModuleN ConfigStringN]
 	[-decrypt_key Key] | [-decrypt_file KeyFile]
         [-dir TestDir1 TestDir2 .. TestDirN] |
         [-suite Suite [[-group Group] [-case Case]]]
@@ -115,6 +121,8 @@
     
 	run_test -shell 
 	[-config ConfigFile1 ConfigFile2 ... ConfigFileN]
+	[-userconfig CallbackModule1 ConfigString1 and CallbackModule2
+     ConfigString2 and .. and CallbackModuleN ConfigStringN]
 	[-decrypt_key Key] | [-decrypt_file KeyFile]

   

   

diff --git a/lib/common_test/doc/src/run_test_chapter.xml b/lib/common_test/doc/src/run_test_chapter.xml
index b7e9ab88e3..00cf4adf52 100644
--- a/lib/common_test/doc/src/run_test_chapter.xml
+++ b/lib/common_test/doc/src/run_test_chapter.xml
@@ -370,6 +370,9 @@
 
       {config, ConfigFiles}.
       {config, NodeRefs, ConfigFiles}.
+
+      {userconfig, {CallbackModule, ConfigStrings}}.
+      {userconfig, NodeRefs, {CallbackModule, ConfigStrings}}.
       
       {alias, DirAlias, Dir}.
       
-- 
cgit v1.2.3


From dbecad9f8004f0a9b53ebdeb1ce8bde35dca7663 Mon Sep 17 00:00:00 2001
From: Andrey Pampukha 
Date: Thu, 8 Apr 2010 18:56:40 +0200
Subject: Introduce ct_slave module

---
 lib/common_test/doc/src/Makefile    | 3 ++-
 lib/common_test/doc/src/ref_man.xml | 1 +
 2 files changed, 3 insertions(+), 1 deletion(-)

(limited to 'lib/common_test/doc')

diff --git a/lib/common_test/doc/src/Makefile b/lib/common_test/doc/src/Makefile
index a2c014418d..6322860088 100644
--- a/lib/common_test/doc/src/Makefile
+++ b/lib/common_test/doc/src/Makefile
@@ -45,7 +45,8 @@ CT_MODULES = \
 	ct_ssh \
 	ct_rpc \
 	ct_snmp \
-	unix_telnet
+	unix_telnet \
+	ct_slave
 
 CT_XML_FILES = $(CT_MODULES:=.xml)
 
diff --git a/lib/common_test/doc/src/ref_man.xml b/lib/common_test/doc/src/ref_man.xml
index beb3ed3247..5f84f75acb 100644
--- a/lib/common_test/doc/src/ref_man.xml
+++ b/lib/common_test/doc/src/ref_man.xml
@@ -75,6 +75,7 @@
   
   
   
+  
 
 
 
-- 
cgit v1.2.3


From ebcab814cabc74407f48aba1b41327df80586fcd Mon Sep 17 00:00:00 2001
From: Andrey Pampukha 
Date: Thu, 15 Apr 2010 12:57:04 +0200
Subject: Document ct_slave and 'eval' terms

---
 lib/common_test/doc/src/ct_master_chapter.xml | 31 +++++++++++++++++++++++++++
 lib/common_test/doc/src/run_test_chapter.xml  | 16 +++++++++++++-
 2 files changed, 46 insertions(+), 1 deletion(-)

(limited to 'lib/common_test/doc')

diff --git a/lib/common_test/doc/src/ct_master_chapter.xml b/lib/common_test/doc/src/ct_master_chapter.xml
index 79288cfe4c..1622b5b29c 100644
--- a/lib/common_test/doc/src/ct_master_chapter.xml
+++ b/lib/common_test/doc/src/ct_master_chapter.xml
@@ -194,6 +194,37 @@
     current working directory settings are not important.

   

 
+  

+    Automatic startup of the test target nodes
+    
+    
Is is possible to start nodes acting like a test targets automatically
+    using a new term in the test specification, node_start:

+    
+     {node, node1, node1@host1}.
+     {node, node2, node1@host2}.
+     {node, node3, node2@host2}.
+     {node_start, node1, [{callback_module, my_slave_callback}]}.
+     {node_start, [node2, node3], [{username, "ct_user"}, {password, "ct_password"}]}.
+    

+    
This test specification declares that node1@host1 is to be started using
+    user's callback my_slave_callback with no parameters, and nodes node1@host2 and
+    node2@host2 will be started with the default callback module ct_slave,
+    using the given user name and password to log into remote host host2.

+    
Default ct_slave callback module delivered with the Common Test has the following features:
+    
+     Starting the Erlang nodes or local or remote hosts (ssh is used for remote ones);
+     Ability to start Erlang emulator with the additional flags (any flags supported by erl are supported);
+     Supervision of the node being start using internal callback functions. Used to prevent hanging of started nodes. Configurable;
+     Monitoring of the master node by the slaves. Slave node may be stopped in case of master node termination. Configurable;
+     Execution of the user's functions after slave node is started. Functions can be given as a list of {Module, Function, Arguments} tuples.
+    
+    

+    
If any eval term is specified for a node which has node_start term
+    defined for it, the evaluation of the functions will be deferred until the node is started.
+    The functions to be evaluated are simply added to the end of the startup_functions list
+    (see ct_slave chapter in the Reference Manual).

+  

+
 
 
 
diff --git a/lib/common_test/doc/src/run_test_chapter.xml b/lib/common_test/doc/src/run_test_chapter.xml
index 00cf4adf52..f5dc477c6f 100644
--- a/lib/common_test/doc/src/run_test_chapter.xml
+++ b/lib/common_test/doc/src/run_test_chapter.xml
@@ -383,6 +383,9 @@
       {event_handler, NodeRefs, EventHandlers}.
       {event_handler, EventHandlers, InitArgs}.
       {event_handler, NodeRefs, EventHandlers, InitArgs}.
+
+      {eval, [{Module, Function, Arguments}]}.
+      {eval, [NodeAlias], [{Module, Function, Arguments}]}.
     

       
Test terms:

     
@@ -455,9 +458,20 @@
       Secondly, the test for system t2 should run. The included suites are
 	t2B and t2C. Included are also test cases test4, test1 and test7 in suite
 	t2A. Note that the test cases will be executed in the specified order.
-      Lastly, all suites for systems t3 are to be completely skipped and this 
+      Lastly, all suites for systems t3 are to be completely skipped and this
 	should be explicitly noted in the log files.
     
+    
It is possible to evaluate any function(s) during processing of the test
+      specification. This feature may be used e.g. to add some directories to
+      the code path, initialise some ETS table etc. New eval terms can be
+      used for this purpose.
+      If only a list of functions is given, then all functions from the list
+      will be consequently applied on the current node. If at least one node
+      alias is given, then the functions will be called remotely on all nodes
+      specified. Please note that in case when node is defined to be started by
+      the CT Master, the evaluation will be deferred.
+      See the Automatic startup of
+      the test target nodes chapter for details.

     
It is possible for the user to provide a test specification that
       includes (for Common Test) unrecognizable terms. If this is desired,
       the -allow_user_terms flag should be used when starting tests with
-- 
cgit v1.2.3


From 1327bd8956b2d0f6b5a9201ce9ecf361f94733aa Mon Sep 17 00:00:00 2001
From: Andrey Pampukha 
Date: Mon, 19 Apr 2010 17:28:07 +0200
Subject: Move 'node_start' and 'eval' terms into new 'init' term

node_start+eval -> init(node_start, eval)
Also include some documentation updates.
---
 lib/common_test/doc/src/ct_master_chapter.xml | 49 ++++++++++++++++++---------
 lib/common_test/doc/src/run_test_chapter.xml  | 16 +++------
 2 files changed, 38 insertions(+), 27 deletions(-)

(limited to 'lib/common_test/doc')

diff --git a/lib/common_test/doc/src/ct_master_chapter.xml b/lib/common_test/doc/src/ct_master_chapter.xml
index 1622b5b29c..4ab891edee 100644
--- a/lib/common_test/doc/src/ct_master_chapter.xml
+++ b/lib/common_test/doc/src/ct_master_chapter.xml
@@ -102,7 +102,7 @@
       
ct_master:abort() (stop all) or ct_master:abort(Nodes)

 
       
For detailed information about the ct_master API, please see the 
-      manual page for this module.

+      manual page for this module.

   
   

     Test Specifications
@@ -197,32 +197,49 @@
   

     Automatic startup of the test target nodes
     
-    
Is is possible to start nodes acting like a test targets automatically
-    using a new term in the test specification, node_start:

+    
Is is possible to perform initial actions on test target nodes
+    automatically using a new term in the test specification, init.

+    
Currently, two sub-terms are supported, node_start and eval.

     
      {node, node1, node1@host1}.
      {node, node2, node1@host2}.
      {node, node3, node2@host2}.
-     {node_start, node1, [{callback_module, my_slave_callback}]}.
-     {node_start, [node2, node3], [{username, "ct_user"}, {password, "ct_password"}]}.
+     {node, node4, node1@host3}.
+     {init, node1, [{node_start, [{callback_module, my_slave_callback}]}]}.
+     {init, [node2, node3], {node_start, [{username, "ct_user"}, {password, "ct_password"}]}}.
+     {init, node4, {eval, {module, function, []}}}.
     

     
This test specification declares that node1@host1 is to be started using
     user's callback my_slave_callback with no parameters, and nodes node1@host2 and
     node2@host2 will be started with the default callback module ct_slave,
-    using the given user name and password to log into remote host host2.

-    
Default ct_slave callback module delivered with the Common Test has the following features:
+    using the given user name and password to log into remote host host2.
+    Also, there will be function module:function/0 evaluated on the
+    node1@host3, and result of this call will be printed to the log.

+    
Default ct_slave callback module
+    delivered with the Common Test has the following features:
     
-     Starting the Erlang nodes or local or remote hosts (ssh is used for remote ones);
-     Ability to start Erlang emulator with the additional flags (any flags supported by erl are supported);
-     Supervision of the node being start using internal callback functions. Used to prevent hanging of started nodes. Configurable;
-     Monitoring of the master node by the slaves. Slave node may be stopped in case of master node termination. Configurable;
-     Execution of the user's functions after slave node is started. Functions can be given as a list of {Module, Function, Arguments} tuples.
+     Starting the Erlang nodes or local or remote hosts
+       (ssh is used for remote ones);
+     
+     Ability to start Erlang emulator with the additional flags
+       (any flags supported by erl are supported);
+     
+     Supervision of the node being start using internal callback
+        functions. Used to prevent hanging of started nodes. Configurable;
+     
+     Monitoring of the master node by the slaves. Slave node may be
+        stopped in case of master node termination. Configurable;
+     
+     Execution of the user's functions after slave node is started.
+        Functions can be given as a list of {Module, Function, Arguments} tuples.
+     
     
     

-    
If any eval term is specified for a node which has node_start term
-    defined for it, the evaluation of the functions will be deferred until the node is started.
-    The functions to be evaluated are simply added to the end of the startup_functions list
-    (see ct_slave chapter in the Reference Manual).

+    
Note that it is possible to specify eval term for the node as well
+    as startup_functions in the node_start options list. In this
+    case first node will be started, then the startup_functions are
+    executed, and finally functions specified with eval will be called.
+    

   

 
 
diff --git a/lib/common_test/doc/src/run_test_chapter.xml b/lib/common_test/doc/src/run_test_chapter.xml
index f5dc477c6f..44b4077ec4 100644
--- a/lib/common_test/doc/src/run_test_chapter.xml
+++ b/lib/common_test/doc/src/run_test_chapter.xml
@@ -384,8 +384,8 @@
       {event_handler, EventHandlers, InitArgs}.
       {event_handler, NodeRefs, EventHandlers, InitArgs}.
 
-      {eval, [{Module, Function, Arguments}]}.
-      {eval, [NodeAlias], [{Module, Function, Arguments}]}.
+      {init, Options}.
+      {init, [NodeAlias], Options}.
     

       
Test terms:

     
@@ -461,15 +461,9 @@
       Lastly, all suites for systems t3 are to be completely skipped and this
 	should be explicitly noted in the log files.
     
-    
It is possible to evaluate any function(s) during processing of the test
-      specification. This feature may be used e.g. to add some directories to
-      the code path, initialise some ETS table etc. New eval terms can be
-      used for this purpose.
-      If only a list of functions is given, then all functions from the list
-      will be consequently applied on the current node. If at least one node
-      alias is given, then the functions will be called remotely on all nodes
-      specified. Please note that in case when node is defined to be started by
-      the CT Master, the evaluation will be deferred.
+    
It is possible to specify initialization options for nodes defined in the
+      test specification. Currently, there are options to start the node and/or to
+      evaluate any function on the node.
       See the Automatic startup of
       the test target nodes chapter for details.

     
It is possible for the user to provide a test specification that
-- 
cgit v1.2.3


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 ++++++++++++------------
 1 file changed, 74 insertions(+), 74 deletions(-)

(limited to 'lib/common_test/doc')

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.

-- cgit v1.2.3 From 5cf552a62742c6ddc974ba5491188576d512254e Mon Sep 17 00:00:00 2001 From: Peter Andersson Date: Mon, 24 May 2010 17:38:19 +0200 Subject: Add run_test program for Common Test Common Test may now be started with the program run_test instead of the legacy shell script with the same name. Minor updates have also been made to the Webtool application. --- lib/common_test/doc/src/ct_master_chapter.xml | 2 +- lib/common_test/doc/src/event_handler_chapter.xml | 2 +- lib/common_test/doc/src/install_chapter.xml | 135 ++++++++++----------- lib/common_test/doc/src/run_test.xml | 59 +++++---- lib/common_test/doc/src/run_test_chapter.xml | 21 ++-- lib/common_test/doc/src/test_structure_chapter.xml | 4 +- 6 files changed, 109 insertions(+), 114 deletions(-) (limited to 'lib/common_test/doc') diff --git a/lib/common_test/doc/src/ct_master_chapter.xml b/lib/common_test/doc/src/ct_master_chapter.xml index 4ab891edee..14f318759e 100644 --- a/lib/common_test/doc/src/ct_master_chapter.xml +++ b/lib/common_test/doc/src/ct_master_chapter.xml @@ -186,7 +186,7 @@ Running Test Suites chapter). The result is that any test specified to run on a node with the same name as the Common Test node in question (typically ct@somehost if started - with the run_test script), will be performed. Tests without explicit + with the run_test program), will be performed. Tests without explicit node association will always be performed too of course!

It is recommended that absolute paths are used for log directories, diff --git a/lib/common_test/doc/src/event_handler_chapter.xml b/lib/common_test/doc/src/event_handler_chapter.xml index a550810850..35b684730e 100644 --- a/lib/common_test/doc/src/event_handler_chapter.xml +++ b/lib/common_test/doc/src/event_handler_chapter.xml @@ -74,7 +74,7 @@ example).

It is not possible to specify start arguments to the event handlers when - using the run_test script. You may however pass along start arguments + using the run_test program. You may however pass along start arguments if you use the ct:run_test/1 function. An event_handler tuple in the argument Opts has the following definition (see also ct:run_test/1 in the reference manual):

diff --git a/lib/common_test/doc/src/install_chapter.xml b/lib/common_test/doc/src/install_chapter.xml index e1ff5abf6a..d5a12cd9f3 100644 --- a/lib/common_test/doc/src/install_chapter.xml +++ b/lib/common_test/doc/src/install_chapter.xml @@ -4,7 +4,7 @@
- 20072009 + 20072010 Ericsson AB. All Rights Reserved. @@ -33,82 +33,77 @@ General information -

The two main interfaces for running tests with Common Test - are an executable Bourne shell script named run_test and an - erlang module named ct. The shell script will work on Unix/Linux - (and Linux-like environments such as Cygwin on Windows) and the - ct interface functions can be called from the Erlang shell - (or from any Erlang function) on any supported platform.

- -

The Common Test application is installed with the Erlang/OTP - system and no explicit installation is required to start using - Common Test by means of the interface functions in the ct - module. If you wish to use run_test, however, this script - needs to be generated first, according to the instructions below.

- - -
- Unix/Linux - -

Go to the ]]> directory, located - among the other OTP applications (under the OTP lib directory). Here you - execute the install.sh script with argument local:

+

The two main interfaces for running tests with Common Test + are an executable program named run_test and an + erlang module named ct. The run_test program + is compiled for the underlying operating system (e.g. Unix/Linux + or Windows) during the build of the Erlang/OTP system, and is + installed automatically with other executable programs in + the top level bin directory of Erlang/OTP. + The ct interface functions can be called from the Erlang shell, + or from any Erlang function, on any supported platform.

+ +

A legacy Bourne shell script - also named run_test - exists, + which may be manually generated and installed. This script may be used + instead of the run_test program mentioned above, e.g. if the user + wishes to modify or customize the Common Test start flags in a simpler + way than making changes to the run_test C program.

-

- $ ./install.sh local -

+

The Common Test application is installed with the Erlang/OTP + system and no additional installation step is required to start using + Common Test by means of the run_test executable program, and/or the interface + functions in the ct module. If you wish to use the legacy Bourne + shell script version of run_test, however, this script needs to be + generated first, according to the instructions below.

+ +

Before reading on, please note that since Common Test version + 1.5, the run_test shell script is no longer required for starting + tests with Common Test from the OS command line. The run_test + program (descibed above) is the new recommended command line interface + for Common Test. The shell script exists mainly for legacy reasons and + may not be updated in future releases of Common Test. It may even be removed. +

+ +

Optional step to generate a shell script for starting Common Test:

+

To generate the run_test shell script, navigate to the + ]]> directory, located among the other + OTP applications (under the OTP lib directory). Here execute the + install.sh script with argument local:

+ +

+ $ ./install.sh local +

-

This generates the executable run_test script in the - /priv/bin]]> directory. The script - will include absolute paths to the Common Test and Test Server - application directories, so it's possible to copy or move the script to - a different location on the file system, if desired, without having to - update it. It's of course possible to leave the script under the - priv/bin directory and update the PATH variable accordingly (or - create a link or alias to it).

- -

If you, for any reason, have copied Common Test and Test Server - to a different location than the default OTP lib directory, you can - generate a run_test script with a different top level directory, - simply by specifying the directory, instead of local, when running - install.sh. Example:

- -

- $ install.sh /usr/local/test_tools +

This generates the executable run_test script in the + /priv/bin]]> directory. The script + will include absolute paths to the Common Test and Test Server + application directories, so it's possible to copy or move the script to + a different location on the file system, if desired, without having to + update it. It's of course possible to leave the script under the + priv/bin directory and update the PATH variable accordingly (or + create a link or alias to it).

+ +

If you, for any reason, have copied Common Test and Test Server + to a different location than the default OTP lib directory, you can + generate a run_test script with a different top level directory, + simply by specifying the directory, instead of local, when running + install.sh. Example:

+ +

+ $ install.sh /usr/local/test_tools

Note that the ]]> and - ]]> directories must be located under the - same top directory. Note also that the install script does not copy files - or update environment variables. It only generates the run_test - script.

+ ]]> directories must be located under the + same top directory. Note also that the install script does not copy files + or update environment variables. It only generates the run_test + script.

-

Whenever you install a new version of Erlang/OTP, the run_test - script needs to be regenerated, or updated manually with new directory names - (new version numbers), for it to "see" the latest Common Test and Test Server - versions.

+

Whenever you install a new version of Erlang/OTP, the run_test + script needs to be regenerated, or updated manually with new directory names + (new version numbers), for it to "see" the latest Common Test and Test Server + versions.

-

For more information on the run_test script and the ct - module, please see the reference manual.

-
- -
- Windows - -

On Windows it is very convenient to use Cygwin (www.cygwin.com) - for running Common Test and Erlang, since it enables you to use the - run_test script for starting Common Test. If you are a Cygwin - user, simply follow the instructions above for generating the run_test - script.

- -

If you do not use Cygwin, you have to rely on the API functions - in the ct module (instead of run_test) for running - Common Test as described initially in this chapter.

- -

If you, for any reason, have chosen to store Common Test and Test Server - in a different location than the default OTP lib directory, make - sure the ebin directories of these applications are included - in the Erlang code server path (so the application modules can be loaded).

diff --git a/lib/common_test/doc/src/run_test.xml b/lib/common_test/doc/src/run_test.xml index 451d3c5737..49538a7483 100644 --- a/lib/common_test/doc/src/run_test.xml +++ b/lib/common_test/doc/src/run_test.xml @@ -21,7 +21,7 @@ - The run_test shell script + The run_test program Peter Andersson Peter Andersson @@ -31,38 +31,39 @@ PA2 run_test.xml
- run_test - Shell script used for starting - Common Test from the Unix command line. + run_test + Program used for starting Common Test from the + OS command line. -

The run_test script is automatically generated as Common - Test is installed (please see the Installation chapter in the Common - Test User's Guide for more information). The script accepts a number - of different start flags. Some flags trigger run_test - to start the Common Test application and pass on data to it. Some - flags start an Erlang node prepared for running Common Test in a - particular mode.

-

run_test also accepts Erlang emulator - flags. These are used when run_test calls erl to - start the Erlang node (making it possible to e.g. add directories to - the code server path, change the cookie on the node, start - additional applications, etc).

+

The run_test program is automatically installed with Erlang/OTP + and Common Test (please see the Installation chapter in the Common + Test User's Guide for more information). The program accepts a number + of different start flags. Some flags trigger run_test + to start the Common Test application and pass on data to it. Some + flags start an Erlang node prepared for running Common Test in a + particular mode.

+ +

run_test also accepts Erlang emulator flags. These are used + when run_test calls erl to start the Erlang node + (making it possible to e.g. add directories to the code server path, + change the cookie on the node, start additional applications, etc).

+

If run_test is called without parameters, it prints all valid - start flags to stdout.

+ start flags to stdout.
Run tests from command line 
-    	run_test [-dir TestDir1 TestDir2 .. TestDirN] |	
-	[-suite Suite1 Suite2 .. SuiteN 
+	run_test [-dir TestDir1 TestDir2 .. TestDirN] |
+	[-suite Suite1 Suite2 .. SuiteN
 	 [[-group Group1 Group2 .. GroupN] [-case Case1 Case2 .. CaseN]]]
 	[-step [config | keep_inactive]]
 	[-config ConfigFile1 ConfigFile2 .. ConfigFileN]
 	[-userconfig CallbackModule1 ConfigString1 and CallbackModule2
-    ConfigString2 and .. and CallbackModuleN ConfigStringN]
+         ConfigString2 and .. and CallbackModuleN ConfigStringN]
 	[-decrypt_key Key] | [-decrypt_file KeyFile]
 	[-logdir LogDir]
 	[-silent_connections [ConnType1 ConnType2 .. ConnTypeN]]
@@ -82,7 +83,7 @@
 	run_test -spec TestSpec1 TestSpec2 .. TestSpecN
 	[-config ConfigFile1 ConfigFile2 .. ConfigFileN]
 	[-userconfig CallbackModule1 ConfigString1 and CallbackModule2
-    ConfigString2 and .. and CallbackModuleN ConfigStringN]
+         ConfigString2 and .. and CallbackModuleN ConfigStringN]
 	[-decrypt_key Key] | [-decrypt_file KeyFile]
 	[-logdir LogDir]
 	[-allow_user_terms]
@@ -103,7 +104,7 @@
         run_test -vts [-browser Browser]
 	[-config ConfigFile1 ConfigFile2 .. ConfigFileN]
 	[-userconfig CallbackModule1 ConfigString1 and CallbackModule2
-    ConfigString2 and .. and CallbackModuleN ConfigStringN]
+         ConfigString2 and .. and CallbackModuleN ConfigStringN]
 	[-decrypt_key Key] | [-decrypt_file KeyFile]
         [-dir TestDir1 TestDir2 .. TestDirN] |
         [-suite Suite [[-group Group] [-case Case]]]
@@ -119,10 +120,10 @@
   

     Run CT in interactive mode
     
-	run_test -shell 
+	run_test -shell
 	[-config ConfigFile1 ConfigFile2 ... ConfigFileN]
 	[-userconfig CallbackModule1 ConfigString1 and CallbackModule2
-     ConfigString2 and .. and CallbackModuleN ConfigStringN]
+         ConfigString2 and .. and CallbackModuleN ConfigStringN]
 	[-decrypt_key Key] | [-decrypt_file KeyFile]

   

   

@@ -137,12 +138,10 @@
   

 
   

-  See also
-  
Please read the Running Test Suites
-  chapter in the Common Test User's Guide for information about the meaning of the
-  different start flags.

+    See also
+    
Please read the Running Test Suites
+      chapter in the Common Test User's Guide for information about the meaning of the
+      different start flags.

   

 
 
-
-
diff --git a/lib/common_test/doc/src/run_test_chapter.xml b/lib/common_test/doc/src/run_test_chapter.xml
index 44b4077ec4..917f3374db 100644
--- a/lib/common_test/doc/src/run_test_chapter.xml
+++ b/lib/common_test/doc/src/run_test_chapter.xml
@@ -102,10 +102,10 @@
- Running tests from the UNIX command line + Running tests from the OS command line -

The script run_test can be used for running tests from - the Unix/Linux command line, e.g. +

The run_test program can be used for running tests from + the OS command line, e.g.

-dir ]]> @@ -168,7 +168,7 @@ the current working directory of the Erlang Runtime System during the test run!

-

For details on how to generate the run_test script, see the +

For more information about the run_test program, see the Installation chapter.

@@ -177,7 +177,7 @@ Running tests from the Web based GUI

The web based GUI, VTS, is started with the run_test - script. From the GUI you can load config files, and select + program. From the GUI you can load config files, and select directories, suites and cases to run. You can also state the config files, directories, suites and cases on the command line when starting the web based GUI. @@ -201,10 +201,11 @@

Example:

Note that the browser must run as a separate OS process or VTS will hang!

-

If no specific browser start command is specified, netscape will +

If no specific browser start command is specified, Firefox will be the default browser on Unix platforms and Internet Explorer on Windows. - If Common Test fails to start a browser automatically, start your - favourite browser manually instead and type in the URL that Common Test + If Common Test fails to start a browser automatically, or 'none' is + specified as the value for -browser (i.e. -browser none), start your + favourite browser manually and type in the URL that Common Test displays in the shell.

@@ -214,7 +215,7 @@

Common Test provides an Erlang API for running tests. The main (and most flexible) function for specifying and executing tests is called ct:run_test/1. This function takes the same start parameters as - the run_test script described above, only the flags are instead + the run_test program described above, only the flags are instead given as options in a list of key-value tuples. E.g. a test specified with run_test like:

$ run_test -suite ./my_SUITE -logdir ./results

@@ -240,7 +241,7 @@ manually and call ct:install/1 to install any configuration data you might need (use [] as argument otherwise), then call ct:start_interactive/0 to start Common Test. If you use - the run_test script, you may start the Erlang shell and Common Test + the run_test program, you may start the Erlang shell and Common Test in the same go by using the -shell and, optionally, the -config flag:

diff --git a/lib/common_test/doc/src/test_structure_chapter.xml b/lib/common_test/doc/src/test_structure_chapter.xml index c8628b3a7a..60d01161ae 100644 --- a/lib/common_test/doc/src/test_structure_chapter.xml +++ b/lib/common_test/doc/src/test_structure_chapter.xml @@ -146,8 +146,8 @@ run_test - The name of an executable Bourne shell script that may be - used on Linux/Unix as an interface for specifying and running + The name of an executable program that may be + used as an interface for specifying and running tests with Common Test. -- cgit v1.2.3 From 7b33aa92bb2558ba04a6436203638fd46592b8d2 Mon Sep 17 00:00:00 2001 From: Peter Andersson Date: Thu, 27 May 2010 00:46:37 +0200 Subject: Improve documentation and fix minor problems General documentation and code updates. --- lib/common_test/doc/src/ct_master_chapter.xml | 52 ++++++++++++++------------- lib/common_test/doc/src/run_test_chapter.xml | 14 ++++---- 2 files changed, 36 insertions(+), 30 deletions(-) (limited to 'lib/common_test/doc') diff --git a/lib/common_test/doc/src/ct_master_chapter.xml b/lib/common_test/doc/src/ct_master_chapter.xml index 14f318759e..bc51957aee 100644 --- a/lib/common_test/doc/src/ct_master_chapter.xml +++ b/lib/common_test/doc/src/ct_master_chapter.xml @@ -30,6 +30,7 @@
+ General

Large scale automated testing requires running multiple independent test sessions in parallel. This is accomplished by running @@ -105,6 +106,7 @@ manual page for this module.

+ Test Specifications

The test specifications used as input to CT Master are fully compatible with the specifications used as input to the regular CT server. The syntax is described in the @@ -195,11 +197,12 @@

- Automatic startup of the test target nodes + Automatic startup of test target nodes -

Is is possible to perform initial actions on test target nodes - automatically using a new term in the test specification, init.

+

Is is possible to automatically start, and perform initial actions, on + test target nodes by using the test specification term init.

Currently, two sub-terms are supported, node_start and eval.

+

Example:

      {node, node1, node1@host1}.
      {node, node2, node1@host2}.
@@ -207,38 +210,39 @@
      {node, node4, node1@host3}.
      {init, node1, [{node_start, [{callback_module, my_slave_callback}]}]}.
      {init, [node2, node3], {node_start, [{username, "ct_user"}, {password, "ct_password"}]}}.
-     {init, node4, {eval, {module, function, []}}}.
-
+ {init, node4, {eval, {module, function, []}}}. +

This test specification declares that node1@host1 is to be started using - user's callback my_slave_callback with no parameters, and nodes node1@host2 and - node2@host2 will be started with the default callback module ct_slave, - using the given user name and password to log into remote host host2. - Also, there will be function module:function/0 evaluated on the - node1@host3, and result of this call will be printed to the log.

-

Default ct_slave callback module - delivered with the Common Test has the following features: + the user callback function callback_module:my_slave_callback/0, and nodes + node1@host2 and node2@host2 will be started with the default callback + module ct_slave. The given user name and password is used to log into remote + host host2. Also, the function module:function/0 will be evaluated on + node1@host3, and the result of this call will be printed to the log.

+ +

The default ct_slave callback module, + which is part of the Common Test application, has the following features: - Starting the Erlang nodes or local or remote hosts - (ssh is used for remote ones); + Starting Erlang target nodes on local or remote hosts + (ssh is used for communication). - Ability to start Erlang emulator with the additional flags - (any flags supported by erl are supported); + Ability to start an Erlang emulator with additional flags + (any flags supported by erl are supported). - Supervision of the node being start using internal callback - functions. Used to prevent hanging of started nodes. Configurable; + Supervision of a node being started by means of internal callback + functions. Used to prevent hanging nodes. (Configurable). - Monitoring of the master node by the slaves. Slave node may be - stopped in case of master node termination. Configurable; + Monitoring of the master node by the slaves. A slave node may be + stopped in case the master node terminates. (Configurable). - Execution of the user's functions after slave node is started. + Execution of user functions after a slave node is started. Functions can be given as a list of {Module, Function, Arguments} tuples.

-

Note that it is possible to specify eval term for the node as well +

Note that it is possible to specify an eval term for the node as well as startup_functions in the node_start options list. In this - case first node will be started, then the startup_functions are - executed, and finally functions specified with eval will be called. + case first the node will be started, then the startup_functions are + executed, and finally functions specified with eval are called.

diff --git a/lib/common_test/doc/src/run_test_chapter.xml b/lib/common_test/doc/src/run_test_chapter.xml index 917f3374db..7fd3174e71 100644 --- a/lib/common_test/doc/src/run_test_chapter.xml +++ b/lib/common_test/doc/src/run_test_chapter.xml @@ -354,13 +354,17 @@

Below is the test specification syntax. Test specifications can be used to run tests both in a single test host environment and in - a distributed Common Test environment. Node parameters are only relevant in the - latter (see the chapter about running Common Test in distributed mode for information). - For details on the event_handler term, see the + a distributed Common Test environment (Large Scale Testing). The init term, + as well as node parameters, are only relevant in the latter (see the + Large Scale Testing + chapter for information). For details on the event_handler term, see the Event Handling chapter.

Config terms:

+      {init, InitOptions}.
+      {init, [NodeAlias], InitOptions}.
+
       {node, NodeAlias, Node}.
  
       {cover, CoverSpecFile}.
@@ -384,9 +388,6 @@
       {event_handler, NodeRefs, EventHandlers}.
       {event_handler, EventHandlers, InitArgs}.
       {event_handler, NodeRefs, EventHandlers, InitArgs}.
-
-      {init, Options}.
-      {init, [NodeAlias], Options}.

Test terms:

@@ -404,6 +405,7 @@

Types:

+      InitOptions   = term()
       NodeAlias     = atom()
       Node          = node()
       NodeRef       = NodeAlias | Node | master
-- 
cgit v1.2.3


From 7c6504029f84c52de40a6b29b2fd1b17c053ccec Mon Sep 17 00:00:00 2001
From: Peter Andersson 
Date: Thu, 3 Jun 2010 14:34:09 +0200
Subject: Add event_handler_init start flag that can pass init arguments to
 event handlers

Also changed: The userconfig option in ct:run_test/1 from 3-tuple to 2-tuple.
---
 lib/common_test/doc/src/run_test.xml | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

(limited to 'lib/common_test/doc')

diff --git a/lib/common_test/doc/src/run_test.xml b/lib/common_test/doc/src/run_test.xml
index 49538a7483..f98cefd0ee 100644
--- a/lib/common_test/doc/src/run_test.xml
+++ b/lib/common_test/doc/src/run_test.xml
@@ -63,13 +63,15 @@
 	[-step [config | keep_inactive]]
 	[-config ConfigFile1 ConfigFile2 .. ConfigFileN]
 	[-userconfig CallbackModule1 ConfigString1 and CallbackModule2
-         ConfigString2 and .. and CallbackModuleN ConfigStringN]
+	 ConfigString2 and .. and CallbackModuleN ConfigStringN]
 	[-decrypt_key Key] | [-decrypt_file KeyFile]
 	[-logdir LogDir]
 	[-silent_connections [ConnType1 ConnType2 .. ConnTypeN]]
 	[-stylesheet CSSFile]
 	[-cover CoverCfgFile]
-	[-event_handler EvHandler1 EvHandler2 .. EvHandlerN]
+	[-event_handler EvHandler1 EvHandler2 .. EvHandlerN] |
+        [-event_handler_init EvHandler1 InitArg1 and
+	 EvHandler2 InitArg2 and .. EvHandlerN InitArgN]
 	[-include InclDir1 InclDir2 .. InclDirN]
 	[-no_auto_compile]
         [-repeat N [-force_stop]] |
@@ -90,7 +92,9 @@
 	[-silent_connections [ConnType1 ConnType2 .. ConnTypeN]]
 	[-stylesheet CSSFile]
 	[-cover CoverCfgFile]
-	[-event_handler EvHandler1 EvHandler2 .. EvHandlerN]
+	[-event_handler EvHandler1 EvHandler2 .. EvHandlerN] |
+        [-event_handler_init EvHandler1 InitArg1 and
+	 EvHandler2 InitArg2 and .. EvHandlerN InitArgN]
 	[-include InclDir1 InclDir2 .. InclDirN]
 	[-no_auto_compile]
         [-repeat N [-force_stop]] |
-- 
cgit v1.2.3


From aef5c74eba885b7c28d310b4a2522de854012e33 Mon Sep 17 00:00:00 2001
From: Peter Andersson 
Date: Tue, 8 Jun 2010 12:41:57 +0200
Subject: Add documentation for run_test program

---
 lib/common_test/doc/src/run_test.xml | 33 ++++++++++++++++++++++++++-------
 1 file changed, 26 insertions(+), 7 deletions(-)

(limited to 'lib/common_test/doc')

diff --git a/lib/common_test/doc/src/run_test.xml b/lib/common_test/doc/src/run_test.xml
index f98cefd0ee..feef18fe33 100644
--- a/lib/common_test/doc/src/run_test.xml
+++ b/lib/common_test/doc/src/run_test.xml
@@ -50,8 +50,26 @@
     (making it possible to e.g. add directories to the code server path,
     change the cookie on the node, start additional applications, etc).

 
-  
If run_test is called without parameters, it prints all valid
-    start flags to stdout.

+  
With the optional flag:

+  
-erl_args

+  
it's possible to divide the options on the run_test command line into
+    two groups, one that Common Test should process (those preceding -erl_args),
+    and one it should completely ignore and pass on directly to the emulator
+    (those following -erl_args). Options preceding -erl_args that Common Test
+    doesn't recognize, also get passed on to the emulator untouched.
+    By means of -erl_args the user may specify flags with the same name, but
+    with different destinations, on the run_test command line.

+  
If -pa or -pz flags are specified in the Common Test group of options
+    (preceding -erl_args), relative directories will be converted to
+    absolute and re-inserted into the code path by Common Test (to avoid
+    problems loading user modules when Common Test changes working directory
+    during test runs). Common Test will however ignore -pa and -pz flags
+    following -erl_args on the command line. These directories are added
+    to the code path normally (i.e. on specified form)

+
+  
If run_test is called with option:

+    
-help

+    
it prints all valid start flags to stdout.

   
 
   

@@ -74,6 +92,8 @@
 	 EvHandler2 InitArg2 and .. EvHandlerN InitArgN]
 	[-include InclDir1 InclDir2 .. InclDirN]
 	[-no_auto_compile]
+	[-muliply_timetraps Multiplier]
+	[-scale_timetraps]
         [-repeat N [-force_stop]] |
         [-duration HHMMSS [-force_stop]] |
         [-until [YYMoMoDD]HHMMSS [-force_stop]]
@@ -97,6 +117,8 @@
 	 EvHandler2 InitArg2 and .. EvHandlerN InitArgN]
 	[-include InclDir1 InclDir2 .. InclDirN]
 	[-no_auto_compile]
+	[-muliply_timetraps Multiplier]
+	[-scale_timetraps]
         [-repeat N [-force_stop]] |
         [-duration HHMMSS [-force_stop]] |
         [-until [YYMoMoDD]HHMMSS [-force_stop]]
@@ -114,6 +136,8 @@
         [-suite Suite [[-group Group] [-case Case]]]
 	[-include InclDir1 InclDir2 .. InclDirN]
 	[-no_auto_compile]
+	[-muliply_timetraps Multiplier]
+	[-scale_timetraps]
 	[-basic_html]
@@ -130,11 +154,6 @@ ConfigString2 and .. and CallbackModuleN ConfigStringN] [-decrypt_key Key] | [-decrypt_file KeyFile]
-
- Start an Erlang node with a given name - 
-	run_test -ctname NodeName
-
Start a Common Test Master node 
-- 
cgit v1.2.3


From 2d7ba88ebbb59a473dbcefd0f9dee1f1b816935e Mon Sep 17 00:00:00 2001
From: Peter Andersson 
Date: Tue, 8 Jun 2010 14:44:05 +0200
Subject: Misc documentation updates

---
 lib/common_test/doc/src/common_test_app.xml       |  4 +--
 lib/common_test/doc/src/event_handler_chapter.xml | 16 +++++-----
 lib/common_test/doc/src/run_test_chapter.xml      | 31 +++++++++++++-----
 lib/common_test/doc/src/write_test_chapter.xml    | 38 ++++++++++++++++++++---
 4 files changed, 67 insertions(+), 22 deletions(-)

(limited to 'lib/common_test/doc')

diff --git a/lib/common_test/doc/src/common_test_app.xml b/lib/common_test/doc/src/common_test_app.xml
index 7b52883f8a..70efe5a14b 100644
--- a/lib/common_test/doc/src/common_test_app.xml
+++ b/lib/common_test/doc/src/common_test_app.xml
@@ -337,7 +337,7 @@
       
       
     
-      Module:testcase() -> [Info] 
+      Module:Testcase() -> [Info] 
       Test case info function. 
       
 	 Info = {timetrap,Time} | {require,Required} | 
@@ -396,7 +396,7 @@
       
     
     
-	Module:testcase(Config) ->  void() | {skip,Reason} | {comment,Comment} | {save_config,SaveConfig} | {skip_and_save,Reason,SaveConfig} | exit() 
+	Module:Testcase(Config) ->  void() | {skip,Reason} | {comment,Comment} | {save_config,SaveConfig} | {skip_and_save,Reason,SaveConfig} | exit() 
       A test case
       
 	 Config = SaveConfig = [{Key,Value}]
diff --git a/lib/common_test/doc/src/event_handler_chapter.xml b/lib/common_test/doc/src/event_handler_chapter.xml
index 35b684730e..1508b7ce33 100644
--- a/lib/common_test/doc/src/event_handler_chapter.xml
+++ b/lib/common_test/doc/src/event_handler_chapter.xml
@@ -68,29 +68,27 @@
     Example:

     
$ run_test -suite test/my_SUITE -event_handler handlers/my_evh1 
     handlers/my_evh2 -pa $PWD/handlers

+    
Use the  option instead of
+       to pass start arguments to the event handler
+      init function.

     
All event handler modules must have gen_event behaviour. Note also that 
     these modules must be precompiled, and that their locations must be
     added explicitly to the Erlang code server search path (like in the
     example).

 
-    
It is not possible to specify start arguments to the event handlers when
-    using the run_test program. You may however pass along start arguments
-    if you use the ct:run_test/1 function. An event_handler tuple in the argument 
-    Opts has the following definition (see also ct:run_test/1 in the 
-    reference manual):

+    
An event_handler tuple in the argument Opts has the following
+      definition (see also ct:run_test/1 in the reference manual):

 
     
     {event_handler,EventHandlers}
 
     EventHandlers = EH | [EH]
     EH = atom() | {atom(),InitArgs} | {[atom()],InitArgs}
-    InitArgs = [term()] 
-    

+    InitArgs = [term()]

Example:

-    1> ct:run_test([{suite,"test/my_SUITE"},{event_handler,[my_evh1,{my_evh2,[node()]}]}]).
-
+ 1> ct:run_test([{suite,"test/my_SUITE"},{event_handler,[my_evh1,{my_evh2,[node()]}]}]).

This will install two event handlers for the my_SUITE test. Event handler my_evh1 is started with [] as argument to the init function. Event handler my_evh2 is started with the name of the current node in the init argument list.

diff --git a/lib/common_test/doc/src/run_test_chapter.xml b/lib/common_test/doc/src/run_test_chapter.xml index 7fd3174e71..54e9a3174c 100644 --- a/lib/common_test/doc/src/run_test_chapter.xml +++ b/lib/common_test/doc/src/run_test_chapter.xml @@ -97,8 +97,12 @@ the option with . With automatic compilation disabled, the user is responsible for compiling the test suite modules - (and any help modules) before the test run. Common Test will only verify - that the specified test suites exist before starting the tests.

+ (and any help modules) before the test run. If the modules can not be loaded + from the local file system during startup of Common Test, the user needs to + pre-load the modules before starting the test. Common Test will only verify + that the specified test suites exist (i.e. that they are, or can be, loaded). + This is useful e.g. if the test suites are transferred and loaded as binaries via + RPC from a remote node.

@@ -139,8 +143,14 @@ Code Coverage Analysis). ]]>, to install event handlers. + ]]>, to install + event handlers including start arguments. , specifies include directories (see above). , disables the automatic test suite compilation feature (see above). + ]]>, extends timetrap + timeout values. + ]]>, enables automatic timetrap + timeout scaling. ]]>, tells Common Test to repeat the tests n times (see below). ]]>, tells Common Test to repeat the tests for duration of time (see below). ]]>, tells Common Test to repeat the tests until stop_time (see below). @@ -243,11 +253,12 @@ call ct:start_interactive/0 to start Common Test. If you use the run_test program, you may start the Erlang shell and Common Test in the same go by using the -shell and, optionally, the -config - flag: + and/or -userconfig flag. Examples:

run_test -shell - ]]> + +

If no config file is given with the run_test command, @@ -272,7 +283,8 @@ 2> ct_telnet:open(unix_telnet). {ok,<0.105.0>} 4> ct_telnet:cmd(unix_telnet, "ls ."). - {ok,["ls .","file1 ...",...]} + {ok,["ls .","file1 ...",...]} +

Everything that Common Test normally prints in the test case logs, will in the interactive mode be written to a log named @@ -362,10 +374,13 @@ chapter.

Config terms:

+      {node, NodeAlias, Node}.
+
       {init, InitOptions}.
       {init, [NodeAlias], InitOptions}.
 
-      {node, NodeAlias, Node}.
+      {multiply_timetraps, N}.
+      {scale_timetraps, Bool}.
  
       {cover, CoverSpecFile}.
       {cover, NodeRef, CoverSpecFile}.
@@ -405,11 +420,13 @@

Types:

-      InitOptions   = term()
       NodeAlias     = atom()
+      InitOptions   = term()
       Node          = node()
       NodeRef       = NodeAlias | Node | master
       NodeRefs      = all_nodes | [NodeRef] | NodeRef
+      N             = integer()
+      Bool          = true | false
       CoverSpecFile = string()
       IncludeDirs   = string() | [string()]
       ConfigFiles   = string() | [string()]
diff --git a/lib/common_test/doc/src/write_test_chapter.xml b/lib/common_test/doc/src/write_test_chapter.xml
index 212e3d85be..e2106469b7 100644
--- a/lib/common_test/doc/src/write_test_chapter.xml
+++ b/lib/common_test/doc/src/write_test_chapter.xml
@@ -157,6 +157,15 @@
       {skipped,Reason} (where Reason is a user specific term).
     

 
+    
The end_per_testcase/2 function is called even after a
+      test case terminates due to a call to ct:abort_current_testcase/1,
+      or after a timetrap timeout. However, end_per_testcase
+      will then execute on a different process than the test case
+      function, and in this situation, end_per_testcase will
+      not be able to change the reason for test case termination by
+      returning {fail,Reason}, nor will it be able to save data with
+      {save_config,Data}.

+
     
If init_per_testcase crashes, the test case itself is skipped 
     automatically (so called auto skipped). If init_per_testcase
     returns a skip tuple, also then will the test case be skipped (so
@@ -682,12 +691,33 @@
       end_per_suite execute, like test cases, on dedicated Erlang
       processes.
     

+
+
+ Timetrap timeouts +

The default time limit for a test case is 30 minutes, unless a - timetrap is specified either by the test case info function - or the suite/0 function. -

- + timetrap is specified either by the suite info function + or a test case info function. The timetrap timeout value defined + in suite/0 is the value that will be used for each test case + in the suite (as well as for the configuration functions + init_per_suite/1 and end_per_suite). A timetrap timeout + value set with the test case info function will override the value set + by suite/0, but only for that particular test case.

+

It is also possible to set/reset a timetrap during test case (or + configuration function) execution. This is done by calling + ct:timetrap/1. This function will cancel the current timetrap + and start a new one.

+

Timetrap values can be extended with a multiplier value specified at + startup with the multiply_timetraps option. It is also possible + to let Test Server decide to scale up timetrap timeout values + automatically, e.g. if tools such as cover or trace are running during + the test. This feature is disabled by default and can be enabled with + the scale_timetraps start option.

+

If a test case needs to suspend itself for a time that also gets + multipled by multiply_timetraps, and possibly scaled up if + scale_timetraps is enabled, the function ct:sleep/1 + may be called.

-- cgit v1.2.3