The Test Server Controller

MODULE

test_server_ctrl

MODULE SUMMARY

This module provides a low level operators interface to the Test Server.

DESCRIPTION

The test_server_ctrl module provides a low level operators interface to the Test Server. This interface is normally not used directly by the tester, instead a framework built on top of the test_server_ctrl is used.

The Test Server Framework ts is such a framework used for testing OTP. Please turn to the Test Server User's Guide and the reference manual for the ts module for more information about this.

If you want to write your own framework, some more information can be found in the chapter named "Writing your own test server framework" in the Test Server User's Guide. Details about the interface provided by test_server_ctrl can of course be found below in this reference manual.

EXPORTS

start() -> Result
start(ParameterFile) -> Result

Types:
Result = ok | {error, {already_started, pid()}
ParameterFile = atom() | string()

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.

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:

{type,PlatformType}

This is an atom indicating the target platform type, currently supported: PlatformType = vxworks | ose
Mandatory

{target,TargetHost}

This is the name of the target host, can be atom or string.
Mandatory

{slavetargets,SlaveTargets}

This is a list of available hosts where slave nodes can be started. The hostnames are given as atoms or strings.
Optional, default SlaveTargets = []

{longnames,Bool}

This indicates if longnames shall be used, i.e. if the -name option should be used for the target node instead of -sname
Optional, default Bool = false

{master, {MasterHost, MasterCookie}}

If target is remote and the target node is started as a slave node (which is the case for OSE/Delta), this option indicates which master and cookie to use. The given master will also be used as master for slave nodes started with test_server:start_node/3. It is expected that the erl_boot_server is started on the master node before the test_server_ctrl:start/1 function is called.
Optional, if not given the test server controller node is used as master and the erl_boot_server is automatically started.

stop() -> ok

This stops the test server (both controller and target) and all its activity. The running test suite (if any) will be halted.

add_dir(Name, Dir) -> ok
add_dir(Name, Dir, Pattern) -> ok
add_dir(Name, [Dir|Dirs]) -> ok
add_dir(Name, [Dir|Dirs], Pattern) -> ok

Types:
Name = term()

The jobname for this directory.
Dir = term()

The directory to scan for test suites.
Dirs = [term()]

List of directories to scan for test suites.
Pattern = term()

Suite match pattern. Directories will be scanned for Pattern_SUITE.erl files.

Puts a collection of suites matching (*_SUITE) in given directories into the job queue. Name is an arbitrary name for the job, it can be any erlang term. If Pattern is given, only modules matching Pattern* will be added.

add_module(Mod) -> ok
add_module(Name, [Mod|Mods]) -> ok

Types:
Mod = atom()
Mods = [atom()]

The name(s) of the module(s) to add.
Name = term()

Name for the job.

This function adds a module or a list of modules, to the test servers job queue. Name may be any Erlang term. When Name is not given, the job gets the name of the module.

add_case(Mod, Case) -> ok

Types:
Mod = atom()

Name of the module the test case is in.
Case = atom()

Function name of the test case to add.

This function will add one test case to the job queue. The job will be given the module's name.

add_spec(TestSpecFile) -> ok | {error, nofile}

Types:
TestSpecFile = string()

Name of the test specification file

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 test.spec, the job will be called test.

See the reference manual for the test server application for details about the test specification file.

set_levels(Console, Major, Minor) -> ok

Types:
Console = integer()

Level for I/O to be sent to console.
Major = integer()

Level for I/O to be sent to the major logfile.
Minor = integer()

Level for I/O to be sent to the minor logfile.

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 io:format/2) 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).

All output with detail level:

• Less than or equal to Console is displayed on the screen (default 1)


• Less than or equal to Major is logged in the major log file (default 19)


• Greater than or equal to Minor is logged in the minor log files (default 10)



To view the currently set thresholds, use the get_levels/0 function.

get_levels() -> {Console, Major, Minor}

Returns the current levels. See set_levels/3 for types.

jobs() -> JobQueue

Types:
JobQueue = [{list(), pid()}]

This function will return all the jobs currently in the job queue.

trc(TraceInfoFile) -> ok | {error, Reason}

Types:
TraceInfoFile = atom() | string()

Name of a file defining which functions to trace and how

This function starts call trace on target and on slave or peer nodes that are started or will be started by the test suites.

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.

The trace information file specified by the TraceInfoFile argument is a text file containing one or more of the following elements:

• {SetTP,Module,Pattern}.


• {SetTP,Module,Function,Pattern}.


• {SetTP,Module,Function,Arity,Pattern}.


• ClearTP.


• {ClearTP,Module}.


• {ClearTP,Module,Function}.


• {ClearTP,Module,Function,Arity}.



SetTP = tp | tpl

This is maps to the corresponding functions in the ttb module in the observer application. tp means set trace pattern on global function calls. tpl means set trace pattern on local and global function calls.

ClearTP = ctp | ctpl | ctpg

This is maps to the corresponding functions in the ttb module in the observer application. ctp means clear trace pattern (i.e. turn off) on global and local function calls. ctpl means clear trace pattern on local function calls only and ctpg means clear trace pattern on global function calls only.

Module = atom()

The module to trace

Function = atom()

The name of the function to trace

Arity = integer()

The arity of the function to trace

Pattern = [] | match_spec()

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.

The trace result will be logged in a (binary) file called NodeName-test_server in the current directory of the test server controller node. The log must be formatted using ttb:format/1/2.

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

stop_trace() -> ok | {error, not_tracing}

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.

FUNCTIONS INVOKED FROM COMMAND LINE

The following functions are supposed to be invoked from the command line using the -s option when starting the erlang node.

EXPORTS

run_test(CommandLine) -> ok

Types:
CommandLine = FlagList

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.

The CommandLine argument is a list of command line flags, typically ['KEY1', Value1, 'KEY2', Value2, ...]. The valid command line flags are listed below.

Under a UNIX command prompt, this function can be invoked like this:
erl -noshell -s test_server_ctrl run_test KEY1 Value1 KEY2 Value2 ... -s erlang halt

Or make an alias (this is for unix/tcsh)
alias erl_test 'erl -noshell -s test_server_ctrl run_test \!* -s erlang halt'

And then use it like this
erl_test KEY1 Value1 KEY2 Value2 ...


The valid command line flags are

DIR dir

Adds all test modules in the directory dir to the job queue.

MODULE mod

Adds the module mod to the job queue.

SPEC spec

Runs the test specification file spec.

SKIPMOD mod

Skips all test cases in the module mod

SKIPCASE mod case

Skips the test case case in module mod.

NAME name

Names the test suite to something else than the default name. This does not apply to SPEC which keeps it's names.

PARAMETERS parameterfile

Specifies the parameter file to use when starting remote target

TRACE traceinfofile

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 trc/1 above for more information about the syntax of this file.

AUTHORS

Janne Lindblad - support@erlang.ericsson.se
Mattias Nilsson - support@erlang.ericsson.se
Siri Hansen - support@erlang.ericsson.se