.TH test_server_ctrl 3 "test_server  3.2.2" "Ericsson AB" "ERLANG MODULE DEFINITION"
.SH MODULE
The Test Server Controller \- This module provides a low level interface to the Test Server\&.
.SH DESCRIPTION
.LP
The \fItest_server_ctrl\fR module provides a low level interface to the Test Server\&. This interface is normally not used directly by the tester, but through a framework built on top of \fItest_server_ctrl\fR\&. 
.LP
Common Test is such a framework, well suited for automated black box testing of target systems of any kind (not necessarily implemented in Erlang)\&. Common Test is also a very useful tool for white box testing Erlang programs and OTP applications\&. Please see the Common Test User\&'s Guide and reference manual for more information\&. 
.LP
If you want to write your own framework, some more information can be found in the chapter "Writing your own test server framework" in the Test Server User\&'s Guide\&. Details about the interface provided by \fItest_server_ctrl\fR follows below\&. 

.SH EXPORTS
.LP
.B
start() -> Result
.br
.B
start(ParameterFile) -> Result
.br
.RS
.TP
Types
Result = ok | {error, {already_started, pid()}
.br
ParameterFile = atom() | string()
.br
.RE
.RS
.LP
This function starts the test server\&. If the parameter file is given, it indicates that the target is remote\&. In that case the target node is started and a socket connection is established between the controller and the target node\&. 
.LP
The parameter file is a text file containing key-value tuples\&. Each tuple must be followed by a dot-newline sequence\&. The following key-value tuples are allowed: 
.RS 2
.TP 4
.B
\fI{type, PlatformType}\fR:
This is an atom indicating the target platform type, currently supported: \fIPlatformType = vxworks\fR 
.br
 Mandatory
.TP 4
.B
\fI{target, TargetHost}\fR:
This is the name of the target host, can be atom or string\&. 
.br
 Mandatory
.TP 4
.B
\fI{slavetargets, SlaveTargets}\fR:
This is a list of available hosts where slave nodes can be started\&. The hostnames are given as atoms or strings\&. 
.br
 Optional, default \fISlaveTargets = []\fR
.TP 4
.B
\fI{longnames, Bool}\fR:
This indicates if longnames shall be used, i\&.e\&. if the \fI-name\fR option should be used for the target node instead of \fI-sname\fR 
.br
 Optional, default \fIBool = false\fR
.TP 4
.B
\fI{master, {MasterHost, MasterCookie}}\fR:
If target is remote and the target node is started as a slave node, this option indicates which master and cookie to use\&. The given master will also be used as master for slave nodes started with \fItest_server:start_node/3\fR\&. It is expected that the \fIerl_boot_server\fR is started on the master node before the \fItest_server_ctrl:start/1\fR function is called\&. 
.br
 Optional, if not given the test server controller node is used as master and the \fIerl_boot_server\fR is automatically started\&.
.RE
.RE
.LP
.B
stop() -> ok
.br
.RS
.LP
This stops the test server (both controller and target) and all its activity\&. The running test suite (if any) will be halted\&.
.RE
.LP
.B
add_dir(Name, Dir) -> ok
.br
.B
add_dir(Name, Dir, Pattern) -> ok
.br
.B
add_dir(Name, [Dir|Dirs]) -> ok
.br
.B
add_dir(Name, [Dir|Dirs], Pattern) -> ok
.br
.RS
.TP
Types
Name = term()
.br
  The jobname for this directory\&.
.br
Dir = term()
.br
  The directory to scan for test suites\&.
.br
Dirs = [term()]
.br
  List of directories to scan for test suites\&.
.br
Pattern = term()
.br
  Suite match pattern\&. Directories will be scanned for Pattern_SUITE\&.erl files\&.
.br
.RE
.RS
.LP
Puts a collection of suites matching (*_SUITE) in given directories into the job queue\&. \fIName\fR is an arbitrary name for the job, it can be any erlang term\&. If \fIPattern\fR is given, only modules matching \fIPattern*\fR will be added\&.
.RE
.LP
.B
add_module(Mod) -> ok
.br
.B
add_module(Name, [Mod|Mods]) -> ok
.br
.RS
.TP
Types
Mod = atom()
.br
Mods = [atom()]
.br
  The name(s) of the module(s) to add\&.
.br
Name = term()
.br
  Name for the job\&.
.br
.RE
.RS
.LP
This function adds a module or a list of modules, to the test servers job queue\&. \fIName\fR may be any Erlang term\&. When \fIName\fR is not given, the job gets the name of the module\&.
.RE
.LP
.B
add_case(Mod, Case) -> ok
.br
.RS
.TP
Types
Mod = atom()
.br
  Name of the module the test case is in\&.
.br
Case = atom() 
.br
  Function name of the test case to add\&.
.br
.RE
.RS
.LP
This function will add one test case to the job queue\&. The job will be given the module\&'s name\&.
.RE
.LP
.B
add_case(Name, Mod, Case) -> ok
.br
.RS
.TP
Types
Name = string()
.br
  Name to use for the test job\&.
.br
.RE
.RS
.LP
Equivalent to \fIadd_case/2\fR, but the test job will get the specified name\&.
.RE
.LP
.B
add_cases(Mod, Cases) -> ok
.br
.RS
.TP
Types
Mod = atom()
.br
  Name of the module the test case is in\&.
.br
Cases = [Case] 
.br
Case = atom() 
.br
  Function names of the test cases to add\&.
.br
.RE
.RS
.LP
This function will add one or more test cases to the job queue\&. The job will be given the module\&'s name\&.
.RE
.LP
.B
add_cases(Name, Mod, Cases) -> ok
.br
.RS
.TP
Types
Name = string()
.br
  Name to use for the test job\&.
.br
.RE
.RS
.LP
Equivalent to \fIadd_cases/2\fR, but the test job will get the specified name\&.
.RE
.LP
.B
add_spec(TestSpecFile) -> ok | {error, nofile}
.br
.RS
.TP
Types
TestSpecFile = string()
.br
  Name of the test specification file
.br
.RE
.RS
.LP
This function will add the content of the given test specification file to the job queue\&. The job will be given the name of the test specification file, e\&.g\&. if the file is called \fItest\&.spec\fR, the job will be called \fItest\fR\&. 
.LP
See the reference manual for the test server application for details about the test specification file\&.
.RE
.LP
.B
add_dir_with_skip(Name, [Dir|Dirs], Skip) -> ok
.br
.B
add_dir_with_skip(Name, [Dir|Dirs], Pattern, Skip) -> ok
.br
.B
add_module_with_skip(Mod, Skip) -> ok
.br
.B
add_module_with_skip(Name, [Mod|Mods], Skip) -> ok
.br
.B
add_case_with_skip(Mod, Case, Skip) -> ok
.br
.B
add_case_with_skip(Name, Mod, Case, Skip) -> ok
.br
.B
add_cases_with_skip(Mod, Cases, Skip) -> ok
.br
.B
add_cases_with_skip(Name, Mod, Cases, Skip) -> ok
.br
.RS
.TP
Types
Skip = [SkipItem]
.br
  List of items to be skipped from the test\&.
.br
SkipItem = {Mod, Comment} | {Mod, Case, Comment} | {Mod, Cases, Comment}
.br
Mod = atom()
.br
  Test suite name\&.
.br
Comment = string()
.br
  Reason why suite or case is being skipped\&.
.br
Cases = [Case]
.br
Case = atom()
.br
  Name of test case function\&.
.br
.RE
.RS
.LP
These functions add test jobs just like the add_dir, add_module, add_case and add_cases functions above, but carry an additional argument, Skip\&. Skip is a list of items that should be skipped in the current test run\&. Test job items that occur in the Skip list will be logged as SKIPPED with the associated Comment\&.
.RE
.LP
.B
add_tests_with_skip(Name, Tests, Skip) -> ok
.br
.RS
.TP
Types
Name = term()
.br
  The jobname for this directory\&.
.br
Tests = [TestItem]
.br
  List of jobs to add to the run queue\&.
.br
TestItem = {Dir, all, all} | {Dir, Mods, all} | {Dir, Mod, Cases}
.br
Dir = term()
.br
  The directory to scan for test suites\&.
.br
Mods = [Mod]
.br
Mod = atom()
.br
  Test suite name\&.
.br
Cases = [Case]
.br
Case = atom()
.br
  Name of test case function\&.
.br
Skip = [SkipItem]
.br
  List of items to be skipped from the test\&.
.br
SkipItem = {Mod, Comment} | {Mod, Case, Comment} | {Mod, Cases, Comment}
.br
Comment = string()
.br
  Reason why suite or case is being skipped\&.
.br
.RE
.RS
.LP
This function adds various test jobs to the test_server_ctrl job queue\&. These jobs can be of different type (all or specific suites in one directory, all or specific cases in one suite, etc)\&. It is also possible to get particular items skipped by passing them along in the Skip list (see the add_*_with_skip functions above)\&.
.RE
.LP
.B
set_levels(Console, Major, Minor) -> ok
.br
.RS
.TP
Types
Console = integer()
.br
  Level for I/O to be sent to console\&.
.br
Major = integer()
.br
  Level for I/O to be sent to the major logfile\&.
.br
Minor = integer()
.br
  Level for I/O to be sent to the minor logfile\&.
.br
.RE
.RS
.LP
Determines where I/O from test suites/test server will go\&. All text output from test suites and the test server is tagged with a priority value which ranges from 0 to 100, 100 being the most detailed\&. (see the section about log files in the user\&'s guide)\&. Output from the test cases (using \fIio:format/2\fR) has a detail level of 50\&. Depending on the levels set by this function, this I/O may be sent to the console, the major log file (for the whole test suite) or to the minor logfile (separate for each test case)\&. 
.LP
All output with detail level:
.RS 2
.TP 2
*
Less than or equal to \fIConsole\fR is displayed on the screen (default 1)
.TP 2
*
Less than or equal to \fIMajor\fR is logged in the major log file (default 19)
.TP 2
*
Greater than or equal to \fIMinor\fR is logged in the minor log files (default 10)
.RE
.LP
To view the currently set thresholds, use the \fIget_levels/0\fR function\&.
.RE
.LP
.B
get_levels() -> {Console, Major, Minor}
.br
.RS
.LP
Returns the current levels\&. See \fIset_levels/3\fR for types\&.
.RE
.LP
.B
jobs() -> JobQueue
.br
.RS
.TP
Types
JobQueue = [{list(), pid()}]
.br
.RE
.RS
.LP
This function will return all the jobs currently in the job queue\&.
.RE
.LP
.B
multiply_timetraps(N) -> ok
.br
.RS
.TP
Types
N = integer() | infinity
.br
.RE
.RS
.LP
This function should be called before a test is started which requires extended timetraps, e\&.g\&. if extensivie tracing is used\&. All timetraps started after this call will be multiplied by \fIN\fR\&.
.RE
.LP
.B
cover(Application,Analyse) -> ok
.br
.B
cover(CoverFile,Analyse) -> ok
.br
.B
cover(App,CoverFile,Analyse) -> ok
.br
.RS
.TP
Types
Application = atom()
.br
  OTP application to cover compile
.br
CoverFile = string()
.br
  Name of file listing modules to exclude from or include in cover compilation\&. The filename must include full path to the file\&.
.br
Analyse = details | overview
.br
.RE
.RS
.LP
This function informs the test_server controller that next test shall run with code coverage analysis\&. All timetraps will automatically be multiplied by 10 when cover i run\&. 
.LP
\fIApplication\fR and \fICoverFile\fR indicates what to cover compile\&. If \fIApplication\fR is given, the default is that all modules in the \fIebin\fR directory of the application will be cover compiled\&. The \fIebin\fR directory is found by adding \fIebin\fR to \fIcode:lib_dir(Application)\fR\&. 
.LP
A \fICoverFile\fR can have the following entries:

.nf
{exclude, all | ExcludeModuleList}\&.
{include, IncludeModuleList}\&.        
.fi
.LP
Note that each line must end with a full stop\&. \fIExcludeModuleList\fR and \fIIncludeModuleList\fR are lists of atoms, where each atom is a module name\&. 
.LP
If both an \fIApplication\fR and a \fICoverFile\fR is given, all modules in the application are cover compiled, except for the modules listed in \fIExcludeModuleList\fR\&. The modules in \fIIncludeModuleList\fR are also cover compiled\&. 
.LP
If a \fICoverFile\fR is given, but no \fIApplication\fR, only the modules in \fIIncludeModuleList\fR are cover compiled\&. 
.LP
\fIAnalyse\fR indicates the detail level of the cover anlysis\&. If \fIAnalyse = details\fR, each cover compiled module will be analysed with \fIcover:analyse_to_file/1\fR\&. If \fIAnalyse = overview\fR an overview of all cover compiled modules is created, listing the number of covered and not covered lines for each module\&. 
.LP
If the test following this call starts any slave or peer nodes with \fItest_server:start_node/3\fR, the same cover compiled code will be loaded on all nodes\&. If the loading fails, e\&.g\&. if the node runs an old version of OTP, the node will simply not be a part of the coverage analysis\&. Note that slave or peer nodes must be stopped with \fItest_server:stop_node/1\fR for the node to be part of the coverage analysis, else the test server will not be able to fetch coverage data from the node\&. 
.LP
When the test is finished, the coverage analysis is automatically completed, logs are created and the cover compiled modules are unloaded\&. If another test is to be run with coverage analysis, \fItest_server_ctrl:cover/2/3\fR must be called again\&. 
.RE
.LP
.B
cross_cover_analyse(Level) -> ok
.br
.RS
.TP
Types
Level = details | overview
.br
.RE
.RS
.LP
Analyse cover data collected from all tests\&. The modules analysed are the ones listed in the cross cover file \fIcross\&.cover\fR in the current directory of the test server\&.
.LP
The modules listed in the \fIcross\&.cover\fR file are modules that are heavily used by other applications than the one they belong to\&. This function should be run after all tests are completed, and the result will be stored in a file called cross_cover\&.html in the run\&.<timestamp> directory of the application the modules belong to\&. 
.LP
The \fIcross\&.cover\fR file contains elements like this:

.nf
{App,Modules}\&.        
.fi
.LP
where \fIApp\fR can be an application name or the atom \fIall\fR\&. The application (or all applications) will cover compile the listed \fIModules\fR\&. 
.RE
.LP
.B
trc(TraceInfoFile) -> ok | {error, Reason}
.br
.RS
.TP
Types
TraceInfoFile = atom() | string()
.br
  Name of a file defining which functions to trace and how
.br
.RE
.RS
.LP
This function starts call trace on target and on slave or peer nodes that are started or will be started by the test suites\&. 
.LP
Timetraps are not extended automatically when tracing is used\&. Use \fImultiply_timetraps/1\fR if necessary\&. 
.LP
Note that the trace support in the test server is in a very early stage of the implementation, and thus not yet as powerful as one might wish for\&. 
.LP
The trace information file specified by the \fITraceInfoFile\fR argument is a text file containing one or more of the following elements: 
.RS 2
.TP 2
*
\fI{SetTP, Module, Pattern}\&.\fR
.TP 2
*
\fI{SetTP, Module, Function, Pattern}\&.\fR
.TP 2
*
\fI{SetTP, Module, Function, Arity, Pattern}\&.\fR
.TP 2
*
\fIClearTP\&.\fR
.TP 2
*
\fI{ClearTP, Module}\&.\fR
.TP 2
*
\fI{ClearTP, Module, Function}\&.\fR
.TP 2
*
\fI{ClearTP, Module, Function, Arity}\&.\fR
.RE
.RS 2
.TP 4
.B
\fISetTP = tp | tpl\fR:
This is maps to the corresponding functions in the \fIttb\fR module in the \fIobserver\fR application\&. \fItp\fR means set trace pattern on global function calls\&. \fItpl\fR means set trace pattern on local and global function calls\&.
.TP 4
.B
\fIClearTP = ctp | ctpl | ctpg\fR:
This is maps to the corresponding functions in the \fIttb\fR module in the \fIobserver\fR application\&. \fIctp\fR means clear trace pattern (i\&.e\&. turn off) on global and local function calls\&. \fIctpl\fR means clear trace pattern on local function calls only and \fIctpg\fR means clear trace pattern on global function calls only\&.
.TP 4
.B
\fIModule = atom()\fR:
The module to trace
.TP 4
.B
\fIFunction = atom()\fR:
The name of the function to trace
.TP 4
.B
\fIArity = integer()\fR:
The arity of the function to trace
.TP 4
.B
\fIPattern = [] | match_spec()\fR:
The trace pattern to set for the module or function\&. For a description of the match_spec() syntax, please turn to the User\&'s guide for the runtime system (erts)\&. The chapter "Match Specification in Erlang" explains the general match specification language\&.
.RE
.LP
The trace result will be logged in a (binary) file called \fINodeName-test_server\fR in the current directory of the test server controller node\&. The log must be formatted using \fIttb:format/1/2\fR\&. 
.LP
This is valid for all targets except the OSE/Delta target for which all nodes will be logged and automatically formatted in one single text file called \fIallnodes-test_server\fR\&.
.RE
.LP
.B
stop_trace() -> ok | {error, not_tracing}
.br
.RS
.LP
This function stops tracing on target, and on slave or peer nodes that are currently running\&. New slave or peer nodes will no longer be traced after this\&.
.RE
.SH FUNCTIONS INVOKED FROM COMMAND LINE
.LP
The following functions are supposed to be invoked from the command line using the \fI-s\fR option when starting the erlang node\&.
.SH EXPORTS
.LP
.B
run_test(CommandLine) -> ok
.br
.RS
.TP
Types
CommandLine = FlagList
.br
.RE
.RS
.LP
This function is supposed to be invoked from the commandline\&. It starts the test server, interprets the argument supplied from the commandline, runs the tests specified and when all tests are done, stops the test server and returns to the Erlang prompt\&. 
.LP
The \fICommandLine\fR argument is a list of command line flags, typically \fI[\&'KEY1\&', Value1, \&'KEY2\&', Value2, \&.\&.\&.]\fR\&. The valid command line flags are listed below\&. 
.LP
Under a UNIX command prompt, this function can be invoked like this: 
.br
\fIerl -noshell -s test_server_ctrl run_test KEY1 Value1 KEY2 Value2 \&.\&.\&. -s erlang halt\fR
.LP
Or make an alias (this is for unix/tcsh) 
.br
\fIalias erl_test \&'erl -noshell -s test_server_ctrl run_test \e!* -s erlang halt\&'\fR
.LP
And then use it like this 
.br
\fIerl_test KEY1 Value1 KEY2 Value2 \&.\&.\&.\fR 
.br

.LP
The valid command line flags are
.RS 2
.TP 4
.B
\fIDIR dir\fR:
Adds all test modules in the directory \fIdir\fR to the job queue\&.
.TP 4
.B
\fIMODULE mod\fR:
Adds the module \fImod\fR to the job queue\&.
.TP 4
.B
\fICASE mod case\fR:
Adds the case \fIcase\fR in module \fImod\fR to the job queue\&.
.TP 4
.B
\fISPEC spec\fR:
Runs the test specification file \fIspec\fR\&.
.TP 4
.B
\fISKIPMOD mod\fR:
Skips all test cases in the module \fImod\fR
.TP 4
.B
\fISKIPCASE mod case\fR:
Skips the test case \fIcase\fR in module \fImod\fR\&.
.TP 4
.B
\fINAME name\fR:
Names the test suite to something else than the default name\&. This does not apply to \fISPEC\fR which keeps it\&'s names\&.
.TP 4
.B
\fIPARAMETERS parameterfile\fR:
Specifies the parameter file to use when starting remote target
.TP 4
.B
\fICOVER app cover_file analyse\fR:
Indicates that the test should be run with cover alanysis\&. \fIapp\fR, \fIcover_file\fR and \fIanalyse\fR corresponds to the parameters to \fItest_server_ctrl:cover/3\fR\&. If no cover file is used, the atom \fInone\fR should be given\&.
.TP 4
.B
\fITRACE traceinfofile\fR:
Specifies a trace information file\&. When this option is given, call tracing is started on the target node and all slave or peer nodes that are started\&. The trace information file specifies which modules and functions to trace\&. See the function \fItrc/1\fR above for more information about the syntax of this file\&.
.RE
.RE
.SH FRAMEWORK CALLBACK FUNCTIONS
.LP
A test server framework can be defined by setting the environment variable \fITEST_SERVER_FRAMEWORK\fR to a module name\&. This module will then be framework callback module, and it must export the following function:
.SH EXPORTS
.LP
.B
get_suite(Mod,Func) -> TestCaseList
.br
.RS
.TP
Types
Mod = atom()
.br
Func = atom()
.br
TestCaseList = [, SubCase]
.br
.RE
.RS
.LP
This function is called before a test case is started\&. The purpose is to retrieve a list of subcases\&. The default behaviour of this function should be to call \fIMod:Func(suite)\fR and return the result from this call\&.
.RE
.LP
.B
init_tc(Mod,Func,Args) -> {ok,Args}
.br
.RS
.TP
Types
Mod = atom()
.br
Func = atom()
.br
Args = [tuple()]
.br
  Normally Args = [Config]
.br
.RE
.RS
.LP
This function is called when a test case is started\&. It is called on the process executing the test case function (\fIMod:Func\fR)\&. Typical use of this function can be to alter the input parameters to the test case function (\fIArgs\fR) or to set properties for the executing process\&.
.RE
.LP
.B
end_tc(Mod,Func,Args) -> ok
.br
.RS
.TP
Types
Mod = atom()
.br
Func = atom()
.br
Args = [tuple()]
.br
  Normally Args = [Config]
.br
.RE
.RS
.LP
This function is called when a test case is completed\&. It is called on the process where the test case function (\fIMod:Func\fR) was executed\&. Typical use of this function can be to clean up stuff done by \fIinit_tc/3\fR\&.
.RE
.LP
.B
report(What,Data) -> ok
.br
.RS
.TP
Types
What = atom()
.br
Data = term()
.br
.RE
.RS
.LP
This function is called in order to keep the framework upto date about the progress of the test\&. This is useful e\&.g\&. if the framework implements a GUI where the progress information is constantly updated\&. The following can be reported: 
.LP
\fIWhat = tests_start, Data = {Name, NumCases}\fR 
.br
\fIWhat = tests_done, Data = {Ok, Failed, Skipped}\fR 
.br
\fIWhat = tc_start, Data = {Mod, Func}\fR 
.br
\fIWhat = tc_done, Data = {Mod, Func, Result}\fR
.RE
.LP
.B
error_notification(Mod, Case, Args, Error) -> ok
.br
.RS
.TP
Types
Mod = atom()
.br
  Test suite name\&.
.br
Case = atom()
.br
  Name of test case function\&.
.br
Args = [tuple()]
.br
  Normally Args = [Config]
.br
Error = {Reason, Location}
.br
Reason = term()
.br
  Reason for termination\&.
.br
Location = unknown | [{Mod, Case, Line}]
.br
  Last known position in Mod before termination\&.
.br
Line = integer()
.br
  Line number in file Mod\&.erl\&.
.br
.RE
.RS
.LP
This function is called as the result of testcase Mod:Case failing with Reason at Location\&. The function is intended mainly to aid specific logging or error handling in the framework application\&. Note that for Location to have relevant values (i\&.e\&. other than unknown), the \fIline\fR macro or \fItest_server_line\fR parse transform must be used\&. For details, please see the section about test suite line numbers in the \fItest_server\fR reference manual page\&.
.RE
.LP
.B
warn(What) -> boolean()
.br
.RS
.TP
Types
What = processes | nodes
.br
.RE
.RS
.LP
The test server checks the number of processes and nodes before and after the test is executed\&. This function is a question to the framework if the test server should warn when the number of processes or nodes has changed during the test execution\&. If \fItrue\fR is returned, a warning will be written in the test case minor log file\&.
.RE
.LP
.B
target_info() -> InfoStr
.br
.RS
.TP
Types
InfoStr = string() | ""
.br
.RE
.RS
.LP
The test server will ask the framework for information about the test target system and print InfoStr in the test case log file below the host information\&.
.RE