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.
start() -> Result
start(ParameterFile) -> Result
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}
PlatformType = vxworks | ose
{target,TargetHost}
{slavetargets,SlaveTargets}
SlaveTargets = []
{longnames,Bool}
-name
option should be used for the target node
instead of -sname
Bool = false
{master, {MasterHost, MasterCookie}}
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.
erl_boot_server
is
automatically started.
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
Name = term()
Dir = term()
Dirs = [term()]
Pattern = term()
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
Mod = atom()
Mods = [atom()]
Name = term()
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.
Mod = atom()
Case = atom()
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}
TestSpecFile = string()
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
Console = integer()
Major = integer()
Minor = integer()
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:
Console
is displayed on
the screen (default 1)
Major
is logged in the
major log file (default 19)
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.
JobQueue = [{list(), pid()}]
This function will return all the jobs currently in the job queue.
trc(TraceInfoFile) -> ok | {error, Reason}
TraceInfoFile = atom() | string()
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
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
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()
Function = atom()
Arity = integer()
Pattern = [] | match_spec()
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.
The following functions are supposed to be invoked from the
command line using the -s
option when starting the erlang
node.
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
dir
to
the job queue.
MODULE mod
mod
to the job queue.
SPEC spec
spec
.
SKIPMOD mod
mod
SKIPCASE mod case
case
in module mod
.
NAME name
SPEC
which keeps
it's names.
PARAMETERS parameterfile
TRACE traceinfofile
trc/1
above for more information about the
syntax of this file.